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

package/src/screens/consent/model.ts

@@ -1,7 +1,11 @@
+import { configScope, isFaceScope } from '../../lib/scope';
 import type { MyazaKYCConfig } from '../../types/config';
 import type { IconName } from '../../components/Icon';
 import { fillTokens } from '../../utils/tokens';
 import { hasEmailVerificationStep, hasPhoneVerificationStep } from '../../config/contact';
+import { hasActiveQuestionnaire } from '../../config/questionnaire';
+import { hasProofOfAddressStep } from '../../config/proofOfAddress';
+import { hasAddressCollectionStep } from '../../config/addressCollection';
 import {
   hasApplicantVerification,
   hasBusinessDocumentsStep,
@@ -45,15 +49,55 @@ const DEFAULT_DESCRIPTION =
 const DEFAULT_BUSINESS_DESCRIPTION =
   'We need to verify your business to comply with regulatory requirements. This process is quick and secure.';
 
+const SCOPE_TITLES: Record<string, string> = {
+  address: 'Address Verification',
+  'biometric-authentication': 'Face Check',
+  'biometric-enrollment': 'Face Enrolment',
+  questionnaire: 'A Few Questions',
+  contact: 'Confirm Your Contact Details',
+};
+
+const SCOPE_DESCRIPTIONS: Record<string, string> = {
+  address:
+    'We need to confirm your home address to comply with regulatory requirements. This process is quick and secure.',
+  'biometric-authentication':
+    'A quick face check confirms it is really you. This takes a few seconds and is secure.',
+  'biometric-enrollment':
+    'A quick selfie sets up face checks for next time, so you will not have to prove your identity again. This takes a few seconds and is secure.',
+  questionnaire:
+    'A few questions keep your account details up to date and help us comply with regulatory requirements.',
+  contact:
+    'We need to re-confirm the email address and phone number on your account. This takes a minute and is secure.',
+};
+
+const SCOPE_BULLETS: Record<string, ConsentProcessStep[]> = {
+  address: [
+    { icon: 'map-pin-house', label: 'Pin your home address on a map' },
+    { icon: 'badge-check', label: 'Confirm the details only you can know' },
+  ],
+  'biometric-authentication': [
+    { icon: 'scan-face', label: 'Take a quick selfie with liveness checks' },
+    { icon: 'badge-check', label: 'We match it against your enrolled face' },
+  ],
+  'biometric-enrollment': [
+    { icon: 'scan-face', label: 'Take a quick selfie with liveness checks' },
+    { icon: 'badge-check', label: 'It becomes your face check for next time' },
+  ],
+  questionnaire: [{ icon: 'badge-check', label: 'Answer a few short questions' }],
+  contact: [{ icon: 'lock', label: 'Confirm your contact details with a one-time code' }],
+};
+
 export function buildConsentModel(config: MyazaKYCConfig): ConsentModel {
   const isBusiness = config.subjectType === 'business';
+  const scope = isBusiness ? null : configScope(config);
+  const faceScope = isFaceScope(scope);
   const firstName = config.userData?.firstName ?? '';
 
   const defaultTitle = firstName
     ? `Welcome, ${firstName}`
     : isBusiness
       ? 'Business Verification'
-      : 'Identity Verification';
+      : SCOPE_TITLES[scope ?? ''] ?? 'Identity Verification';
   const title = config.consent?.title
     ? fillTokens(config.consent.title, config.userData)
     : defaultTitle;
@@ -61,40 +105,65 @@ export function buildConsentModel(config: MyazaKYCConfig): ConsentModel {
     ? fillTokens(config.consent.description, config.userData)
     : isBusiness
       ? DEFAULT_BUSINESS_DESCRIPTION
-      : DEFAULT_DESCRIPTION;
+      : SCOPE_DESCRIPTIONS[scope ?? ''] ?? 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);
+    : faceScope || (!scope && config.enableSelfie !== false);
+  const recordsVideo =
+    capturesFace || (!isBusiness && !scope && 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' },
       ]
-    : [
+    : scope
+      ? // COPY the catalogue entry: pushing below would otherwise mutate the
+        // shared constant, appending one more bullet per re-render.
+        [...(SCOPE_BULLETS[scope] ?? [])]
+      : [
         { 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' });
+  // On the CONTACT scope the catalogue bullet already says this — appending
+  // the generic line showed "confirm your contact details" twice the moment
+  // both channels were on.
+  const hasEmail = hasEmailVerificationStep(config.emailVerification);
+  const hasPhone = hasPhoneVerificationStep(config.phoneVerification);
+  if (scope !== 'contact' && (hasEmail || hasPhone)) {
+    const what = hasEmail && hasPhone ? 'email and phone number' : hasEmail ? 'email' : 'phone number';
+    steps.push({ icon: 'lock', label: `Confirm your ${what} with a one-time code` });
   }
-  if (!isBusiness && config.enableDocumentCapture !== false) {
+  if (!isBusiness && !scope && 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) {
+  if (!isBusiness && !scope && config.nfc?.enabled) {
     steps.push({ icon: 'nfc', label: 'Scan your document’s security chip (NFC)' });
   }
-  if (!isBusiness && config.enableSelfie !== false) {
+  if (!isBusiness && !scope && config.enableSelfie !== false) {
     steps.push({ icon: 'scan-face', label: 'Take a selfie for facial verification' });
   }
+  // Post-capture features, in the order the flow runs them. Each is gated on
+  // the flow that actually asks for it, and skipped where a scope's own
+  // catalogue bullet already covers the same step.
+  if (!isBusiness && hasProofOfAddressStep(config.proofOfAddress)) {
+    steps.push({ icon: 'file-text', label: 'Upload a proof of address document' });
+  }
+  if (scope !== 'address' && hasAddressCollectionStep(config.addressCollection)) {
+    steps.push({ icon: 'map-pin-house', label: 'Pin your address on a map' });
+  }
+  // The step-order predicate, not a raw fields check: a questionnaire with
+  // questions but enabled: false never runs, so it must not be promised.
+  if (scope !== 'questionnaire' && hasActiveQuestionnaire(config.questionnaire)) {
+    steps.push({ icon: 'badge-check', label: 'Answer a few short questions' });
+  }
   if (isBusiness && hasKeyPeopleCollection(config.business)) {
     steps.push({ icon: 'users', label: "List the company's directors and owners" });
   }

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

@@ -27,7 +27,8 @@ export function LivenessComplete({
   onRetake,
   onContinue,
 }: {
-  selfieUri: string;
+  /** Null on a restored session: the mediaId survived, the local file did not. */
+  selfieUri: string | null;
   upload: SelfieUpload;
   onRetake: () => void;
   onContinue: () => void;
@@ -40,7 +41,7 @@ export function LivenessComplete({
         <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})…`}
+            {`Upload failed, retrying (${retryInfo.attempt}/${retryInfo.total})`}
           </MyazaText>
         ) : null}
         <View style={{ height: spacing.md }} />
@@ -51,7 +52,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,24 @@ 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 }: { uri: string | null; 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' }}>
+      <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' }]}>

package/src/screens/liveness/ShutterFlash.tsx

@@ -0,0 +1,25 @@
+import React, { useEffect, useRef } from 'react';
+import { Animated, Easing } from 'react-native';
+import { StyleAbsFill } from './constants';
+
+// The shutter: a white flash over the camera circle as the still is taken,
+// fading out over the beat the ring takes to close and go green. Mirrors the
+// web SDK's animate-capture-flash (600ms ease-out). Core Animated on the
+// native driver — opacity only — is the same recipe LightingBanner uses.
+export function ShutterFlash() {
+  const opacity = useRef(new Animated.Value(0.85)).current;
+  useEffect(() => {
+    Animated.timing(opacity, {
+      toValue: 0,
+      duration: 600,
+      easing: Easing.out(Easing.cubic),
+      useNativeDriver: true,
+    }).start();
+  }, [opacity]);
+  return (
+    <Animated.View
+      pointerEvents="none"
+      style={[StyleAbsFill, { backgroundColor: '#FFFFFF', opacity }]}
+    />
+  );
+}

package/src/screens/liveness/index.ts

@@ -3,6 +3,10 @@ export { StyleAbsFill, FRESH_FACE_TIMEOUT_MS, INSTRUCTION_HEIGHT } from './const
 export { LightingBanner } from './LightingBanner';
 export { resolveGuidance } from './resolveGuidance';
 export { ProgressDots } from './ProgressDots';
+export { CaptureRing } from './CaptureRing';
+export { ShutterFlash } from './ShutterFlash';
 export { SelfiePreview } from './SelfiePreview';
 export { useSelfieUpload } from './useSelfieUpload';
 export { LivenessComplete, LivenessFailed } from './LivenessOutcome';
+export { LivenessCamera } from './LivenessCamera';
+export { LivenessHandover, useSelfieAutoAdvance } from './LivenessHandover';

package/src/screens/liveness/useSelfieUpload.ts

@@ -44,12 +44,29 @@ export function useSelfieUpload(): SelfieUpload {
   const config = useKycConfig();
   const api = useKyc((s) => s.api);
   const setMediaId = useKyc((s) => s.setMediaId);
+  const setSelfiePreview = useKyc((s) => s.setSelfiePreview);
+  // The store-side progress report. The liveness step may hand over before
+  // the upload lands (the biometric scopes hide the review), so the submitted
+  // step waits on THIS rather than on this hook's local state.
+  const setSelfieUpload = useKyc((s) => s.setSelfieUpload);
+  const storedPreview = useKyc((s) => s.selfiePreviewUri);
+  const storedSelfieId = useKyc((s) => s.mediaIds.selfie);
 
-  const [selfieUri, setSelfieUri] = useState<string | null>(null);
+  // Hydrated from the STORE so leaving the step and returning lands on the
+  // review screen with the same selfie, exactly as document captures do. The
+  // setter writes through, keeping the store the source of truth.
+  const [selfieUri, setSelfieUriState] = useState<string | null>(storedPreview);
+  const setSelfieUri = useCallback(
+    (uri: string | null) => {
+      setSelfieUriState(uri);
+      setSelfiePreview(uri);
+    },
+    [setSelfiePreview],
+  );
   const [uploading, setUploading] = useState(false);
   const [retryInfo, setRetryInfo] = useState<{ attempt: number; total: number } | null>(null);
   const [uploadError, setUploadError] = useState<string | null>(null);
-  const selfieIdRef = useRef<string | null>(null);
+  const selfieIdRef = useRef<string | null>(storedSelfieId ?? null);
   const videoPathRef = useRef<string | null>(null);
 
   const uploadSelfieAndVideo = useCallback(
@@ -57,6 +74,7 @@ export function useSelfieUpload(): SelfieUpload {
       setUploading(true);
       setUploadError(null);
       setRetryInfo(null);
+      setSelfieUpload({ status: 'uploading', message: null });
       const onRetry = (attempt: number, total: number) => setRetryInfo({ attempt, total });
       try {
         const selfieId = await withRetry(
@@ -81,16 +99,18 @@ export function useSelfieUpload(): SelfieUpload {
         }
         setRetryInfo(null);
         setUploading(false);
+        setSelfieUpload({ status: 'done', message: null });
       } catch (err) {
         setRetryInfo(null);
         setUploading(false);
         const kycError = mapToKycError(err, 'upload');
         setUploadError(kycError.message);
+        setSelfieUpload({ status: 'failed', message: kycError.message });
         toast.show({ variant: 'error', title: 'Upload failed', message: kycError.message });
         safeReportError(config.onError, kycError);
       }
     },
-    [api, setMediaId, config.onError, toast],
+    [api, setMediaId, setSelfieUpload, config.onError, toast],
   );
 
   return {

package/src/screens/nfc/NfcReadProgress.tsx

@@ -30,6 +30,7 @@ const STEPS: NfcReadStage[] = [
   'readingData',
   'readingSecurity',
   'readingPhoto',
+  'readingDetails',
 ];
 
 export function NfcReadProgress({ stage }: { stage: NfcReadStage }): React.ReactElement {

package/src/screens/nfc/NfcScanIllustration.tsx

@@ -1,6 +1,6 @@
 import React, { useEffect, useRef, useState } from 'react';
 import { AccessibilityInfo, Animated, Easing, View } from 'react-native';
-import Svg, { Circle, Defs, G, Path, RadialGradient, Rect, Stop } from 'react-native-svg';
+import Svg, { Circle, G, Path, Rect } from 'react-native-svg';
 
 import { useTheme } from '../../components/runtime';
 
@@ -112,22 +112,6 @@ export function NfcScanIllustration(): React.ReactElement {
     // Same footprint as the web: full width up to 384 (`max-w-sm`), 320:240.
     <View style={{ width: '100%', maxWidth: 384, aspectRatio: 320 / 240, alignSelf: 'center' }}>
       <Svg width="100%" height="100%" viewBox="0 0 320 240">
-        <Defs>
-          {/* The field falls off with distance — the reason the document has
-              to be held CLOSE, said as a gradient instead of a caption. */}
-          <RadialGradient
-            id="kyc-nfc-field"
-            cx={COUPLING.x}
-            cy={COUPLING.y}
-            r={90}
-            gradientUnits="userSpaceOnUse"
-          >
-            <Stop offset="0" stopColor={colors.primary} stopOpacity={0.18} />
-            <Stop offset="0.55" stopColor={colors.primary} stopOpacity={0.06} />
-            <Stop offset="1" stopColor={colors.primary} stopOpacity={0} />
-          </RadialGradient>
-        </Defs>
-
         {/* ── The document, tucked BEHIND the phone: portrait, chip, MRZ. ── */}
         <G rotation={7} origin="212, 112">
           <Rect
@@ -224,7 +208,12 @@ export function NfcScanIllustration(): React.ReactElement {
         </G>
 
         {/* ── The field, over both objects. ── */}
-        <Circle cx={COUPLING.x} cy={COUPLING.y} r={90} fill="url(#kyc-nfc-field)" />
+        {/* The field falls off with distance — the reason the document has to
+            be held CLOSE. Flat concentric steps (no gradients in the flow,
+            house rule 2026-08-29). */}
+        <Circle cx={COUPLING.x} cy={COUPLING.y} r={90} fill={colors.primary} fillOpacity={0.04} />
+        <Circle cx={COUPLING.x} cy={COUPLING.y} r={56} fill={colors.primary} fillOpacity={0.07} />
+        <Circle cx={COUPLING.x} cy={COUPLING.y} r={28} fill={colors.primary} fillOpacity={0.12} />
         <Circle cx={COUPLING.x} cy={COUPLING.y} r={4.5} fill={colors.primary} />
         {WAVES.map((w, i) => (
           <AnimatedPath

package/src/screens/useAddressPhotoAttach.ts

@@ -0,0 +1,77 @@
+import { useCallback, useState } from 'react';
+import * as ImagePicker from 'expo-image-picker';
+
+import { isAcceptedAddressPhotoMimeType } from '../config/addressCollection';
+import { IMAGE_MAX_BYTES } from '../config/uploadLimits';
+
+// ---------------------------------------------------------------------------
+// Getting the door photo off the device — the address step's slim sibling of
+// usePoaAttach. Camera or photo library only: the door photo is a PICTURE of a
+// place, so there is no PDF/file case, and each pick closes the source sheet
+// before the picker opens.
+// ---------------------------------------------------------------------------
+
+/** What the picker handed back, so the screen can preview it. */
+export interface AddressPhotoPick {
+  uri: string;
+  mimeType: string | undefined;
+  name: string;
+}
+
+type UploadFn = (pick: AddressPhotoPick) => Promise<void>;
+
+export function useAddressPhotoAttach(
+  upload: UploadFn,
+  setError: (message: string) => void,
+): {
+  pick: () => void;
+  sheetOpen: boolean;
+  closeSheet: () => void;
+  choosePhoto: () => Promise<void>;
+  takePhoto: () => Promise<void>;
+} {
+  const [sheetOpen, setSheetOpen] = useState(false);
+  const pick = useCallback(() => setSheetOpen(true), []);
+  const closeSheet = useCallback(() => setSheetOpen(false), []);
+
+  const accept = useCallback(
+    async (asset: ImagePicker.ImagePickerAsset | undefined, fallbackName: string) => {
+      if (!asset) return;
+      if (typeof asset.fileSize === 'number' && asset.fileSize > IMAGE_MAX_BYTES) {
+        setError('Photo is too large (max 5 MB).');
+        return;
+      }
+      const mimeType = asset.mimeType ?? 'image/jpeg';
+      // The picker's media filter is advisory on some platforms, so what came
+      // back is re-checked rather than trusted.
+      if (!isAcceptedAddressPhotoMimeType(mimeType)) {
+        setError('Please choose a photo (JPEG, PNG or WebP).');
+        return;
+      }
+      await upload({ uri: asset.uri, mimeType, name: asset.fileName ?? fallbackName });
+    },
+    [setError, upload],
+  );
+
+  const takePhoto = useCallback(async () => {
+    setSheetOpen(false);
+    const permission = await ImagePicker.requestCameraPermissionsAsync();
+    if (!permission.granted) {
+      setError('Camera access is needed to photograph the entrance.');
+      return;
+    }
+    const result = await ImagePicker.launchCameraAsync({ mediaTypes: ['images'], quality: 1 });
+    await accept(result.canceled ? undefined : result.assets[0], 'address-photo.jpg');
+  }, [accept, setError]);
+
+  const choosePhoto = useCallback(async () => {
+    setSheetOpen(false);
+    const result = await ImagePicker.launchImageLibraryAsync({
+      mediaTypes: ['images'],
+      quality: 1,
+    });
+    await accept(result.canceled ? undefined : result.assets[0], 'address-photo.jpg');
+  }, [accept]);
+
+  return { pick, sheetOpen, closeSheet, choosePhoto, takePhoto };
+}