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

package/src/screens/document/CaptureCheckNotice.tsx

@@ -0,0 +1,77 @@
+import React from 'react';
+import { View } from 'react-native';
+
+import { spacing } from '../../config/theme';
+import { MyazaAlert } from '../../components/MyazaAlert';
+import { MyazaButton } from '../../components/MyazaButton';
+import { documentReviewCopy } from '../../components/documentReviewCopy';
+import {
+  CAPTURE_CHECK_CONTINUE_ANYWAY,
+  CAPTURE_CHECK_TITLE,
+  captureProblemMessage,
+  captureRetakeLabel,
+  captureRetakeSides,
+  type CaptureProblem,
+} from '../../lib/documentCaptureCheck';
+import type { DocumentCaptureSide } from '../../services/api-types';
+
+// ─── The review footer when a document photo will not read ───────────────────
+//
+// Shown in place of Continue after the server's capture check found no face on
+// the printed photo or no readable barcode (lib/documentCaptureCheck). The
+// words come from that module so they stay in lockstep with the web and
+// Flutter SDKs.
+//
+// A notice, never a gate: the detectors can miss, so "Continue anyway" is
+// always offered and moves on with the photos already uploaded. The first
+// retake is the primary action because a retake is the likelier fix.
+
+export function CaptureCheckNotice({
+  problems,
+  uploadOnly,
+  onRetake,
+  onContinueAnyway,
+}: {
+  problems: readonly CaptureProblem[];
+  /** The sides were picked from the device, so they are replaced, not retaken. */
+  uploadOnly: boolean;
+  onRetake: (side: DocumentCaptureSide) => void;
+  onContinueAnyway: () => void;
+}): React.ReactElement {
+  // Once per kind: two sides with the same problem need one sentence, not two.
+  const messages = [...new Set(problems.map((p) => captureProblemMessage(p.kind)))];
+  const sides = captureRetakeSides(problems);
+  const copy = documentReviewCopy(uploadOnly ? 'upload' : 'scan', true);
+
+  return (
+    <View style={{ gap: spacing.sm }}>
+      {/* Grouped and announced: the notice replaces the button the applicant
+          just pressed, so a screen reader has to say why nothing moved on. */}
+      <View
+        accessible
+        accessibilityRole="alert"
+        accessibilityLiveRegion="polite"
+        accessibilityLabel={`${CAPTURE_CHECK_TITLE}. ${messages.join(' ')}`}
+      >
+        <MyazaAlert variant="warning" title={CAPTURE_CHECK_TITLE} message={messages.join('\n\n')} />
+      </View>
+      {sides.map((side, i) => (
+        <MyazaButton
+          key={side}
+          label={captureRetakeLabel(side, uploadOnly)}
+          variant={i === 0 ? 'primary' : 'outline'}
+          leadingIcon="refresh"
+          accessibilityLabel={copy.redoAccessibility(side === 'front' ? 'Front' : 'Back')}
+          onPress={() => onRetake(side)}
+        />
+      ))}
+      <MyazaButton
+        label={CAPTURE_CHECK_CONTINUE_ANYWAY}
+        variant="outline"
+        accessibilityLabel={CAPTURE_CHECK_CONTINUE_ANYWAY}
+        accessibilityHint="Carries on with these photos as they are"
+        onPress={onContinueAnyway}
+      />
+    </View>
+  );
+}

package/src/screens/document/UploadPhase.tsx

