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

package/src/screens/address/use-address-flow.ts

@@ -0,0 +1,200 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { useKyc, useKycConfig, useKycStore } from '../../components/runtime';
+import { addressFlowFor } from '../../config/addressCollection';
+import { webViewAvailable } from '../../lib/webview-available';
+import { isBusinessFlow } from '../../config/business';
+import { addressFlowSteps, addressVendorsStubbed, isAddressStep } from '../../lib/address-flow';
+import { addressExitStep, recoverAddressStep } from '../../lib/address-step-recovery';
+import { defaultMapView } from '../../lib/map-tiles';
+import { buildStepOrder, nextStepInOrder } from '../../config/stepOrder';
+import { geoDefaultCountry } from '../../lib/country-adoption';
+import { configScope } from '../../lib/scope';
+import { stepOrderOptions } from '../../store/kycStore';
+import { deviceFixFields } from '../../services/location';
+import { savePresencePin } from '../../presence/store';
+import { usePinActions } from './use-pin-actions';
+import type { KYCStep } from '../../types/config';
+import type { AddressState } from '../../store/state';
+
+// ---------------------------------------------------------------------------
+// The address flow's shared brain: every address step mounts this hook and gets
+// the same derived flags, the same step list, and the same actions — which is
+// what keeps four separate screens telling one story.
+//
+// Navigation rides the SDK's ONE ordered step list rather than a second copy:
+// the flow's steps are already in `buildStepOrder`, so stepping forward, going
+// back, and backing out of the flow entirely all fall out of the same list the
+// progress bar reads. That is why nothing here reimplements goBack — the
+// sheet's own back button already walks it — and why goNext is the store's
+// nextStep. `nextAddressStep`/`prevAddressStep` stay in lib/address-flow as
+// part of the pure mirror the three SDKs share.
+//
+// A MIRROR of the web SDK's steps/address/use-address-flow.ts.
+// ---------------------------------------------------------------------------
+
+export function useAddressFlow() {
+  const config = useKycConfig();
+  const store = useKycStore();
+  const address = useKyc((s) => s.address);
+  const serverSearch = useKyc((s) => s.serverConfig.addressSearch === true);
+  const selectedCountry = useKyc((s) => s.selectedCountry);
+  const businessCountry = useKyc((s) => s.business.country);
+  const [uploading, setUploading] = useState(false);
+  const [confirming, setConfirming] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const cfg = config.addressCollection;
+  const isBusiness = isBusinessFlow(config);
+  const vendorEnvironment = useKyc((s) => s.serverConfig.environment ?? null);
+  const mapsFrameUrl = useKyc((s) => s.serverConfig.mapsFrameUrl ?? null);
+  const flow = addressFlowFor(
+    config,
+    serverSearch,
+    addressVendorsStubbed({ environment: vendorEnvironment }),
+    Boolean(mapsFrameUrl) && webViewAvailable(),
+  );
+  // KYB: the premises pin + directions ARE the capture, so the flow is that
+  // single step and its Continue commits.
+  //
+  // Memoised on the three flags it derives from, so `steps` — and the two
+  // navigation callbacks that close over it — keep a stable identity. A fresh
+  // array on every render would make `goNext` a new function each time, and
+  // the entrance step depends on that identity inside an effect.
+  const { searchAvailable, photoMode, streetViewOffered } = flow;
+  const steps: KYCStep[] = useMemo(
+    () =>
+      isBusiness
+        ? ['address-collection']
+        : addressFlowSteps({ searchAvailable, photoMode, streetViewOffered }),
+    [isBusiness, searchAvailable, photoMode, streetViewOffered],
+  );
+
+  // A resumed attempt restores the step it was saved on, and the flow may have
+  // changed shape since: `searchAvailable` is a SERVER flag that lands after the
+  // restore, and a republish can drop the entrance photo. Left alone the
+  // applicant sits on a screen the order does not contain, where Continue has
+  // nothing to advance to and Back has no predecessor. Gated on the config
+  // having settled: until then the order is not the real one.
+  const configSettled = useKyc((s) => s.serverConfig.status !== 'loading');
+  const currentStep = useKyc((s) => s.currentStep);
+  useEffect(() => {
+    if (!configSettled || !isAddressStep(currentStep)) return;
+    const options = stepOrderOptions(store.getState());
+    const inFlow = buildStepOrder(options).filter(isAddressStep);
+    const exit = addressExitStep(buildStepOrder({ ...options, hasAddressCollection: true }));
+    const recovered = recoverAddressStep(currentStep, inFlow, exit);
+    if (recovered) store.getState().goToStep(recovered);
+  }, [configSettled, currentStep, store]);
+
+  // The address scope declares the visitor's IP country by default, ONCE,
+  // while nothing is declared; a geocode or a picked address then corrects
+  // the guess (lib/country-adoption.ts). A full flow never defaults from it.
+  const geoCountry = useKyc((s) => s.serverConfig.geoCountry ?? null);
+  useEffect(() => {
+    const s = store.getState();
+    const country = geoDefaultCountry({
+      geoCountry,
+      selectedCountry: s.selectedCountry,
+      scope: configScope(s.config),
+      accepted: s.config.proofOfAddress?.countries,
+    });
+    if (country) s.setCountryAuto(country);
+  }, [geoCountry, store]);
+
+  const pin = address ? { lat: address.lat, lng: address.lng } : null;
+  const country = isBusiness ? (businessCountry ?? undefined) : (selectedCountry ?? config.country);
+  const view = defaultMapView(country);
+
+  const pinActions = usePinActions(store, setError);
+
+  /** Leave the address flow forwards: after the review, a KYB commit, a skip. */
+  const exitForward = useCallback(() => {
+    const state = store.getState();
+    const last = steps[steps.length - 1]!;
+    store.getState().goToStep(nextStepInOrder(last, stepOrderOptions(state)));
+  }, [steps, store]);
+
+  /**
+   * The step after the current one within the flow, else the flow's exit:
+   * exactly what the store's own `nextStep` computes, since the flow's steps
+   * are contiguous in the ordered list. Going through the store also keeps
+   * the navigation direction and the camera flag handled in one place.
+   */
+  const goNext = useCallback(() => store.getState().nextStep(), [store]);
+
+  const pickPhoto = useCallback(
+    async (upload: () => Promise<string>, previewUri: string) => {
+      setError(null);
+      setUploading(true);
+      try {
+        const mediaId = await upload();
+        store.getState().setAddressPhoto(mediaId);
+        store.getState().setAddressPhotoPreview(previewUri);
+      } catch (err) {
+        setError(
+          err instanceof Error && err.message
+            ? err.message
+            : 'Upload failed. Please check your connection and try again.',
+        );
+      } finally {
+        setUploading(false);
+      }
+    },
+    [store],
+  );
+
+  const removePhoto = useCallback(() => {
+    store.getState().setAddressPhoto(null);
+    store.getState().setAddressPhotoPreview(null);
+  }, [store]);
+
+  /** Commit: the one-shot attest fix (best-effort), then leave the flow. */
+  const confirm = useCallback(async () => {
+    const current = store.getState().address;
+    if (!current) return;
+    setConfirming(true);
+    let committed: AddressState = current;
+    if (cfg?.attestPresence) {
+      // Best-effort by contract: a denied prompt or a slow read costs the
+      // `attested` tier, never the flow.
+      committed = { ...current, ...(await deviceFixFields()) };
+      store.getState().setAddress(committed);
+    }
+    // Presence verification keeps the confirmed pin ON-DEVICE so later
+    // foreground reports evaluate the fence locally. Keyed by the org's user
+    // reference: without one there is nothing to report against.
+    if (cfg?.presence?.enabled === true && config.userId) {
+      savePresencePin(
+        config.userId,
+        { lat: committed.lat, lng: committed.lng },
+        { alwaysOn: cfg.presence.alwaysOn === true },
+      );
+    }
+    setConfirming(false);
+    exitForward();
+  }, [cfg?.attestPresence, cfg?.presence?.enabled, config.userId, exitForward, store]);
+
+  return {
+    cfg,
+    address,
+    isBusiness,
+    steps,
+    pin,
+    view,
+    country,
+    photoMode: flow.photoMode,
+    streetViewOffered: flow.streetViewOffered,
+    searchAvailable: flow.searchAvailable,
+    uploading,
+    confirming,
+    error,
+    setError,
+    pickPhoto,
+    removePhoto,
+    goNext,
+    exitForward,
+    confirm,
+    ...pinActions,
+  };
+}

