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

package/src/screens/DocumentCaptureStep.tsx

@@ -1,7 +1,6 @@
 import React, { useCallback, useEffect, useRef, useState } from 'react';
 import { Image, Platform, Pressable, View } from 'react-native';
 import * as ImagePicker from 'expo-image-picker';
-import { useCameraDevice, useCameraPermission } from 'react-native-vision-camera';
 import { initialWindowMetrics } from 'react-native-safe-area-context';
 
 import { radius, spacing } from '../config/theme';
@@ -10,8 +9,8 @@ import { withRetry } from '../services/retry';
 import { mapToKycError, safeReportError } from '../services/errors';
 import { compressDocumentImage, compressVideo, cropCardRegion } from '../services/mediaCompress';
 import { MAX_VIDEO_BYTES } from '../config/captureSettings';
-import { KYCError } from '../types/verification';
 import type { DocumentCapturePhase } from '../store/kycStore';
+import { documentCaptureMethods } from '../config/documentCaptureMethods';
 import { useEffectiveCountry, useKyc, useKycConfig, useKycStore, useTheme } from '../components/runtime';
 import { MyazaText } from '../components/Typography';
 import { MyazaButton } from '../components/MyazaButton';
@@ -20,17 +19,34 @@ import { MyazaPulseLoader } from '../components/MyazaPulseLoader';
 import { CameraPhase } from './document/CameraPhase';
 import { CameraPermissionView, CameraUnavailableView, CameraPermissionPrimingView } from '../components/CameraPermissionView';
 import { ReadyPrimer } from '../components/ReadyPrimer';
+import { RequiredDocumentPill } from '../components/RequiredDocumentPill';
 import { READY_DOCUMENT } from '../components/readyPrimerContent';
 import { DocumentCropper } from '../components/DocumentCropper';
 import { DocumentReview } from '../components/DocumentReview';
 import { scanMrzFromImage } from '../mrz/textRecognizer';
 import { Icon } from '../components/Icon';
+import { useDocumentCamera, type DocumentCamera } from './document/useDocumentCamera';
+import { UploadPhase, documentUploadMeta } from './document/UploadPhase';
+import { CaptureCheckNotice } from './document/CaptureCheckNotice';
+import { isBusinessFlow } from '../config/business';
+import { captureCheckProblems, runCaptureChecks, type CaptureProblem } from '../lib/documentCaptureCheck';
+import type { DocumentCaptureCheckRequest, DocumentCaptureSide } from '../services/api';
 
 // Document capture — the RN mirror of the Flutter/web DocumentCaptureStep.
 // Phases: front → front-preview → back → review (two-sided); front → review
 // (one-sided). Manual shutter (VisionCamera) or gallery upload; each side is
 // compressed (OCR-conservative) then eagerly uploaded on Continue with retry.
 //
+// Which of the two ways in is offered comes from `documentCaptureMethods`
+// (allowDocumentScan / allowDocumentUpload). With scanning off, each side is
+// UploadPhase instead of the camera, and the camera's hooks are never mounted.
+//
+// Before moving on, each uploaded side goes past the server's capture check
+// (lib/documentCaptureCheck): no face on the printed photo, or a barcode that
+// will not read, turns the review footer into a retake notice. A notice, never
+// a gate: "Continue anyway" always advances, and a failed or slow check reads
+// as no problem.
+//
 // The per-phase title/description live in the SHEET HEADER (KycFlow reads the
 // synced `documentCapturePhase` from the store and calls `documentCaptureMeta`),
 // not in the body — mirroring Flutter's header `docReviewPhase` sync.