@@ -0,0 +1,177 @@
+import React from 'react';
+import { ActivityIndicator, Pressable, View } from 'react-native';
+
+import { radius, spacing } from '../../config/theme';
+import { useTheme } from '../../components/runtime';
+import { MyazaText } from '../../components/Typography';
+import { Icon, type IconName } from '../../components/Icon';
+import { DashedBorder } from '../../components/DashedBorder';
+import type { DocumentCapturePhase } from '../../store/state';
+import { RequiredPill } from './RequiredPill';
+
+// ─── Document capture without the camera ──────────────────────────────────────
+//
+// One side of the document when the workflow switches scanning off
+// (`allowDocumentScan: false`): a photo chosen from the device, never a camera
+// shot. It renders in place of the camera gates, and nothing here touches
+// VisionCamera, so an upload-only flow never asks for camera access and never
+// records a capture video.
+//
+// Only the ASK differs. What happens after the pick is the step's own and shared
+// with the camera path: the interactive cropper, the compress, the MRZ read off
+// the front, the front preview and the review.
+
+/** The sheet header for an upload-only capture phase (see documentCaptureMeta). */
+export function documentUploadMeta(
+  phase: DocumentCapturePhase,
+  documentLabel: string,
+): { title: string; description: string } {
+  switch (phase) {
+    case 'front':
+      return {
+        title: `Upload Your ${documentLabel}`,
+        description: `Choose a clear photo of your ${documentLabel} from your device.`,
+      };
+    case 'front-preview':
+      return {
+        title: 'Front Side Added',
+        description: 'Looks good? Tap Next to add a photo of the back.',
+      };
+    case 'back':
+      return {
+        title: 'Upload Back Side',
+        description: `Now choose a photo of the back of your ${documentLabel}.`,
+      };
+    case 'review':
+    default:
+      return {
+        title: `Review Your ${documentLabel}`,
+        description: 'Tap Continue to upload and submit your document.',
+      };
+  }
+}
+
+const TIPS: ReadonlyArray<{ icon: IconName; label: string }> = [
+  { icon: 'id-card', label: 'The whole document in view, all four corners' },
+  { icon: 'sun', label: 'Sharp and evenly lit, with no glare' },
+];
+
+export interface UploadPhaseProps {
+  isBack: boolean;
+  documentLabel: string;
+  isTwoSided: boolean;
+  /** A picked photo is being cropped and compressed. */
+  busy: boolean;
+  onUpload: () => void;
+}
+
+export function UploadPhase(p: UploadPhaseProps): React.ReactElement {
+  const { colors } = useTheme();
+  const subject = !p.isTwoSided ? `your ${p.documentLabel}` : p.isBack ? 'the back' : 'the front';
+  const ask = `Add a photo of ${subject}`;
+  const choose = () => {
+    if (!p.busy) p.onUpload();
+  };
+
+  return (
+    <View>
+      <RequiredPill
+        documentLabel={p.documentLabel}
+        sideBadge={p.isTwoSided ? (p.isBack ? 'Back Side' : 'Front Side') : undefined}
+        stepLabel={p.isTwoSided ? (p.isBack ? 'Step 2 of 2' : 'Step 1 of 2') : undefined}
+      />
+      {p.isBack ? (
+        <View style={{ flexDirection: 'row', alignItems: 'center', marginTop: spacing.sm, marginBottom: spacing.xs }}>
+          <Icon name="credit-card" size={14} color={colors.primary} />
+          <View style={{ width: 4 }} />
+          <MyazaText variant="bodySmall" color={colors.primary} style={{ fontWeight: '500' }}>
+            Turn the card over and add a photo of the other side
+          </MyazaText>
+        </View>
+      ) : null}
+      <View style={{ height: spacing.md }} />
+
+      {/* The whole card is the target and there is no button beside it: on a
+          screen whose only job is to open the photo picker, the card is where
+          the thumb goes. A press deepens the fill and solidifies the border;
+          the primary line at the bottom says what a tap does. */}
+      <Pressable
+        testID={`kyc.document.upload.${p.isBack ? 'back' : 'front'}`}
+        onPress={choose}
+        disabled={p.busy}
+        accessibilityRole="button"
+        accessibilityLabel={p.busy ? 'Preparing your photo' : ask}
+        accessibilityHint="Opens your photos"
+        accessibilityState={{ busy: p.busy, disabled: p.busy }}
+        style={({ pressed }) => ({
+          alignItems: 'center',
+          paddingVertical: spacing.xl,
+          paddingHorizontal: spacing.lg,
+          borderRadius: radius.md,
+          backgroundColor: pressed ? `${colors.primary}1A` : `${colors.primary}0D`,
+          transform: [{ scale: pressed ? 0.99 : 1 }],
+        })}
+      >
+        {({ pressed }) => (
+          <>
+            <DashedBorder
+              color={pressed ? colors.primary : `${colors.primary}66`}
+              radius={radius.md}
+              strokeWidth={1.5}
+            />
+            <View
+              style={{
+                width: 64,
+                height: 64,
+                borderRadius: radius.full,
+                backgroundColor: `${colors.primary}1A`,
+                alignItems: 'center',
+                justifyContent: 'center',
+              }}
+            >
+              {p.busy ? (
+                <ActivityIndicator size="small" color={colors.primary} />
+              ) : (
+                <Icon name="image" size={30} color={colors.primary} />
+              )}
+            </View>
+            <View style={{ height: spacing.md }} />
+            <MyazaText variant="heading3" style={{ textAlign: 'center' }}>
+              {p.busy ? 'Preparing your photo…' : ask}
+            </MyazaText>
+            <View style={{ height: spacing.xs }} />
+            <MyazaText variant="bodySmall" color={colors.textSecondary} style={{ textAlign: 'center' }}>
+              Choose a clear photo from your device. You can crop it on the next screen.
+            </MyazaText>
+            <View style={{ height: spacing.md }} />
+            {/* Stays in the layout while busy so the card keeps its height. */}
+            <View
+              style={{ flexDirection: 'row', alignItems: 'center', opacity: p.busy ? 0 : 1 }}
+              accessibilityElementsHidden
+              importantForAccessibility="no-hide-descendants"
+            >
+              <Icon name="upload" size={16} color={colors.primary} />
+              <View style={{ width: spacing.xs }} />
+              <MyazaText variant="label" color={colors.primary} style={{ fontWeight: '600' }}>
+                Tap to choose a photo
+              </MyazaText>
+              <View style={{ width: 2 }} />
+              <Icon name="chevron-right" size={16} color={colors.primary} />
+            </View>
+          </>
+        )}
+      </Pressable>
+
+      <View style={{ height: spacing.md }} />
+      {TIPS.map((tip) => (
+        <View key={tip.label} style={{ flexDirection: 'row', alignItems: 'center', marginBottom: spacing.xs }}>
+          <Icon name={tip.icon} size={16} color={colors.textMuted} />
+          <View style={{ width: spacing.sm }} />
+          <MyazaText variant="bodySmall" color={colors.textSecondary} style={{ flexShrink: 1 }}>
+            {tip.label}
+          </MyazaText>
+        </View>
+      ))}
+    </View>
+  );
+}

