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

package/src/components/fonts.ts

@@ -1,26 +1,29 @@
 import type { TextStyle } from 'react-native';
 import { useFonts } from 'expo-font';
-import { SpaceGrotesk_500Medium, SpaceGrotesk_600SemiBold, SpaceGrotesk_700Bold } from '@expo-google-fonts/space-grotesk';
-import { Karla_400Regular, Karla_500Medium, Karla_600SemiBold, Karla_700Bold } from '@expo-google-fonts/karla';
 import { fontFamilyFor } from '../config/font-resolve';
 import { useTheme } from './theme-provider';
 
 export { fontFamilyFor, markFamilyName, brandFamilyName, BRAND_WEIGHTS } from '../config/font-resolve';
 
-
 // Typography fonts — the SAME families the Flutter SDK uses via google_fonts:
 // Space Grotesk for headings, Karla for body. Loaded at runtime through
 // expo-font (already natively linked), so no native rebuild is needed. Each
 // weight is its own RN font family, so we resolve family-by-weight below.
-
+//
+// The files are VENDORED under src/assets/fonts and required one by one (see
+// the README there). They used to be named imports from the
+// @expo-google-fonts packages, whose index requires EVERY weight the family
+// ships — and Metro bundles every `require` it can see, used or not — so 19
+// font files reached every integrator's app for the seven faces the SDK draws
+// with. Measured at 1.85 MB on a real integrator's release APK.
 export const MYAZA_FONTS = {
-  SpaceGrotesk_500Medium,
-  SpaceGrotesk_600SemiBold,
-  SpaceGrotesk_700Bold,
-  Karla_400Regular,
-  Karla_500Medium,
-  Karla_600SemiBold,
-  Karla_700Bold,
+  SpaceGrotesk_500Medium: require('../assets/fonts/SpaceGrotesk_500Medium.ttf'),
+  SpaceGrotesk_600SemiBold: require('../assets/fonts/SpaceGrotesk_600SemiBold.ttf'),
+  SpaceGrotesk_700Bold: require('../assets/fonts/SpaceGrotesk_700Bold.ttf'),
+  Karla_400Regular: require('../assets/fonts/Karla_400Regular.ttf'),
+  Karla_500Medium: require('../assets/fonts/Karla_500Medium.ttf'),
+  Karla_600SemiBold: require('../assets/fonts/Karla_600SemiBold.ttf'),
+  Karla_700Bold: require('../assets/fonts/Karla_700Bold.ttf'),
 };
 
 /** Loads the Myaza fonts. Returns true once they're ready (system font until then). */
@@ -29,12 +32,6 @@ export function useMyazaFonts(): boolean {
   return loaded;
 }
 
-/**
- * Resolves the concrete RN font family for a (heading vs body, weight) pair.
- * Returns `undefined` until fonts are loaded so text falls back to the system
- * font + `fontWeight` without triggering an "unrecognized font" warning.
- */
-
 /**
  * The body font family for a TEXT INPUT, at the given weight.
  *

package/src/components/icons/glyphs.ts

@@ -0,0 +1,35 @@
+import type { IconSvgElement } from '@hugeicons/react-native';
+
+/**
+ * Glyphs Hugeicons does not carry, drawn in the set's own stroke language.
+ *
+ * Kept to the strict minimum: every other icon comes from the set, and this
+ * file exists only where the set has no equivalent at all. It MIRRORS the web
+ * SDK's `components/icons/glyphs.ts` - same geometry, same stroke attributes -
+ * so the two platforms draw one arrow rather than two near-misses.
+ */
+
+const STROKE = {
+  stroke: 'currentColor',
+  strokeLinecap: 'round',
+  strokeLinejoin: 'round',
+  strokeWidth: '1.5',
+} as const;
+
+/**
+ * A LONG left arrow - a full-width shaft with a small head.
+ *
+ * Hugeicons has no such glyph. Its longest one-way left arrow is
+ * `ArrowLeft02Icon`, whose shaft spans 13.5 of the 24-unit viewBox; the rest
+ * are shorter, bare chevrons, or arrows into a vertical bar. This SDK's back
+ * control drew Lucide's `MoveLeft` before the migration, whose shaft is 20
+ * units, so moving to the set would visibly shorten it.
+ *
+ * The geometry is Lucide's, inset to sit on the same optical margins as its
+ * Hugeicons siblings (they start at ~3.5 rather than Lucide's 2), and the
+ * stroke attributes are copied from the set so weight and joins match exactly.
+ */
+export const LONG_ARROW_LEFT: IconSvgElement = [
+  ['path', { d: 'M20.5 12H3.5', ...STROKE, key: '0' }],
+  ['path', { d: 'M8 7.5L3.5 12L8 16.5', ...STROKE, key: '1' }],
+];

