@myazahq/kyc-sdk-react-native 2.0.2 → 2.1.0

package/src/types/config.ts

@@ -1,57 +1,34 @@
-import type { KYCSubmission, KYCError } from './verification';
-
 // ---------------------------------------------------------------------------
-// Supported countries & ID types  (identical set to the web + Flutter SDKs)
+// The SDK's public configuration.
+//
+// The country/ID matrix, the presentation types and the workflow-driven blocks
+// live in their own modules (200-line rule) and are re-exported here, so
+// `types/config` remains the single import for consumers.
 // ---------------------------------------------------------------------------
 
-export type SupportedCountry = 'NG' | 'GH' | 'KE' | 'ZA' | 'CI';
-
-export type NigeriaIdType = 'bvn' | 'bvn-premium' | 'nin' | 'vnin' | 'tax-id' | 'passport' | 'drivers-license' | 'pvc';
-export type GhanaIdType = 'ghana-card' | 'voters' | 'drivers-license' | 'ssnit' | 'passport';
-export type KenyaIdType = 'national-id' | 'passport';
-export type SouthAfricaIdType = 'national-id';
-export type IvoryCoastIdType = 'cni' | 'residence-card';
-
-export type IdType =
-  | NigeriaIdType
-  | GhanaIdType
-  | KenyaIdType
-  | SouthAfricaIdType
-  | IvoryCoastIdType;
-
-/** Maps a country code to the ID types available in that country. */
-export type IdTypeForCountry<C extends SupportedCountry> =
-  C extends 'NG' ? NigeriaIdType :
-  C extends 'GH' ? GhanaIdType :
-  C extends 'KE' ? KenyaIdType :
-  C extends 'ZA' ? SouthAfricaIdType :
-  C extends 'CI' ? IvoryCoastIdType :
-  never;
-
-export interface IdTypeDefinition {
-  key: IdType;
-  label: string;
-  /**
-   * What the user actually types when it differs from the ID's name — e.g.
-   * Tax ID lookups are keyed off the person's NIN, so the input asks for a NIN.
-   */
-  inputLabel?: string;
-  digits?: number;
-  pattern?: RegExp;
-  /** Whether this ID type requires photographing/uploading a physical document. */
-  requiresDocumentCapture: boolean;
-  /**
-   * How many sides of the document need to be scanned. Only present when
-   * `requiresDocumentCapture` is true.
-   * - `front_only` — single scan (passports, data-page only)
-   * - `front_and_back` — both sides required
-   */
-  scanSides?: 'front_only' | 'front_and_back';
-}
-
-export type IdTypesByCountry = {
-  [K in SupportedCountry]: readonly IdTypeDefinition[];
-};
+import type { KYCSubmission, KYCError } from './verification';
+import type { IdType, IdTypeForCountry, SupportedCountry } from './id-types';
+import type {
+  KYCAppearance,
+  KYCConsentContent,
+  KYCSuccessContent,
+  VoiceGuidanceOption,
+} from './appearance';
+import type { SubjectType, WorkflowBusinessConfig } from './business';
+import type {
+  EmailVerificationConfig,
+  LivenessMode,
+  NfcConfig,
+  PhoneVerificationConfig,
+  ProofOfAddressConfig,
+  QuestionnaireConfig,
+  WorkflowCountry,
+} from './workflow';
+
+export type * from './workflow';
+export type * from './appearance';
+export type * from './id-types';
+export type * from './business';
 
 // ---------------------------------------------------------------------------
 // KYC flow steps