package/src/screens/document/useDocumentCamera.ts

@@ -0,0 +1,109 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCameraDevice, useCameraPermission } from 'react-native-vision-camera';
+
+import { safeReportError } from '../../services/errors';
+import { KYCError } from '../../types/verification';
+
+// The document camera's permission and hardware state, lifted out of
+// DocumentCaptureStep so that only a workflow which SCANS ever calls
+// VisionCamera's hooks. An upload-only workflow (`allowDocumentScan: false`)
+// never mounts the component that uses this, so it never reads the camera
+// permission, never enumerates devices and never prompts. The logic is the
+// step's own, moved rather than changed.
+
+export type DocumentCameraPermission = 'priming' | 'requesting' | 'granted' | 'denied';
+
+export interface DocumentCamera {
+  perm: DocumentCameraPermission;
+  /** A back camera exists (false on a simulator, which has none). */
+  hasDevice: boolean;
+  /** No camera hardware at all, once the device list has had a moment. */
+  cameraUnavailable: boolean;
+  /** The "Allow camera access" primer, shown before the OS prompt. */
+  showPrimer: boolean;
+  /** A real camera exists but the OS blocked access. */
+  permissionDenied: boolean;
+  /** Fire the real OS prompt: the primer's "Grant access", or a retry. */
+  requestAccess: () => void;
+}
+
+export function useDocumentCamera(onError: ((error: KYCError) => void) | undefined): DocumentCamera {
+  // ── 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<DocumentCameraPermission>(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;
+
+  // 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(
+        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, onError]);
+
+  const requestAccess = useCallback(() => {
+    setPerm('requesting');
+  }, []);
+
+  return {
+    perm,
+    hasDevice: !!device,
+    cameraUnavailable,
+    showPrimer: perm === 'priming' && !!device,
+    permissionDenied,
+    requestAccess,
+  };
+}

package/src/screens/liveness/CaptureRing.tsx