package/src/components/icons/index.ts

@@ -0,0 +1,3 @@
+export type { IconName } from './names';
+export { ICONS } from './map';
+export { LONG_ARROW_LEFT } from './glyphs';

package/src/components/icons/map.ts

@@ -0,0 +1,165 @@
+import type { IconSvgElement } from '@hugeicons/react-native';
+
+import Add01Icon from '@hugeicons/core-free-icons/Add01Icon';
+import AlertCircleIcon from '@hugeicons/core-free-icons/AlertCircleIcon';
+import BadgeCheckIcon from '@hugeicons/core-free-icons/BadgeCheckIcon';
+import BellRingIcon from '@hugeicons/core-free-icons/BellRingIcon';
+import BookUserIcon from '@hugeicons/core-free-icons/BookUserIcon';
+import BubbleChatIcon from '@hugeicons/core-free-icons/BubbleChatIcon';
+import Building02Icon from '@hugeicons/core-free-icons/Building02Icon';
+import BulbIcon from '@hugeicons/core-free-icons/BulbIcon';
+import Calendar01Icon from '@hugeicons/core-free-icons/Calendar01Icon';
+import Camera01Icon from '@hugeicons/core-free-icons/Camera01Icon';
+import CameraOff01Icon from '@hugeicons/core-free-icons/CameraOff01Icon';
+import Cancel01Icon from '@hugeicons/core-free-icons/Cancel01Icon';
+import CancelCircleIcon from '@hugeicons/core-free-icons/CancelCircleIcon';
+import Car01Icon from '@hugeicons/core-free-icons/Car01Icon';
+import CheckIcon from '@hugeicons/core-free-icons/CheckIcon';
+import CheckmarkCircle02Icon from '@hugeicons/core-free-icons/CheckmarkCircle02Icon';
+import ChevronDownIcon from '@hugeicons/core-free-icons/ChevronDownIcon';
+import ChevronLeftIcon from '@hugeicons/core-free-icons/ChevronLeftIcon';
+import ChevronRightIcon from '@hugeicons/core-free-icons/ChevronRightIcon';
+import CircleDashedIcon from '@hugeicons/core-free-icons/CircleDashedIcon';
+import ContactIcon from '@hugeicons/core-free-icons/ContactIcon';
+import CopyIcon from '@hugeicons/core-free-icons/CopyIcon';
+import CreditCardIcon from '@hugeicons/core-free-icons/CreditCardIcon';
+import ExpandIcon from '@hugeicons/core-free-icons/ExpandIcon';
+import FaceIdIcon from '@hugeicons/core-free-icons/FaceIdIcon';
+import File02Icon from '@hugeicons/core-free-icons/File02Icon';
+import FilterIcon from '@hugeicons/core-free-icons/FilterIcon';
+import FingerPrintIcon from '@hugeicons/core-free-icons/FingerPrintIcon';
+import FlashOffIcon from '@hugeicons/core-free-icons/FlashOffIcon';
+import FlaskConicalIcon from '@hugeicons/core-free-icons/FlaskConicalIcon';
+import GlobeIcon from '@hugeicons/core-free-icons/GlobeIcon';
+import Gps02Icon from '@hugeicons/core-free-icons/Gps02Icon';
+import HelpCircleIcon from '@hugeicons/core-free-icons/HelpCircleIcon';
+import Home01Icon from '@hugeicons/core-free-icons/Home01Icon';
+import IdentityCardIcon from '@hugeicons/core-free-icons/IdentityCardIcon';
+import Image01Icon from '@hugeicons/core-free-icons/Image01Icon';
+import InformationCircleIcon from '@hugeicons/core-free-icons/InformationCircleIcon';
+import LandmarkIcon from '@hugeicons/core-free-icons/LandmarkIcon';
+import Link02Icon from '@hugeicons/core-free-icons/Link02Icon';
+import Location02Icon from '@hugeicons/core-free-icons/Location02Icon';
+import LocationCheck01Icon from '@hugeicons/core-free-icons/LocationCheck01Icon';
+import LockIcon from '@hugeicons/core-free-icons/LockIcon';
+import Mail01Icon from '@hugeicons/core-free-icons/Mail01Icon';
+import MapPinHouseIcon from '@hugeicons/core-free-icons/MapPinHouseIcon';
+import MapPinIcon from '@hugeicons/core-free-icons/MapPinIcon';
+import Message01Icon from '@hugeicons/core-free-icons/Message01Icon';
+import MinusSignIcon from '@hugeicons/core-free-icons/MinusSignIcon';
+import MoonIcon from '@hugeicons/core-free-icons/MoonIcon';
+import NfcIcon from '@hugeicons/core-free-icons/NfcIcon';
+import PencilEdit01Icon from '@hugeicons/core-free-icons/PencilEdit01Icon';
+import PencilIcon from '@hugeicons/core-free-icons/PencilIcon';
+import Radar01Icon from '@hugeicons/core-free-icons/Radar01Icon';
+import RefreshCwIcon from '@hugeicons/core-free-icons/RefreshCwIcon';
+import RefreshIcon from '@hugeicons/core-free-icons/RefreshIcon';
+import ScanIcon from '@hugeicons/core-free-icons/ScanIcon';
+import Search01Icon from '@hugeicons/core-free-icons/Search01Icon';
+import SecurityCheckIcon from '@hugeicons/core-free-icons/SecurityCheckIcon';
+import Share01Icon from '@hugeicons/core-free-icons/Share01Icon';
+import SlidersHorizontalIcon from '@hugeicons/core-free-icons/SlidersHorizontalIcon';
+import SmartPhone01Icon from '@hugeicons/core-free-icons/SmartPhone01Icon';
+import StampIcon from '@hugeicons/core-free-icons/StampIcon';
+import Sun01Icon from '@hugeicons/core-free-icons/Sun01Icon';
+import Timer01Icon from '@hugeicons/core-free-icons/Timer01Icon';
+import Upload01Icon from '@hugeicons/core-free-icons/Upload01Icon';
+import UserAdd01Icon from '@hugeicons/core-free-icons/UserAdd01Icon';
+import UserCircleIcon from '@hugeicons/core-free-icons/UserCircleIcon';
+import UserGroupIcon from '@hugeicons/core-free-icons/UserGroupIcon';
+import VideoOffIcon from '@hugeicons/core-free-icons/VideoOffIcon';
+import VoteIcon from '@hugeicons/core-free-icons/VoteIcon';
+import ZapIcon from '@hugeicons/core-free-icons/ZapIcon';
+
+import { LONG_ARROW_LEFT } from './glyphs';
+import type { IconName } from './names';
+
+/**
+ * Each role, and the glyph that draws it.
+ *
+ * Imports are DEEP - one module per icon - and must stay that way. Importing
+ * from the package index instead pulls the whole 6,025-icon pack into the
+ * bundle: measured at +8.33 MB for five icons against +7 KB for the same five
+ * imported this way. The pack declares a `./*` export for exactly this, and
+ * iconImports.test.ts fails the build on a barrel import.
+ *
+ * The glyphs are the ones the web SDK and Flutter already chose for these
+ * names, so the three SDKs draw one set. Where neither had a choice to copy,
+ * it was made against the catalogue by meaning and is noted below.
+ */
+export const ICONS: Record<IconName, IconSvgElement> = {
+  close: Cancel01Icon,
+  back: LONG_ARROW_LEFT,
+  moon: MoonIcon,
+  sun: Sun01Icon,
+  check: CheckIcon,
+  lock: LockIcon,
+  alert: AlertCircleIcon,
+  // The environment banner's mark, shared with the web SDK (same lucide glyph)
+  // and mirrored by Flutter's Icons.science_outlined.
+  flask: FlaskConicalIcon,
+  refresh: RefreshCwIcon,
+  'refresh-ccw': RefreshIcon,
+  maximize: ExpandIcon,
+  calendar: Calendar01Icon,
+  image: Image01Icon,
+  'chevron-left': ChevronLeftIcon,
+  'chevron-right': ChevronRightIcon,
+  'chevron-down': ChevronDownIcon,
+  shield: SecurityCheckIcon,
+  'badge-check': BadgeCheckIcon,
+  'circle-dashed': CircleDashedIcon,
+  'circle-check': CheckmarkCircle02Icon,
+  'circle-help': HelpCircleIcon,
+  'circle-x': CancelCircleIcon,
+  'building-2': Building02Icon,
+  stamp: StampIcon,
+  user: UserCircleIcon,
+  info: InformationCircleIcon,
+  'user-plus': UserAdd01Icon,
+  plus: Add01Icon,
+  link: Link02Icon,
+  copy: CopyIcon,
+  share: Share01Icon,
+  users: UserGroupIcon,
+  'scan-line': ScanIcon,
+  'scan-face': FaceIdIcon,
+  nfc: NfcIcon,
+  filter: FilterIcon,
+  pencil: PencilIcon,
+  'pencil-line': PencilEdit01Icon,
+  search: Search01Icon,
+  zap: ZapIcon,
+  'zap-off': FlashOffIcon,
+  timer: Timer01Icon,
+  fingerprint: FingerPrintIcon,
+  'credit-card': CreditCardIcon,
+  globe: GlobeIcon,
+  car: Car01Icon,
+  vote: VoteIcon,
+  'file-text': File02Icon,
+  house: Home01Icon,
+  landmark: LandmarkIcon,
+  'map-pin': MapPinIcon,
+  'map-pin-house': MapPinHouseIcon,
+  'map-pin-check': LocationCheck01Icon,
+  'map-pinned': Location02Icon,
+  radar: Radar01Icon,
+  'bell-ring': BellRingIcon,
+  sliders: SlidersHorizontalIcon,
+  locate: Gps02Icon,
+  minus: MinusSignIcon,
+  'id-card': IdentityCardIcon,
+  contact: ContactIcon,
+  passport: BookUserIcon,
+  camera: Camera01Icon,
+  'camera-off': CameraOff01Icon,
+  'video-off': VideoOffIcon,
+  upload: Upload01Icon,
+  x: Cancel01Icon,
+  lightbulb: BulbIcon,
+  mail: Mail01Icon,
+  smartphone: SmartPhone01Icon,
+  'message-square': Message01Icon,
+  'message-circle': BubbleChatIcon,
+};