package/src/screens/address/use-label-pin.ts

@@ -0,0 +1,80 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { REVERSE_DEBOUNCE_MS, addressVendorsStubbed, SAMPLE_ADDRESS_LINE } from '../../lib/address-flow';
+import type { KycStore } from '../../store/state';
+
+// ---------------------------------------------------------------------------
+// Reverse geocoding: the pin's human-readable line. Split from
+// use-pin-actions.ts (200-line rule).
+//
+// Debounced, because a drag settles several times, and DROPPED when the pin
+// moved again meanwhile: the comparison is exact coordinate equality, so a
+// late answer can never label somewhere the applicant has already left.
+// Failures are swallowed; the line is a convenience. Display only, and the
+// pin's own country is handed to `onGeocoded` so the declaration can follow
+// the evidence (lib/country-adoption.ts). Mirrors Flutter's
+// address_pin_label.dart.
+// ---------------------------------------------------------------------------
+
+export function useLabelPin(
+  store: KycStore,
+  onGeocoded: (country: string | null | undefined) => void,
+): { labelPin: (lat: number, lng: number, delay?: number) => void; labelling: boolean } {
+  const reverseTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // The summary line shows nothing while a pin has no address, so it has to
+  // say WHY: an answer is coming, or none is.
+  const [labelling, setLabelling] = useState(false);
+
+  useEffect(
+    () => () => {
+      if (reverseTimer.current) clearTimeout(reverseTimer.current);
+    },
+    [],
+  );
+
+  const labelPin = useCallback(
+    (lat: number, lng: number, delay = REVERSE_DEBOUNCE_MS) => {
+      if (reverseTimer.current) clearTimeout(reverseTimer.current);
+      setLabelling(true);
+      // SANDBOX never reverse-geocodes: the sample line demonstrates the
+      // summary card with no network call (the web SDK's preview/sandbox rule).
+      if (addressVendorsStubbed({ environment: store.getState().serverConfig.environment })) {
+        reverseTimer.current = setTimeout(() => {
+          const cur = store.getState().address;
+          if (!cur || cur.lat !== lat || cur.lng !== lng || cur.label) return;
+          store.getState().setAddress({ ...cur, label: SAMPLE_ADDRESS_LINE });
+          setLabelling(false);
+        }, 0);
+        return;
+      }
+      reverseTimer.current = setTimeout(() => {
+        void store
+          .getState()
+          .api.addressReverse(lat, lng)
+          .then((r) => {
+            const cur = store.getState().address;
+            // Exact coordinate equality: anything else means the pin moved
+            // while the request was out, and this answer describes a spot the
+            // applicant has already left.
+            if (!r.line || !cur || cur.lat !== lat || cur.lng !== lng) return;
+            store.getState().setAddress({
+              ...cur,
+              label: r.line,
+              ...(r.parts ? { parts: r.parts } : {}),
+              // A resolved street retires the typed one (its input hides) —
+              // back to UNDEFINED, never '': the details sheet reads '' as
+              // deliberately cleared, which suppressed the resolved-street
+              // prefill it should be showing.
+              ...(r.parts?.street ? { street: undefined } : {}),
+            });
+            onGeocoded(r.parts?.country);
+          })
+          .catch(() => undefined)
+          .finally(() => setLabelling(false));
+      }, delay);
+    },
+    [onGeocoded, store],
+  );
+
+  return { labelPin, labelling };
+}

