@incodetech/prizma-core-screens 0.1.0

package/src/flows.ts

@@ -0,0 +1,711 @@
+// Per-module screen sequences — the data the FlowPlayer prototypes step
+// through. A flow is pure data: ordered `{ screenId, component }` entries plus
+// the fixed `variant` props that pin a component to ONE Figma spec section when
+// a single component covers several (GUIDELINES.md §8).
+//
+// Flows carry NO copy: every screen takes the module's one `strings` object, so
+// the player renders `<step.component strings={strings} {...step.variant} />`.
+
+import type { ComponentType } from 'react';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type {
+  FaceCaptureCapturingState,
+  FaceCaptureStrings,
+} from './FaceCaptureStrings';
+import { FaceCaptureTutorialScreen } from './FaceCaptureTutorialScreen';
+import { FaceCaptureCapturingScreen } from './FaceCaptureCapturingScreen';
+import { FaceCaptureManualCaptureScreen } from './FaceCaptureManualCaptureScreen';
+import { FaceCaptureLoadingScreen } from './FaceCaptureLoadingScreen';
+import { FaceCaptureResultSuccessScreen } from './FaceCaptureResultSuccessScreen';
+import { FaceCaptureResultErrorScreen } from './FaceCaptureResultErrorScreen';
+import { FaceCaptureNoConnectionScreen } from './FaceCaptureNoConnectionScreen';
+import type {
+  FaceMatchComparisonVariant,
+  FaceMatchLivenessVerdict,
+  FaceMatchResultStatus,
+  FaceMatchStrings,
+} from './FaceMatchStrings';
+import { FaceMatchComparisonScreen } from './FaceMatchComparisonScreen';
+import { FaceMatchComparisonCompactScreen } from './FaceMatchComparisonCompactScreen';
+import { FaceMatchResultScreen } from './FaceMatchResultScreen';
+import type {
+  DocumentCaptureConfirmStage,
+  DocumentCaptureMethodSelectionVariant,
+  DocumentCaptureStrings,
+  DocumentCaptureTutorialVariant,
+} from './DocumentCaptureStrings';
+import { DocumentCaptureTutorialScreen } from './DocumentCaptureTutorialScreen';
+import { DocumentCaptureMethodSelectionScreen } from './DocumentCaptureMethodSelectionScreen';
+import { DocumentCaptureCaptureScreen } from './DocumentCaptureCaptureScreen';
+import { DocumentCaptureConfirmImageScreen } from './DocumentCaptureConfirmImageScreen';
+import { DocumentCaptureConfirmUploadScreen } from './DocumentCaptureConfirmUploadScreen';
+import { DocumentCaptureNextPageScreen } from './DocumentCaptureNextPageScreen';
+import { DocumentCaptureCommonIssuesScreen } from './DocumentCaptureCommonIssuesScreen';
+import { DocumentCaptureGenericErrorScreen } from './DocumentCaptureGenericErrorScreen';
+import { DocumentCaptureNoConnectionScreen } from './DocumentCaptureNoConnectionScreen';
+import type {
+  IdCaptureDocumentType,
+  IdCaptureSide,
+  IdCaptureStageState,
+  IdCaptureStrings,
+} from './IdCaptureStrings';
+import {
+  IdCaptureTutorialScreen,
+  type IdCaptureTutorialVariant,
+} from './IdCaptureTutorialScreen';
+import { IdCaptureStageScreen } from './IdCaptureStageScreen';
+import {
+  IdCaptureResultScreen,
+  type IdCaptureResultVerdict,
+} from './IdCaptureResultScreen';
+import { IdCaptureAnalyzingScreen } from './IdCaptureAnalyzingScreen';
+import { IdCaptureFlipScreen } from './IdCaptureFlipScreen';
+import { IdCaptureHoldOnScreen } from './IdCaptureHoldOnScreen';
+import { IdCaptureNoConnectionScreen } from './IdCaptureNoConnectionScreen';
+import { IdCaptureDocumentSelectionScreen } from './IdCaptureDocumentSelectionScreen';
+import { IdCaptureAgeVerificationScreen } from './IdCaptureAgeVerificationScreen';
+import { IdCaptureCommonIssuesScreen } from './IdCaptureCommonIssuesScreen';
+import { IdCapturePermissionScreen } from './IdCapturePermissionScreen';
+import { IdCaptureDocumentErrorScreen } from './IdCaptureDocumentErrorScreen';
+
+/** The prop shape EVERY Face Capture screen accepts — the flow player needs
+ *  nothing more to render any step. */
+export interface FaceCaptureScreenProps {
+  strings: FaceCaptureStrings;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/** Fixed variant props: they select the Figma spec section, never the copy. */
+export interface FaceCaptureFlowVariant {
+  /** FaceCaptureTutorialScreen — `faceCapture.tutorial.loading`. */
+  ctaLoading?: boolean;
+  /** FaceCaptureCapturingScreen — which of the 15 `capturing.*` sections. */
+  state?: FaceCaptureCapturingState;
+  /** FaceCaptureLoadingScreen — `loading.uploading` vs `loading.processing`. */
+  stage?: 'uploading' | 'processing';
+  /** FaceCaptureResultErrorScreen — the `*Exhausted` half of the error pairs. */
+  exhausted?: boolean;
+}
+
+export interface FaceCaptureFlowStep {
+  /** Stable screen id — also what the screen reports through `onAction`. */
+  screenId: string;
+  component: ComponentType<FaceCaptureScreenProps>;
+  variant?: FaceCaptureFlowVariant;
+}
+
+/**
+ * Face Capture — the happy path, in the order the purple Figma sections are
+ * numbered (1 tutorial → 2 capturing → 3 manualCapture → 4 loading →
+ * 5 resultSuccess), which is also GUIDELINES.md §8's canonical capture
+ * sequence.
+ *
+ * `faceCapture.resultError.*` and `faceCapture.genericErrors.noConnection` are
+ * NOT steps: they are branches the host swaps in when a verdict or the network
+ * fails. They are exported separately so a player can offer them without
+ * implying they follow success.
+ */
+export const faceCaptureFlow: readonly FaceCaptureFlowStep[] = [
+  { screenId: 'face-capture-tutorial', component: FaceCaptureTutorialScreen },
+  {
+    screenId: 'face-capture-capturing',
+    component: FaceCaptureCapturingScreen,
+    variant: { state: 'initiating' },
+  },
+  {
+    screenId: 'face-capture-capturing-align',
+    component: FaceCaptureCapturingScreen,
+    variant: { state: 'alignFace' },
+  },
+  {
+    screenId: 'face-capture-capturing-ready',
+    component: FaceCaptureCapturingScreen,
+    variant: { state: 'getReady' },
+  },
+  {
+    screenId: 'face-capture-uploading',
+    component: FaceCaptureLoadingScreen,
+    variant: { stage: 'uploading' },
+  },
+  {
+    screenId: 'face-capture-processing',
+    component: FaceCaptureLoadingScreen,
+    variant: { stage: 'processing' },
+  },
+  { screenId: 'face-capture-success', component: FaceCaptureResultSuccessScreen },
+];
+
+/** The off-path screens: manual capture (offered when auto-capture is turned
+ *  off or gives up), the two error verdicts, and the connectivity error. */
+export const faceCaptureBranches: readonly FaceCaptureFlowStep[] = [
+  {
+    screenId: 'face-capture-manual-capture',
+    component: FaceCaptureManualCaptureScreen,
+  },
+  { screenId: 'face-capture-error', component: FaceCaptureResultErrorScreen },
+  {
+    screenId: 'face-capture-error-exhausted',
+    component: FaceCaptureResultErrorScreen,
+    variant: { exhausted: true },
+  },
+  {
+    screenId: 'face-capture-no-connection',
+    component: FaceCaptureNoConnectionScreen,
+  },
+];
+
+/* ── Face Match ─────────────────────────────────────────────────────────────
+ * Purple sections of the Face Match Figma file (BXeJ6Q3TXahJVWEt8QoMVA, page
+ * 18:19332): faceMatch.comparison (5) · comparisonCompact (1) · error (3) ·
+ * success (3).
+ *
+ * NOTE ON REUSE: no Face Capture component appears in these flows. Face Match
+ * ships no tutorial and no capture stage — its images come from the modules
+ * upstream — and its three screens each differ structurally from the Face
+ * Capture screen they superficially resemble: the comparison view is a new
+ * two/three-photo composition, `comparisonCompact.matching` really centers (so
+ * it is archetype C, while FaceCaptureLoadingScreen is archetype B), and the six
+ * result sections need a positive status and a verdict Snackbar that
+ * FaceCaptureResultErrorScreen has no slot for. What IS reused is the
+ * foundation: PrizmaProcessingScreen verbatim, plus ScreenShell / ScreenNav /
+ * ScreenLayout.css. DEVIATIONS.md #24. */
+
+/** The prop shape EVERY Face Match screen accepts. */
+export interface FaceMatchScreenProps {
+  strings: FaceMatchStrings;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/** Fixed variant props: they select the Figma spec section, never the copy. */
+export interface FaceMatchFlowVariant {
+  /** FaceMatchComparisonScreen — which purple photo set. */
+  variant?: FaceMatchComparisonVariant;
+  /** FaceMatchComparisonScreen — the converged `*.matching` sections. */
+  matching?: boolean;
+  /** FaceMatchResultScreen — `success.*` vs `error.*`. */
+  status?: FaceMatchResultStatus;
+  /** FaceMatchResultScreen — the `*.liveness{Success,Failed}` halves. */
+  liveness?: FaceMatchLivenessVerdict;
+}
+
+export interface FaceMatchFlowStep {
+  /** Stable screen id — also what the screen reports through `onAction`. */
+  screenId: string;
+  component: ComponentType<FaceMatchScreenProps>;
+  variant?: FaceMatchFlowVariant;
+}
+
+/**
+ * Face Match — the happy path: the two captured photos are presented, they
+ * converge while the comparison runs, and the verdict is a match.
+ *
+ * The other comparison variants (`nfc`, `firstAndSecondID`,
+ * `threeFacesMatching`), the photo-less compact matching state and the failing /
+ * liveness verdicts are branches, exported separately.
+ */
+export const faceMatchFlow: readonly FaceMatchFlowStep[] = [
+  {
+    screenId: 'face-match-comparison',
+    component: FaceMatchComparisonScreen,
+    variant: { variant: 'selfieId' },
+  },
+  {
+    screenId: 'face-match-comparison-matching',
+    component: FaceMatchComparisonScreen,
+    variant: { variant: 'selfieId', matching: true },
+  },
+  {
+    screenId: 'face-match-matched',
+    component: FaceMatchResultScreen,
+    variant: { status: 'matched' },
+  },
+];
+
+/**
+ * The off-path screens: the three-photo comparison variants (NFC portrait, or a
+ * second document, joining the selfie), the compact matching state shown when
+ * the captures are not displayed, and the five remaining verdicts.
+ *
+ * `comparison.threeFacesMatching` is the converged state of BOTH three-photo
+ * variants — Figma authors it once, with the labels hidden, so `nfc` stands in
+ * for either.
+ */
+export const faceMatchBranches: readonly FaceMatchFlowStep[] = [
+  {
+    screenId: 'face-match-comparison-nfc',
+    component: FaceMatchComparisonScreen,
+    variant: { variant: 'nfc' },
+  },
+  {
+    screenId: 'face-match-comparison-first-and-second-id',
+    component: FaceMatchComparisonScreen,
+    variant: { variant: 'firstAndSecondID' },
+  },
+  {
+    screenId: 'face-match-comparison-three-faces-matching',
+    component: FaceMatchComparisonScreen,
+    variant: { variant: 'nfc', matching: true },
+  },
+  {
+    screenId: 'face-match-comparison-compact',
+    component: FaceMatchComparisonCompactScreen,
+  },
+  {
+    screenId: 'face-match-not-matched',
+    component: FaceMatchResultScreen,
+    variant: { status: 'notMatched' },
+  },
+  {
+    screenId: 'face-match-matched-liveness-success',
+    component: FaceMatchResultScreen,
+    variant: { status: 'matched', liveness: 'success' },
+  },
+  {
+    screenId: 'face-match-matched-liveness-failed',
+    component: FaceMatchResultScreen,
+    variant: { status: 'matched', liveness: 'failed' },
+  },
+  {
+    screenId: 'face-match-not-matched-liveness-success',
+    component: FaceMatchResultScreen,
+    variant: { status: 'notMatched', liveness: 'success' },
+  },
+  {
+    screenId: 'face-match-not-matched-liveness-failed',
+    component: FaceMatchResultScreen,
+    variant: { status: 'notMatched', liveness: 'failed' },
+  },
+];
+
+/* ══════════════════════════════════════════════════════════════════════════
+   Document Capture (wave 2)
+   ══════════════════════════════════════════════════════════════════════════ */
+
+/** The prop shape EVERY Document Capture screen accepts. */
+export interface DocumentCaptureScreenProps {
+  strings: DocumentCaptureStrings;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/** Fixed variant props: they select the Figma spec section, never the copy. */
+export interface DocumentCaptureFlowVariant {
+  /** DocumentCaptureTutorialScreen — which `tutorial.*` intro section. */
+  variant?: DocumentCaptureTutorialVariant;
+  /** DocumentCaptureMethodSelectionScreen — 2-row (web), 3-row (native), or the
+   *  native pair without the camera row (nativeUpload). */
+  method?: DocumentCaptureMethodSelectionVariant;
+  /** DocumentCaptureCaptureScreen — `capture.default` vs `capture.filled`. */
+  state?: 'empty' | 'filled';
+  /** DocumentCaptureConfirm*Screen — review / analyzing / success. */
+  stage?: DocumentCaptureConfirmStage;
+  /** DocumentCaptureNextPageScreen — the `.mandatory` half of the pair. */
+  mandatory?: boolean;
+  /** DocumentCaptureGenericErrorScreen — the `*Exhausted` half of the pair. */
+  exhausted?: boolean;
+}
+
+export interface DocumentCaptureFlowStep {
+  /** Stable screen id — also what the screen reports through `onAction`. */
+  screenId: string;
+  component: ComponentType<DocumentCaptureScreenProps>;
+  variant?: DocumentCaptureFlowVariant;
+}
+
+/**
+ * Document Capture BRANCHES at the tutorial: the method sheet sends the user
+ * down the camera path or the upload path, and the two paths have different
+ * confirmation screens (`confirmImage.*` vs `confirmUpload.*`). So the module
+ * ships three sequences instead of one:
+ *
+ *   documentCaptureFlow        the shared head — tutorial → method sheet
+ *   documentCaptureCameraFlow  capture → confirmImage(review→analyzing→success)
+ *   documentCaptureUploadFlow  confirmUpload(review→analyzing→success)
+ *
+ * `documentCaptureBranchesByMethod` maps the sheet's two answers onto the two
+ * tails, so a player can resolve the branch without hardcoding screen ids.
+ *
+ * Not steps in any sequence: `commonIssues` (help, reachable from the camera
+ * stage's "?" control), the two generic-error verdicts, and the connectivity
+ * error. They are exported as `documentCaptureBranches`.
+ */
+export const documentCaptureFlow: readonly DocumentCaptureFlowStep[] = [
+  {
+    screenId: 'document-capture-tutorial-default',
+    component: DocumentCaptureTutorialScreen,
+    variant: { variant: 'default' },
+  },
+  {
+    screenId: 'document-capture-method-selection-web',
+    component: DocumentCaptureMethodSelectionScreen,
+    variant: { method: 'web' },
+  },
+];
+
+/** Tail A — "Take photo": the dark camera stage, then the photo confirmation. */
+export const documentCaptureCameraFlow: readonly DocumentCaptureFlowStep[] = [
+  {
+    screenId: 'document-capture-capture-empty',
+    component: DocumentCaptureCaptureScreen,
+    variant: { state: 'empty' },
+  },
+  {
+    screenId: 'document-capture-capture-filled',
+    component: DocumentCaptureCaptureScreen,
+    variant: { state: 'filled' },
+  },
+  {
+    screenId: 'document-capture-confirm-image-review',
+    component: DocumentCaptureConfirmImageScreen,
+    variant: { stage: 'review' },
+  },
+  {
+    screenId: 'document-capture-confirm-image-analyzing',
+    component: DocumentCaptureConfirmImageScreen,
+    variant: { stage: 'analyzing' },
+  },
+  {
+    screenId: 'document-capture-confirm-image-success',
+    component: DocumentCaptureConfirmImageScreen,
+    variant: { stage: 'success' },
+  },
+];
+
+/** Tail B — "Upload document": the picker is OS chrome (DEVIATIONS #20), so the
+ *  Prizma sequence resumes at the file confirmation. */
+export const documentCaptureUploadFlow: readonly DocumentCaptureFlowStep[] = [
+  {
+    screenId: 'document-capture-confirm-upload-review',
+    component: DocumentCaptureConfirmUploadScreen,
+    variant: { stage: 'review' },
+  },
+  {
+    screenId: 'document-capture-confirm-upload-analyzing',
+    component: DocumentCaptureConfirmUploadScreen,
+    variant: { stage: 'analyzing' },
+  },
+  {
+    screenId: 'document-capture-confirm-upload-success',
+    component: DocumentCaptureConfirmUploadScreen,
+    variant: { stage: 'success' },
+  },
+];
+
+/** The method sheet's two answers → the tail each one leads to. */
+export const documentCaptureBranchesByMethod: Readonly<
+  Record<'camera' | 'upload', readonly DocumentCaptureFlowStep[]>
+> = {
+  camera: documentCaptureCameraFlow,
+  upload: documentCaptureUploadFlow,
+};
+
+/** The off-path screens: the two native method sheets, the multi-page prompt,
+ *  the common-issues help, the two error verdicts, and the connectivity error. */
+export const documentCaptureBranches: readonly DocumentCaptureFlowStep[] = [
+  {
+    screenId: 'document-capture-tutorial-captureOnly',
+    component: DocumentCaptureTutorialScreen,
+    variant: { variant: 'captureOnly' },
+  },
+  {
+    screenId: 'document-capture-tutorial-uploadOnly',
+    component: DocumentCaptureTutorialScreen,
+    variant: { variant: 'uploadOnly' },
+  },
+  {
+    screenId: 'document-capture-method-selection-native',
+    component: DocumentCaptureMethodSelectionScreen,
+    variant: { method: 'native' },
+  },
+  {
+    screenId: 'document-capture-method-selection-nativeUpload',
+    component: DocumentCaptureMethodSelectionScreen,
+    variant: { method: 'nativeUpload' },
+  },
+  {
+    screenId: 'document-capture-next-page',
+    component: DocumentCaptureNextPageScreen,
+  },
+  {
+    screenId: 'document-capture-next-page-mandatory',
+    component: DocumentCaptureNextPageScreen,
+    variant: { mandatory: true },
+  },
+  {
+    screenId: 'document-capture-common-issues',
+    component: DocumentCaptureCommonIssuesScreen,
+  },
+  {
+    screenId: 'document-capture-generic-error',
+    component: DocumentCaptureGenericErrorScreen,
+  },
+  {
+    screenId: 'document-capture-generic-error-exhausted',
+    component: DocumentCaptureGenericErrorScreen,
+    variant: { exhausted: true },
+  },
+  {
+    screenId: 'document-capture-no-connection',
+    component: DocumentCaptureNoConnectionScreen,
+  },
+];
+
+/* ── ID Capture ───────────────────────────────────────────────────────────── */
+
+/** The prop shape EVERY ID Capture screen accepts — the flow player needs
+ *  nothing more to render any step. */
+export interface IdCaptureScreenProps {
+  strings: IdCaptureStrings;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/** Fixed variant props: they select the Figma spec section, never the copy. */
+export interface IdCaptureFlowVariant {
+  /** IdCaptureTutorialScreen — which of the three tutorial sections. */
+  variant?: IdCaptureTutorialVariant;
+  /** IdCaptureStageScreen / IdCaptureResultScreen / IdCaptureAnalyzingScreen —
+   *  `id` vs `passport` (the `Passport capture` groups). */
+  documentType?: IdCaptureDocumentType;
+  /** IdCaptureStageScreen — which face of a two-sided document. */
+  side?: IdCaptureSide;
+  /** The `↕️ vertical` groups. */
+  vertical?: boolean;
+  /** IdCaptureStageScreen — which stage section. */
+  state?: IdCaptureStageState;
+  /** IdCaptureStageScreen — the `*-manual` sections. */
+  manual?: boolean;
+  /** IdCaptureResultScreen — which verdict section. */
+  verdict?: IdCaptureResultVerdict;
+  /** IdCaptureDocumentErrorScreen — the `-empty` section. */
+  empty?: boolean;
+}
+
+export interface IdCaptureFlowStep {
+  /** Stable screen id — also what the screen reports through `onAction`. */
+  screenId: string;
+  component: ComponentType<IdCaptureScreenProps>;
+  variant?: IdCaptureFlowVariant;
+}
+
+/**
+ * ID Capture — the happy path of a TWO-SIDED document, in the order the purple
+ * sections are numbered: document selection (1-1) → tutorial (1-2) → camera
+ * stage (1-5 … 1-8) → analyzing (1-9-1) → review (1-9-2) → front success (1-10)
+ * → flip (1-11) → back stage (1-12 … 1-15) → back analyzing (1-16-1) → back
+ * success (1-17) → hold on (1-18).
+ *
+ * The passport path is the same list without the flip and the back half, with
+ * `documentType: 'passport'` on every capture step (the `Passport capture`
+ * group's numbering, 3-x, mirrors it exactly) — see `idCapturePassportFlow`.
+ * Failures and the chrome-free error screens are branches, not steps, so they
+ * are exported separately: nothing about them follows success.
+ */
+export const idCaptureFlow: readonly IdCaptureFlowStep[] = [
+  {
+    screenId: 'id-capture-document-selection',
+    component: IdCaptureDocumentSelectionScreen,
+  },
+  {
+    screenId: 'id-capture-tutorial-front',
+    component: IdCaptureTutorialScreen,
+    variant: { variant: 'front' },
+  },
+  {
+    screenId: 'id-capture-front-empty',
+    component: IdCaptureStageScreen,
+    variant: { side: 'front', state: 'empty' },
+  },
+  {
+    screenId: 'id-capture-front-hint',
+    component: IdCaptureStageScreen,
+    variant: { side: 'front', state: 'hint' },
+  },
+  {
+    screenId: 'id-capture-front-countdown',
+    component: IdCaptureStageScreen,
+    variant: { side: 'front', state: 'countdown' },
+  },
+  {
+    screenId: 'id-capture-front-flash',
+    component: IdCaptureStageScreen,
+    variant: { side: 'front', state: 'flash' },
+  },
+  { screenId: 'id-capture-analyzing', component: IdCaptureAnalyzingScreen },
+  {
+    screenId: 'id-capture-review',
+    component: IdCaptureResultScreen,
+    variant: { verdict: 'review' },
+  },
+  {
+    screenId: 'id-capture-front-success',
+    component: IdCaptureResultScreen,
+    variant: { verdict: 'success' },
+  },
+  { screenId: 'id-capture-flip', component: IdCaptureFlipScreen },
+  {
+    screenId: 'id-capture-tutorial-back',
+    component: IdCaptureTutorialScreen,
+    variant: { variant: 'back' },
+  },
+  {
+    screenId: 'id-capture-back-empty',
+    component: IdCaptureStageScreen,
+    variant: { side: 'back', state: 'empty' },
+  },
+  {
+    screenId: 'id-capture-back-countdown',
+    component: IdCaptureStageScreen,
+    variant: { side: 'back', state: 'countdown' },
+  },
+  {
+    screenId: 'id-capture-back-analyzing',
+    component: IdCaptureAnalyzingScreen,
+  },
+  {
+    screenId: 'id-capture-back-success',
+    component: IdCaptureResultScreen,
+    variant: { verdict: 'success' },
+  },
+  { screenId: 'id-capture-hold-on', component: IdCaptureHoldOnScreen },
+];
+
+/** The single-sided passport path — the `Passport capture` group (3-x). */
+export const idCapturePassportFlow: readonly IdCaptureFlowStep[] = [
+  {
+    screenId: 'id-capture-tutorial-passport',
+    component: IdCaptureTutorialScreen,
+    variant: { variant: 'passport' },
+  },
+  {
+    screenId: 'id-capture-passport-empty',
+    component: IdCaptureStageScreen,
+    variant: { documentType: 'passport', state: 'empty' },
+  },
+  {
+    screenId: 'id-capture-passport-hint',
+    component: IdCaptureStageScreen,
+    variant: { documentType: 'passport', state: 'hint' },
+  },
+  {
+    screenId: 'id-capture-passport-countdown',
+    component: IdCaptureStageScreen,
+    variant: { documentType: 'passport', state: 'countdown' },
+  },
+  {
+    screenId: 'id-capture-passport-analyzing',
+    component: IdCaptureAnalyzingScreen,
+    variant: { documentType: 'passport' },
+  },
+  {
+    screenId: 'id-capture-passport-review',
+    component: IdCaptureResultScreen,
+    variant: { documentType: 'passport', verdict: 'review' },
+  },
+  {
+    screenId: 'id-capture-passport-success',
+    component: IdCaptureResultScreen,
+    variant: { documentType: 'passport', verdict: 'success' },
+  },
+];
+
+/**
+ * The off-path screens: the manual stage (offered when auto-capture is turned
+ * off or gives up), the five on-camera error stages, every verdict failure, the
+ * help sheet, the permission gate, the document-error screens and the
+ * connectivity error.
+ *
+ * The `↕️ vertical` groups are not separate branches — they are the same steps
+ * with `vertical: true`, which is why `idCaptureVerticalOf` exists below.
+ */
+export const idCaptureBranches: readonly IdCaptureFlowStep[] = [
+  {
+    screenId: 'id-capture-permission',
+    component: IdCapturePermissionScreen,
+  },
+  {
+    screenId: 'id-capture-age-verification',
+    component: IdCaptureAgeVerificationScreen,
+  },
+  {
+    screenId: 'id-capture-front-manual',
+    component: IdCaptureStageScreen,
+    variant: { state: 'empty', manual: true },
+  },
+  {
+    screenId: 'id-capture-front-error-wrong-side',
+    component: IdCaptureStageScreen,
+    variant: { state: 'error-wrong-side' },
+  },
+  {
+    screenId: 'id-capture-front-error-not-aligned',
+    component: IdCaptureStageScreen,
+    variant: { state: 'error-not-aligned' },
+  },
+  {
+    screenId: 'id-capture-front-error-blurry',
+    component: IdCaptureStageScreen,
+    variant: { state: 'error-blurry' },
+  },
+  {
+    screenId: 'id-capture-front-error-glare',
+    component: IdCaptureStageScreen,
+    variant: { state: 'error-glare' },
+  },
+  {
+    screenId: 'id-capture-front-error-too-dark',
+    component: IdCaptureStageScreen,
+    variant: { state: 'error-too-dark' },
+  },
+  { screenId: 'id-capture-common-issues', component: IdCaptureCommonIssuesScreen },
+  {
+    screenId: 'id-capture-error',
+    component: IdCaptureResultScreen,
+    variant: { verdict: 'error' },
+  },
+  {
+    screenId: 'id-capture-exhausted',
+    component: IdCaptureResultScreen,
+    variant: { verdict: 'exhausted' },
+  },
+  {
+    screenId: 'id-capture-classification',
+    component: IdCaptureResultScreen,
+    variant: { verdict: 'classification' },
+  },
+  {
+    screenId: 'id-capture-document-error',
+    component: IdCaptureDocumentErrorScreen,
+  },
+  {
+    screenId: 'id-capture-document-error-empty',
+    component: IdCaptureDocumentErrorScreen,
+    variant: { empty: true },
+  },
+  {
+    screenId: 'id-capture-no-connection',
+    component: IdCaptureNoConnectionScreen,
+  },
+];
+
+/**
+ * The `ID capture ↕️ vertical` (2-x) and `Passport capture ↕️ vertical` (4-x)
+ * groups: the SAME steps with the portrait frame. Kept as a derivation rather
+ * than two more literal lists, because that is precisely what the Figma groups
+ * are — the numbering, the states and the copy are identical and only
+ * `PrizmaIdCapture.isVertical` flips.
+ */
+export const idCaptureVerticalOf = (
+  steps: readonly IdCaptureFlowStep[],
+): readonly IdCaptureFlowStep[] =>
+  steps.map((step) => ({
+    ...step,
+    screenId: `${step.screenId}-vertical`,
+    variant: { ...step.variant, vertical: true },
+  }));