package/src/components/icons/names.ts

@@ -0,0 +1,86 @@
+/**
+ * The icon roles this SDK draws, by MEANING rather than by glyph name.
+ *
+ * This is the boundary that lets the set underneath change without touching a
+ * call site: a screen asks for 'close', and `icons/map.ts` decides what that
+ * looks like. Adding a role here means adding its glyph there.
+ */
+
+export type IconName =
+  // chrome
+  | 'close'
+  | 'back'
+  | 'moon'
+  | 'sun'
+  | 'check'
+  | 'lock'
+  | 'alert'
+  | 'flask'
+  | 'refresh'
+  | 'refresh-ccw'
+  | 'maximize'
+  | 'calendar'
+  | 'image'
+  | 'chevron-left'
+  | 'chevron-right'
+  | 'chevron-down'
+  // consent hero + process steps
+  | 'shield'
+  | 'badge-check'
+  | 'circle-dashed'
+  | 'circle-check'
+  | 'circle-help'
+  | 'circle-x'
+  | 'building-2'
+  | 'stamp'
+  | 'user'
+  | 'user-plus'
+  | 'plus'
+  | 'info'
+  | 'users'
+  | 'scan-line'
+  | 'scan-face'
+  | 'nfc'
+  | 'filter'
+  | 'pencil'
+  | 'pencil-line'
+  | 'search'
+  | 'zap'
+  | 'link'
+  | 'copy'
+  | 'share'
+  | 'zap-off'
+  | 'timer'
+  // id-type glyphs
+  | 'fingerprint'
+  | 'credit-card'
+  | 'globe'
+  | 'car'
+  | 'vote'
+  | 'file-text'
+  | 'house'
+  | 'landmark'
+  | 'id-card'
+  | 'contact'
+  | 'passport'
+  | 'camera'
+  | 'camera-off'
+  | 'video-off'
+  | 'upload'
+  | 'x'
+  // address collection (map picker + the presence milestone track)
+  | 'map-pin'
+  | 'map-pin-house'
+  | 'map-pin-check'
+  | 'map-pinned'
+  | 'radar'
+  | 'bell-ring'
+  | 'sliders'
+  | 'locate'
+  | 'minus'
+  | 'lightbulb'
+  // contact verification (OTP channels + step footer)
+  | 'mail'
+  | 'smartphone'
+  | 'message-square'
+  | 'message-circle';