@@ -59,82 +36,27 @@ export type IdTypesByCountry = {
 
 export type KYCStep =
   | 'consent'
+  // Contact-verification OTP steps — right after consent (a cheap pre-filter
+  // before capture/registry spend). Present when the workflow enables them.
+  | 'email-verification'
+  | 'phone-verification'
+  | 'country-select'
   | 'id-type'
   | 'id-input'
   | 'document-capture'
+  // eMRTD chip read — a real step here, unlike the web SDK where it exists only
+  // as a builder-preview screen (Web NFC can't do ISO-DEP).
+  | 'nfc'
+  // KYB application steps — present only when the workflow configures them.
+  | 'business-details'
+  | 'business-key-people'
+  | 'business-documents'
+  | 'applicant-role'
   | 'liveness'
+  | 'proof-of-address'
+  | 'questionnaire'
   | 'submitted';
 
-// ---------------------------------------------------------------------------
-// Appearance / theming
-// ---------------------------------------------------------------------------
-
-export interface KYCAppearance {
-  /** Brand color — drives buttons, selected states, focus rings. */
-  primaryColor?: string;
-  /** Text/icon color rendered on top of `primaryColor` (e.g. button labels). */
-  primaryTextColor?: string;
-  /** Accent color for subtle hover/active surfaces. */
-  accentColor?: string;
-  /** Modal/sheet background color. */
-  backgroundColor?: string;
-  /** Elevated surface color for cards/panels. */
-  surfaceColor?: string;
-  /** Border + input outline color. */
-  borderColor?: string;
-  /** Primary text color. */
-  textColor?: string;
-  companyName?: string;
-  /**
-   * Logo to show in the flow.
-   * - An image URL renders that logo.
-   * - The literal `'default'` renders the org's own logo from the server config
-   *   response (falls back to the built-in shield if the org has none set).
-   * - Omitted renders the built-in shield badge.
-   */
-  logo?: string;
-  /** Initial light/dark mode. Applied on mount; the theme toggle can flip it. */
-  theme?: 'light' | 'dark';
-}
-
-// ---------------------------------------------------------------------------
-// Consent / success screen content
-// ---------------------------------------------------------------------------
-
-export interface KYCConsentContent {
-  /** Consent heading. Supports `{firstName}` / `{lastName}` tokens. */
-  title?: string;
-  /** Sub-text under the heading. Same tokens. */
-  description?: string;
-}
-
-export interface KYCSuccessContent {
-  /** Success heading. Supports `{firstName}` / `{lastName}` tokens. */
-  title?: string;
-  /** Sub-text under the heading. Same tokens. */
-  description?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Voice guidance (spoken liveness instructions — TTS output only, no mic)
-// ---------------------------------------------------------------------------
-
-/**
- * Configuration for the spoken liveness instructions. TTS **output** for
- * accessibility — it never records audio, so no microphone permission is
- * involved. An object (not a bare boolean) so a `language` can be added later
- * without a breaking change.
- */
-export interface VoiceGuidanceConfig {
-  /** Whether spoken guidance plays. Default `true`. */
-  enabled?: boolean;
-  /** BCP-47 voice tag (e.g. `'en-US'`, `'fr-FR'`). Default `'en-US'`. */
-  language?: string;
-}
-
-/** Accepts a bare boolean for ergonomics or the full {@link VoiceGuidanceConfig}. */
-export type VoiceGuidanceOption = boolean | VoiceGuidanceConfig;
-
 // ---------------------------------------------------------------------------
 // Client-side SDK config  (MyazaKYC.show() / useMyazaKYC options)
 // ---------------------------------------------------------------------------
@@ -156,17 +78,57 @@ export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
    */
   devUrl?: string;
 
-  /** Two-letter country code. */
-  country: C;
+  /**
+   * A published workflow to run (`wf_…`). The flow is resolved BEFORE the SDK
+   * mounts and its config wins over the props below — so an org can change the
+   * flow's shape in the dashboard builder without a redeploy. Runtime data
+   * (`userId`, `userData`, `metadata`, callbacks) always stays yours.
+   *
+   * A workflow supplies `country`, so it may be omitted alongside this.
+   */
+  workflowId?: string;
+
+  /**
+   * KYB only: the mapped applicant workflow's id (business.applicant.workflowId,
+   * resolved server-side). Set by the workflow gate after overlaying its
+   * capture template; stamped on the applicant's own submission so the server
+   * applies that workflow's gates, pricing and decision graph. Internal —
+   * never set this yourself.
+   */
+  applicantWorkflowId?: string;
+
+  /**
+   * Two-letter (ISO-2) country code. Required unless {@link workflowId} is set
+   * (the flow carries the country) or {@link subjectType} is `'business'` (the
+   * business block carries its own registry country). When both are present the
+   * flow's country wins.
+   */
+  country?: C;
 
   /** Subset of ID types to offer. Only types valid for the country are accepted. */
   idTypes?: IdTypeForCountry<C>[];
 
+  /**
+   * The org's own reference for the person being verified (e.g. your internal
+   * user id). It is **not** matched during verification — it becomes
+   * `Entity.externalUserId` at the KYC seam, so repeat checks of the same user
+   * collapse onto one entity and you can correlate results back to your record.
+   * Optional; when omitted the server falls back to the provider record id.
+   */
+  userId?: string;
+
   /** Pre-populated user data. Fields provided here won't be collected again. */
   userData?: {
     firstName?: string;
     lastName?: string;
     dateOfBirth?: string;
+    /**
+     * The business's display name, for `{businessName}` tokens in consent
+     * copy on KYB flows. Registration details aren't collected until after
+     * consent, so this resolves only when the integrator passes it in —
+     * mirroring the web SDK.
+     */
+    businessName?: string;
   };
 
   /** Enable the live-selfie capture step. */
@@ -185,6 +147,52 @@ export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
   /** Enable liveness detection during selfie capture. Default `true`. */
   enableLiveness?: boolean;
 
+  /**
+   * Which liveness method runs: randomized gestures (default), the screen-
+   * reflection flash, or both. Workflow-driven.
+   */
+  livenessMode?: LivenessMode;
+
+  /** Colours in the flash sequence (2–5, default 4). Flash modes only. */
+  flashSequenceLength?: number;
+
+  // ── Workflow-driven blocks ────────────────────────────────────────────────
+  // Authored in the dashboard's workflow builder, not usually in consumer code.
+  // A resolved flow always wins over a prop of the same name.
+
+  /** What this flow verifies. Absent = 'individual' (classic KYC). */
+  subjectType?: SubjectType;
+
+  /** KYB registry configuration. Required when `subjectType` is 'business'. */
+  business?: WorkflowBusinessConfig;
+
+  /**
+   * Multi-region: every country this flow serves. More than one inserts a
+   * country-select step between consent and ID type.
+   */
+  countries?: WorkflowCountry[];
+
+  /** Email OTP possession check, right after consent. */
+  emailVerification?: EmailVerificationConfig;
+
+  /** Phone OTP possession check, right after consent / email. */
+  phoneVerification?: PhoneVerificationConfig;
+
+  /** Proof-of-address document check, after capture. */
+  proofOfAddress?: ProofOfAddressConfig;
+
+  /** Compliance declarations asked just before submission. */
+  questionnaire?: QuestionnaireConfig;
+
+  /** eMRTD chip read for chip-capable documents. */
+  nfc?: NfcConfig;
+
+  /** Collect device + IP fraud signals. Default `true`. */
+  deviceIntelligence?: boolean;
+
+  /** Refuse to run on a desktop/laptop. Default `false`. */
+  requireMobileDevice?: boolean;
+
   /**
    * Spoken liveness instructions (accessibility). `true`/omitted = on,
    * `false` = off, or a {@link VoiceGuidanceConfig}. TTS output only — no
@@ -213,7 +221,11 @@ export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
   /** Override the success (submitted) screen copy. */
   success?: KYCSuccessContent;
 
-  /** Arbitrary metadata forwarded with every verification request. */
+  /**
+   * Arbitrary, free-form metadata forwarded verbatim with every verification
+   * request. Nothing here is required or interpreted by the SDK/server — use
+   * {@link userId} for the user reference, not a `userId` key in here.
+   */
   metadata?: Record<string, string>;
 
   // Callbacks
@@ -232,6 +244,20 @@ export interface MyazaKYCConfig<C extends SupportedCountry = SupportedCountry> {
   onError?: (error: KYCError) => void;
 }
 
+/**
+ * The config the FLOW runs on, as opposed to the config a consumer writes.
+ *
+ * `country` is optional on the public surface because a `workflowId` supplies
+ * it — but by the time anything mounts, the workflow gate has resolved one, and
+ * every screen from ID-type onward needs it. Making that guarantee a type keeps
+ * the "is it there yet?" question at the single place that answers it (the
+ * gate) instead of in every screen.
+ */
+export type ResolvedKYCConfig<C extends SupportedCountry = SupportedCountry> = Omit<
+  MyazaKYCConfig<C>,
+  'country'
+> & { country: C };
+
 // ---------------------------------------------------------------------------
 // useMyazaKYC() hook return type
 // ---------------------------------------------------------------------------

package/src/types/id-types.ts

@@ -0,0 +1,57 @@
+// ---------------------------------------------------------------------------
+// The country and ID-type matrix.
+//
+// Split from config.ts (200-line rule). These exist for compile-time ergonomics
+// — autocomplete and per-country narrowing — not enforcement: the org's actual
+// grants live server-side, and Global Documents means any ISO country can be
+// offered. Adding a country here does not grant it.
+// ---------------------------------------------------------------------------
+
+export type SupportedCountry = 'NG' | 'GH' | 'KE' | 'ZA' | 'CI';
+
+export type NigeriaIdType = 'bvn' | 'bvn-premium' | 'nin' | 'vnin' | 'tax-id' | 'passport' | 'drivers-license' | 'pvc';
+export type GhanaIdType = 'ghana-card' | 'voters' | 'drivers-license' | 'ssnit' | 'passport';
+export type KenyaIdType = 'national-id' | 'passport';
+export type SouthAfricaIdType = 'national-id';
+export type IvoryCoastIdType = 'cni' | 'residence-card';
+
+export type IdType =
+  | NigeriaIdType
+  | GhanaIdType
+  | KenyaIdType
+  | SouthAfricaIdType
+  | IvoryCoastIdType;
+
+/** Maps a country code to the ID types available in that country. */
+export type IdTypeForCountry<C extends SupportedCountry> =
+  C extends 'NG' ? NigeriaIdType :
+  C extends 'GH' ? GhanaIdType :
+  C extends 'KE' ? KenyaIdType :
+  C extends 'ZA' ? SouthAfricaIdType :
+  C extends 'CI' ? IvoryCoastIdType :
+  never;
+
+export interface IdTypeDefinition {
+  key: IdType;
+  label: string;
+  /**
+   * What the user actually types when it differs from the ID's name — e.g.
+   * Tax ID lookups are keyed off the person's NIN, so the input asks for a NIN.
+   */
+  inputLabel?: string;
+  digits?: number;
+  pattern?: RegExp;
+  /** Whether this ID type requires photographing/uploading a physical document. */
+  requiresDocumentCapture: boolean;
+  /**
+   * How many sides of the document need to be scanned. Only present when
+   * `requiresDocumentCapture` is true.
+   * - `front_only` — single scan (passports, data-page only)
+   * - `front_and_back` — both sides required
+   */
+  scanSides?: 'front_only' | 'front_and_back';
+}
+
+export type IdTypesByCountry = {
+  [K in SupportedCountry]: readonly IdTypeDefinition[];
+};

package/src/types/verification.ts

@@ -34,6 +34,11 @@ export interface KYCSubmission {
 export type KYCErrorCode =
   | 'network_error'
   | 'invalid_api_key'
+  // A `workflowId` that is unknown, unpublished, archived, or belongs to
+  // another org/environment. Blocking — the flow never mounts.
+  | 'invalid_workflow'
+  // The props are unusable as given (e.g. no `country` and no `workflowId`).
+  | 'invalid_config'
   | 'insufficient_credits'
   | 'upload_failed'
   | 'camera_permission_denied'

package/src/types/workflow.ts

@@ -0,0 +1,141 @@
+// ---------------------------------------------------------------------------
+// Workflow-driven configuration blocks.
+//
+// These are the parts of the flow an org authors in the dashboard's workflow
+// builder rather than in consumer code: extra steps (contact OTP, proof of
+// address, questionnaire, NFC), the KYB subject, and multi-region. They arrive
+// either as props or from `GET /api/kyc/workflows/:id`, and the flow always
+// wins over props (see `mergeWorkflowConfig`).
+//
+// Shapes mirror the web SDK's `types/config.ts` + `types/business.ts` exactly —
+// they are the server's published contract, so the three SDKs must not drift.
+// ---------------------------------------------------------------------------
+
+// ── Proof of Address ────────────────────────────────────────────────────────
+
+export type PoaDocumentType = 'utility_bill' | 'bank_statement' | 'tenancy_agreement' | 'other';
+
+export interface ProofOfAddressConfig {
+  /** Adds the Proof of Address step (after capture, before the questionnaire). */
+  enabled?: boolean;
+  /** Accepted document kinds (absent = all). */
+  documentTypes?: PoaDocumentType[];
+  /** Custom label for the 'other' kind (absent = "Other document"). */
+  otherLabel?: string;
+  /** Recency window the server checks the document date against (default 90). */
+  maxAgeDays?: number;
+}
+
+// ── NFC chip read (eMRTD) ───────────────────────────────────────────────────
+
+export interface NfcConfig {
+  /** Adds the chip-read step. */
+  enabled?: boolean;
+  /** Which chip-capable IDs run it, as "CC/idType" keys (absent = all). */
+  idTypes?: string[];
+  /**
+   * Show a manual skip so someone who can't complete the read can proceed.
+   * Devices with no NFC radio auto-skip regardless — this is the escape hatch
+   * on NFC-capable phones.
+   */
+  allowSkip?: boolean;
+  /** Match the selfie against the authenticated chip portrait (default on). */
+  facialMatch?: boolean;
+}
+
+// ── Contact verification (email / phone OTP) ────────────────────────────────
+
+/** Which code field the SDK renders — the org picks this in the builder. */
+export type OtpInputStyle = 'segmented' | 'text';
+
+export interface EmailVerificationConfig {
+  /** Adds the email OTP step (right after consent). */
+  enabled?: boolean;
+  /**
+   * Whether a verified email is required to proceed (default true when
+   * enabled). `false` shows a "skip for now" affordance and the server accepts
+   * a submission without the proof.
+   */
+  required?: boolean;
+  /** Digits in the code (4–8; default 6). Drives the OTP-input slots. */
+  codeLength?: number;
+  /** Wrong entries allowed per code before it's dead (1–5; default 3). */
+  maxAttempts?: number;
+  inputStyle?: OtpInputStyle;
+}
+
+export interface PhoneVerificationConfig {
+  /** Adds the phone OTP step (after consent / email verification). */
+  enabled?: boolean;
+  required?: boolean;
+  codeLength?: number;
+  maxAttempts?: number;
+  inputStyle?: OtpInputStyle;
+  /** Offered delivery channels (default ['sms']). */
+  channels?: Array<'sms' | 'whatsapp'>;
+  /** Default dial-code country (falls back to the flow's country). */
+  defaultCountry?: string;
+}
+
+// ── Questionnaire (compliance declarations) ─────────────────────────────────
+
+export interface QuestionnaireFieldOption {
+  value: string;
+  label: string;
+}
+
+export interface QuestionnaireField {
+  /** Stable snake_case key — also the webhook/decisioning field name. */
+  key: string;
+  label: string;
+  /**
+   * 'money' = amount + currency. The answer stores `<key>` (number, 2dp) and a
+   * `<key>_currency` companion (ISO code).
+   */
+  type: 'text' | 'number' | 'money' | 'select' | 'multiselect' | 'boolean' | 'date';
+  required?: boolean;
+  placeholder?: string;
+  helpText?: string;
+  options?: QuestionnaireFieldOption[];
+  min?: number;
+  max?: number;
+  /** money only: allowed ISO currency codes; the first is the default. */
+  currencies?: string[];
+}
+
+export interface QuestionnaireConfig {
+  /**
+   * Off switch for the step. Omitted/true = shown; false = skipped even though
+   * the questions remain configured (the builder's Questionnaire toggle).
+   */
+  enabled?: boolean;
+  title?: string;
+  description?: string;
+  fields: QuestionnaireField[];
+}
+
+export type QuestionnaireAnswerValue = string | number | boolean | string[];
+
+// ── Multi-region ────────────────────────────────────────────────────────────
+
+export interface WorkflowIdOption {
+  govDbCheck?: boolean;
+  documentIntelligence?: boolean;
+  facialMatch?: boolean;
+}
+
+export interface WorkflowCountry {
+  /** ISO-3166 alpha-2. */
+  country: string;
+  /** Offered IDs for this country (absent/empty = every granted ID). */
+  idTypes?: string[];
+  /** Per-ID validation toggles — restrict-only; they never widen a grant. */
+  idOptions?: Record<string, WorkflowIdOption>;
+  govDbCheck?: boolean;
+  documentIntelligence?: boolean;
+}
+
+// ── Liveness ────────────────────────────────────────────────────────────────
+
+/** Gestures (default), screen-reflection flash, or both. */
+export type LivenessMode = 'gestures' | 'flash' | 'both';

package/src/utils/amountFormat.ts

@@ -0,0 +1,73 @@
+// ---------------------------------------------------------------------------
+// Amount formatting
+//
+// Groups thousands as the user types (250000 → 250,000) and caps the decimals,
+// matching the Flutter SDK's AmountInputFormatter and the web SDK's money
+// input. Long figures are the norm for the expected-volume question in
+// low-denomination currencies, and an ungrouped "250000" is genuinely hard to
+// read back.
+//
+// The DISPLAY is grouped; the ANSWER stays a number. Storing the grouped string
+// would fail validation — `Number("250,000")` is NaN — and would reach the
+// server as text where the decision graph expects something comparable.
+// ---------------------------------------------------------------------------
+
+/** Keeps digits plus at most one '.', truncating past `decimalDigits`. */
+function clean(input: string, decimalDigits: number): string {
+  let out = '';
+  let seenDot = false;
+  let decimals = 0;
+
+  for (const ch of input) {
+    if (ch === '.') {
+      // Integer-only: everything past the point is fractional, so DROP the
+      // rest. Merely skipping the '.' would splice "1234.99" into "123499".
+      if (decimalDigits === 0) break;
+      if (seenDot) continue;
+      seenDot = true;
+      out += ch;
+      continue;
+    }
+    if (ch < '0' || ch > '9') continue;
+    if (seenDot) {
+      if (decimals >= decimalDigits) continue;
+      decimals += 1;
+    }
+    out += ch;
+  }
+  return out;
+}
+
+function group(digits: string): string {
+  if (digits.length <= 3) return digits;
+  const lead = digits.length % 3;
+  const parts: string[] = [];
+  let i = 0;
+  if (lead > 0) {
+    parts.push(digits.slice(0, lead));
+    i = lead;
+  }
+  while (i < digits.length) {
+    parts.push(digits.slice(i, i + 3));
+    i += 3;
+  }
+  return parts.join(',');
+}
+
+/** "250000.5" → "250,000.5". Non-numeric characters are dropped. */
+export function formatGroupedAmount(input: string, decimalDigits = 2): string {
+  const cleaned = clean(input, decimalDigits);
+  if (cleaned === '') return '';
+  const dot = cleaned.indexOf('.');
+  const whole = dot === -1 ? cleaned : cleaned.slice(0, dot);
+  const fraction = dot === -1 ? '' : cleaned.slice(dot);
+  return group(whole) + fraction;
+}
+
+/** Numeric value of a grouped amount string ("250,000.50" → 250000.5). */
+export function parseGroupedAmount(text: string): number | null {
+  const raw = text.replace(/,/g, '').trim();
+  if (raw === '' || raw === '.') return null;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : null;
+}

package/src/utils/tokens.ts

@@ -1,10 +1,12 @@
 import type { MyazaKYCConfig } from '../types/config';
 
-// Replaces {firstName} / {lastName} tokens with values from userData (or ''),
-// mirroring the Flutter SDK's `_fillTokens` and the web SDK's token handling.
+// Replaces {firstName} / {lastName} / {businessName} tokens with values from
+// userData (or ''), mirroring the Flutter SDK's `_fillTokens` and the web
+// SDK's token handling ({businessName} is the KYB consent-copy token).
 export function fillTokens(template: string, userData: MyazaKYCConfig['userData']): string {
   return template
     .replace(/\{firstName\}/g, userData?.firstName ?? '')
     .replace(/\{lastName\}/g, userData?.lastName ?? '')
+    .replace(/\{businessName\}/g, userData?.businessName ?? '')
     .trim();
 }

package/src/__tests__/cardCrop.test.ts

@@ -1,39 +0,0 @@
-import { cardCropRect } from '../services/cardCrop';
-import { CARD_GUIDE_ASPECT, PASSPORT_GUIDE_ASPECT } from '../config/idTypes';
-
-describe('cardCropRect', () => {
-  it('produces a crop whose aspect equals the guide aspect', () => {
-    const r = cardCropRect(4000, 3000, CARD_GUIDE_ASPECT);
-    expect(r.width / r.height).toBeCloseTo(CARD_GUIDE_ASPECT, 3);
-  });
-
-  it('stays within the image bounds', () => {
-    for (const [w, h] of [
-      [4000, 3000], // landscape sensor
-      [3000, 4000], // portrait sensor
-      [1920, 1080], // 16:9
-    ] as const) {
-      const r = cardCropRect(w, h, CARD_GUIDE_ASPECT);
-      expect(r.originX).toBeGreaterThanOrEqual(0);
-      expect(r.originY).toBeGreaterThanOrEqual(0);
-      expect(r.originX + r.width).toBeLessThanOrEqual(w + 0.01);
-      expect(r.originY + r.height).toBeLessThanOrEqual(h + 0.01);
-    }
-  });
-
-  it('centres the crop within the cover-fit 3:4 slice (landscape sensor)', () => {
-    // 4000×3000 → visible slice is 2250×3000 centred at x=875.
-    const r = cardCropRect(4000, 3000, CARD_GUIDE_ASPECT);
-    const sliceCentreX = 875 + 2250 / 2;
-    expect(r.originX + r.width / 2).toBeCloseTo(sliceCentreX, 3);
-    expect(r.originY + r.height / 2).toBeCloseTo(3000 / 2, 3); // vertically centred (no shift)
-  });
-
-  it('gives passports a taller crop (smaller aspect) than ID cards', () => {
-    const card = cardCropRect(4000, 3000, CARD_GUIDE_ASPECT);
-    const passport = cardCropRect(4000, 3000, PASSPORT_GUIDE_ASPECT);
-    expect(passport.height).toBeGreaterThan(card.height);
-    expect(passport.width).toBeCloseTo(card.width, 3); // same 88% width
-    expect(passport.width / passport.height).toBeCloseTo(PASSPORT_GUIDE_ASPECT, 3);
-  });
-});