@myazahq/kyc-sdk-react-native 2.0.2 → 2.2.0

package/src/screens/consent/model.ts

@@ -0,0 +1,109 @@
+import type { MyazaKYCConfig } from '../../types/config';
+import type { IconName } from '../../components/Icon';
+import { fillTokens } from '../../utils/tokens';
+import { hasEmailVerificationStep, hasPhoneVerificationStep } from '../../config/contact';
+import {
+  hasApplicantVerification,
+  hasBusinessDocumentsStep,
+  hasKeyPeopleCollection,
+} from '../../config/businessSteps';
+
+// ---------------------------------------------------------------------------
+// What the consent screen SAYS, derived from what the flow actually DOES.
+//
+// Mirrors the web SDK's ConsentStep derivations exactly — a KYB flow gets the
+// business title, description, step list and data clause, never the identity
+// copy ("verify your government-issued ID" on a registry-lookup flow is simply
+// false). The biometric sentence is derived, not assumed: claiming facial
+// recognition on a flow with no face capture would be a false statement in a
+// legal notice, and recording video without saying so is the failure that
+// actually carries risk.
+//
+// Pure (no RN imports beyond types) so it is unit-testable next to the web
+// SDK's consent-disclosure tests. The screen just renders this.
+// ---------------------------------------------------------------------------
+
+export interface ConsentProcessStep {
+  icon: IconName;
+  label: string;
+}
+
+export interface ConsentModel {
+  isBusiness: boolean;
+  title: string;
+  description: string;
+  steps: ConsentProcessStep[];
+  /** Drives the "facial recognition" sentence in the legal notice. */
+  capturesFace: boolean;
+  /** Drives the "recording this session" sentence. */
+  recordsVideo: boolean;
+}
+
+const DEFAULT_DESCRIPTION =
+  'We need to verify your identity to comply with regulatory requirements. This process is quick and secure.';
+
+const DEFAULT_BUSINESS_DESCRIPTION =
+  'We need to verify your business to comply with regulatory requirements. This process is quick and secure.';
+
+export function buildConsentModel(config: MyazaKYCConfig): ConsentModel {
+  const isBusiness = config.subjectType === 'business';
+  const firstName = config.userData?.firstName ?? '';
+
+  const defaultTitle = firstName
+    ? `Welcome, ${firstName}`
+    : isBusiness
+      ? 'Business Verification'
+      : 'Identity Verification';
+  const title = config.consent?.title
+    ? fillTokens(config.consent.title, config.userData)
+    : defaultTitle;
+  const description = config.consent?.description
+    ? fillTokens(config.consent.description, config.userData)
+    : isBusiness
+      ? DEFAULT_BUSINESS_DESCRIPTION
+      : DEFAULT_DESCRIPTION;
+
+  // A business flow captures a face only when the applicant verifies their own
+  // identity in-flow; an individual flow whenever the selfie step is on.
+  const capturesFace = isBusiness
+    ? hasApplicantVerification(config.business)
+    : config.enableSelfie !== false;
+  const recordsVideo = capturesFace || (!isBusiness && config.enableDocumentCapture !== false);
+
+  const steps: ConsentProcessStep[] = isBusiness
+    ? [
+        { icon: 'building-2', label: 'Collect your business registration details' },
+        { icon: 'badge-check', label: 'Verify your business against the official registry' },
+      ]
+    : [
+        { icon: 'badge-check', label: 'Verify your government-issued ID' },
+        { icon: 'user', label: 'Collect basic personal information' },
+      ];
+  if (hasEmailVerificationStep(config.emailVerification) || hasPhoneVerificationStep(config.phoneVerification)) {
+    steps.push({ icon: 'lock', label: 'Confirm your contact details with a one-time code' });
+  }
+  if (!isBusiness && config.enableDocumentCapture !== false) {
+    steps.push({ icon: 'scan-line', label: 'Capture a photo of your ID document' });
+  }
+  // Chip-capable IDs additionally read the document's NFC chip — listed when
+  // the flow enables NFC so the user knows to have the physical document to
+  // hand (a non-chip ID simply skips the step). Individual flows only; a KYB
+  // config can't carry `nfc`.
+  if (!isBusiness && config.nfc?.enabled) {
+    steps.push({ icon: 'nfc', label: 'Scan your document’s security chip (NFC)' });
+  }
+  if (!isBusiness && config.enableSelfie !== false) {
+    steps.push({ icon: 'scan-face', label: 'Take a selfie for facial verification' });
+  }
+  if (isBusiness && hasKeyPeopleCollection(config.business)) {
+    steps.push({ icon: 'users', label: "List the company's directors and owners" });
+  }
+  if (isBusiness && hasBusinessDocumentsStep(config.business)) {
+    steps.push({ icon: 'file-text', label: 'Upload supporting business documents' });
+  }
+  if (isBusiness && hasApplicantVerification(config.business)) {
+    steps.push({ icon: 'scan-face', label: 'Verify your own identity' });
+  }
+
+  return { isBusiness, title, description, steps, capturesFace, recordsVideo };
+}