@@ -39,7 +55,10 @@ import { Icon } from '../components/Icon';
 export function documentCaptureMeta(
   phase: DocumentCapturePhase,
   documentLabel: string,
+  mode: 'scan' | 'upload' = 'scan',
 ): { title: string; description: string } {
+  // An upload-only workflow asks for a photo, so it cannot say "scan".
+  if (mode === 'upload') return documentUploadMeta(phase, documentLabel);
   // Copy matches the Flutter SDK's document-capture header meta exactly.
   switch (phase) {
     case 'front':
@@ -77,6 +96,33 @@ function cameraBottomInset(): number {
 }
 
 export function DocumentCaptureStep(): React.ReactElement {
+  const config = useKycConfig();
+  const methods = documentCaptureMethods(config);
+  // The camera's hooks live in their own wrapper so an upload-only workflow
+  // (`allowDocumentScan: false`) never mounts them: no permission read, no
+  // device enumeration, no prompt. The element types stay fixed for a given
+  // config, so the capture state below keeps the step's whole lifetime.
+  return methods.scan ? (
+    <ScanningDocumentCapture allowUpload={methods.upload} />
+  ) : (
+    <DocumentCapture camera={null} allowUpload />
+  );
+}
+
+function ScanningDocumentCapture({ allowUpload }: { allowUpload: boolean }): React.ReactElement {
+  const config = useKycConfig();
+  const camera = useDocumentCamera(config.onError);
+  return <DocumentCapture camera={camera} allowUpload={allowUpload} />;
+}
+
+function DocumentCapture({
+  camera,
+  allowUpload,
+}: {
+  /** Null in upload-only mode, where each side is a photo from the device. */
+  camera: DocumentCamera | null;
+  allowUpload: boolean;
+}): React.ReactElement {
   const { colors } = useTheme();
   const toast = useToast();
   const config = useKycConfig();
@@ -90,12 +136,23 @@ export function DocumentCaptureStep(): React.ReactElement {
   const setImmersiveCapture = useKyc((s) => s.setImmersiveCapture);
   const store = useKycStore();
   const nextStep = useKyc((s) => s.nextStep);
+  const sessionId = useKyc((s) => s.sessionId);
 
-  const allowUpload = config.allowDocumentUpload !== false;
   const documentLabel =
     (selectedIdType && Object.values(ID_TYPES).flat().find((t) => t.key === selectedIdType)?.label) || 'Document';
   const scanSides = selectedIdType ? getScanSides(selectedIdType) : 'front_only';
   const isTwoSided = scanSides === 'front_and_back';
+
+  // "Required: <document>" — shown on the screens either side of the camera,
+  // matching the web SDK's badge and Flutter's _RequiredPill. Not over a live
+  // viewfinder: that screen is full-bleed and owns the display.
+  const requiredPill = (side: 'front' | 'back' | null) => (
+    <RequiredDocumentPill
+      idTypeLabel={documentLabel}
+      sideBadge={isTwoSided && side ? (side === 'back' ? 'Back Side' : 'Front Side') : null}
+      stepLabel={isTwoSided && side ? (side === 'back' ? 'Step 2 of 2' : 'Step 1 of 2') : null}
+    />
+  );
   const guideAspect = documentGuideAspect(selectedIdType);
 
   const [phase, setPhase] = useState<DocumentCapturePhase>('front');
@@ -106,6 +163,10 @@ export function DocumentCaptureStep(): React.ReactElement {
   const [retryInfo, setRetryInfo] = useState<{ attempt: number; total: number } | null>(null);
   const [uploadError, setUploadError] = useState<string | null>(null);
   const [cropUri, setCropUri] = useState<string | null>(null); // gallery photo awaiting crop
+  // What the server's capture check found wrong with the uploaded sides. Set
+  // only when there is something to retake; any new capture clears it, so the
+  // next Continue uploads and checks again.
+  const [captureProblems, setCaptureProblems] = useState<CaptureProblem[] | null>(null);
   // Best-effort document videos recorded alongside each side's still (uploaded as
   // document_front_video / document_back_video). Refs — they don't drive the UI.
   const frontVideoRef = useRef<string | null>(null);
@@ -117,42 +178,14 @@ export function DocumentCaptureStep(): React.ReactElement {
   }, [phase, setDocumentCapturePhase]);
 
 
-  // ── Camera permission ──────────────────────────────────────────────────────
-  // `perm` is derived from the ASYNC requestPermission result, not synchronously
-  // from `hasPermission` — otherwise the brief window while the OS prompt is open
-  // (hasPermission still false) would read as "denied" and fire onError early.
-  // 'priming' shows the "Allow camera access" screen BEFORE the OS prompt
-  // (Stripe-style); the prompt only fires (→ 'requesting') once the user taps
-  // "Grant access".
-  const { hasPermission, requestPermission } = useCameraPermission();
-  const [perm, setPerm] = useState<'priming' | 'requesting' | 'granted' | 'denied'>(
-    hasPermission ? 'granted' : 'priming',
-  );
-  const permReportedRef = useRef(false);
-
-  // ── Camera availability ─────────────────────────────────────────────────────
-  // Even with permission granted, there may be no usable back camera (the iOS/
-  // Android simulator has none; a real device may fail to init). Give the device
-  // list a moment to resolve, then surface a proper "Camera not available" error
-  // with an upload fallback — on every iOS version (glass or not) and Android.
-  // Device enumeration does NOT need camera permission (iOS AVCaptureDevice /
-  // Android CameraManager list hardware regardless), so `!device` reliably means
-  // "no back-camera hardware" — true on every simulator. That's a different state
-  // from "permission denied": no hardware → nothing to grant.
-  const device = useCameraDevice('back');
-  const [cameraGrace, setCameraGrace] = useState(false);
-  useEffect(() => {
-    const t = setTimeout(() => setCameraGrace(true), 1500);
-    return () => clearTimeout(t);
-  }, []);
-  // No camera hardware at all → "Camera not available" (regardless of what the
-  // permission API says — on a camera-less sim it may even report denied).
-  const cameraUnavailable = cameraGrace && !device;
+  // ── Camera permission + availability ───────────────────────────────────────
+  // Owned by `useDocumentCamera` (called by ScanningDocumentCapture), so
+  // `camera` is null in upload-only mode and every camera gate below is skipped.
+  //
   // Gate the camera path on the user acknowledging the primer. Shown once for
   // the step, not per side — repeating it before the back of a card would be
   // noise, not a warning.
   const [ready, setReady] = useState(false);
-  const showPrimer = perm === 'priming' && !!device;
   // Tell the shell when the full-bleed camera is on screen. Scoped tightly:
   // only the live preview earns the whole display — the ready primer, the
   // permission screens, the previews and the review all keep their chrome.
@@ -161,56 +194,21 @@ export function DocumentCaptureStep(): React.ReactElement {
   // cleanup here would fire during any remount and fight the effect that had
   // just raised it.
   const cameraLive =
-    (phase === 'front' || phase === 'back') && ready && perm === 'granted' && !!device;
+    (phase === 'front' || phase === 'back') &&
+    ready &&
+    !!camera &&
+    camera.perm === 'granted' &&
+    camera.hasDevice;
   useEffect(() => {
     setImmersiveCapture(cameraLive);
   }, [cameraLive, setImmersiveCapture]);
 
-  // Reflect an externally-granted permission.
-  useEffect(() => {
-    if (hasPermission) setPerm('granted');
-  }, [hasPermission]);
-
-  // Fire the real OS prompt only after the user taps "Grant access" (or retry).
-  useEffect(() => {
-    if (perm !== 'requesting') return;
-    let cancelled = false;
-    void (async () => {
-      const granted = await requestPermission();
-      if (!cancelled) setPerm(granted ? 'granted' : 'denied');
-    })();
-    return () => {
-      cancelled = true;
-    };
-  }, [perm, requestPermission]);
-
-  // A *genuine* permission denial requires a camera to exist but be blocked. On a
-  // camera-less sim the OS may report denied — that's "not available", not a
-  // permission problem, so don't treat it as denied or report onError there.
-  const permissionDenied = perm === 'denied' && !!device;
-  useEffect(() => {
-    if (permissionDenied && !permReportedRef.current) {
-      permReportedRef.current = true;
-      safeReportError(
-        config.onError,
-        new KYCError(
-          'camera_permission_denied',
-          'Camera access is required to photograph your document. Allow camera access or upload a photo instead.',
-        ),
-      );
-    }
-    if (!permissionDenied) permReportedRef.current = false;
-  }, [permissionDenied, config.onError]);
-
-  const retryPermission = useCallback(() => {
-    setPerm('requesting');
-  }, []);
-
   // ── Capture → compress → store for the current side ────────────────────────
   const storeCapture = useCallback(
     async (rawUri: string) => {
       setBusy(true);
       setUploadError(null);
+      setCaptureProblems(null);
       try {
         const compressed = await compressDocumentImage(rawUri);
         // Read the MRZ off the FRONT while we have it. It is the key that
@@ -317,25 +315,34 @@ export function DocumentCaptureStep(): React.ReactElement {
     [api, setMediaId],
   );
 
-  // ── Upload both sides, then advance (KycFlow routes to liveness/submitted) ──
+  // ── Advance (KycFlow routes to liveness/submitted, or the next multi-ID ID) ─
+  // Shared by a clean Continue and "Continue anyway". The media ids are already
+  // in the store, so moving on never uploads or checks a second time.
+  const advance = useCallback(() => {
+    setCaptureProblems(null);
+    nextStep();
+  }, [nextStep]);
+
+  // ── Upload both sides, check they will read, then advance ──────────────────
   const handleContinue = useCallback(async () => {
     if (!frontUri) return;
     setUploading(true);
     setUploadError(null);
+    setCaptureProblems(null);
     setRetryInfo(null);
     const onRetry = (attempt: number, total: number) => setRetryInfo({ attempt, total });
+    const uploaded: { side: DocumentCaptureSide; mediaId: string }[] = [];
     try {
       const frontId = await withRetry(() => api.upload({ uri: frontUri, type: 'image/jpeg' }, 'document_front'), { onRetry });
       setMediaId('documentFront', frontId);
+      uploaded.push({ side: 'front', mediaId: frontId });
       await uploadDocVideo(frontVideoRef.current, 'document_front_video', 'documentFrontVideo');
       if (isTwoSided && backUri) {
         const backId = await withRetry(() => api.upload({ uri: backUri, type: 'image/jpeg' }, 'document_back'), { onRetry });
         setMediaId('documentBack', backId);
+        uploaded.push({ side: 'back', mediaId: backId });
         await uploadDocVideo(backVideoRef.current, 'document_back_video', 'documentBackVideo');
       }
-      setRetryInfo(null);
-      setUploading(false);
-      nextStep();
     } catch (err) {
       setRetryInfo(null);
       setUploading(false);
@@ -343,11 +350,51 @@ export function DocumentCaptureStep(): React.ReactElement {
       setUploadError(kycError.message);
       toast.show({ variant: 'error', title: 'Upload failed', message: kycError.message });
       safeReportError(config.onError, kycError);
+      return;
+    }
+    setRetryInfo(null);
+
+    // The same workflow the submission will carry: a KYB flow's document is
+    // the applicant's own leg, which submits under the mapped applicant
+    // workflow (store/submitApplicant). Best-effort throughout:
+    // runCaptureChecks never throws and gives up on a side after 8s.
+    const workflowId = isBusinessFlow(config) ? config.applicantWorkflowId : config.workflowId;
+    const requests: DocumentCaptureCheckRequest[] = selectedIdType
+      ? uploaded.map(({ side, mediaId }) => ({
+          mediaId,
+          side,
+          country,
+          idType: selectedIdType,
+          ...(workflowId ? { workflowId } : {}),
+          ...(sessionId ? { sessionId } : {}),
+        }))
+      : [];
+    const results = await runCaptureChecks(requests, (body, signal) => api.checkDocumentCapture(body, signal));
+    const problems = captureCheckProblems(results);
+    setUploading(false);
+    if (problems.length > 0) {
+      setCaptureProblems(problems);
+      return;
     }
-  }, [frontUri, backUri, isTwoSided, api, setMediaId, nextStep, config.onError, toast, uploadDocVideo]);
+    advance();
+  }, [
+    frontUri,
+    backUri,
+    isTwoSided,
+    api,
+    setMediaId,
+    config,
+    toast,
+    uploadDocVideo,
+    selectedIdType,
+    country,
+    sessionId,
+    advance,
+  ]);
 
-  const retake = (side: 'front' | 'back') => {
+  const retake = (side: DocumentCaptureSide) => {
     setUploadError(null);
+    setCaptureProblems(null);
     if (side === 'back') {
       setBackUri(null);
       backVideoRef.current = null;
@@ -377,7 +424,25 @@ export function DocumentCaptureStep(): React.ReactElement {
   // states keep the title/description in the header, and always offer the gallery
   // escape hatch). These never overlap: one needs a device, the other needs none.
   if (phase === 'front' || phase === 'back') {
-    if (cameraUnavailable) {
+    if (!camera) {
+      // Upload-only: no ready primer (it describes a camera scan), no
+      // permission screens, no viewfinder. The pick runs the same cropper and
+      // store path a gallery photo takes from the camera screen.
+      return (
+        <>
+          {cropper}
+          <View style={{ marginBottom: spacing.md }}>{requiredPill(phase === 'back' ? 'back' : 'front')}</View>
+          <UploadPhase
+            isBack={phase === 'back'}
+            documentLabel={documentLabel}
+            isTwoSided={isTwoSided}
+            busy={busy}
+            onUpload={pickFromGallery}
+          />
+        </>
+      );
+    }
+    if (camera.cameraUnavailable) {
       // No back-camera hardware (e.g. a simulator) — permission is moot here.
       return (
         <>
@@ -393,28 +458,29 @@ export function DocumentCaptureStep(): React.ReactElement {
       return (
         <>
           {cropper}
+          <View style={{ marginBottom: spacing.md }}>{requiredPill(phase === 'back' ? 'back' : 'front')}</View>
           <ReadyPrimer content={READY_DOCUMENT} onReady={() => setReady(true)} />
         </>
       );
     }
-    if (showPrimer) {
+    if (camera.showPrimer) {
       // Primer before the OS prompt — camera not started yet.
       return (
         <>
           {cropper}
           <CameraPermissionPrimingView
             message="When prompted, allow camera access to photograph your document."
-            onGrant={() => setPerm('requesting')}
+            onGrant={camera.requestAccess}
           />
         </>
       );
     }
-    if (permissionDenied) {
+    if (camera.permissionDenied) {
       // A real camera exists but the OS blocked access.
       return (
         <>
           {cropper}
-          <CameraPermissionView onRetry={retryPermission} onUpload={pickFromGallery} />
+          <CameraPermissionView onRetry={camera.requestAccess} onUpload={pickFromGallery} />
         </>
       );
     }
@@ -426,7 +492,7 @@ export function DocumentCaptureStep(): React.ReactElement {
         <CameraPhase
           isBack={isBack}
           cameraLive={cameraLive}
-          active={perm === 'granted'}
+          active={camera.perm === 'granted'}
           documentLabel={documentLabel}
           guideAspect={guideAspect}
           isTwoSided={isTwoSided}
@@ -453,13 +519,19 @@ export function DocumentCaptureStep(): React.ReactElement {
   if (phase === 'front-preview') {
     return (
       <View>
+        <View style={{ marginBottom: spacing.md }}>{requiredPill('front')}</View>
         <DocImage uri={frontUri!} />
         <View style={{ flexDirection: 'row', gap: spacing.md, marginTop: spacing.md }}>
           <View style={{ flex: 1 }}>
-            <MyazaButton label="Retake" variant="outline" leadingIcon="refresh" onPress={() => retake('front')} />
+            <MyazaButton
+              label={camera ? 'Retake' : 'Replace'}
+              variant="outline"
+              leadingIcon="refresh"
+              onPress={() => retake('front')}
+            />
           </View>
           <View style={{ flex: 1 }}>
-            <MyazaButton label="Next — Scan Back" onPress={() => setPhase('back')} />
+            <MyazaButton label={camera ? 'Next: Scan Back' : 'Next: Add Back'} onPress={() => setPhase('back')} />
           </View>
         </View>
       </View>
@@ -468,7 +540,10 @@ export function DocumentCaptureStep(): React.ReactElement {
 
   // ── Review ─────────────────────────────────────────────────────────────────
   return (
-    <DocumentReview
+    <>
+      <View style={{ marginBottom: spacing.md }}>{requiredPill(null)}</View>
+      <DocumentReview
+      mode={camera ? 'scan' : 'upload'}
       frontUri={frontUri!}
       backUri={isTwoSided ? backUri : null}
       aspect={guideAspect}
@@ -494,18 +569,27 @@ export function DocumentCaptureStep(): React.ReactElement {
         <>
           {retryInfo && uploading ? (
             <MyazaText variant="bodySmall" color={colors.warning} style={{ textAlign: 'center', marginBottom: spacing.sm }}>
-              {`Upload failed — retrying (${retryInfo.attempt}/${retryInfo.total})…`}
+              {`Upload failed. Retrying (${retryInfo.attempt}/${retryInfo.total})…`}
             </MyazaText>
           ) : null}
           {uploadError ? (
             // The error message is shown as a top toast; keep a retry action here.
             <MyazaButton label="Try Again" onPress={handleContinue} loading={uploading} />
+          ) : captureProblems ? (
+            // A side will not read: retake it, or carry on with what was sent.
+            <CaptureCheckNotice
+              problems={captureProblems}
+              uploadOnly={!camera}
+              onRetake={retake}
+              onContinueAnyway={advance}
+            />
           ) : (
             <MyazaButton label="Continue" onPress={handleContinue} loading={uploading} />
           )}
         </>
       }
-    />
+      />
+    </>
   );
 }
 

package/src/screens/LivenessAvatar.tsx

@@ -1,21 +1,22 @@
 import React, { useEffect, useRef, useState } from 'react';
 import { Animated, Easing, Image } from 'react-native';
 
-import { useTheme } from '../components/runtime';
+import { useTheme, useKycConfig } from '../components/runtime';
 import { Icon } from '../components/Icon';
+import { livenessAvatarUrl } from '../liveness/avatarSource';
 import type { LivenessChallenge } from '../liveness/types';
 
 // Animated GIF avatar demonstrating the requested gesture — the RN mirror of the
-// web/Flutter `LivenessAvatar`. Shows the same Nod/Turn/Blink/Smile GIFs in a
-// circular badge (primary-tinted, like Flutter), sliding up + fading in when the
-// challenge changes. RN's <Image> animates GIFs natively.
-
-const GIFS: Record<LivenessChallenge, number> = {
-  nod: require('../assets/liveness/Nod.gif'),
-  turn: require('../assets/liveness/Turn.gif'),
-  blink: require('../assets/liveness/Blink.gif'),
-  smile: require('../assets/liveness/Smile.gif'),
-};
+// web/Flutter `LivenessAvatar`. Shows the same Nod/Turn/Blink/Smile animations in
+// a circular badge (primary-tinted, like Flutter), sliding up + fading in when
+// the challenge changes. RN's <Image> animates GIFs natively.
+//
+// The animations are FETCHED (see liveness/avatarSource) rather than bundled.
+// They were 5.5 MB of this package, in every integrator's app, for a badge the
+// liveness step shows for a few seconds. The flow prefetches all four at open,
+// so by the time this renders the file is normally already on the device; when
+// it is not, `broken` renders the gesture icon exactly as it always did for a
+// failed decode.
 
 /** The badge on a tall phone; the step hands a smaller size down on a short one
  *  (lib/livenessLayout), so the gesture stays on screen beside the circle. */
@@ -33,9 +34,13 @@ export function LivenessAvatar({
 }): React.ReactElement {
   const SIZE = size;
   const { colors } = useTheme();
+  const { apiKey, devUrl } = useKycConfig();
   const [displayed, setDisplayed] = useState<LivenessChallenge>(challenge);
   const [broken, setBroken] = useState(false);
   const anim = useRef(new Animated.Value(1)).current;
+  // `displayed`, not `challenge`: the badge cross-fades, so the image must keep
+  // showing the outgoing gesture until the transition swaps it.
+  const uri = livenessAvatarUrl(displayed, apiKey, devUrl);
 
   // Slide-up + fade transition when the challenge changes (mirrors Flutter's
   // AnimatedSwitcher: Offset(0, 0.4) → 0, easeOutCubic, ~350ms).
@@ -66,11 +71,11 @@ export function LivenessAvatar({
         transform: [{ translateY: anim.interpolate({ inputRange: [0, 1], outputRange: [SIZE * 0.4, 0] }) }],
       }}
     >
-      {broken ? (
+      {broken || uri == null ? (
         <Icon name="scan-face" size={iconSize} color={colors.primary} />
       ) : (
         <Image
-          source={GIFS[displayed]}
+          source={{ uri }}
           style={{ width: '100%', height: '100%' }}
           resizeMode="cover"
           onError={() => setBroken(true)}

package/src/screens/LivenessStep.tsx

@@ -14,6 +14,7 @@ import { radius, spacing } from '../config/theme';
 import { withRetry } from '../services/retry';
 import { mapToKycError, safeReportError } from '../services/errors';
 import { compressSelfieImage, compressVideo } from '../services/mediaCompress';
+import { isSelfieBlurry, measureSelfieSharpness } from '../lib/selfie-sharpness';
 import { KYCError } from '../types/verification';
 import { useStore } from 'zustand';
 import { useKyc, useKycConfig, useKycStore, useTheme } from '../components/runtime';
@@ -184,6 +185,11 @@ export function LivenessStep(): React.ReactElement {
     uploadSelfieAndVideo,
   } = upload;
 
+  // The still the review should flag as soft, held BY URI, so a measurement
+  // that lands after a retake can never flag the next photo. A notice only,
+  // never a gate: see lib/selfie-sharpness.
+  const [softSelfieUri, setSoftSelfieUri] = useState<string | null>(null);
+
   // A stored selfie with no uploaded mediaId is an interrupted upload (failed,
   // or the user left mid-flight): resume it once on mount. Idempotent — with a
   // mediaId there is nothing to do.
@@ -255,6 +261,11 @@ export function LivenessStep(): React.ReactElement {
       const raw = `file://${file.filePath}`;
       const compressed = await compressSelfieImage(raw).catch(() => raw);
       setSelfieUri(compressed);
+      // Measured on the still the applicant is about to see. It never holds
+      // the review back: the notice appears when the answer does.
+      void measureSelfieSharpness(compressed).then((score) => {
+        if (isSelfieBlurry(score)) setSoftSelfieUri(compressed);
+      });
       // Recorded at capture, not at submit: by then the liveness hook is gone
       // and its flash result with it.
       setCaptureIntegrity({
@@ -448,6 +459,7 @@ export function LivenessStep(): React.ReactElement {
     return (
       <LivenessComplete
         selfieUri={selfieUri}
+        soft={!!selfieUri && softSelfieUri === selfieUri}
         upload={upload}
         onRetake={() => {
           setSelfieUri(null);
@@ -492,6 +504,31 @@ export function LivenessStep(): React.ReactElement {
   if (permissionDenied) {
     return <CameraPermissionView onRetry={() => setPerm('requesting')} />;
   }
+  // The model is still arriving. Measured at ~9s on a freshly installed device
+  // over fast wifi, and the connections this SDK actually serves are slower, so
+  // the head start from opening the flow does not always win the race.
+  //
+  // Without this the camera opened anyway and `detectFace` returned
+  // `faceCount: 0` for every frame, which is indistinguishable from "no face in
+  // shot" — so the user was told to position a face that was never going to
+  // register, for as long as the download took. That is the exact failure the
+  // readiness gate exists to prevent, and MrzScanView already answers it this
+  // way; only this screen was missing it.
+  //
+  // Deliberately AFTER the primer and the permission prompt: those need no
+  // model, so letting them run first keeps the download overlapping something
+  // the user is already reading. Only the camera itself waits.
+  if (modelState === 'preparing') {
+    return (
+      <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center', padding: spacing.lg }}>
+        <MyazaPulseLoader size={24} />
+        <View style={{ height: spacing.md }} />
+        <MyazaText variant="bodyMedium" style={{ textAlign: 'center' }}>
+          Getting face verification ready. This only happens once.
+        </MyazaText>
+      </View>
+    );
+  }
 
   if (liveness.phase === 'failed') {
     return <LivenessFailed reason={liveness.failureReason} onRetry={liveness.reset} />;

package/src/screens/MrzScanView.tsx

@@ -15,6 +15,7 @@ import { MyazaButton } from '../components/MyazaButton';
 import { MyazaPulseLoader } from '../components/MyazaPulseLoader';
 import { extractMrz } from '../mrz/extract';
 import { recognizeMrzLines, MRZ_BAND_FRACTION } from '../mrz/textRecognizer';
+import { useTextModelReady } from '../mrz/useTextModelReady';
 import type { MrzScan } from '../mrz/parse';
 
 // ---------------------------------------------------------------------------
@@ -45,6 +46,11 @@ export function MrzScanView({
   const device = useCameraDevice('back');
   const { hasPermission, requestPermission } = useCameraPermission();
   const [denied, setDenied] = useState(false);
+  // Android fetches the text model through Play Services rather than bundling
+  // it. A recogniser that cannot run reports exactly what a blank page reports
+  // — no lines — so without this the user would aim at their passport while a
+  // scanner that can never read sat there pulsing. iOS is always ready.
+  const modelState = useTextModelReady();
 
   // A ref, not state: the worklet callback lands on the JS thread after the
   // frame that found the MRZ, and a stale render would let a second frame
@@ -113,6 +119,33 @@ export function MrzScanView({
     );
   }
 
+  // Worded like the camera-denied case above, and for the same reason: the chip
+  // is optional, so the honest thing is to say the code cannot be read and let
+  // the user carry on rather than leave them waiting on something that will not
+  // arrive.
+  if (modelState === 'unavailable') {
+    return (
+      <Centered>
+        <MyazaText variant="bodyMedium" style={{ textAlign: 'center' }}>
+          The text reader could not be set up on this device, so the printed code
+          cannot be read. You can still continue without the chip.
+        </MyazaText>
+      </Centered>
+    );
+  }
+
+  if (modelState === 'preparing') {
+    return (
+      <Centered>
+        <MyazaPulseLoader size={24} />
+        <View style={{ height: spacing.md }} />
+        <MyazaText variant="bodyMedium" style={{ textAlign: 'center' }}>
+          Getting the text reader ready. This only happens once.
+        </MyazaText>
+      </Centered>
+    );
+  }
+
   return (
     <View
       style={{