@myazahq/kyc-sdk-react-native 2.0.1 → 2.1.0

package/src/screens/nfc/NfcSuccessPanel.tsx

@@ -0,0 +1,162 @@
+import React, { useState } from 'react';
+import { Image, View } from 'react-native';
+
+import { spacing } from '../../config/theme';
+import { useTheme } from '../../components/runtime';
+import { MyazaText } from '../../components/Typography';
+import { MyazaButton } from '../../components/MyazaButton';
+import { Icon } from '../../components/Icon';
+import { useChipPortrait } from './useChipPortrait';
+import { NfcScannedSummary } from './NfcScannedSummary';
+import type { EmrtdReadResult } from '../../emrtd';
+import type { MrzScan } from '../../mrz/parse';
+
+// ---------------------------------------------------------------------------
+// "Chip read successfully".
+//
+// The read used to advance silently, which gave the user nothing to show for
+// the one step that asks them to hold a phone against a passport.
+//
+// The chip's OWN portrait is the confirmation when we can show it: it is the
+// issuing government's photo of the holder, which is a far stronger signal
+// than a tick. Most passports store it as JPEG 2000, which React Native cannot
+// decode, so the generic mark is the ordinary case rather than a failure — the
+// read stands either way and the bytes still go to the server.
+// ---------------------------------------------------------------------------
+
+export function NfcSuccessPanel({
+  result,
+  mrz,
+  onContinue,
+  onRescan,
+}: {
+  result: EmrtdReadResult;
+  mrz: MrzScan | null;
+  onContinue: () => void;
+  onRescan: () => void;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  const portraitUri = useChipPortrait(result.dg2);
+  // A URI that turns out unrenderable (a corrupt slice, a format the Image
+  // component rejects) must degrade to the generic mark, not an empty circle.
+  const [portraitBroken, setPortraitBroken] = useState(false);
+  const portrait = portraitBroken ? null : portraitUri;
+  const name = [mrz?.firstName, mrz?.lastName].filter(Boolean).join(' ');
+
+  return (
+    <View style={{ alignItems: 'center' }}>
+      <View style={{ height: spacing.lg }} />
+      {/* The chip's own portrait, circular, with the success mark tucked into
+          its lower-right — 1:1 with Flutter.
+          
+          Circular and large on purpose: this is the issuing government's photo
+          of the holder, and seeing it is a far stronger confirmation than a
+          tick. The tick rides ON the portrait rather than replacing it, so the
+          screen says "verified" and "this is who it says" at once. */}
+      <View style={{ width: PORTRAIT, height: PORTRAIT }}>
+        {portrait ? (
+          <Image
+            source={{ uri: portrait }}
+            style={{
+              width: PORTRAIT,
+              height: PORTRAIT,
+              borderRadius: PORTRAIT / 2,
+              backgroundColor: colors.backgroundSecondary,
+            }}
+            resizeMode="cover"
+            onError={() => {
+              if (__DEV__) console.log('[myaza] chip portrait: Image failed to render the URI');
+              setPortraitBroken(true);
+            }}
+          />
+        ) : (
+          // No renderable portrait — the generic mark, at the same size, so the
+          // layout does not jump between documents that carry one and those
+          // that do not.
+          <View
+            style={{
+              width: PORTRAIT,
+              height: PORTRAIT,
+              borderRadius: PORTRAIT / 2,
+              backgroundColor: `${colors.primary}1A`,
+              alignItems: 'center',
+              justifyContent: 'center',
+            }}
+          >
+            <Icon name="badge-check" size={56} color={colors.primary} />
+          </View>
+        )}
+        <View
+          style={{
+            position: 'absolute',
+            right: 0,
+            bottom: 2,
+            width: BADGE,
+            height: BADGE,
+            borderRadius: BADGE / 2,
+            backgroundColor: colors.success,
+            alignItems: 'center',
+            justifyContent: 'center',
+            // Punched out of the portrait rather than floating over it.
+            borderWidth: 3,
+            borderColor: colors.background,
+          }}
+        >
+          <Icon name="check" size={20} color="#FFFFFF" />
+        </View>
+      </View>
+
+      <View style={{ height: spacing.lg }} />
+      <MyazaText variant="heading2" style={{ textAlign: 'center' }}>
+        Chip read successfully
+      </MyazaText>
+      <View style={{ height: spacing.xs }} />
+      <MyazaText variant="bodyMedium" color={colors.textSecondary} style={{ textAlign: 'center' }}>
+        {name
+          ? `We read the secure chip in ${name}’s document.`
+          : 'The secure chip in your document was read and verified.'}
+      </MyazaText>
+
+      {/* Said plainly rather than hidden: without the signed security object
+          the server cannot verify the chip data against the issuer, so the read
+          is worth materially less — and the user is the only one who can
+          retry it. */}
+      {!result.sod ? (
+        <>
+          <View style={{ height: spacing.md }} />
+          <MyazaText variant="bodySmall" color={colors.textMuted} style={{ textAlign: 'center' }}>
+            The document&#8217;s security file could not be read, so the chip data
+            cannot be fully verified. You can try again or continue.
+          </MyazaText>
+        </>
+      ) : null}
+
+      {/* What was read, shown back — the same card the pre-read screen uses, so
+          the user checks the same two fields against the printed page. */}
+      {mrz ? (
+        <>
+          <View style={{ height: spacing.lg }} />
+          <View style={{ alignSelf: 'stretch' }}>
+            <NfcScannedSummary scan={mrz} />
+          </View>
+        </>
+      ) : null}
+
+      <View style={{ height: spacing.lg }} />
+      <View style={{ alignSelf: 'stretch' }}>
+        <MyazaButton label="Continue" onPress={onContinue} />
+        {!result.sod ? (
+          <>
+            <View style={{ height: spacing.sm }} />
+            <MyazaButton label="Scan again" variant="ghost" onPress={onRescan} />
+          </>
+        ) : null}
+      </View>
+    </View>
+  );
+}
+
+/** Portrait diameter. Large enough to read a face at arm's length. */
+const PORTRAIT = 132;
+/** The success mark overlapping its lower-right corner. */
+const BADGE = 40;

package/src/screens/nfc/availability.ts

@@ -0,0 +1,73 @@
+// ---------------------------------------------------------------------------
+// Is NFC actually unavailable, or has the native module simply not appeared yet?
+//
+// These two look identical at the first render and mean opposite things. Nitro
+// populates its registry asynchronously, so `isNfcAvailable()` can report false
+// for a moment on a phone that reads chips perfectly well — observed on a real
+// device where three consecutive reloads reported available and the fourth did
+// not, with no code change between them.
+//
+// The consequence is out of proportion to the cause: the chip step SKIPS ITSELF
+// when NFC is unavailable, so one unlucky sample deletes the whole NFC screen
+// with nothing logged. That is how it first surfaced — reported as the screen
+// simply not being there.
+//
+// Deliberately free of native imports so the rule is testable on its own.
+// ---------------------------------------------------------------------------
+
+/**
+ * How long to keep asking before believing the answer is no.
+ *
+ * Two failures wear the same face and deserve different patience:
+ *
+ *   • `device_unsupported` — the native module answered, and the answer is that
+ *     this phone cannot read chips. Final; no amount of waiting changes it.
+ *   • `module_not_registered` — Nitro's registry has not produced the object
+ *     yet. That is OUR race, not the device's, and it resolves in milliseconds
+ *     once the registry lands.
+ *
+ * The window was 1200ms and the capability probe was still reporting false at
+ * 1500ms on real launches — with the rectangle detector failing alongside it,
+ * which has nothing to do with NFC hardware and so proves the registry, not the
+ * phone, was the problem. Three seconds costs a one-off wait only on devices
+ * that genuinely have no NFC, and buys back a step that was vanishing on
+ * perfectly capable ones.
+ */
+export const SETTLE_MS = 3000;
+/** Gap between samples. Short — the registry usually lands on the first retry. */
+export const POLL_MS = 120;
+
+export type NfcAvailability =
+  /** Still resolving — render nothing yet. */
+  | 'checking'
+  /** The chip step can run. */
+  | 'available'
+  /** The native module answered: this device cannot read chips. Skip. */
+  | 'unsupported'
+  /**
+   * The native module never registered. NOT the same as the device saying no —
+   * this is our own wiring failing, and it must not delete a verification step.
+   */
+  | 'module_missing';
+
+/**
+ * Asymmetric on purpose: a positive answer is trusted immediately, a negative
+ * one only after the window has elapsed.
+ *
+ * The two errors are not equally costly. Believing a false negative removes a
+ * verification step entirely; believing a premature positive costs nothing,
+ * because the read itself still has to succeed on its own merits.
+ */
+export function settleVerdict(
+  present: boolean,
+  elapsedMs: number,
+  reason?: 'module_not_registered' | 'device_unsupported' | null,
+): NfcAvailability {
+  if (present) return 'available';
+  if (elapsedMs < SETTLE_MS) return 'checking';
+  // Whose failure is it? A device that says it cannot read chips is a fact to
+  // act on. A module that never registered is OUR bug, and silently dropping
+  // the chip read to hide it is the worst of the three options — the user is
+  // told nothing and the verification quietly loses a factor.
+  return reason === 'device_unsupported' ? 'unsupported' : 'module_missing';
+}

package/src/screens/nfc/readErrorMessage.ts

@@ -0,0 +1,93 @@
+import { EmrtdSessionError } from '../../emrtd/session';
+
+// ---------------------------------------------------------------------------
+// What to tell the user when a chip read fails.
+//
+// NEVER the platform's own string. iOS produces things like
+//   Error Domain=NFCError Code=202 "Session invalidated unexpectedly"
+// which was being rendered verbatim on the screen: it tells the user nothing
+// they can act on, and reads as a crash rather than a retryable hiccup.
+//
+// Each message names the thing the user can actually change — where the phone
+// is, which document was scanned, whether to try again. Mirrors the Flutter
+// SDK's `_messageFor`.
+// ---------------------------------------------------------------------------
+
+/** Raw platform error shapes worth distinguishing, matched in the string. */
+const RAW_PATTERNS: Array<[RegExp, string]> = [
+  // 200 — the user dismissed the system sheet. Not a failure worth apologising
+  // for; just offer the read again.
+  [/Code=200\b/, 'Chip reading was cancelled. You can try again.'],
+  // 201 — the sheet timed out waiting for a document.
+  [
+    /Code=201\b/,
+    'No chip was found in time. Hold the top edge of your document flat against the back of your phone and try again.',
+  ],
+  // 202 — the session ended on its own. Almost always the document shifting out
+  // of range mid-read, which is exactly what the user should adjust.
+  [
+    /Code=202\b/,
+    'The connection to the chip dropped. Hold the document still against the back of your phone and try again.',
+  ],
+  // 203 — the NFC radio is busy elsewhere (Apple Pay, another reader).
+  [/Code=203\b/, 'The NFC reader is busy. Wait a moment and try again.'],
+  // 100–104 — the transceive-level family: how a physical drop surfaces while a
+  // command is in flight (tag lost / retry exceeded / response error / session
+  // invalidated / not connected). Same user remedy as 202: keep it still.
+  [
+    /Code=10[0-4]\b/,
+    'The connection to the chip dropped. Hold the document still against the back of your phone and try again.',
+  ],
+  // Android's IsoDep raises TagLostException("Tag was lost.") for the same
+  // physical case.
+  [
+    /tag was lost/i,
+    'The connection to the chip dropped. Hold the document still against the back of your phone and try again.',
+  ],
+  // Android's own detection timeout (see HybridMyazaEmrtd.kt) — the reader
+  // waited and no document ever arrived.
+  [
+    /no chip was detected/i,
+    'No chip was found in time. Hold the top edge of your document flat against the back of your phone and try again.',
+  ],
+];
+
+/**
+ * A human sentence for a failed chip read.
+ *
+ * `stageAtFailure` (when the caller tracked it) disambiguates the one code
+ * that means two different things: a 202 AFTER chip contact is the document
+ * shifting out of range, but a 202 while still `'waiting'` — before any chip
+ * was ever detected — means the READER itself failed to start (a wedged NFC
+ * daemon, or a build signed without the NFC entitlement). Telling that user
+ * to hold the document still sends them chasing a positioning problem that
+ * does not exist; a phone restart is what actually clears a wedged reader.
+ */
+export function readErrorMessage(err: unknown, stageAtFailure?: string): string {
+  if (stageAtFailure === 'waiting') {
+    const raw = err instanceof Error ? err.message : String(err ?? '');
+    if (/Code=202\b/.test(raw)) {
+      return "The NFC reader couldn't start. Restart your phone and try again.";
+    }
+  }
+  if (err instanceof EmrtdSessionError) {
+    switch (err.code) {
+      case 'bac_failed':
+        // The MRZ is check-digit validated, so this is not a typo — the chip
+        // belongs to a different document than the page that was scanned.
+        return "Couldn't unlock the chip with this document's details. Make sure you scanned the photo page of the same document.";
+      case 'select_failed':
+        return "This document's chip could not be opened. It may not be an electronic document.";
+      case 'read_failed':
+        return 'The chip moved out of range. Hold the document still against the back of your phone.';
+      default:
+        break;
+    }
+  }
+
+  const raw = err instanceof Error ? err.message : String(err ?? '');
+  for (const [pattern, message] of RAW_PATTERNS) {
+    if (pattern.test(raw)) return message;
+  }
+  return "Couldn't read the chip. Please try again.";
+}

package/src/screens/nfc/useChipPortrait.ts

@@ -0,0 +1,58 @@
+import { useEffect, useState } from 'react';
+
+import { decodeChipImage } from '../../emrtd';
+import { extractChipPortrait } from '../../emrtd/dg2';
+
+// ---------------------------------------------------------------------------
+// The chip's own portrait, made renderable.
+//
+// Seeing the photo the issuing government stored on the chip is a far stronger
+// confirmation than a tick — it is the one moment the user can check the
+// document against itself.
+//
+// Most passports store DG2 as JPEG 2000, which React Native cannot display. The
+// portrait was therefore being read, hash-verified against the signed security
+// object, and then discarded unshown on the majority of documents. The platform
+// has a decoder (ImageIO on iOS, BitmapFactory on Android), so the JP2 case is
+// handed to it and comes back as JPEG.
+//
+// Best-effort throughout: a portrait that cannot be decoded yields null and the
+// panel falls back to its generic mark. The chip read's verdict never depends
+// on whether the picture could be drawn.
+// ---------------------------------------------------------------------------
+
+export function useChipPortrait(dg2: string | undefined): string | null {
+  // JPEG needs no help — use it immediately rather than waiting a frame on a
+  // native round trip that has nothing to do.
+  const direct = extractChipPortrait(dg2);
+  const [decoded, setDecoded] = useState<string | null>(null);
+
+  useEffect(() => {
+    // Four ways to end up with no picture, and they need different fixes: the
+    // chip never gave up DG2 (SOD failed, so it was never requested — or the
+    // document lifted during the photo read, the longest transfer), DG2
+    // arrived in a format we did not recognise, the platform declined to
+    // decode it, or a direct-JPEG slice that does not actually render. Logged
+    // on EVERY path — the direct-JPEG case used to be silent, which made "no
+    // photo" undiagnosable from the field.
+    if (__DEV__) {
+      console.log('[myaza] chip portrait:', {
+        dg2Bytes: dg2 ? dg2.length : 0,
+        format: direct.format,
+        direct: direct.dataUri != null,
+      });
+    }
+    if (direct.dataUri || !direct.imageBase64) return;
+    let live = true;
+    // The extracted IMAGE, not the DG2 container — see ChipPortrait.imageBase64.
+    void decodeChipImage(direct.imageBase64).then((jpegBase64) => {
+      if (__DEV__) console.log('[myaza] chip portrait decode:', jpegBase64 ? 'ok' : 'declined');
+      if (live && jpegBase64) setDecoded(`data:image/jpeg;base64,${jpegBase64}`);
+    });
+    return () => {
+      live = false;
+    };
+  }, [dg2, direct.dataUri, direct.imageBase64]);
+
+  return direct.dataUri ?? decoded;
+}

package/src/screens/nfc/useNfcAvailability.ts

@@ -0,0 +1,82 @@
+import { useEffect, useState } from 'react';
+import { AppState, type AppStateStatus } from 'react-native';
+
+import { isNfcAvailable, nfcUnavailableReason } from '../../emrtd';
+import { POLL_MS, settleVerdict, type NfcAvailability } from './availability';
+
+export { settleVerdict, type NfcAvailability } from './availability';
+
+// ---------------------------------------------------------------------------
+// Is NFC actually unavailable, or has the native module simply not appeared yet?
+//
+// These two look identical at first render and mean opposite things. Nitro's
+// registry is populated asynchronously, so `isNfcAvailable()` can report false
+// for a moment on a phone that reads chips perfectly well — observed on a
+// device where three consecutive reloads reported true and the fourth false,
+// with no code change between them.
+//
+// That mattered because the chip step SKIPS ITSELF when NFC is unavailable. A
+// single unlucky read therefore deleted the whole NFC screen with nothing
+// logged and no way to get back to it — indistinguishable from a phone with no
+// radio, which is why it was first reported as "there was no NFC screen".
+//
+// So: don't decide on one sample. Re-check across a short window and only
+// conclude "unavailable" once it has stayed false the whole time. A device
+// that genuinely has no radio pays a fraction of a second before skipping; a
+// device that has one no longer loses the step to a race.
+// ---------------------------------------------------------------------------
+
+/**
+ * Availability as a settled verdict rather than a snapshot.
+ *
+ * `available` is returned as soon as it is true — the wait only ever applies to
+ * the negative answer, because that is the one that is destructive if wrong.
+ */
+export function useNfcAvailability(): NfcAvailability {
+  const [state, setState] = useState<NfcAvailability>(() =>
+    isNfcAvailable() ? 'available' : 'checking',
+  );
+
+  // A verdict reached while the app was not fully foregrounded is not a verdict.
+  //
+  // `NFCTagReaderSession.readingAvailable` is documented as a device capability,
+  // but iOS reports it FALSE while the app is backgrounded or mid-transition —
+  // and this flow sends users away and back (a passport arrives from a chat, the
+  // phone is unlocked mid-step). A device that reads chips perfectly well then
+  // answers "unsupported" once, permanently, for that mount.
+  //
+  // So a settled negative is re-opened when the app becomes active again. The
+  // positive is never re-examined: it cannot become wrong.
+  useEffect(() => {
+    const sub = AppState.addEventListener('change', (next: AppStateStatus) => {
+      if (next === 'active') setState((prev) => (prev === 'available' ? prev : 'checking'));
+    });
+    return () => sub.remove();
+  }, []);
+
+  useEffect(() => {
+    if (state !== 'checking') return;
+
+    let live = true;
+    const startedAt = Date.now();
+
+    const tick = (): void => {
+      if (!live) return;
+      const verdict = settleVerdict(isNfcAvailable(), Date.now() - startedAt, nfcUnavailableReason());
+      if (verdict !== 'checking') {
+        setState(verdict);
+        return;
+      }
+      timer = setTimeout(tick, POLL_MS);
+    };
+
+    let timer = setTimeout(tick, POLL_MS);
+    return () => {
+      live = false;
+      clearTimeout(timer);
+    };
+    // Runs once: after the first resolution the verdict is final for this mount.
+  }, [state]);
+
+  return state;
+}

package/src/screens/useFlashHole.ts

@@ -0,0 +1,105 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { View } from 'react-native';
+
+import type { FlashHole } from '../components/flashHoleGeometry';
+
+// ---------------------------------------------------------------------------
+// Where the preview circle actually sits on the physical screen.
+//
+// The flash paints in a full-screen modal over the sheet, so the hole has to be
+// given in window coordinates — it cannot be derived from the step's own
+// spacing constants.
+//
+// Measuring ONCE is not enough, and this is the subtle part: iOS stacks a
+// presenting sheet BACK when a modal is presented over it. The sheet scales
+// down and shifts, so the preview MOVES as a direct consequence of showing the
+// overlay that is measuring it. A single reading taken before or during that
+// animation describes a position the preview has already left — the observed
+// result was a hole both larger than the preview and higher up, off by exactly
+// the transform.
+//
+// So it re-measures until the answer stops changing, then stops. Nothing else
+// on screen moves during a flash (guidance banners are suppressed), so a
+// settled value stays valid for the rest of the sequence.
+//
+// Failure is not fatal: a null hole paints a solid flash, which still lights
+// the face. See FlashOverlay.
+// ---------------------------------------------------------------------------
+
+/** How often to re-read while the position is still settling. */
+const POLL_MS = 120;
+
+/**
+ * How long to keep watching. Comfortably longer than the sheet-stacking
+ * animation, and it stops early as soon as two readings agree.
+ */
+const SETTLE_WINDOW_MS = 1000;
+
+/** Sub-pixel differences are not movement. */
+const EPSILON = 0.5;
+
+function same(a: FlashHole | null, b: FlashHole): boolean {
+  return (
+    a !== null &&
+    Math.abs(a.x - b.x) < EPSILON &&
+    Math.abs(a.y - b.y) < EPSILON &&
+    Math.abs(a.size - b.size) < EPSILON
+  );
+}
+
+export function useFlashHole(active: boolean): {
+  ref: React.RefObject<View | null>;
+  hole: FlashHole | null;
+} {
+  const ref = useRef<View | null>(null);
+  const [hole, setHole] = useState<FlashHole | null>(null);
+  const latest = useRef<FlashHole | null>(null);
+
+  const measure = useCallback((onSettled: () => void) => {
+    const node = ref.current;
+    if (!node) return;
+    node.measureInWindow((x, y, width, height) => {
+      // A zero-sized measurement means the view is not laid out yet; punching a
+      // hole there would leave a gap in the wrong place, which is worse than
+      // painting solid.
+      if (!width || !height) return;
+      // The preview is a circle in a square box, so the smaller side is the
+      // diameter — guards against a reading taken mid-layout.
+      const next = { x, y, size: Math.min(width, height) };
+      if (same(latest.current, next)) {
+        onSettled();
+        return;
+      }
+      latest.current = next;
+      setHole(next);
+    });
+  }, []);
+
+  useEffect(() => {
+    if (!active) {
+      latest.current = null;
+      setHole(null);
+      return;
+    }
+
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    let stopped = false;
+    const stop = (): void => {
+      stopped = true;
+      if (timer) clearTimeout(timer);
+    };
+    const deadline = Date.now() + SETTLE_WINDOW_MS;
+
+    const tick = (): void => {
+      if (stopped) return;
+      measure(stop);
+      if (!stopped && Date.now() < deadline) timer = setTimeout(tick, POLL_MS);
+    };
+
+    // One frame's grace so the flash phase's own render has committed.
+    timer = setTimeout(tick, 0);
+    return stop;
+  }, [active, measure]);
+
+  return { ref, hole };
+}

package/src/screens/useFlashSequence.ts

@@ -0,0 +1,96 @@
+import { useEffect, useRef, useState } from 'react';
+
+import { runFlashSequence } from '../liveness/flashRunner';
+import { DEFAULT_FLASH_SEQUENCE, generateFlashSequence } from '../liveness/flashDetector';
+import type { FlashResult, Rgb } from '../liveness/flashDetector';
+
+// ---------------------------------------------------------------------------
+// Running the flash sequence from the liveness screen.
+//
+// Split out of LivenessStep (200-line rule). It starts once when the machine
+// asks, and tears down on unmount so a half-finished sequence can never leave
+// the screen painted a solid colour with no way back.
+// ---------------------------------------------------------------------------
+
+/** A sequence that could not run at all — unmeasured, which fails soft. */
+const UNMEASURED: FlashResult = {
+  passed: true,
+  score: 0,
+  matched: 0,
+  total: 0,
+  inconclusive: 0,
+  sequence: [],
+};
+
+export function useFlashSequence({
+  active,
+  shouldContinue,
+  sequenceLength,
+  readFaceRgb,
+  onComplete,
+}: {
+  /** True while the machine is in the flash phase. */
+  active: boolean;
+  /**
+   * Aborts mid-sequence when it returns false — a second face, or a swapped
+   * one. Finishing would measure a reflection off somebody who is not the
+   * subject, which is worse than no measurement at all.
+   */
+  shouldContinue?: () => boolean;
+  sequenceLength: number | undefined;
+  readFaceRgb: () => Rgb | null;
+  onComplete: (result: FlashResult) => void;
+}): { flashColor: string | null } {
+  const [flashColor, setFlashColor] = useState<string | null>(null);
+  const startedRef = useRef(false);
+  const liveRef = useRef(true);
+  // The callbacks are read through refs so the effect below never re-runs on
+  // their identity — restarting a sequence mid-flight would leave the screen
+  // painted and the counter of measured flashes wrong.
+  const completeRef = useRef(onComplete);
+  completeRef.current = onComplete;
+  const readRef = useRef(readFaceRgb);
+  readRef.current = readFaceRgb;
+  const continueRef = useRef(shouldContinue);
+  continueRef.current = shouldContinue;
+
+  useEffect(
+    () => () => {
+      liveRef.current = false;
+    },
+    [],
+  );
+
+  useEffect(() => {
+    // Re-arm when the phase leaves flash. The guard exists to stop the sequence
+    // restarting while it is ALREADY running (the effect re-runs whenever the
+    // screen re-renders), but it was never cleared — so a retake found it still
+    // set from the first attempt, returned immediately, and left the machine
+    // parked in the flash phase with nothing driving it. The step hung with no
+    // error, because from its point of view a sequence was still in flight.
+    if (!active) {
+      startedRef.current = false;
+      return;
+    }
+    if (startedRef.current) return;
+    startedRef.current = true;
+    void runFlashSequence(
+      {
+        setColor: setFlashColor,
+        readFaceRgb: () => readRef.current(),
+        isActive: () => liveRef.current && (continueRef.current?.() ?? true),
+      },
+      generateFlashSequence(sequenceLength ?? DEFAULT_FLASH_SEQUENCE),
+    )
+      .then((result) => completeRef.current(result))
+      .catch(() => {
+        // A failed sequence is a MISSING measurement, not a failed check — the
+        // user is not at fault for a camera hiccup, and the server re-analyses
+        // the recorded video regardless.
+        setFlashColor(null);
+        completeRef.current(UNMEASURED);
+      });
+  }, [active, sequenceLength]);
+
+  return { flashColor };
+}