package/src/screens/document/CameraPhase.tsx

@@ -0,0 +1,150 @@
+import React from 'react';
+import { Modal, Pressable, View } from 'react-native';
+
+import { spacing } from '../../config/theme';
+import { useTheme } from '../../components/runtime';
+import { MyazaText } from '../../components/Typography';
+import { Icon } from '../../components/Icon';
+import { CameraViewfinder } from '../../components/CameraViewfinder';
+import { RequiredPill } from './RequiredPill';
+import type { MrzScan } from '../../mrz/parse';
+
+export interface CameraPhaseProps {
+  isBack: boolean;
+  /** True once the live preview is actually on screen — drives immersive mode. */
+  cameraLive: boolean;
+  active: boolean;
+  documentLabel: string;
+  guideAspect: number;
+  isTwoSided: boolean;
+  busy: boolean;
+  allowUpload: boolean;
+  country: string;
+  idType?: string;
+  mrzAlreadyCaptured: boolean;
+  onMrz: (scan: MrzScan) => void;
+  onCapture: (uri: string, videoPath: string | null, viewAr: number) => void;
+  onUpload: () => void;
+  onBack: () => void;
+  /** Safe-area bottom inset for the full-bleed camera's controls. */
+  bottomInset?: number;
+}
+
+/**
+ * The document-capture camera, in both of its shapes.
+ *
+ * IMMERSIVE is the normal one: the camera owns the screen, because the sheet's
+ * header, padding and scroll view are exactly what force a small viewfinder on
+ * a short phone — and a camera you have to scroll to is a broken camera. The
+ * pill and helper text go with it; the viewfinder carries that information as
+ * live overlays instead.
+ *
+ * The framed shape below it is what renders in the brief window while the OS
+ * permission prompt is open, where there is no live preview to hand the screen
+ * to yet.
+ */
+export function CameraPhase(p: CameraPhaseProps): React.ReactElement {
+  const { colors } = useTheme();
+
+  const viewfinder = (extra: {
+    fill?: boolean;
+    onBack?: () => void;
+    onUpload?: (() => void) | null;
+    bottomInset?: number;
+  }) => (
+    <CameraViewfinder
+      active={p.active}
+      side={p.isBack ? 'back' : 'front'}
+      documentLabel={p.documentLabel}
+      guideAspect={p.guideAspect}
+      onCapture={p.onCapture}
+      busy={p.busy}
+      // Auto-capture needs to know WHICH document it is looking for — without
+      // this it would fire on any text-dense frame.
+      country={p.country}
+      idType={p.idType}
+      // Banking the MRZ from a live frame is what spares the user scanning the
+      // same passport again at the chip step. Only the front carries one.
+      onMrz={p.isBack ? undefined : p.onMrz}
+      mrzAlreadyCaptured={p.mrzAlreadyCaptured}
+      {...extra}
+    />
+  );
+
+  if (p.cameraLive) {
+    // A FULL-SCREEN modal of its own, not just full-bleed content.
+    //
+    // The SDK's sheet is an iOS pageSheet: inset from the top, rounded, with
+    // the card visible behind it. Filling that still leaves the camera in a
+    // letterboxed card — and a document held at arm's length needs every pixel.
+    //
+    // Presenting it as a Modal rather than switching the sheet's own
+    // presentationStyle matters: a Modal's children stay in the SAME React
+    // tree, so this step keeps its state (the acknowledged primer, the captured
+    // front) — where changing presentationStyle on a live modal remounts the
+    // subtree and loses it. It closes when the capture finishes, and the sheet
+    // is exactly as it was.
+    return (
+      <Modal
+        visible
+        animationType="fade"
+        presentationStyle="fullScreen"
+        statusBarTranslucent
+        onRequestClose={p.onBack}
+      >
+        <View style={{ flex: 1, backgroundColor: '#000000' }}>
+          {viewfinder({
+            fill: true,
+            onBack: p.onBack,
+            // The gallery escape stays reachable full-screen: it is the
+            // fallback when the camera will not read a worn or laminated
+            // document.
+            onUpload: p.allowUpload ? p.onUpload : null,
+            bottomInset: p.bottomInset ?? 0,
+          })}
+        </View>
+      </Modal>
+    );
+  }
+
+  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' }}>
+            Flip the card over and scan the other side
+          </MyazaText>
+        </View>
+      ) : null}
+      <View style={{ height: spacing.md }} />
+      {viewfinder({})}
+      {!p.busy ? (
+        <>
+          <View style={{ height: spacing.md }} />
+          <MyazaText variant="bodySmall" style={{ textAlign: 'center' }}>
+            Tap the button to capture manually
+          </MyazaText>
+          {p.allowUpload ? (
+            <Pressable onPress={p.onUpload} style={{ marginTop: spacing.sm }}>
+              <View style={{ flexDirection: 'row', alignItems: 'center', justifyContent: 'center' }}>
+                <MyazaText variant="bodySmall">Having trouble? </MyazaText>
+                <Icon name="upload" size={14} color={colors.primary} />
+                <View style={{ width: 4 }} />
+                <MyazaText variant="bodySmall" color={colors.primary} style={{ fontWeight: '700' }}>
+                  Upload a photo instead
+                </MyazaText>
+              </View>
+            </Pressable>
+          ) : null}
+        </>
+      ) : null}
+    </View>
+  );
+}