@@ -0,0 +1,91 @@
+import React, { useEffect, useRef } from 'react';
+import Svg, { Circle } from 'react-native-svg';
+import { advanceTarget, easeToward, mixHex } from '../../lib/captureRing';
+
+// A single line traced around the camera circle's edge for the length of the
+// liveness test: empty when it starts, closed at the shutter, one way only, no
+// rotation. The frame's own border filling in, not a spinner on top of it.
+//
+// Driven OUTSIDE React. `getTarget` is read every frame in a requestAnimationFrame
+// loop and the arc is written with setNativeProps — no state, no re-render.
+// react-native-reanimated is deliberately not a dependency of this SDK, and a
+// native module is the wrong price for one ring; setNativeProps per frame is
+// the no-render path core React Native offers, and the write is a single prop
+// on a single leaf node. Judge it on a release build on the slowest Android
+// you support.
+
+const STROKE = 4; // the frame's own border width
+const GREEN_MS = 300;
+
+export function CaptureRing({
+  size,
+  getTarget,
+  color,
+  successColor,
+  complete,
+}: {
+  size: number;
+  /** Latest 0..1 progress. Read every frame; must be a stable function. */
+  getTarget: () => number;
+  color: string;
+  successColor: string;
+  /** Turns the closed ring green — on the same frame as the shutter. */
+  complete: boolean;
+}) {
+  const ref = useRef<React.ElementRef<typeof Circle>>(null);
+  const targetRef = useRef(0);
+  const shownRef = useRef(0);
+  const completeRef = useRef(complete);
+  const greenSinceRef = useRef<number | null>(null);
+  completeRef.current = complete;
+
+  const r = size / 2 - STROKE / 2;
+  const circumference = 2 * Math.PI * r;
+
+  useEffect(() => {
+    let frame = 0;
+    let last = Date.now();
+    const tick = () => {
+      const now = Date.now();
+      const dt = Math.min((now - last) / 1000, 0.1); // a backgrounded app must not jump
+      last = now;
+      targetRef.current = advanceTarget(targetRef.current, getTarget());
+      shownRef.current = easeToward(shownRef.current, targetRef.current, dt);
+      if (completeRef.current && greenSinceRef.current == null) greenSinceRef.current = now;
+      const green = greenSinceRef.current == null ? 0 : (now - greenSinceRef.current) / GREEN_MS;
+      ref.current?.setNativeProps({
+        strokeDashoffset: circumference * (1 - shownRef.current),
+        stroke: green > 0 ? mixHex(color, successColor, green) : color,
+      });
+      frame = requestAnimationFrame(tick);
+    };
+    frame = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(frame);
+  }, [getTarget, circumference, color, successColor]);
+
+  return (
+    <Svg
+      pointerEvents="none"
+      style={{ position: 'absolute', top: 0, left: 0 }}
+      width={size}
+      height={size}
+      // Static origin, not motion: the arc starts at twelve o'clock.
+      rotation={-90}
+      originX={size / 2}
+      originY={size / 2}
+    >
+      <Circle
+        ref={ref}
+        cx={size / 2}
+        cy={size / 2}
+        r={r}
+        fill="none"
+        stroke={color}
+        strokeWidth={STROKE}
+        strokeLinecap="butt"
+        strokeDasharray={[circumference]}
+        strokeDashoffset={circumference}
+      />
+    </Svg>
+  );
+}

package/src/screens/liveness/LivenessCamera.tsx

@@ -0,0 +1,63 @@
+import React from 'react';
+import { ActivityIndicator, View } from 'react-native';
+import { Camera, type CameraDevice, type CameraViewProps } from 'react-native-vision-camera';
+
+// ─── The front camera inside the liveness circle ────────────────────────────
+//
+// The Camera is mounted inside a plain, BORDERLESS wrapper, and that wrapper is
+// the fix for a preview that did not reach the right-hand edge of the circle
+// on Android (Galaxy S24, 2026-09-07: a vertical line one border-width in from
+// the ring, the clip box's ground showing through).
+//
+// VisionCamera installs a "hierarchy fitter" on its Android PreviewView: the
+// moment CameraX adds the SurfaceView, it re-runs `layout(0, 0, w, h)` on the
+// PreviewView so the new child gets measured (React Native never lays native
+// children out on its own). That call keeps the SIZE React Native gave the view
+// and throws away its POSITION — so a Camera that is the direct child of a
+// bordered box snaps from (border, border) back to the box's outer corner. The
+// 3:4 preview buffer overflows the circle vertically and hides the shift on
+// that axis; horizontally it fits exactly, and the missing border-width is the
+// line. iOS has no fitter, which is why only Android showed it.
+//
+// A wrapper with no border sits at (border, border) itself, laid out by React
+// Native, so the fitter's (0, 0) is now the right answer. The wrapper must be
+// `collapsable={false}`: a View that carries nothing but layout is FLATTENED on
+// Android (it never exists natively, its child is re-parented to the
+// grandparent), which put the Camera straight back inside the bordered box
+// and reproduced the line on the first attempt. Never mount VisionCamera's
+// Camera as the direct child of a view with `borderWidth`.
+// Pinned by __tests__/livenessCameraWrapper.test.ts.
+
+interface LivenessCameraProps {
+  device: CameraDevice | undefined;
+  active: boolean;
+  outputs: NonNullable<CameraViewProps['outputs']>;
+  /** Diameter of the circle, for the Camera's own rounded clip. */
+  circle: number;
+}
+
+export function LivenessCamera({ device, active, outputs, circle }: LivenessCameraProps): React.ReactElement {
+  return (
+    <View style={{ flex: 1 }} collapsable={false}>
+      {device ? (
+        <Camera
+          // borderRadius repeated on the Camera — iOS does not reliably clip
+          // a native child to a rounded parent, so the preview's square
+          // corners showed through the circle. Same fix the selfie preview
+          // and the header brand bar already carry.
+          style={{ flex: 1, borderRadius: circle / 2, overflow: 'hidden' }}
+          device={device}
+          isActive={active}
+          outputs={outputs}
+          // Mirror the front-camera preview + capture so it reads like a
+          // mirror (matches the web SDK's scaleX(-1) video).
+          mirrorMode="on"
+        />
+      ) : (
+        <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
+          <ActivityIndicator color="#FFFFFF" />
+        </View>
+      )}
+    </View>
+  );
+}

