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

package/src/index.ts

@@ -11,16 +11,6 @@
 export { MyazaKYC, useMyazaKYC } from './MyazaKYC';
 export type { MyazaKYCProps, UseMyazaKYCReturn } from './MyazaKYC';
 
-// Returning-user face re-authentication (the web SDK's MyazaBiometricAuth).
-export { MyazaBiometricAuth } from './MyazaBiometricAuth';
-export type { MyazaBiometricAuthProps } from './MyazaBiometricAuth';
-export type {
-  BiometricAuthRequest,
-  BiometricAuthResponse,
-  BiometricStatusResponse,
-  BiometricLivenessClaim,
-} from './services/api-types-biometric';
-
 // Public config + callback types
 export type {
   MyazaKYCConfig,
@@ -192,6 +182,11 @@ export { mrzCheckDigit, parseMrz, type MrzScan } from './mrz/parse';
 // "this document has no MRZ" — the two look identical from the outside, and
 // only the first is worth reporting as a build problem.
 export { hasTextRecognizer } from './mrz/textRecognizer';
+// Whether that recogniser can run RIGHT NOW. On Android the model is fetched
+// through Play Services rather than bundled, so a build that HAS the recogniser
+// can still be unable to read for a while after install — a different fact from
+// the probe above, and the one a host app would show a "getting ready" note for.
+export { isTextModelReady, primeTextModel } from './mrz/textRecognizer';
 export { hasRectDetector } from './capture/rectDetector';
 export { extractMrz, sanitizeMrzLine } from './mrz/extract';
 

package/src/lib/documentCaptureCheck.ts

@@ -0,0 +1,136 @@
+// ─── Will the server be able to read these document photos? ──────────────────
+//
+// The React Native mirror of the web SDK's document capture check and the
+// Flutter SDK's. Keep the three in lockstep: the problem order and every
+// string below are word for word the same on each platform.
+//
+// Right after a document side uploads, the server runs the SAME detectors it
+// later decides the verification with: a face on the photo printed on the
+// front (only when the workflow will compare the selfie with that photo), and
+// a readable barcode (only for documents whose details are read from one, such
+// as a Nigerian voter's card or driver's licence). Asking here turns a decline
+// that arrives by webhook into a retake that costs a few seconds.
+//
+// A NOTICE, NEVER A GATE. A detector can miss, so the applicant can always
+// continue with the photos they have. And the check itself must never block
+// the flow: a timeout, a network error or any answer we cannot read counts as
+// "no problem", exactly like a check that found nothing wrong.
+//
+// Pure apart from the runner's timer, so the rules are pinned by a test
+// without mounting React Native.
+
+import type {
+  DocumentCaptureCheckRequest,
+  DocumentCaptureCheckResponse,
+  DocumentCaptureSide,
+} from '../services/api-types';
+
+export type DocumentCaptureCheckResult = DocumentCaptureCheckResponse;
+
+export type CaptureProblemKind = 'no_face' | 'no_barcode';
+
+export interface CaptureProblem {
+  side: DocumentCaptureSide;
+  kind: CaptureProblemKind;
+}
+
+/** How long Continue waits for each side's check before treating it as fine. */
+export const CAPTURE_CHECK_TIMEOUT_MS = 8000;
+
+export const CAPTURE_CHECK_TITLE = 'Check your photos';
+
+export const CAPTURE_CHECK_CONTINUE_ANYWAY = 'Continue anyway';
+
+const SIDE_ORDER: readonly DocumentCaptureSide[] = ['front', 'back'];
+
+/**
+ * The problems worth a retake, front before back and, within a side, the face
+ * before the barcode. Only an explicit `false` is a problem: `true` is fine and
+ * `null` means the check did not apply or could not look.
+ */
+export function captureCheckProblems(results: readonly DocumentCaptureCheckResult[]): CaptureProblem[] {
+  const problems: CaptureProblem[] = [];
+  for (const side of SIDE_ORDER) {
+    const forSide = results.filter((r) => r.side === side);
+    if (forSide.some((r) => r.face === false)) problems.push({ side, kind: 'no_face' });
+    if (forSide.some((r) => r.barcode === false)) problems.push({ side, kind: 'no_barcode' });
+  }
+  return problems;
+}
+
+/** The sides a retake button is offered for, once each and in problem order. */
+export function captureRetakeSides(problems: readonly CaptureProblem[]): DocumentCaptureSide[] {
+  const sides: DocumentCaptureSide[] = [];
+  for (const p of problems) if (!sides.includes(p.side)) sides.push(p.side);
+  return sides;
+}
+
+export function captureProblemMessage(kind: CaptureProblemKind): string {
+  switch (kind) {
+    case 'no_face':
+      return "We couldn't see the face in the photo on the front of your ID. Retake it in good light, with the ID out of any plastic cover and no glare over the photo.";
+    case 'no_barcode':
+      return "We couldn't read the barcode on the back of your ID. Retake it with the ID out of any plastic cover, flat, filling the frame and with no glare over the barcode.";
+  }
+}
+
+/**
+ * The retake button's words. A side picked from the device (upload-only mode)
+ * was never taken with the camera, so it is replaced rather than retaken,
+ * matching the review screen's own wording.
+ */
+export function captureRetakeLabel(side: DocumentCaptureSide, uploadOnly: boolean): string {
+  const verb = uploadOnly ? 'Replace' : 'Retake';
+  return `${verb} ${side}`;
+}
+
+/**
+ * Check every uploaded side at once and return what came back in time.
+ *
+ * Never throws and never waits longer than `timeoutMs` per side: a side whose
+ * call rejects or runs out of time is simply left out, which reads as "no
+ * problem". The side each result describes is the side we ASKED about, and a
+ * field that is not a boolean is read as `null`, so a malformed answer cannot
+ * invent a problem.
+ */
+export async function runCaptureChecks(
+  requests: readonly DocumentCaptureCheckRequest[],
+  check: (body: DocumentCaptureCheckRequest, signal: AbortSignal) => Promise<DocumentCaptureCheckResponse>,
+  timeoutMs: number = CAPTURE_CHECK_TIMEOUT_MS,
+): Promise<DocumentCaptureCheckResult[]> {
+  const settled = await Promise.all(requests.map((body) => checkOneSide(body, check, timeoutMs)));
+  return settled.filter((r): r is DocumentCaptureCheckResult => r !== null);
+}
+
+async function checkOneSide(
+  body: DocumentCaptureCheckRequest,
+  check: (body: DocumentCaptureCheckRequest, signal: AbortSignal) => Promise<DocumentCaptureCheckResponse>,
+  timeoutMs: number,
+): Promise<DocumentCaptureCheckResult | null> {
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timedOut = new Promise<null>((resolve) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      resolve(null);
+    }, timeoutMs);
+  });
+  try {
+    const answered = check(body, controller.signal).then(
+      (res): DocumentCaptureCheckResult => ({
+        side: body.side,
+        face: readVerdict(res?.face),
+        barcode: readVerdict(res?.barcode),
+      }),
+    );
+    return await Promise.race([answered, timedOut]);
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function readVerdict(value: unknown): boolean | null {
+  return typeof value === 'boolean' ? value : null;
+}

package/src/lib/model-ready.ts

@@ -0,0 +1,82 @@
+import { useEffect, useRef, useState } from 'react';
+
+// ─── The on-device model readiness gate ───────────────────────────────────────
+//
+// 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
+// where a detector 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, and neither detector can
+// answer it itself. The face detector reports through `FaceResult`, where a
+// missing model and an empty frame are both `faceCount: 0`; the text recogniser
+// reports through `TextResult`, where both are an empty `lines` array. Gating on
+// the per-frame result would strand the user on "position your face", or aiming
+// at a passport that never reads, with the SDK unable to say why. That single
+// failure mode is the whole reason this gate exists.
+//
+// Shared by both because the rule and the reasoning are identical — a copy per
+// detector would be two places for one decision to drift.
+//
+// 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';
+
+/**
+ * How long to wait for a model before calling it unavailable. Generous on
+ * purpose: the text model is about 10 MB, the native side requests it as an
+ * urgent install, and a slow connection is the common case. The cost is that a
+ * phone with no Play Services at all waits the full minute before being told;
+ * the bundled build (`myazaKycBundledMlKit`) is the answer for those fleets.
+ */
+const MODEL_WAIT_MS = 60_000;
+/** Gap between readiness polls while the download is in flight. */
+const POLL_INTERVAL_MS = 500;
+
+/**
+ * Tracks whether an on-device model can run.
+ *
+ * Returns `'preparing'` while Play Services fetches it, `'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 the step this is normally already `'ready'` and no waiting screen
+ * is ever shown.
+ *
+ * @param isReady whether the model can run right now
+ * @param prime starts the download; called again here because the step can be
+ *   reached directly in a resumed flow, and priming is a no-op once ready
+ */
+export function useNativeModelReady(
+  isReady: () => boolean,
+  prime: () => void,
+): ModelReadyState {
+  const [state, setState] = useState<ModelReadyState>(() =>
+    isReady() ? 'ready' : 'preparing',
+  );
+  const startedAt = useRef(Date.now());
+  // Refs, not deps: a caller passing inline arrows would otherwise restart the
+  // poll, and the wait clock with it, on every render.
+  const fns = useRef({ isReady, prime });
+  fns.current = { isReady, prime };
+
+  useEffect(() => {
+    if (state !== 'preparing') return;
+
+    fns.current.prime();
+
+    const id = setInterval(() => {
+      if (fns.current.isReady()) {
+        setState('ready');
+      } else if (Date.now() - startedAt.current > MODEL_WAIT_MS) {
+        setState('unavailable');
+      }
+    }, POLL_INTERVAL_MS);
+
+    return () => clearInterval(id);
+  }, [state]);
+
+  return state;
+}

package/src/lib/prime-models.ts

@@ -0,0 +1,50 @@
+import { useEffect, useRef } from 'react';
+
+import { primeFaceModel } from '../liveness/visionCameraFaceDetector';
+import { primeLivenessAvatars } from '../liveness/avatarSource';
+import { primeTextModel } from '../mrz/textRecognizer';
+
+// ─── Warming the on-device work the flow is about to need ────────────────────
+//
+// Android fetches ML Kit's models through Play Services rather than bundling
+// them, and the gesture animations are served rather than shipped. All three
+// are wanted in front of a camera, which is the worst possible moment to start
+// a download — so they start the moment the flow opens instead, overlapping
+// the screens the user is already reading (consent, ID type, the document
+// step). Mirrors the web SDK's primeFaceMesh().
+//
+// Best-effort throughout: every step still gates on its own readiness, so a
+// failure here costs a head start and nothing else.
+//
+// SHARED BY BOTH ENTRY POINTS, and that is the whole point of the file. This
+// effect used to live inside the <MyazaKYC/> trigger component, so a consumer
+// using useMyazaKYC() — the hook the SDK's own example uses, and the one
+// documented for programmatic control — primed NOTHING. The face model was
+// first requested when the liveness step mounted, in front of a camera the
+// user was already looking at, and the gesture GIFs were fetched at the same
+// moment. On a device that had never downloaded the model (a fresh install,
+// the common case for a real applicant) that is a ~8 MB wait with the camera
+// already up. A warm device hides it completely, which is why it survived:
+// isModelReady() answers true on the first call and every path looks correct.
+//
+// The text model is the exception that proves it — useAutoCapture primes it at
+// the document step, so it kept a head start on both paths regardless.
+export function usePrimeModels(
+  wantOpen: boolean,
+  apiKey: string,
+  devUrl?: string,
+): void {
+  // Once per open sequence: priming is idempotent, but re-running it on every
+  // render would ask Play Services the same question a few times a second.
+  const primedRef = useRef(false);
+  useEffect(() => {
+    if (!wantOpen || primedRef.current) return;
+    primedRef.current = true;
+    primeFaceModel();
+    // The larger of the two, and wanted EARLIER in the flow than the face one
+    // (the document step comes before liveness), so it has the least time to
+    // arrive and the most to gain from the head start.
+    primeTextModel();
+    primeLivenessAvatars(apiKey, devUrl);
+  }, [wantOpen, apiKey, devUrl]);
+}

package/src/lib/resubmit.ts

@@ -17,6 +17,30 @@ export interface ResubmitConfig {
   steps: string[];
   /** Reviewer's note to the applicant. */
   message?: string | null;
+  /**
+   * The ID the verification being redone used, when the server CARRIES it.
+   *
+   * A redo keeps the verification id, so a reviewer who did not tick the ID
+   * has asked for nothing about it: the server keeps the original number,
+   * document photos, typed name and chip read, and says so by sending the
+   * idType here. Present only on an individual, single-ID send-back whose
+   * reviewer did not tick 'id-type'. Absent (an older server, a business redo,
+   * a multi-ID run, or the ID was ticked) keeps the old behaviour.
+   */
+  idType?: string | null;
+}
+
+/**
+ * The ID a redo keeps, or null when the applicant must name one again.
+ *
+ * Read defensively rather than trusted: an idType beside a plan that ticks the
+ * ID picker, or beside no plan at all, is not an instruction to skip it.
+ */
+export function keptIdType(resubmit: ResubmitConfig | undefined | null): string | null {
+  const asked = resubmit?.steps;
+  if (!asked?.length || asked.includes('id-type')) return null;
+  const idType = resubmit?.idType;
+  return typeof idType === 'string' && idType.trim().length > 0 ? idType : null;
 }
 
 /**
@@ -48,10 +72,12 @@ const EVIDENCE: KYCStep[] = ['id-input', 'document-capture', 'nfc'];
  * Steps a narrowed flow keeps regardless, because without them it cannot
  * produce a submission at all.
  *
- * A resubmission is a NEW verification on a FRESH session: nothing is carried
- * forward from the one being redone, so the applicant must still say which ID
- * this is and supply it. `POST /verify` requires an `idType`, and a number-only
- * ID requires the number with it.
+ * Unless the server carries the original ID (`keptIdType`), nothing is carried
+ * forward from the attempt being redone, so the applicant must still say which
+ * ID this is and supply it. `POST /verify` requires an `idType`, and a
+ * number-only ID requires the number with it. When the ID IS carried, the
+ * identity steps drop out: the SDK preselects the kept ID and the server fills
+ * in the number, the document photos and the chip read.
  *
  * So narrowing removes the things arranged AROUND the identity — liveness,
  * proof of address, the questionnaire, contact checks — and never the identity
@@ -93,9 +119,12 @@ export function applyResubmitSteps(
 
   const wanted = new Set<string>(asked);
   if (wantsEvidence) for (const step of EVIDENCE) wanted.add(step);
-  for (const step of order.includes('business-details') ? BUSINESS_REQUIRED : INDIVIDUAL_REQUIRED) {
-    wanted.add(step);
-  }
+  // A kept ID needs no picker and, unless the reviewer asked for the evidence,
+  // no evidence step either: the redo is only what was ticked. KYB never keeps
+  // an ID (the server never sends one for a business redo), so it stays as is.
+  const isBusiness = order.includes('business-details');
+  const required = isBusiness ? BUSINESS_REQUIRED : keptIdType(resubmit) ? [] : INDIVIDUAL_REQUIRED;
+  for (const step of required) wanted.add(step);
 
   const narrowed = order.filter((step) => wanted.has(step) || ALWAYS.includes(step));
 

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