package/src/components/stepHeaderMeta.tsx

@@ -1,6 +1,7 @@
 import { ID_TYPES } from '../config/idTypes';
 import { poaDocumentTypes, poaMaxAgeDays, poaNamePolicy } from '../config/proofOfAddress';
 import { documentCaptureMeta } from '../screens/DocumentCaptureStep';
+import { documentCaptureMethods } from '../config/documentCaptureMethods';
 import { questionnaireMeta } from '../screens/QuestionnaireStep';
 import { contactCodeLength, contactMeta, type ContactChallenge } from '../config/contact';
 
@@ -9,6 +10,8 @@ import { addressStepMeta } from '../screens/address';
 import { countrySelectMeta } from '../screens/CountrySelectStep';
 import { businessDetailsMeta } from '../screens/BusinessDetailsStep';
 import { businessKeyPeopleMeta } from '../screens/BusinessKeyPeopleStep';
+import { supportingDocumentsMeta } from '../screens/SupportingDocumentsStep';
+import { resolveSupportingDocuments, verifiedIdsFor } from '../config/supportingDocuments';
 import { businessDocumentsMeta } from '../screens/BusinessDocumentsStep';
 import { applicantRoleMeta } from '../screens/ApplicantRoleStep';
 import { nfcMeta } from '../screens/NfcStep';