package/src/screens/liveness/LivenessHandover.tsx

@@ -0,0 +1,43 @@
+import React, { useEffect, useRef } from 'react';
+
+import { useKycConfig } from '../../components/runtime';
+import { configScope } from '../../lib/scope';
+import { describeWaiting } from '../../lib/result-copy';
+import { waitsForResult } from '../../config/biometricOptions';
+import { biometricCopyFor } from '../../lib/biometric-copy';
+import { SubmittedWaiting } from '../SubmittedWaiting';
+
+// ─── Handing over without the review ────────────────────────────────────────
+//
+// On the biometric scopes the selfie review (Retake / Continue) is OFF by
+// default (config/biometricOptions.ts): a re-authentication is a few-second
+// check and a review screen is a stop in the middle of it. The step hands
+// over the moment the ring has closed, WITHOUT waiting for the upload: the
+// upload keeps running and reports to the store, and the submitted step waits
+// on that record (lib/selfie-upload-wait.ts). So the person sees one loading
+// screen from the shutter to the verdict, not one per step. The view below
+// exists for the single render between "ready" and the step change, and it
+// is the same screen the submitted step shows, so nothing visibly changes.
+// An upload that fails BEFORE the ring closes still gets the review, whose
+// Try Again is the recovery.
+
+/** Advance exactly once, the first render on which `ready` holds. */
+export function useSelfieAutoAdvance(opts: { enabled: boolean; ready: boolean; onAdvance: () => void }): void {
+  const advanced = useRef(false);
+  const { enabled, ready, onAdvance } = opts;
+  useEffect(() => {
+    if (!enabled || !ready || advanced.current) return;
+    advanced.current = true;
+    onAdvance();
+  }, [enabled, ready, onAdvance]);
+}
+
+export function LivenessHandover(): React.ReactElement {
+  const config = useKycConfig();
+  const copy = describeWaiting({
+    scope: configScope(config),
+    waitsForResult: waitsForResult(config),
+    override: biometricCopyFor(config).waiting,
+  });
+  return <SubmittedWaiting title={copy.title} description={copy.description} />;
+}

package/src/screens/liveness/LivenessOutcome.tsx