package/src/screens/document/RequiredPill.tsx

@@ -0,0 +1,60 @@
+import React from 'react';
+import { View } from 'react-native';
+
+import { radius, spacing } from '../../config/theme';
+import { useTheme } from '../../components/runtime';
+import { MyazaText } from '../../components/Typography';
+import { Icon } from '../../components/Icon';
+
+// "Required: {label}" pill with optional side badge + step label — mirrors the
+// Flutter SDK's _RequiredPill on the capture screen.
+export function RequiredPill({
+  documentLabel,
+  sideBadge,
+  stepLabel,
+}: {
+  documentLabel: string;
+  sideBadge?: string;
+  stepLabel?: string;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <View style={{ flexDirection: 'row', alignItems: 'center' }}>
+      <View
+        style={{
+          flex: 1,
+          flexDirection: 'row',
+          alignItems: 'center',
+          flexWrap: 'wrap',
+          borderWidth: 1,
+          borderColor: `${colors.primary}33`,
+          backgroundColor: `${colors.primary}0D`,
+          borderRadius: radius.md,
+          paddingHorizontal: spacing.sm + 4,
+          paddingVertical: spacing.sm,
+        }}
+      >
+        <Icon name="credit-card" size={16} color={colors.primary} />
+        <View style={{ width: 8 }} />
+        <MyazaText variant="bodySmall" color={colors.primary} style={{ fontWeight: '600' }}>
+          Required:{' '}
+        </MyazaText>
+        <MyazaText variant="bodySmall" color={colors.primary} style={{ flexShrink: 1 }}>
+          {documentLabel}
+        </MyazaText>
+        {sideBadge ? (
+          <View style={{ backgroundColor: `${colors.primary}26`, borderRadius: radius.full, paddingHorizontal: 8, paddingVertical: 2, marginLeft: 8 }}>
+            <MyazaText variant="bodySmall" color={colors.primary} style={{ fontWeight: '600', fontSize: 11 }}>
+              {sideBadge}
+            </MyazaText>
+          </View>
+        ) : null}
+      </View>
+      {stepLabel ? (
+        <MyazaText variant="bodySmall" color={colors.textMuted} style={{ marginLeft: spacing.sm }}>
+          {stepLabel}
+        </MyazaText>
+      ) : null}
+    </View>
+  );
+}