@@ -48,6 +51,9 @@ export interface StepHeaderContext {
   /** The proof-of-address kind the applicant has picked, so the header can ask
    *  for what the workflow's name rule wants on THAT document. */
   poaDocumentType?: string | null;
+  /** The committed multi-ID slots, so the supporting-documents header resolves
+   *  the SAME list the screen shows. */
+  multiIdSlots?: Array<{ idType: string }>;
 }
 
 export function stepHeaderMeta(
@@ -61,6 +67,7 @@ export function stepHeaderMeta(
     addressIntroPending,
     addressEntranceFraming,
     poaDocumentType,
+    multiIdSlots,
   }: StepHeaderContext,
 ): { title: string; description: string | null } {
   const label = labelFor(country, selectedIdType);
@@ -77,7 +84,11 @@ export function stepHeaderMeta(
       case 'document-capture':
         // Phase-aware title/description live in the header (synced from the
         // capture screen via `documentCapturePhase`) — mirrors Flutter.
-        return documentCaptureMeta(documentCapturePhase, label);
+        return documentCaptureMeta(
+          documentCapturePhase,
+          label,
+          documentCaptureMethods(config).scan ? 'scan' : 'upload',
+        );
       case 'liveness':
         return { title: 'Face Verification', description: 'Follow the on-screen instructions' };
       case 'questionnaire':
@@ -116,6 +127,15 @@ export function stepHeaderMeta(
         return businessKeyPeopleMeta;
       case 'business-documents':
         return businessDocumentsMeta;
+      case 'supporting-documents':
+        // Resolved exactly as the screen resolves its own slots, or the header
+        // could name a number the body does not show.
+        return supportingDocumentsMeta(
+          resolveSupportingDocuments(
+            config.supportingDocuments,
+            verifiedIdsFor({ country, idType: selectedIdType, multiIdSlots }),
+          ),
+        );
       case 'applicant-role':
         return applicantRoleMeta;
       case 'nfc':

package/src/config/documentCaptureMethods.ts

@@ -0,0 +1,31 @@
+// ---------------------------------------------------------------------------
+// How the applicant may put a document in front of us.
+//
+// Two workflow switches, each on unless set to `false`: `allowDocumentScan`
+// (photograph it with the live camera) and `allowDocumentUpload` (choose a
+// photo of it from the device). The server refuses to publish a workflow with
+// both off, but a stored or prop-supplied config can still carry that, and a
+// document step with no way in is a dead end. So the camera comes back on in
+// that case: it is the method the step was built around.
+//
+// Screens read the pair through here and never the raw keys, so the fallback
+// is one rule rather than a check every screen has to remember. Mirrors the
+// web and Flutter SDKs.
+// ---------------------------------------------------------------------------
+
+export interface DocumentCaptureMethods {
+  /** Photograph the document with the live camera. */
+  scan: boolean;
+  /** Choose a photo of the document from the device. */
+  upload: boolean;
+}
+
+export function documentCaptureMethods(config: {
+  allowDocumentScan?: boolean;
+  allowDocumentUpload?: boolean;
+}): DocumentCaptureMethods {
+  const upload = config.allowDocumentUpload !== false;
+  // With upload off the camera is the only way left, whatever its flag says.
+  const scan = upload ? config.allowDocumentScan !== false : true;
+  return { scan, upload };
+}

package/src/config/stepOrder.ts

@@ -44,6 +44,14 @@ export interface StepOrderOptions {
   hasEmailVerification: boolean;
   hasPhoneVerification: boolean;
   hasPoa: boolean;
+  /**
+   * Whether the supporting-documents step has anything to ask for on THIS
+   * attempt. Resolved by the caller (config/supportingDocuments.ts) because
+   * the list depends on the ID the person actually picked — a document scoped
+   * to one ID is not asked of somebody who used another, and a step with an
+   * empty list must not appear at all.
+   */
+  hasSupportingDocuments: boolean;
   hasAddressCollection: boolean;
   /**
    * Which address screens the flow has, from the ONE `addressFlowFor` call.
@@ -120,11 +128,15 @@ function fullStepOrder(o: StepOrderOptions): KYCStep[] {
   if (o.scope === 'address') {
     const steps: KYCStep[] = [...openingSteps(o), ...contactSteps(o)];
     if (o.hasPoa) steps.push('proof-of-address');
-    steps.push(
-      ...addressFlowSteps(
-        o.addressFlow ?? { searchAvailable: false, photoMode: 'optional', streetViewOffered: false },
-      ),
-    );
+    // Gated like the full flow, and like Flutter has always done it: an
+    // address flow that asks only for proof of address never opens a map.
+    if (o.hasAddressCollection) {
+      steps.push(
+        ...addressFlowSteps(
+          o.addressFlow ?? { searchAvailable: false, photoMode: 'optional', streetViewOffered: false },
+        ),
+      );
+    }
     if (o.hasQuestionnaire) steps.push('questionnaire');
     steps.push('submitted');
     return steps;
@@ -143,6 +155,9 @@ function fullStepOrder(o: StepOrderOptions): KYCStep[] {
   }
 
   const middle: KYCStep[] = [...captureLeg(o)];
+  // Paperwork the org files comes BEFORE the address evidence the
+  // verification is judged on (user decision 2026-09-22).
+  if (o.hasSupportingDocuments) middle.push('supporting-documents');
   if (o.hasPoa) middle.push('proof-of-address');
   // The address flow is FOUR real steps on an individual flow (find it, confirm
   // it, show it, commit it), so the progress bar advances through them and back

package/src/config/supportingDocuments.ts

@@ -0,0 +1,131 @@
+import type { SupportingDocumentsConfig } from '../types/workflow';
+
+// Which supporting documents this flow asks for, given the ID the person
+// actually verified with.
+//
+// MIRROR of the server's `requestedSupportingDocuments`
+// (kyc-core src/lib/workflows/supporting-documents-config.ts) and of the web
+// SDK's lib/supporting-documents.ts. Three copies of one rule: the mobile SDKs
+// cannot import the web package, so a change here changes all three in the
+// same commit. The server VALIDATES what the client produced, so a client that
+// resolved differently just builds submissions the server refuses.
+//
+// There is no catalogue to mirror: a document is whatever the ORG named it, so
+// the SDK renders the title and guidance the workflow sent rather than
+// captioning a key it recognises.
+
+export interface RequestedSupportingDocument {
+  key: string;
+  label: string;
+  /** Guidance under the slot, when the author wrote some. */
+  description: string | null;
+  required: boolean;
+  /**
+   * The names of the values the server will read off it, for the card to show.
+   *
+   * DISPLAY ONLY, and deliberately not a mirror of the server's own field
+   * resolution: it drops blanks and repeats and stops there. The server decides
+   * what is actually read, and an extra name on a chip costs an applicant
+   * nothing.
+   */
+  reads: string[];
+}
+
+/** The names on one document's fields: what the applicant is told we read. */
+function documentReads(fields: Array<{ label?: string }> | undefined): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const field of fields ?? []) {
+    const label = field.label?.trim();
+    if (!label || seen.has(label.toLowerCase())) continue;
+    seen.add(label.toLowerCase());
+    out.push(label);
+  }
+  return out;
+}
+
+/** `${country}/${idType}` — the composite a document's `idTypes` is written in. */
+export function idComposite(country: string, idType: string): string {
+  return `${country.trim().toUpperCase()}/${idType.trim()}`;
+}
+
+/**
+ * The documents to ask for. An empty result means the step does not appear:
+ * a document that exists only because the person used a particular ID must not
+ * be put in front of somebody who used another.
+ */
+export function resolveSupportingDocuments(
+  config: SupportingDocumentsConfig | undefined | null,
+  verifiedIds: string[],
+): RequestedSupportingDocument[] {
+  if (!config?.enabled) return [];
+  const wanted = new Set(verifiedIds.map((id) => id.toUpperCase()));
+  const seen = new Set<string>();
+  const out: RequestedSupportingDocument[] = [];
+  for (const entry of config.types ?? []) {
+    const label = entry.label?.trim();
+    // A nameless slot reaches nobody. Publish refuses one, so this only ever
+    // bites a draft mid-edit.
+    if (!label) continue;
+    const scoped = entry.idTypes && entry.idTypes.length > 0;
+    const inScope =
+      !scoped || entry.idTypes!.some((id) => wanted.has(id.trim().toUpperCase()));
+    // `alwaysAsk` keeps the slot on screen for everybody, so the scope decides
+    // only who must fill it: an out-of-scope applicant may hand the document
+    // over and is never blocked for not having one.
+    if (!inScope && entry.alwaysAsk !== true) continue;
+    if (seen.has(entry.key)) continue;
+    seen.add(entry.key);
+    out.push({
+      key: entry.key,
+      label,
+      description: entry.description?.trim() || null,
+      required: entry.required === true && inScope,
+      reads: documentReads(entry.fields),
+    });
+  }
+  return out;
+}
+
+/** The composites this attempt has committed — one per ID, multi-ID included. */
+export function verifiedIdsFor(input: {
+  country?: string | null;
+  idType?: string | null;
+  multiIdSlots?: Array<{ idType: string }>;
+}): string[] {
+  if (!input.country) return [];
+  const slots = input.multiIdSlots ?? [];
+  const ids = slots.length > 0 ? slots.map((s) => s.idType) : input.idType ? [input.idType] : [];
+  return [...new Set(ids.map((id) => idComposite(input.country!, id)))];
+}
+
+/**
+ * Whether the flow may ask for a supporting document AT ALL.
+ *
+ * The CONSENT screen's question, deliberately not the step order's.
+ * `hasSupportingDocumentsStep` resolves against the VERIFIED IDS, and consent
+ * runs before an ID is picked — so every SCOPED document answers "nothing to
+ * ask for" there, and a slip scoped to one ID (the commonest case there is)
+ * would go undisclosed.
+ *
+ * Consent is a DISCLOSURE of what MAY be collected: an applicant seeing a
+ * bullet for paperwork they are never asked for is the cheap error, and being
+ * asked for undisclosed paperwork is the real one.
+ *
+ * Still not a raw field check — a disabled step and a nameless entry each
+ * promise nothing, the same two gates the resolver applies.
+ */
+export function mayAskSupportingDocuments(
+  config: SupportingDocumentsConfig | undefined | null,
+): boolean {
+  if (!config?.enabled) return false;
+  return (config.types ?? []).some((entry) => (entry.label ?? '').trim().length > 0);
+}
+
+/** Whether the step has anything to ask for on this attempt. */
+export function hasSupportingDocumentsStep(
+  config: SupportingDocumentsConfig | undefined | null,
+  verifiedIds: string[],
+): boolean {
+  return resolveSupportingDocuments(config, verifiedIds).length > 0;
+}

package/src/config/theme.ts

@@ -161,6 +161,22 @@ function toHex({ r, g, b }: Rgb): string {
 }
 
 /** Alpha-blends `fg` over `bg` at opacity `alpha` (0–1). */
+/**
+ * `color` at `alpha`, as an 8-digit hex React Native composites itself.
+ *
+ * Falls back to blending against `fallbackBg` when the colour is not hex (an
+ * `rgb()` or a named colour), which is the old behaviour rather than a crash.
+ */
+function withAlpha(color: string, alpha: number, fallbackBg: string): string {
+  const parsed = parseHex(color);
+  if (!parsed) return alphaBlend(color, fallbackBg, alpha);
+  const byte = Math.round(Math.min(Math.max(alpha, 0), 1) * 255)
+    .toString(16)
+    .padStart(2, '0');
+  const hex = (n: number) => Math.round(n).toString(16).padStart(2, '0');
+  return `#${hex(parsed.r)}${hex(parsed.g)}${hex(parsed.b)}${byte}`;
+}
+
 function alphaBlend(fg: string, bg: string, alpha: number): string {
   const f = parseHex(fg);
   const b = parseHex(bg);
@@ -197,9 +213,19 @@ export function applyAppearance(
 
   if (appearance.primaryColor) {
     next.primary = appearance.primaryColor;
-    next.primary50 = alphaBlend(appearance.primaryColor, background, 0.04);
-    next.primary100 = alphaBlend(appearance.primaryColor, background, 0.1);
-    next.primary200 = alphaBlend(appearance.primaryColor, background, 0.2);
+    // Real alpha, not a pre-blend. These tints are drawn on several different
+    // surfaces - the sheet, a card, a pill - and pre-blending has to guess ONE
+    // of them. It guessed `background`, so on a card (backgroundSecondary) the
+    // 10% tint landed within 3/255 of the card it sat on and the supporting
+    // documents step drew its numbered markers invisibly (user report
+    // 2026-09-25). Carrying the alpha lets each one composite against whatever
+    // it is actually on, which is what the web SDK's `bg-primary/10` does and
+    // why it never had this bug. On `background` the result matches the old
+    // pre-blend to within 1/255 - an alpha byte cannot hold 0.1 exactly - so
+    // nothing that was already correct moves perceptibly.
+    next.primary50 = withAlpha(appearance.primaryColor, 0.04, background);
+    next.primary100 = withAlpha(appearance.primaryColor, 0.1, background);
+    next.primary200 = withAlpha(appearance.primaryColor, 0.2, background);
   }
   if (appearance.accentColor) {
     next.primary100 = appearance.accentColor;