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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myazahq/kyc-sdk-react-native",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Myaza KYC SDK for React Native (Expo) — ID verification, liveness detection, and document capture",
   "author": "Flitstack Technologies Inc.",
   "repository": {
@@ -54,7 +54,6 @@
     "expo-document-picker": ">=56",
     "expo-localization": ">=56",
     "expo-task-manager": ">=14",
-    "react-native-webview": ">=13",
     "react": ">=19",
     "react-native": ">=0.83",
     "react-native-nitro-image": ">=0.15",
@@ -62,6 +61,7 @@
     "react-native-safe-area-context": ">=4",
     "react-native-svg": ">=15",
     "react-native-vision-camera-worklets": ">=5",
+    "react-native-webview": ">=13",
     "react-native-worklets": ">=0.8"
   },
   "peerDependenciesMeta": {
@@ -85,21 +85,22 @@
     }
   },
   "dependencies": {
+    "@hugeicons/core-free-icons": "4.3.5",
+    "@hugeicons/react-native": "1.0.16",
     "country-flag-icons": "^1.6.17",
-    "libphonenumber-js": "^1.13.8",
-    "expo-crypto": "~56.0.4",
     "expo-clipboard": "~56.0.0",
+    "expo-crypto": "~56.0.4",
+    "expo-file-system": "~56.0.0",
     "expo-font": "~56.0.5",
     "expo-glass-effect": "~56.0.4",
     "expo-image-manipulator": "~56.0.17",
     "expo-image-picker": "~56.0.16",
     "expo-location": "~56.0.24",
     "expo-speech": "~56.0.3",
-    "lucide-react-native": "^1.17.0",
+    "libphonenumber-js": "^1.13.8",
     "react-native-compressor": "^1.19.0",
     "react-native-vision-camera": "^5.0.11",
-    "zustand": "^5.0.2",
-    "expo-file-system": "~56.0.0"
+    "zustand": "^5.0.2"
   },
   "devDependencies": {
     "@types/jest": "^29.5.12",

package/src/components/GlassIconButton.tsx

@@ -17,8 +17,6 @@ export interface GlassIconButtonProps {
   size?: number;
   iconSize?: number;
   disabled?: boolean;
-  /** Render the glyph solid/filled (e.g. the theme toggle). */
-  solid?: boolean;
   /**
    * Skip this button's own glass surface — used when it sits inside a
    * {@link GlassGroup} that already provides one shared glass capsule, so the
@@ -35,7 +33,6 @@ export function GlassIconButton({
   size = 40,
   iconSize = 20,
   disabled = false,
-  solid = false,
   plain = false,
   accessibilityLabel,
 }: GlassIconButtonProps): React.ReactElement {
@@ -54,7 +51,7 @@ export function GlassIconButton({
         overflow: 'hidden',
       }}
     >
-      <Icon name={icon} size={iconSize} color={iconColor} solid={solid} />
+      <Icon name={icon} size={iconSize} color={iconColor} />
     </View>
   );
 
@@ -71,7 +68,7 @@ export function GlassIconButton({
           justifyContent: 'center',
         }}
       >
-        <Icon name={icon} size={iconSize} color={iconColor} solid={solid} />
+        <Icon name={icon} size={iconSize} color={iconColor} />
       </GlassSurface>
     ) : (
       glyph

package/src/components/Icon.tsx

@@ -1,26 +1,29 @@
 import React from 'react';
+import { HugeiconsIcon } from '@hugeicons/react-native';
 
-import { ICONS, type IconName } from './icon-map';
+import { ICONS, type IconName } from './icons';
 
-export type { IconName } from './icon-map';
+export type { IconName } from './icons';
 
 export interface IconProps {
   name: IconName;
   size?: number;
   color: string;
   strokeWidth?: number;
-  /** Render a solid/filled glyph (used for the theme toggle, matching Flutter's filled moon/sun). */
-  solid?: boolean;
 }
 
-export function Icon({ name, size = 20, color, strokeWidth = 2, solid = false }: IconProps): React.ReactElement {
-  const Glyph = ICONS[name];
-  // The theme toggle's filled moon/sun (Flutter's dark_mode/light_mode). Lucide
-  // ships no filled variants, so the glyph's own body takes the colour: the
-  // moon's crescent and the sun's disc fill, the sun's rays stay strokes. This
-  // replaced an Ionicons import that was the SDK's ONLY use of
-  // @expo/vector-icons, a package whose icon fonts still reached every
-  // integrator's app for those two glyphs (1.35 MB on a real release APK).
-  const fill = solid && (name === 'moon' || name === 'sun') ? color : 'none';
-  return <Glyph size={size} color={color} strokeWidth={strokeWidth} fill={fill} />;
+/**
+ * Every icon this SDK draws goes through here.
+ *
+ * The stroke is 1.6 to match the web SDK and the dashboard, which draw the
+ * same set at that weight. It was 2 while this SDK drew Lucide, whose glyphs
+ * are built for it.
+ *
+ * There is deliberately no `solid` prop. It existed to fill the theme toggle's
+ * moon and sun, which worked because Lucide's glyph bodies take a fill.
+ * Hugeicons' free pack is Stroke Rounded only - the solid styles are Pro - so
+ * the toggle now draws stroked, which is what Flutter has always done.
+ */
+export function Icon({ name, size = 20, color, strokeWidth = 1.6 }: IconProps): React.ReactElement {
+  return <HugeiconsIcon icon={ICONS[name]} size={size} color={color} strokeWidth={strokeWidth} />;
 }

package/src/components/KycFlow.tsx

@@ -109,6 +109,7 @@ export function KycFlow({
         addressIntroPending,
         addressEntranceFraming: state.addressEntranceFraming,
         poaDocumentType: state.poaDocumentType,
+        multiIdSlots: state.multiIdSlots,
       }),
     [
       currentStep,

package/src/components/KycSheet.tsx

@@ -212,7 +212,6 @@ export function KycSheet({
                   <GlassIconButton
                     icon={mode === "dark" ? "sun" : "moon"}
                     onPress={toggle}
-                    solid
                     plain={showClose}
                     accessibilityLabel="Toggle theme"
                   />

package/src/components/StepView.tsx

@@ -11,6 +11,7 @@ import { LivenessStep } from '../screens/LivenessStep';
 import { SubmittedStep } from '../screens/SubmittedStep';
 import { QuestionnaireStep } from '../screens/QuestionnaireStep';
 import { ContactVerificationStep } from '../screens/ContactVerificationStep';
+import { SupportingDocumentsStep } from '../screens/SupportingDocumentsStep';
 import { ProofOfAddressStep } from '../screens/ProofOfAddressStep';
 import {
   AddressEntranceStep,
@@ -84,6 +85,8 @@ function stepScreen(step: KYCStep, onClose: () => void): React.ReactElement {
       return <ContactVerificationStep key="contact-phone" channel="phone" />;
     case 'proof-of-address':
       return <ProofOfAddressStep />;
+    case 'supporting-documents':
+      return <SupportingDocumentsStep />;
     // The address flow, in order: find it, confirm it, show it, commit it.
     // 'address-collection' is the PIN step and keeps that wire name so older
     // session progress restores cleanly.

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

@@ -10,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';
@@ -49,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(
@@ -62,6 +67,7 @@ export function stepHeaderMeta(
     addressIntroPending,
     addressEntranceFraming,
     poaDocumentType,
+    multiIdSlots,
   }: StepHeaderContext,
 ): { title: string; description: string | null } {
   const label = labelFor(country, selectedIdType);
@@ -121,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/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