package/src/screens/liveness/LightingBanner.tsx

@@ -0,0 +1,50 @@
+import React, { useEffect, useRef } from 'react';
+import { Animated, Easing, View } from 'react-native';
+
+import { spacing, radius } from '../../config/theme';
+import { MyazaText } from '../../components/Typography';
+import { Icon } from '../../components/Icon';
+import { AMBER_50, AMBER_200, AMBER_800 } from './constants';
+
+// ---------------------------------------------------------------------------
+// Lighting warning — 1:1 with the Flutter `_LightingWarningBanner`: amber-50
+// background, amber-200 border, amber-800 lightbulb + text, fading and sliding
+// in over ~300ms.
+// ---------------------------------------------------------------------------
+
+export function LightingBanner({ text }: { text: string }): React.ReactElement {
+  const anim = useRef(new Animated.Value(0)).current;
+  useEffect(() => {
+    Animated.timing(anim, { toValue: 1, duration: 300, easing: Easing.out(Easing.cubic), useNativeDriver: true }).start();
+  }, [anim]);
+  return (
+    <Animated.View
+      style={{
+        alignSelf: 'stretch',
+        opacity: anim,
+        transform: [{ translateY: anim.interpolate({ inputRange: [0, 1], outputRange: [-8, 0] }) }],
+      }}
+    >
+      <View
+        style={{
+          flexDirection: 'row',
+          alignItems: 'flex-start',
+          gap: spacing.sm,
+          borderRadius: radius.sm,
+          borderWidth: 1,
+          borderColor: AMBER_200,
+          backgroundColor: AMBER_50,
+          paddingHorizontal: spacing.sm + 4,
+          paddingVertical: 10,
+        }}
+      >
+        <Icon name="lightbulb" size={16} color={AMBER_800} />
+        <MyazaText variant="bodySmall" color={AMBER_800} style={{ flexShrink: 1, lineHeight: 17 }}>
+          {text}
+        </MyazaText>
+      </View>
+    </Animated.View>
+  );
+}
+
+/** The single guidance string + tone to show under the camera. */

package/src/screens/liveness/LivenessOutcome.tsx