package/src/screens/address/use-pin-actions.ts

@@ -0,0 +1,192 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { fixApplied, pinMove, withoutPickedLabel } from '../../lib/address-pin-move';
+import { isAddressStep } from '../../lib/address-flow';
+import {
+  currentFix as cachedFix,
+  currentFixFailure,
+  locating as fixInFlight,
+  locationFailureMessage,
+  prefetchCurrentFix,
+  type CurrentFix,
+} from '../../lib/address-current-location';
+import { adoptionDecision } from '../../lib/country-adoption';
+import { configScope } from '../../lib/scope';
+import { useLabelPin } from './use-label-pin';
+import { fixSourceFor } from './fix-source';
+import type { KycStore } from '../../store/state';
+
+// ---------------------------------------------------------------------------
+// The pin's mechanics — the shared current-location fix and every way the pin
+// can move. Split from use-address-flow.ts (200-line rule); the reverse
+// geocode that labels the pin lives in use-label-pin.ts, the fix source in
+// fix-source.ts. A MIRROR of the web SDK's steps/address/use-pin-actions.ts.
+//
+// One rule runs through all of it: a HUMAN-CONFIRMED label is never silently
+// discarded, and never silently kept against the applicant's wishes either.
+// They decide, via the pin step's keep/update row.
+// ---------------------------------------------------------------------------
+
+export interface PinActions {
+  currentFix: CurrentFix | null;
+  locating: boolean;
+  startPrefetch: () => void;
+  applyCurrentFix: (onDone?: () => void, opts?: { silent?: boolean }) => Promise<void>;
+  setPin: (next: { lat: number; lng: number }, accuracy?: number | null) => void;
+  keepPickedLabel: () => void;
+  adoptPinAddress: () => void;
+  relabelPin: () => void;
+  locateToPin: () => Promise<void>;
+  /** The declared country follows the evidence: the rule, and why each of
+   *  its guards exists, is lib/country-adoption.ts. */
+  adoptGeocodedCountry: (country: string | null | undefined, opts?: { explicit?: boolean }) => void;
+  /** A reverse geocode is out: the pin has no line YET, rather than none. */
+  labelling: boolean;
+}
+
+export function usePinActions(
+  store: KycStore,
+  setError: (message: string | null) => void,
+): PinActions {
+  const [fix, setFix] = useState<CurrentFix | null>(cachedFix());
+  const [fixPending, setFixPending] = useState(fixInFlight());
+
+  const fixSource = useMemo(() => fixSourceFor(store), [store]);
+
+  const adoptGeocodedCountry = useCallback(
+    (country: string | null | undefined, opts?: { explicit?: boolean }) => {
+      const st = store.getState();
+      const decision = adoptionDecision({
+        country,
+        selectedCountry: st.selectedCountry,
+        countryAutoPicked: st.countryAutoPicked,
+        scope: configScope(st.config),
+        accepted: st.config.proofOfAddress?.countries,
+        explicit: opts?.explicit,
+      });
+      if (!decision) return;
+      if (decision.auto) st.setCountryAuto(decision.country);
+      else st.setCountry(decision.country);
+    },
+    [store],
+  );
+  const { labelPin, labelling } = useLabelPin(store, adoptGeocodedCountry);
+
+  // The fix may have resolved on an earlier step (it is module-level): a
+  // guessed declaration is corrected on this mount too, not only when the
+  // prefetch happens to finish here.
+  useEffect(() => {
+    adoptGeocodedCountry(cachedFix()?.parts?.country);
+  }, [adoptGeocodedCountry]);
+
+  // ── The shared current-location fix ───────────────────────────────────────
+  const startPrefetch = useCallback(() => {
+    setFixPending(true);
+    void prefetchCurrentFix(fixSource).then((f) => {
+      setFix(f);
+      setFixPending(false);
+      adoptGeocodedCountry(f?.parts?.country);
+    });
+  }, [adoptGeocodedCountry, fixSource]);
+
+  /**
+   * Land the pin ON the current fix — the bootstrap override, used while no
+   * address exists yet. It sets NO `pickedAt`, so the resulting label is
+   * treated as derived and re-derives freely on the next move.
+   */
+  const applyCurrentFix = useCallback(
+    async (onDone?: () => void, opts?: { silent?: boolean }) => {
+      setError(null);
+      setFixPending(true);
+      // A TAP may retry a previously failed attempt (permission may have been
+      // granted since); the silent auto path never re-prompts.
+      const f = await prefetchCurrentFix(fixSource, { retry: !opts?.silent });
+      setFix(f);
+      setFixPending(false);
+      adoptGeocodedCountry(f?.parts?.country);
+      // The fix can take up to eight seconds, and "Skip for now" is a decision
+      // the applicant may make inside that window. A late fix writing an
+      // address they declined to give (and an onDone navigating them back onto
+      // a step they just left) undoes that decision, so a continuation whose
+      // step is no longer in the address flow drops everything on the floor.
+      if (!isAddressStep(store.getState().currentStep)) return;
+      const cur = store.getState().address;
+      // The silent apply resolves seconds after it started, and the person may
+      // have picked a searched address meanwhile. A late GPS fix must never
+      // overwrite a choice they made; an explicit tap still overrides.
+      if (opts?.silent && cur) {
+        onDone?.();
+        return;
+      }
+      if (f) {
+        store.getState().setAddress(fixApplied(cur, f));
+      } else if (!opts?.silent) {
+        // Which remedy the person needs depends on WHY the read failed.
+        setError(locationFailureMessage(currentFixFailure()));
+      }
+      onDone?.();
+    },
+    [adoptGeocodedCountry, fixSource, setError, store],
+  );
+
+  const setPin = useCallback(
+    (next: { lat: number; lng: number }, accuracy: number | null = null) => {
+      const move = pinMove(store.getState().address, next, accuracy);
+      if (move.kind === 'ignore') return;
+      store.getState().setAddress(move.address);
+      // A kept label needs no reverse geocode: it already names the property.
+      if (move.kind === 'rebuild') labelPin(next.lat, next.lng);
+    },
+    [labelPin, store],
+  );
+
+  const keepPickedLabel = useCallback(() => {
+    const cur = store.getState().address;
+    if (cur) store.getState().setAddress({ ...cur, labelKept: true });
+  }, [store]);
+
+  /** The applicant adopts the PIN's address: drop the pick, re-derive. */
+  const adoptPinAddress = useCallback(() => {
+    const cur = store.getState().address;
+    if (!cur) return;
+    store.getState().setAddress(withoutPickedLabel(cur));
+    labelPin(cur.lat, cur.lng, 0);
+  }, [labelPin, store]);
+
+  /** Reverse-geocode the current pin's line — for a session restored from a
+   *  snapshot saved before labels existed, which would show raw coordinates. */
+  const relabelPin = useCallback(() => {
+    const cur = store.getState().address;
+    if (cur && !cur.label) labelPin(cur.lat, cur.lng, 0);
+  }, [labelPin, store]);
+
+  /**
+   * The on-map locate control: moves the PIN through `setPin`, so a picked
+   * address is protected by the same keep/update prompt as any other pin move
+   * and a mistaken tap destroys nothing.
+   */
+  const locateToPin = useCallback(async () => {
+    setError(null);
+    setFixPending(true);
+    const f = await prefetchCurrentFix(fixSource, { retry: true });
+    setFix(f);
+    setFixPending(false);
+    adoptGeocodedCountry(f?.parts?.country);
+    if (f) setPin({ lat: f.lat, lng: f.lng }, f.accuracy);
+    else setError(locationFailureMessage(currentFixFailure()));
+  }, [adoptGeocodedCountry, fixSource, setError, setPin]);
+
+  return {
+    labelling,
+    currentFix: fix,
+    locating: fixPending,
+    startPrefetch,
+    applyCurrentFix,
+    setPin,
+    keepPickedLabel,
+    adoptPinAddress,
+    relabelPin,
+    locateToPin,
+    adoptGeocodedCountry,
+  };
+}

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" });
   }