@@ -23,11 +23,15 @@ import type { LivenessFailureReason } from '../../liveness/types';
 
 export function LivenessComplete({
   selfieUri,
+  soft = false,
   upload,
   onRetake,
   onContinue,
 }: {
-  selfieUri: string;
+  /** Null on a restored session: the mediaId survived, the local file did not. */
+  selfieUri: string | null;
+  /** The still reads out of focus. A notice on the preview, never a gate. */
+  soft?: boolean;
   upload: SelfieUpload;
   onRetake: () => void;
   onContinue: () => void;
@@ -37,10 +41,10 @@ export function LivenessComplete({
     upload;
   return (
       <View>
-        <SelfiePreview uri={selfieUri} uploading={uploading && !uploadError} />
+        <SelfiePreview uri={selfieUri} uploading={uploading && !uploadError} soft={soft} />
         {retryInfo && uploading ? (
           <MyazaText variant="bodySmall" color={colors.warning} style={{ textAlign: 'center', marginTop: spacing.sm }}>
-            {`Upload failed — retrying (${retryInfo.attempt}/${retryInfo.total})…`}
+            {`Upload failed, retrying (${retryInfo.attempt}/${retryInfo.total})`}
           </MyazaText>
         ) : null}
         <View style={{ height: spacing.md }} />
@@ -51,7 +55,7 @@ export function LivenessComplete({
             // Disabled while the retry is in flight, not spinning — the progress
             // indicator belongs in the selfie frame, where the work is.
             disabled={uploading}
-            onPress={() => void uploadSelfieAndVideo(selfieUri, videoPathRef.current)}
+            onPress={() => selfieUri && void uploadSelfieAndVideo(selfieUri, videoPathRef.current)}
           />
         ) : (
           <View style={{ flexDirection: 'row', gap: spacing.md }}>

package/src/screens/liveness/SelfiePreview.tsx

@@ -11,15 +11,33 @@ import { StyleAbsFill } from './constants';
 // The captured selfie, shown back while it uploads.
 // ---------------------------------------------------------------------------
 
-export function SelfiePreview({ uri, uploading }: { uri: string; uploading?: boolean }): React.ReactElement {
+export function SelfiePreview({
+  uri,
+  uploading,
+  soft = false,
+}: {
+  uri: string | null;
+  uploading?: boolean;
+  /** The still reads out of focus (lib/selfie-sharpness). */
+  soft?: boolean;
+}): React.ReactElement {
   const { colors } = useTheme();
   const S = 200;
   return (
     <View style={{ alignItems: 'center', justifyContent: 'center', alignSelf: 'stretch' }}>
-      <View style={{ width: S, height: S, borderRadius: S / 2, borderWidth: 4, backgroundColor: '#111111', borderColor: `${colors.primary}33`, overflow: 'hidden' }}>
+      <View style={{ width: S, height: S, borderRadius: S / 2, borderWidth: 4, backgroundColor: uri ? '#111111' : `${colors.primary}14`, borderColor: `${colors.primary}33`, overflow: 'hidden', alignItems: 'center', justifyContent: 'center' }}>
         {/* borderRadius repeated on the Image — iOS doesn't reliably clip an Image
-            child to a rounded parent (same fix as the header brand bar). */}
-        <Image source={{ uri }} style={{ width: '100%', height: '100%', borderRadius: S / 2 }} resizeMode="cover" />
+            child to a rounded parent (same fix as the header brand bar). A null
+            uri is a restored session whose local file is gone: the uploaded
+            selfie is the durable record, so show a completed state rather than
+            a broken image. */}
+        {uri ? (
+          <Image source={{ uri }} style={{ width: '100%', height: '100%', borderRadius: S / 2 }} resizeMode="cover" />
+        ) : (
+          <MyazaText variant="bodySmall" color={colors.textSecondary} style={{ textAlign: 'center', paddingHorizontal: spacing.lg }}>
+            Selfie already captured
+          </MyazaText>
+        )}
         {/* Standard upload loader inside the preview circle (mirrors web/Flutter). */}
         {uploading ? (
           <View style={[StyleAbsFill, { backgroundColor: 'rgba(0,0,0,0.45)', alignItems: 'center', justifyContent: 'center' }]}>
@@ -28,11 +46,17 @@ export function SelfiePreview({ uri, uploading }: { uri: string; uploading?: boo
         ) : null}
       </View>
       <View style={{ height: spacing.md }} />
-      <MyazaText variant="heading3" style={{ textAlign: 'center' }}>
-        Looking good!
+      {/* The heading is the review's verdict on the photo, so a soft still must
+          not read "Looking good!". Continue stays available either way: the
+          floor is uncalibrated, and a wrong one should cost a sentence, never
+          a retake loop. */}
+      <MyazaText variant="heading3" color={soft ? colors.warning : undefined} style={{ textAlign: 'center' }}>
+        {soft ? 'This photo looks blurry' : 'Looking good!'}
       </MyazaText>
       <MyazaText variant="bodySmall" color={colors.textSecondary} style={{ textAlign: 'center' }}>
-        Tap Continue to submit, or Retake to try again.
+        {soft
+          ? 'For the best chance of a match, retake it holding the phone steady until your face is sharp.'
+          : 'Tap Continue to submit, or Retake to try again.'}
       </MyazaText>
     </View>
   );