@@ -0,0 +1,109 @@
+import React from 'react';
+import { 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 { SelfiePreview } from './SelfiePreview';
+import type { SelfieUpload } from './useSelfieUpload';
+import type { LivenessFailureReason } from '../../liveness/types';
+
+// ---------------------------------------------------------------------------
+// The two ways the liveness step ends.
+//
+// COMPLETE is not "done": the selfie is uploading behind the preview, so
+// Continue stays disabled until the media id exists. A failed upload keeps the
+// captured selfie and offers a retry rather than sending the user back through
+// the whole check for a network blip.
+//
+// FAILED mirrors the Flutter failed view — a centred red line and a full-width
+// "Try Again", no icon.
+// ---------------------------------------------------------------------------
+
+export function LivenessComplete({
+  selfieUri,
+  upload,
+  onRetake,
+  onContinue,
+}: {
+  selfieUri: string;
+  upload: SelfieUpload;
+  onRetake: () => void;
+  onContinue: () => void;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  const { uploading, uploadError, retryInfo, selfieIdRef, videoPathRef, uploadSelfieAndVideo } =
+    upload;
+  return (
+      <View>
+        <SelfiePreview uri={selfieUri} uploading={uploading && !uploadError} />
+        {retryInfo && uploading ? (
+          <MyazaText variant="bodySmall" color={colors.warning} style={{ textAlign: 'center', marginTop: spacing.sm }}>
+            {`Upload failed — retrying (${retryInfo.attempt}/${retryInfo.total})…`}
+          </MyazaText>
+        ) : null}
+        <View style={{ height: spacing.md }} />
+        {uploadError ? (
+          // The error message itself is shown as a top toast; keep a retry action.
+          <MyazaButton
+            label="Try Again"
+            // 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)}
+          />
+        ) : (
+          <View style={{ flexDirection: 'row', gap: spacing.md }}>
+            <View style={{ flex: 1 }}>
+              <MyazaButton
+                label="Retake"
+                variant="outline"
+                leadingIcon="refresh"
+                disabled={uploading}
+                onPress={onRetake}
+              />
+            </View>
+            <View style={{ flex: 1 }}>
+              {/* No spinner on Continue, deliberately — 1:1 with Flutter.
+              
+                  There is already ONE progress indicator on this screen, inside
+                  the selfie frame, and it is the truthful place for it: what is
+                  loading is the photo, not the button. A second spinner on the
+                  action implies the tap did something, when in fact the upload
+                  started the moment the selfie appeared and the button has been
+                  disabled since. Disabled-and-quiet says "not yet"; a spinner
+                  says "working on your request", which would be a lie. */}
+              <MyazaButton
+                label="Continue"
+                disabled={uploading || !selfieIdRef.current}
+                onPress={onContinue}
+              />
+            </View>
+          </View>
+        )}
+      </View>
+  );
+}
+
+export function LivenessFailed({
+  reason,
+  onRetry,
+}: {
+  reason: LivenessFailureReason | null;
+  onRetry: () => void;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+      <View style={{ alignItems: 'center', justifyContent: 'center', paddingVertical: spacing.xl, gap: spacing.lg }}>
+        <MyazaText variant="bodyMedium" color={colors.error} style={{ textAlign: 'center', fontWeight: '500' }}>
+          {reason === 'timeout'
+            ? "Time's up. Let's try again."
+            : 'Face lost. Please try again.'}
+        </MyazaText>
+        <View style={{ alignSelf: 'stretch' }}>
+          <MyazaButton label="Try Again" onPress={onRetry} />
+        </View>
+      </View>
+  );
+}

package/src/screens/liveness/ProgressDots.tsx

@@ -0,0 +1,67 @@
+import React from 'react';
+import { View } from 'react-native';
+
+import { spacing } from '../../config/theme';
+import { useTheme } from '../../components/runtime';
+import Svg, { Path } from 'react-native-svg';
+
+import { Icon } from '../../components/Icon';
+import { MyazaText } from '../../components/Typography';
+
+// ---------------------------------------------------------------------------
+// Numbered progress dots with connectors.
+//
+// One dot per step the user actually performs — the gestures AND the flash. The
+// flash was omitted for a long time, so in 'both' mode the indicator read as
+// finished while the flash was still to come, and in flash-only mode it showed
+// no steps at all.
+// ---------------------------------------------------------------------------
+
+export function ProgressDots({
+  total,
+  completed,
+  active,
+}: {
+  total: number;
+  completed: number;
+  active: boolean;
+}): React.ReactElement {
+  const { colors } = useTheme();
+  return (
+    <View style={{ flexDirection: 'row', alignItems: 'center', justifyContent: 'center' }}>
+      {Array.from({ length: total }).map((_, i) => {
+        const state: 'passed' | 'active' | 'pending' =
+          i < completed ? 'passed' : i === completed && active ? 'active' : 'pending';
+        return (
+          <React.Fragment key={i}>
+            <View
+              style={{
+                width: 28,
+                height: 28,
+                borderRadius: 14,
+                alignItems: 'center',
+                justifyContent: 'center',
+                backgroundColor: state === 'passed' ? colors.success : state === 'active' ? colors.background : colors.gray300,
+                borderWidth: state === 'active' ? 2 : 0,
+                borderColor: colors.success,
+              }}
+            >
+              {state === 'passed' ? (
+                <Svg width={14} height={14} viewBox="0 0 24 24">
+                  <Path d="M5 13l4 4L19 7" fill="none" stroke="#FFFFFF" strokeWidth={3} strokeLinecap="round" strokeLinejoin="round" />
+                </Svg>
+              ) : (
+                <MyazaText variant="bodySmall" color={state === 'active' ? colors.success : colors.textMuted} style={{ fontWeight: '700' }}>
+                  {String(i + 1)}
+                </MyazaText>
+              )}
+            </View>
+            {i < total - 1 ? (
+              <View style={{ width: 28, height: 2, backgroundColor: i < completed ? colors.success : colors.gray300 }} />
+            ) : null}
+          </React.Fragment>
+        );
+      })}
+    </View>
+  );
+}

package/src/screens/liveness/SelfiePreview.tsx

@@ -0,0 +1,39 @@
+import React from 'react';
+import { ActivityIndicator, Image, View } from 'react-native';
+
+import { spacing } from '../../config/theme';
+import { useTheme } from '../../components/runtime';
+import { MyazaText } from '../../components/Typography';
+import { MyazaPulseLoader } from '../../components/MyazaPulseLoader';
+import { StyleAbsFill } from './constants';
+
+// ---------------------------------------------------------------------------
+// The captured selfie, shown back while it uploads.
+// ---------------------------------------------------------------------------
+
+export function SelfiePreview({ uri, uploading }: { uri: string; uploading?: 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' }}>
+        {/* 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" />
+        {/* 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' }]}>
+            <MyazaPulseLoader size={64} />
+          </View>
+        ) : null}
+      </View>
+      <View style={{ height: spacing.md }} />
+      <MyazaText variant="heading3" style={{ textAlign: 'center' }}>
+        Looking good!
+      </MyazaText>
+      <MyazaText variant="bodySmall" color={colors.textSecondary} style={{ textAlign: 'center' }}>
+        Tap Continue to submit, or Retake to try again.
+      </MyazaText>
+    </View>
+  );
+}

package/src/screens/liveness/constants.ts

@@ -0,0 +1,31 @@
+// ---------------------------------------------------------------------------
+// Layout constants and timings shared across the liveness step's pieces.
+// ---------------------------------------------------------------------------
+
+export const StyleAbsFill = {
+  position: 'absolute' as const,
+  top: 0,
+  left: 0,
+  right: 0,
+  bottom: 0,
+};
+
+/**
+ * How long to wait for the face to reappear before abandoning a capture.
+ *
+ * Generous: a full-screen colour flash can make a face momentarily
+ * undetectable, and giving up on one dropped frame would restart a sequence the
+ * user is still correctly inside.
+ */
+export const FRESH_FACE_TIMEOUT_MS = 1500;
+
+/**
+ * Reserved height of the instruction line. Fixed so the circle does not jump as
+ * the wording changes.
+ */
+export const INSTRUCTION_HEIGHT = 26;
+
+// Lighting warning palette — 1:1 with the Flutter `_LightingWarningBanner`.
+export const AMBER_50 = '#FFFBEB';
+export const AMBER_200 = '#FDE68A';
+export const AMBER_800 = '#92400E';

package/src/screens/liveness/index.ts

@@ -0,0 +1,8 @@
+// Barrel for the liveness step's pieces, so LivenessStep imports one path.
+export { StyleAbsFill, FRESH_FACE_TIMEOUT_MS, INSTRUCTION_HEIGHT } from './constants';
+export { LightingBanner } from './LightingBanner';
+export { resolveGuidance } from './resolveGuidance';
+export { ProgressDots } from './ProgressDots';
+export { SelfiePreview } from './SelfiePreview';
+export { useSelfieUpload } from './useSelfieUpload';
+export { LivenessComplete, LivenessFailed } from './LivenessOutcome';

package/src/screens/liveness/resolveGuidance.ts

@@ -0,0 +1,27 @@
+import {
+  lightingGuidanceText,
+  positionGuidanceText,
+  type useLiveness,
+} from '../../liveness/useLiveness';
+
+// ---------------------------------------------------------------------------
+// Which single line the step shows, and in what tone.
+//
+// Ordered by severity: a warning the user must act on outranks the current
+// instruction, so "move closer" is never buried under "nod your head".
+// ---------------------------------------------------------------------------
+
+export function resolveGuidance(l: ReturnType<typeof useLiveness>): { text: string; tone: 'normal' | 'error' } {
+  if (l.multipleFaces) return { text: l.instruction, tone: 'error' };
+  // Lighting is shown in its own banner (below), not as the main instruction.
+  if (l.phase === 'positioning' && !l.faceDetected) {
+    return { text: 'Position your face in the circle', tone: 'normal' };
+  }
+  if (l.positionGuidance) return { text: positionGuidanceText(l.positionGuidance), tone: 'error' };
+  if (l.wrongGesture) return { text: 'Wrong gesture — follow the prompt', tone: 'error' };
+  return { text: l.instruction, tone: 'normal' };
+}
+
+// Numbered progress steps with connectors — mirrors the web/Flutter SDKs:
+// passed = solid green + checkmark, active = green-outlined number, pending =
+// grey number. `active` marks the current (completed-th) step as in-progress.