@velion-la/onboarding-sdk-react-native 1.0.0-beta.2

package/src/steps/LivenessMatchStep.tsx

@@ -0,0 +1,846 @@
+/**
+ * LIVENESS_MATCH — Iris-driven active liveness over WebSocket.
+ *
+ * Flow:
+ *   1. POST /liveness-init → { liveness_session_id, websocket_url, expires_at,
+ *      challenges, connection_token, frame_integrity_key_base64 }.
+ *   2. Optionally import the HMAC key for frame integrity.
+ *   3. Open vision-camera (front), connect WS with ?token & ?lang.
+ *   4. SESSION_READY → start frame capture loop (interval-driven), watchdog 25s.
+ *   5. Process CHALLENGE / CHALLENGE_PROGRESS / CHALLENGE_COMPLETE / WARNING /
+ *      ERROR / SESSION_COMPLETE.
+ *   6. Terminal WARNING (SPOOF_RISK_HIGH, …) → in-flow retry dialog (re-init
+ *      + fresh WS) without bailing the whole flow.
+ *   7. SESSION_COMPLETE → POST /liveness-verify → resolve the step.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { ScrollView, StyleSheet, Text, View } from 'react-native';
+import * as ImageManipulator from 'expo-image-manipulator';
+import {
+  SdkErrorCode,
+  type LivenessSessionResponse,
+  type SdkError,
+} from '../types';
+import { Banner } from '../ui/primitives/Banner';
+import { Button } from '../ui/primitives/Button';
+import { AnalyzingOverlay } from '../ui/overlays/AnalyzingOverlay';
+import { RetryDialog } from '../ui/overlays/RetryDialog';
+import { StepShell } from '../ui/StepShell';
+import { StepIcon } from '../ui/icons/StepIcon';
+import { mixHex, useTheme } from '../ui/theme';
+import { getStrings } from '../i18n';
+import { log } from '../utils/log';
+import { readJpegFromUri } from '../utils/jpegFromUri';
+import {
+  buildSignedFrameEnvelope,
+  importHmacKey,
+  type HmacKey,
+} from '../utils/hmac';
+import {
+  TERMINAL_WARNING_CODES,
+  openIrisWebSocket,
+  type IrisChallenge,
+  type IrisConnection,
+  type IrisServerMessage,
+} from '../transport/irisWebSocket';
+import {
+  LivenessCamera,
+  type LivenessCameraHandle,
+  type LivenessOvalCue,
+} from '../camera/LivenessCamera';
+import type { ApiCaller } from '../transport/api';
+import type { StepDeps, StepModule } from './types';
+
+// Capture loop defaults tuned for the Iris orchestrator's frame cadence.
+const FRAME_MS_DEFAULT = 350;
+const FRAME_MS_TURN = 220;
+const PROGRESS_WATCHDOG_MS = 25_000;
+const FRAME_MAX_LONG_EDGE = 720;
+const FRAME_QUALITY = 0.55;
+
+export class LivenessMatchStep implements StepModule {
+  private resolveStep!: () => void;
+  private rejectStep!: (err: SdkError) => void;
+  private destroyed = false;
+
+  constructor(private readonly deps: StepDeps) {}
+
+  run(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.resolveStep = resolve;
+      this.rejectStep = reject;
+      this.deps.ui.setNode(
+        <LivenessMatchView
+          api={this.deps.api}
+          sessionId={this.deps.sessionId}
+          locale={this.deps.locale}
+          calibrationLabel={this.deps.livenessCalibrationLabel}
+          showIntro
+          showBackButton
+          onComplete={() => {
+            if (this.destroyed) return;
+            this.deps.ui.setNode(null);
+            this.resolveStep();
+          }}
+          onCancel={(err) => {
+            if (this.destroyed) return;
+            this.deps.ui.setNode(null);
+            this.rejectStep(err);
+          }}
+        />,
+      );
+    });
+  }
+
+  destroy(): void {
+    this.destroyed = true;
+    this.deps.ui.setNode(null);
+  }
+}
+
+interface ViewProps {
+  api: ApiCaller;
+  sessionId: string;
+  locale: string;
+  /** Optional Iris calibration label forwarded to /liveness-init body. */
+  calibrationLabel?: string | undefined;
+  showIntro: boolean;
+  showBackButton: boolean;
+  onComplete: () => void;
+  onCancel: (err: SdkError) => void;
+}
+
+type Phase = 'intro' | 'capturing' | 'finalizing';
+
+function LivenessMatchView({
+  api,
+  sessionId,
+  locale,
+  calibrationLabel,
+  showIntro,
+  showBackButton,
+  onComplete,
+  onCancel,
+}: ViewProps) {
+  const t = getStrings(locale);
+  const theme = useTheme();
+  const cameraRef = useRef<LivenessCameraHandle>(null);
+
+  const [phase, setPhase] = useState<Phase>(showIntro ? 'intro' : 'capturing');
+  const [statusText, setStatusText] = useState<string | null>(null);
+  const [challengeText, setChallengeText] = useState<string | null>(null);
+  const [ovalCue, setOvalCue] = useState<LivenessOvalCue>('NEUTRAL');
+  const [toast, setToast] = useState<
+    | {
+        kind: 'success' | 'warning';
+        message: string;
+      }
+    | null
+  >(null);
+  const [progress, setProgress] = useState<number | null>(null);
+  const [retry, setRetry] = useState<{ message: string; code: string } | null>(null);
+  const [bannerError, setBannerError] = useState<string | null>(null);
+
+  // Long-lived state that the capture loop / WS handlers need without
+  // triggering re-renders: kept in refs.
+  const wsRef = useRef<IrisConnection | null>(null);
+  const hmacRef = useRef<HmacKey | null>(null);
+  const livenessSessionIdRef = useRef<string | null>(null);
+  const currentChallengeRef = useRef<IrisChallenge | null>(null);
+  // Tracks the position of the active challenge inside the session sequence
+  // so we can recognise the LAST challenge completing and switch to the
+  // "Analyzing" overlay immediately, instead of letting the user stare at
+  // the camera with the last instruction frozen on screen for the seconds
+  // it takes the worker to drain its queue and the orchestrator to emit
+  // SESSION_COMPLETE.
+  const lastChallengeMetaRef = useRef<{ index: number; total: number } | null>(
+    null,
+  );
+  const frameMsRef = useRef<number>(FRAME_MS_DEFAULT);
+  const captureTimerRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const inFlightRef = useRef(false);
+  const framesSentRef = useRef(0);
+  const watchdogRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const finalizingRef = useRef(false);
+  const toastTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // Tracks the toast currently on screen so we can extend its visibility when
+  // the same message arrives again (instead of dismount/remount, which made
+  // warnings flash in <2s and the user couldn't read them).
+  const activeToastRef = useRef<{ kind: 'success' | 'warning'; message: string } | null>(null);
+
+  // Each toast stays on screen at least this long. The orchestrator can spam
+  // WARNINGs (POSITIONING_REQUIRED, SPOOF_RISK_HIGH, …) several times per
+  // second; without a floor the user literally cannot read them.
+  const TOAST_MIN_DURATION_MS = 3200;
+
+  const showToast = useCallback(
+    (kind: 'success' | 'warning', message: string) => {
+      const active = activeToastRef.current;
+      if (active && active.kind === kind && active.message === message) {
+        // Identical toast already visible — just refresh the timer so it
+        // stays up while warnings keep arriving. Do NOT touch `setToast`:
+        // a new object would re-trigger the entry animation and flicker.
+        if (toastTimerRef.current) clearTimeout(toastTimerRef.current);
+        toastTimerRef.current = setTimeout(() => {
+          setToast(null);
+          activeToastRef.current = null;
+        }, TOAST_MIN_DURATION_MS);
+        return;
+      }
+      // Different content: replace and guarantee the new toast its own
+      // minimum window.
+      activeToastRef.current = { kind, message };
+      setToast({ kind, message });
+      if (toastTimerRef.current) clearTimeout(toastTimerRef.current);
+      toastTimerRef.current = setTimeout(() => {
+        setToast(null);
+        activeToastRef.current = null;
+      }, TOAST_MIN_DURATION_MS);
+    },
+    [],
+  );
+
+  const stopWatchdog = useCallback(() => {
+    if (watchdogRef.current) {
+      clearTimeout(watchdogRef.current);
+      watchdogRef.current = null;
+    }
+  }, []);
+
+  const stopCapture = useCallback(() => {
+    if (captureTimerRef.current) {
+      clearInterval(captureTimerRef.current);
+      captureTimerRef.current = null;
+    }
+    inFlightRef.current = false;
+  }, []);
+
+  const failWith = useCallback(
+    (err: SdkError) => {
+      stopWatchdog();
+      stopCapture();
+      try {
+        wsRef.current?.close(1000, 'fail');
+      } catch {
+        /* ignore */
+      }
+      wsRef.current = null;
+      onCancel(err);
+    },
+    [onCancel, stopCapture, stopWatchdog],
+  );
+
+  const captureAndSend = useCallback(async () => {
+    if (inFlightRef.current) return;
+    const ws = wsRef.current;
+    if (!ws || !ws.isOpen()) return;
+    inFlightRef.current = true;
+    try {
+      const photo = await cameraRef.current?.takeFrame();
+      if (!photo || !ws.isOpen()) return;
+      const compressed = await ImageManipulator.manipulateAsync(
+        photo.path.startsWith('file://') ? photo.path : `file://${photo.path}`,
+        [{ resize: { width: FRAME_MAX_LONG_EDGE } }],
+        { compress: FRAME_QUALITY, format: ImageManipulator.SaveFormat.JPEG },
+      );
+      if (!ws.isOpen()) return;
+      const jpeg = await readJpegFromUri(compressed.uri);
+      const key = hmacRef.current;
+      if (key) {
+        const envelope = buildSignedFrameEnvelope({
+          key,
+          sessionId: livenessSessionIdRef.current ?? sessionId,
+          frameId: framesSentRef.current,
+          jpegBytes: jpeg.bytes,
+          jpegBase64: jpeg.base64,
+        });
+        ws.sendJson(envelope.json);
+      } else {
+        // Vision-camera + RN's WebSocket need an ArrayBuffer for binary frames.
+        // `Uint8Array.buffer` is a `SharedArrayBuffer` on some Hermes versions
+        // — slice into a fresh ArrayBuffer to be safe.
+        const ab = jpeg.bytes.buffer.slice(
+          jpeg.bytes.byteOffset,
+          jpeg.bytes.byteOffset + jpeg.bytes.byteLength,
+        ) as ArrayBuffer;
+        ws.sendBinary(ab);
+      }
+      framesSentRef.current += 1;
+    } catch (err) {
+      log.warn('[Liveness] frame send failed', err);
+    } finally {
+      inFlightRef.current = false;
+    }
+  }, [sessionId]);
+
+  const startCaptureLoop = useCallback(
+    (ms: number) => {
+      stopCapture();
+      frameMsRef.current = ms;
+      captureTimerRef.current = setInterval(() => {
+        void captureAndSend();
+      }, ms);
+    },
+    [captureAndSend, stopCapture],
+  );
+
+  const adjustFps = useCallback(
+    (ms: number) => {
+      if (frameMsRef.current === ms) return;
+      if (captureTimerRef.current) {
+        startCaptureLoop(ms);
+      } else {
+        frameMsRef.current = ms;
+      }
+    },
+    [startCaptureLoop],
+  );
+
+  const challengeLabel = useCallback(
+    (id: IrisChallenge | null): string => {
+      if (!id) return '';
+      return t.liveness.challenge[id] ?? '';
+    },
+    [t.liveness.challenge],
+  );
+
+  const presentTerminalRetry = useCallback(
+    (code: string, message?: string) => {
+      stopCapture();
+      stopWatchdog();
+      try {
+        wsRef.current?.close(4001, 'terminal_warning_retry_pending');
+      } catch {
+        /* ignore */
+      }
+      wsRef.current = null;
+      setRetry({ code, message: message?.trim() || t.liveness.terminalRetryFallback });
+    },
+    [stopCapture, stopWatchdog, t.liveness.terminalRetryFallback],
+  );
+
+  const resetWatchdog = useCallback(() => {
+    stopWatchdog();
+    watchdogRef.current = setTimeout(() => {
+      log.warn('[Liveness] progress watchdog fired');
+      // The watchdog used to be a hard fail — onCancel → step rejects →
+      // orchestrator surfaces the error and exits the whole liveness step.
+      // That left the user with no in-flow recovery: they had to restart
+      // the entire onboarding. The Iris-side "no progress in N seconds" is
+      // usually a recoverable user-side issue (lighting, framing, not
+      // looking at the camera), so we treat it the same way as a terminal
+      // WARNING: tear down the WS, show the retry dialog, and let the user
+      // restart the verification without leaving the step.
+      presentTerminalRetry('NO_PROGRESS', t.liveness.noProgressMessage);
+    }, PROGRESS_WATCHDOG_MS);
+  }, [presentTerminalRetry, stopWatchdog, t.liveness.noProgressMessage]);
+
+  const handleWsMessage = useCallback(
+    (msg: IrisServerMessage) => {
+      switch (msg.type) {
+        case 'SESSION_READY': {
+          setStatusText(null);
+          // The ~1-2 s gap between SESSION_READY and the first CHALLENGE is
+          // where users decide their posture for the whole session. We use
+          // it for two pieces of guidance, layered:
+          //   - A short "Heads up — starting now" toast above the oval so
+          //     they're not caught looking away when (e.g.) the BLINK window
+          //     opens.
+          //   - A persistent `challengeText` ("Center your face in the oval")
+          //     anchored above the oval so they keep adjusting until the
+          //     first real challenge arrives and overwrites it. Without
+          //     this, every Android calibration session started with the
+          //     face at ~25 % of the frame width and SMILE / MOVE_FARTHER
+          //     failed before the user understood what was being asked.
+          setChallengeText(t.liveness.centerFace);
+          showToast('success', t.liveness.getReady);
+          startCaptureLoop(FRAME_MS_DEFAULT);
+          resetWatchdog();
+          return;
+        }
+        case 'CHALLENGE': {
+          const ch = (msg.challenge ?? null) as IrisChallenge | null;
+          currentChallengeRef.current = ch;
+          // Stash the sequence position so CHALLENGE_COMPLETE can tell
+          // whether this was the LAST challenge and switch to the analyzing
+          // overlay immediately instead of waiting for SESSION_COMPLETE.
+          if (
+            typeof msg.sequenceIndex === 'number' &&
+            typeof msg.totalChallenges === 'number'
+          ) {
+            lastChallengeMetaRef.current = {
+              index: msg.sequenceIndex,
+              total: msg.totalChallenges,
+            };
+          }
+          adjustFps(
+            ch === 'TURN_LEFT' || ch === 'TURN_RIGHT'
+              ? FRAME_MS_TURN
+              : FRAME_MS_DEFAULT,
+          );
+          setChallengeText(challengeLabel(ch));
+          // Map distance challenges to an oval-size cue so the viewfinder
+          // shape reinforces the instruction (grows for closer, returns to
+          // neutral for farther). All other challenges keep the neutral
+          // oval — the dim mask shouldn't move under a turn / smile / blink.
+          setOvalCue(
+            ch === 'MOVE_CLOSER'
+              ? 'MOVE_CLOSER'
+              : ch === 'MOVE_FARTHER'
+                ? 'MOVE_FARTHER'
+                : 'NEUTRAL',
+          );
+          setProgress(0);
+          resetWatchdog();
+          return;
+        }
+        case 'CHALLENGE_PROGRESS': {
+          if (typeof msg.confidence === 'number') {
+            setProgress(msg.confidence);
+          }
+          resetWatchdog();
+          return;
+        }
+        case 'CHALLENGE_COMPLETE': {
+          setProgress(1);
+          currentChallengeRef.current = null;
+          adjustFps(FRAME_MS_DEFAULT);
+          // Reset the oval back to neutral after each challenge so the
+          // next CHALLENGE (or finalize) doesn't inherit a "zoomed" oval.
+          setOvalCue('NEUTRAL');
+          // Last challenge of the sequence completed → switch to the
+          // "Analyzing your video" overlay right away. SESSION_COMPLETE
+          // can take several seconds to land while the worker drains
+          // its queue; without this the user would stare at the camera
+          // and the stale instruction the whole time.
+          const meta = lastChallengeMetaRef.current;
+          if (meta && meta.index >= meta.total - 1) {
+            stopCapture();
+            setPhase('finalizing');
+          }
+          resetWatchdog();
+          return;
+        }
+        case 'WARNING': {
+          if (msg.code && TERMINAL_WARNING_CODES.has(msg.code)) {
+            presentTerminalRetry(msg.code, msg.message);
+            return;
+          }
+          const isPositioningReady = msg.code === 'POSITIONING_READY';
+          // Per-code SDK-side fallback used when the orchestrator forwarded a
+          // code but no localised text (e.g. older orchestrator versions, or
+          // the rare WS message that drops the body). The orchestrator's own
+          // text is preferred — it always wins when present — so the user sees
+          // the server's exact wording in the session's locale.
+          const FALLBACK_BY_CODE: Record<string, string> = {
+            TOO_FAR: t.liveness.warningTooFar,
+            TOO_CLOSE: t.liveness.warningTooClose,
+            MOVE_CLOSER_HINT: t.liveness.warningMoveCloserHint,
+            MOVE_FARTHER_HINT: t.liveness.warningMoveFartherHint,
+          };
+          // Timeout fallback is dynamic: the orchestrator now sends a
+          // challenge-specific message ("No pudimos reconocer el giro hacia
+          // la izquierda"), but if it ever drops it the SDK rebuilds the
+          // same text from the locally tracked active challenge.
+          let timeoutFallback: string | undefined;
+          if (msg.code === 'CHALLENGE_TIMEOUT') {
+            const ch = currentChallengeRef.current;
+            switch (ch) {
+              case 'TURN_LEFT':    timeoutFallback = t.liveness.timeoutTurnLeft; break;
+              case 'TURN_RIGHT':   timeoutFallback = t.liveness.timeoutTurnRight; break;
+              case 'BLINK':        timeoutFallback = t.liveness.timeoutBlink; break;
+              case 'SMILE':        timeoutFallback = t.liveness.timeoutSmile; break;
+              case 'MOVE_CLOSER':  timeoutFallback = t.liveness.timeoutMoveCloser; break;
+              case 'MOVE_FARTHER': timeoutFallback = t.liveness.timeoutMoveFarther; break;
+              default:             timeoutFallback = t.liveness.timeoutGeneric;
+            }
+          }
+          const codedFallback =
+            timeoutFallback ??
+            (msg.code ? FALLBACK_BY_CODE[msg.code] : undefined) ??
+            t.liveness.warningGeneric;
+          // Prefer the server-localised message — it's situationally
+          // accurate ("El fondo tiene mucho movimiento o reflejos. Pasá a
+          // un fondo neutro y plano"). Drop to the SDK fallback only when
+          // the orchestrator did not provide one.
+          const baseText = msg.message ?? codedFallback;
+          const text = isPositioningReady
+            ? t.liveness.positioningReady
+            : typeof msg.consecutiveMisses === 'number' &&
+                msg.consecutiveMisses >= 3
+              ? t.liveness.warningConsecutiveMisses
+                  .replace('{n}', String(msg.consecutiveMisses))
+                  .concat(' — ', baseText)
+              : baseText;
+          showToast(isPositioningReady ? 'success' : 'warning', text);
+          resetWatchdog();
+          return;
+        }
+        case 'ERROR': {
+          failWith({
+            code: SdkErrorCode.LIVENESS_FAILED,
+            message:
+              msg.message ?? msg.code ?? 'Iris reported an error during liveness.',
+          });
+          return;
+        }
+        case 'SESSION_COMPLETE': {
+          stopWatchdog();
+          if (finalizingRef.current) return;
+          finalizingRef.current = true;
+          stopCapture();
+          try {
+            wsRef.current?.close(1000, 'session_complete');
+          } catch {
+            /* ignore */
+          }
+          wsRef.current = null;
+          setPhase('finalizing');
+          (async () => {
+            try {
+              await api.post(`/sessions/${sessionId}/liveness-verify`, {});
+              onComplete();
+            } catch (err) {
+              const message =
+                err && typeof err === 'object' && 'message' in err
+                  ? String((err as { message?: unknown }).message)
+                  : 'Failed to notify the backend that liveness completed.';
+              failWith({
+                code: SdkErrorCode.LIVENESS_FAILED,
+                message,
+                cause: err,
+              });
+            }
+          })();
+          return;
+        }
+        default:
+          return;
+      }
+    },
+    [
+      adjustFps,
+      api,
+      challengeLabel,
+      failWith,
+      onComplete,
+      presentTerminalRetry,
+      resetWatchdog,
+      sessionId,
+      showToast,
+      startCaptureLoop,
+      stopCapture,
+      stopWatchdog,
+      t.liveness.getReady,
+      t.liveness.positioningReady,
+      t.liveness.warningConsecutiveMisses,
+      t.liveness.warningGeneric,
+    ],
+  );
+
+  const startVerification = useCallback(async () => {
+    setBannerError(null);
+    setRetry(null);
+    setStatusText(t.liveness.connecting);
+    finalizingRef.current = false;
+    framesSentRef.current = 0;
+    currentChallengeRef.current = null;
+    lastChallengeMetaRef.current = null;
+    frameMsRef.current = FRAME_MS_DEFAULT;
+    hmacRef.current = null;
+
+    let init: LivenessSessionResponse;
+    try {
+      // `calibration_label` is the wire name expected by the backend
+      // (snake_case mirroring iris-test's `/sessions` POST). Only sent when
+      // the host explicitly enables calibration via VelionConfig.
+      const body: Record<string, unknown> = {};
+      if (calibrationLabel && calibrationLabel.length > 0) {
+        body.calibration_label = calibrationLabel;
+      }
+      init = await api.post<LivenessSessionResponse>(
+        `/sessions/${sessionId}/liveness-init`,
+        body,
+      );
+    } catch (err) {
+      failWith({
+        code: SdkErrorCode.LIVENESS_INIT_FAILED,
+        message:
+          (err && typeof err === 'object' && 'message' in err
+            ? String((err as { message?: unknown }).message)
+            : '') || 'Failed to create the Iris liveness session.',
+        cause: err,
+      });
+      return;
+    }
+    if (!init.liveness_session_id || !init.websocket_url) {
+      failWith({
+        code: SdkErrorCode.LIVENESS_INIT_FAILED,
+        message: 'liveness-init response missing required fields.',
+      });
+      return;
+    }
+    livenessSessionIdRef.current = init.liveness_session_id;
+    if (init.frame_integrity_key_base64) {
+      try {
+        hmacRef.current = importHmacKey(init.frame_integrity_key_base64);
+      } catch (err) {
+        log.warn('[Liveness] failed to import HMAC key', err);
+        hmacRef.current = null;
+      }
+    }
+
+    setStatusText(t.liveness.preparingCamera);
+    let connection: IrisConnection;
+    try {
+      connection = openIrisWebSocket({
+        websocketUrl: init.websocket_url,
+        connectionToken: init.connection_token,
+        locale,
+        onOpen: () => setStatusText(t.liveness.connecting),
+        onMessage: handleWsMessage,
+        onClose: (code, reason) => {
+          if (finalizingRef.current) return;
+          // Code 4001 is the close we send ourselves from
+          // `presentTerminalRetry` to tear down the WS before showing the
+          // retry dialog. Checking the React state `retry` here is unsafe
+          // — this handler is registered via closure on a stale render,
+          // so `retry` reads `null` even when we just called `setRetry`.
+          // The close code is reliable: we always pair 4001 with the
+          // retry-dialog mount.
+          if (code === 4001) return;
+          stopCapture();
+          stopWatchdog();
+          if (code === 1000) return;
+          failWith({
+            code: SdkErrorCode.LIVENESS_FAILED,
+            message: `Iris WebSocket closed before completion (code=${code}${
+              reason ? `, reason=${reason}` : ''
+            }).`,
+          });
+        },
+      });
+    } catch (err) {
+      failWith({
+        code: SdkErrorCode.LIVENESS_FAILED,
+        message:
+          err instanceof Error
+            ? err.message
+            : 'Failed to open the Iris WebSocket.',
+        cause: err,
+      });
+      return;
+    }
+    wsRef.current = connection;
+  }, [
+    api,
+    calibrationLabel,
+    failWith,
+    handleWsMessage,
+    locale,
+    retry,
+    sessionId,
+    stopCapture,
+    stopWatchdog,
+    t.liveness.connecting,
+    t.liveness.preparingCamera,
+  ]);
+
+  // Re-run after a terminal retry — same cleanup as start, but reuses the
+  // mounted camera (no DOM teardown).
+  const restartVerification = useCallback(async () => {
+    setRetry(null);
+    setProgress(null);
+    setChallengeText(null);
+    setOvalCue('NEUTRAL');
+    await startVerification();
+  }, [startVerification]);
+
+  // Effect: when the user enters the capture phase (intro skipped or
+  // confirmed), run the start sequence.
+  useEffect(() => {
+    if (phase !== 'capturing') return;
+    void startVerification();
+    return () => {
+      stopCapture();
+      stopWatchdog();
+      if (toastTimerRef.current) clearTimeout(toastTimerRef.current);
+      try {
+        wsRef.current?.close(1000, 'unmount');
+      } catch {
+        /* ignore */
+      }
+      wsRef.current = null;
+    };
+    // We intentionally only re-run when phase flips into capturing — the
+    // first start; the retry path is handled by `restartVerification`.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [phase]);
+
+  if (retry) {
+    return (
+      <RetryDialog
+        title={t.liveness.terminalRetryTitle}
+        message={retry.message}
+        retryLabel={t.liveness.terminalRetryButton}
+        cancelLabel={t.liveness.terminalCancelButton}
+        onRetry={() => {
+          void restartVerification();
+        }}
+        onCancel={() => {
+          setRetry(null);
+          onCancel({
+            code: SdkErrorCode.LIVENESS_FAILED,
+            message: retry.message,
+          });
+        }}
+      />
+    );
+  }
+
+  if (phase === 'intro') {
+    return (
+      <View style={{ flex: 1 }}>
+        <StepShell
+          title={t.liveness.introTitle}
+          subtitle={t.liveness.introSubtitle}
+          iconNode={<StepIcon name="face" />}
+        >
+          <ScrollView contentContainerStyle={styles.tipsList}>
+            {t.liveness.introTips.map((tip, idx) => (
+              <View
+                key={idx}
+                style={[
+                  styles.tipRow,
+                  {
+                    borderColor: theme.borderColor,
+                    backgroundColor: mixHex(
+                      theme.primaryColor,
+                      theme.backgroundColor,
+                      6,
+                    ),
+                    borderRadius: theme.borderRadiusPx,
+                  },
+                ]}
+              >
+                <View
+                  style={[
+                    styles.tipIcon,
+                    {
+                      backgroundColor: mixHex(
+                        theme.primaryColor,
+                        theme.backgroundColor,
+                        18,
+                      ),
+                    },
+                  ]}
+                >
+                  <Text
+                    style={[styles.tipIconText, { color: theme.primaryColor }]}
+                  >
+                    {idx + 1}
+                  </Text>
+                </View>
+                <Text style={[styles.tipText, { color: theme.textColor }]}>
+                  {tip}
+                </Text>
+              </View>
+            ))}
+          </ScrollView>
+          {bannerError ? <Banner message={bannerError} /> : null}
+          <View style={styles.introActions}>
+            {showBackButton ? (
+              <Button
+                variant="ghost"
+                label={t.liveness.introBack}
+                onPress={() =>
+                  onCancel({
+                    code: SdkErrorCode.LIVENESS_FAILED,
+                    message: 'User exited the liveness intro.',
+                  })
+                }
+                fullWidth={false}
+                style={styles.introBtn}
+              />
+            ) : null}
+            <Button
+              label={t.liveness.introStart}
+              onPress={() => setPhase('capturing')}
+              fullWidth={!showBackButton}
+              style={showBackButton ? styles.introBtn : undefined}
+            />
+          </View>
+        </StepShell>
+      </View>
+    );
+  }
+
+  if (phase === 'finalizing') {
+    return (
+      <AnalyzingOverlay
+        headline={t.liveness.analyzingHeadline}
+        caption={t.liveness.analyzingCaption}
+      />
+    );
+  }
+
+  return (
+    <View style={{ flex: 1 }}>
+      <LivenessCamera
+        ref={cameraRef}
+        statusText={statusText}
+        challengeText={challengeText}
+        ovalCue={ovalCue}
+        toast={toast}
+        progress={progress}
+        permissionDeniedLabel={t.liveness.cameraPermissionDenied}
+        retryLabel={t.liveness.cameraTryAgain}
+        cancelLabel={t.common.cancel}
+        // Intentionally no onCancel during capture. The capture screen is
+        // meant to be fullscreen and uninterruptible — if the user wants
+        // out, the 25 s progress watchdog catches stalled sessions and
+        // routes them through the RetryDialog (with its own Cancel option).
+        // The intro screen keeps the explicit "Atrás" button.
+      />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  tipsList: {
+    paddingVertical: 4,
+    gap: 10,
+  },
+  tipRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: 12,
+    padding: 12,
+    borderWidth: 1,
+  },
+  tipIcon: {
+    width: 32,
+    height: 32,
+    borderRadius: 16,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  tipIconText: {
+    fontSize: 14,
+    fontWeight: '700',
+  },
+  tipText: {
+    flex: 1,
+    fontSize: 14,
+    lineHeight: 20,
+  },
+  introActions: {
+    flexDirection: 'row',
+    gap: 10,
+    marginTop: 6,
+  },
+  introBtn: {
+    flex: 1,
+  },
+});