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

package/README.md

@@ -56,8 +56,11 @@ npx expo install @myazahq/kyc-sdk-react-native \
   react-native-safe-area-context react-native-svg
 ```
 
-Add the config plugins to `app.json`. The SDK's plugin adds the iOS camera usage
-string + Android `CAMERA`/`INTERNET` permissions; the VisionCamera plugin wires up
+Add the config plugins to `app.json`. The SDK's plugin adds the iOS camera and
+location usage strings + Android `CAMERA`/`INTERNET` and foreground location
+permissions (location backs the address-collection step's "Use my current
+location" and presence attestation; `["@myazahq/kyc-sdk-react-native",
+{ "location": false }]` opts out); the VisionCamera plugin wires up
 the camera + frame processors. Make sure the **New Architecture** is on (it is by
 default on Expo SDK 56):
 
@@ -82,8 +85,9 @@ npx expo run:ios                                  # iOS
 JAVA_HOME=/path/to/jdk-17 npx expo run:android    # Android — needs JDK 17
 ```
 
-> The SDK plugin accepts an optional custom camera prompt:
-> `["@myazahq/kyc-sdk-react-native", { "cameraPermission": "Your message…" }]`.
+> The SDK plugin accepts optional custom prompts:
+> `["@myazahq/kyc-sdk-react-native", { "cameraPermission": "Your message…",
+> "locationPermission": "Your message…" }]`.
 
 ### Bare React Native app (no Expo prebuild)
 
@@ -100,7 +104,8 @@ npm install @myazahq/kyc-sdk-react-native \
   react-native-worklets react-native-nitro-modules react-native-nitro-image \
   react-native-safe-area-context react-native-svg \
   expo expo-image-manipulator expo-image-picker expo-speech expo-font \
-  expo-glass-effect expo-application expo-crypto expo-device expo-localization
+  expo-glass-effect expo-application expo-crypto expo-device expo-localization \
+  expo-location
 
 # 3. iOS pods:
 cd ios && pod install && cd ..
@@ -113,11 +118,15 @@ prebuild):
   ```xml
   <key>NSCameraUsageDescription</key>
   <string>We use the camera to photograph your ID and capture a live selfie.</string>
+  <key>NSLocationWhenInUseUsageDescription</key>
+  <string>We use your location to confirm you are at the address you pin during verification.</string>
   ```
 - **Android** — add to `android/app/src/main/AndroidManifest.xml`:
   ```xml
   <uses-permission android:name="android.permission.CAMERA" />
   <uses-permission android:name="android.permission.INTERNET" />
+  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
   ```
 - Ensure the **New Architecture** is enabled (`newArchEnabled=true` in
   `android/gradle.properties`; `RCT_NEW_ARCH_ENABLED=1` for the iOS Podfile install),
@@ -560,3 +569,140 @@ Full documentation, configuration options, and webhook setup: **[trust.myaza.co/
 ## License
 
 MIT © Flitstack Technologies Inc.
+
+## Presence reporting (Address Intelligence)
+
+When a workflow enables presence verification (`addressCollection.presence.enabled`),
+the SDK stores the confirmed pin on-device at capture. Call the reporter from your
+app on a natural moment (app open works well):
+
+```tsx
+import { reportAddressPresence, clearPresencePin } from '@myazahq/kyc-sdk-react-native';
+
+const result = await reportAddressPresence({
+  apiKey: 'pk_live_…',
+  externalUserId: 'user_42', // the same userId the KYC flow ran with
+});
+// result.reason: 'reported' | 'no_pin' | 'services_off' | 'no_fix' | 'outside_fence' | 'network_error'
+```
+
+It never throws and never blocks startup. The geofence is evaluated ON-DEVICE:
+only the derived record (calendar day + a night flag) is transmitted, never a
+coordinate. A fix outside the fence sends nothing (the server scores presence,
+never absence); a mock-location fix is reported flagged. `clearPresencePin`
+drops the stored pin (sign-out, or once the watch resolves).
+
+### Background monitoring (OS geofencing)
+
+The stronger tier: the OS wakes the SDK on fence crossings around the stored
+pin, app closed or not, so dwell and nights accrue with nobody in the loop.
+Entries stamp a timestamp; exits fold the dwell span into per-day aggregates
+and flush them. As with the foreground tier, only the derived day records
+ever leave the phone.
+
+Three opt-ins, each deliberate:
+
+1. Install the optional peer: `npx expo install expo-task-manager` (without
+   it the background tier simply does not exist — never a crash).
+2. Declare background location via the config plugin — this is what changes
+   your app's store review posture, so it is never a default:
+
+   ```json
+   ["@myazahq/kyc-sdk-react-native", { "location": "always" }]
+   ```
+
+3. Register the task at your app's ROOT module (before the component tree —
+   a task defined inside a component never fires headlessly), then enable:
+
+   ```tsx
+   // index.js
+   import { registerBackgroundPresence } from '@myazahq/kyc-sdk-react-native';
+   registerBackgroundPresence();
+
+   // later, after the KYC flow stored a pin:
+   const result = await enableBackgroundPresence({
+     apiKey: 'pk_live_…',
+     externalUserId: 'user_42',
+   });
+   // result.reason: 'enabled' | 'module_missing' | 'no_pin'
+   //              | 'foreground_denied' | 'background_denied' | 'start_failed'
+   ```
+
+`disableBackgroundPresence()` disarms the fence. A permission refusal leaves
+the foreground tier working exactly as before — the tiers degrade, never
+break.
+
+### The Android foreground service (reliability on OEM-managed phones)
+
+A geofence alone is not reliable on Android once a manufacturer's battery
+manager decides your app is idle: transitions are dropped, nothing says so,
+and the watch quietly lapses to inconclusive. The phones on that list (Tecno,
+Infinix, itel, Xiaomi, Oppo, Vivo) are the ones the market carries. A
+foreground service, with its persistent notification, is the one thing those
+managers leave alone — and OkHi's own integration guidance for the same
+markets is exactly this.
+
+Opt-in, Android only (iOS region monitoring is reliable on its own), on the
+same `location: "always"` plugin setting, which also declares the
+`FOREGROUND_SERVICE` and `FOREGROUND_SERVICE_LOCATION` permissions it needs.
+`registerBackgroundPresence()` at the root already defines its task; then:
+
+```tsx
+const result = await enableForegroundService({
+  apiKey: 'pk_live_…',
+  externalUserId: 'user_42',
+  notification: {
+    title: 'Address verification in progress', // shown in the status bar
+    body: 'Open the app to see your progress',
+    color: '#5645F5',
+  },
+});
+// result.reason: 'enabled' | 'unsupported_platform' | 'module_missing' | 'no_pin'
+//              | 'foreground_denied' | 'background_denied' | 'start_failed'
+```
+
+While it runs, a low-power fix every ten minutes (or hundred metres) is
+turned into the same enter/exit spans the geofence folds, on the same stored
+state, so the two never double-count a stay; the queue flushes while the
+process is alive; and a fence the OS dropped (a location toggle clears every
+registered fence) is re-armed. `disableForegroundService()` stops it and its
+notification. Word the notification honestly — it is on screen for days.
+
+### Which tier is running?
+
+Permissions get revoked in Settings and nothing tells the app. Ask:
+
+```tsx
+import { presenceStatus, openLocationSettings } from '@myazahq/kyc-sdk-react-native';
+
+const status = await presenceStatus('user_42');
+// status.tier: 'background' | 'foreground' | 'none'
+// plus pinStored, alwaysOn, locationServicesEnabled, both permission states,
+// geofenceArmed, foregroundServiceRunning
+if (!status.locationServicesEnabled) {
+  // The phone's location toggle is off: permission granted or not, no fix
+  // can be taken. Android deep-links to the toggle itself.
+  await openLocationSettings('services');
+} else if (status.tier === 'none' && status.pinStored) {
+  // The road back runs through Settings — no OS allows re-prompting in-app.
+  await openLocationSettings();
+}
+```
+
+### Showing the person where the check stands
+
+Somebody kept from a feature until their address is verified should be able
+to see the progress in your app, without a webhook relayed through your
+backend. The status endpoint is publishable-safe and enumeration-safe (an
+unknown user and a user with no watch answer the same `not_started` shape):
+
+```ts
+const res = await fetch(`${serverUrl}/api/kyc/address/presence/${externalUserId}`, {
+  headers: { Authorization: `Bearer pk_live_…` },
+});
+const { status, progress, tier } = await res.json();
+// status: 'not_started' | 'in_progress' | 'verified' | 'failed' | 'inconclusive' | 'expired' | 'revoked'
+// progress.score: 0..1 on WEIGHTED evidence (five foreground nights and three
+//                 geofence nights both read 1); nightsObserved/daysObserved beside it
+// tier: 'background' | 'foreground' | null — what is actually feeding it
+```

package/android/src/main/java/com/margelo/nitro/myazakyc/HybridMyazaFaceDetector.kt

@@ -10,7 +10,6 @@ import com.google.mlkit.vision.face.FaceDetection
 import com.google.mlkit.vision.face.FaceDetector
 import com.google.mlkit.vision.face.FaceDetectorOptions
 import com.google.android.gms.common.moduleinstall.ModuleInstall
-import com.google.android.gms.common.moduleinstall.ModuleInstallRequest
 import com.margelo.nitro.NitroModules
 import com.margelo.nitro.core.Promise
 import java.util.concurrent.CountDownLatch
@@ -82,9 +81,12 @@ class HybridMyazaFaceDetector : HybridMyazaFaceDetectorSpec() {
         .addOnSuccessListener { response ->
           ok = response.areModulesAvailable()
           if (!ok) {
-            client.deferredInstall(
-              ModuleInstallRequest.newBuilder().addApi(detector).build(),
-            )
+            // `deferredInstall` takes the OptionalModuleApi itself, varargs.
+            // A ModuleInstallRequest belongs to `installModules`, which is the
+            // FOREGROUND install with its own progress listener — a different
+            // call, and the one this used to hand its request to, which is why
+            // the Android build stopped compiling.
+            client.deferredInstall(detector)
           }
           latch.countDown()
         }

package/app.plugin.js

@@ -37,6 +37,9 @@ const CAMERA_USAGE =
 const NFC_USAGE =
   'We read the secure chip in your passport or ID card to confirm the document is genuine.';
 
+const LOCATION_USAGE =
+  'We use your location to confirm you are at the address you pin during verification.';
+
 /**
  * The eMRTD application identifier.
  *
@@ -62,6 +65,23 @@ function withIosCameraUsage(config, customMessage) {
   });
 }
 
+/**
+ * iOS location usage string, for the address-collection step's one-shot fix
+ * ("Use my current location" + the attest-presence claim). Written by DEFAULT
+ * because its ABSENCE is a crash: iOS kills an app that requests location
+ * without a usage string, and whether the step runs is decided by the org's
+ * WORKFLOW, not by anything the host app author can see at build time. An
+ * unused usage string costs nothing. `location: false` opts out.
+ */
+function withIosLocationUsage(config, customMessage) {
+  return withInfoPlist(config, (cfg) => {
+    if (!cfg.modResults.NSLocationWhenInUseUsageDescription) {
+      cfg.modResults.NSLocationWhenInUseUsageDescription = customMessage || LOCATION_USAGE;
+    }
+    return cfg;
+  });
+}
+
 const AID_KEY = 'com.apple.developer.nfc.readersession.iso7816.select-identifiers';
 const FORMATS_KEY = 'com.apple.developer.nfc.readersession.formats';
 
@@ -112,24 +132,84 @@ function withIosNfc(config, customMessage) {
   });
 }
 
-function withAndroidPermissions(config, { nfc }) {
+/**
+ * The Android permission list for a given set of opt-ins. Pure and exported
+ * so the tests can pin what `location: 'always'` declares — a permission
+ * that changes review posture must never arrive by accident.
+ */
+function androidPermissionsFor({ nfc, location, backgroundLocation }) {
+  return [
+    'android.permission.CAMERA',
+    'android.permission.INTERNET',
+    ...(nfc ? ['android.permission.NFC'] : []),
+    // Foreground location, for the address-collection step's one-shot fix.
+    ...(location
+      ? ['android.permission.ACCESS_COARSE_LOCATION', 'android.permission.ACCESS_FINE_LOCATION']
+      : []),
+    // The always-on presence tier (OkHi model, opt-in): OS geofencing needs
+    // the background grant, and Google Play reviews any app that declares
+    // it — which is why this is `location: 'always'` only, never a default.
+    // The foreground-service pair rides the same opt-in: FOREGROUND_SERVICE
+    // is a normal permission, and FOREGROUND_SERVICE_LOCATION (API 34+) is
+    // what lets expo-location's service declare the `location` type; Play
+    // reviews it under the same location declaration.
+    ...(backgroundLocation
+      ? [
+          'android.permission.ACCESS_BACKGROUND_LOCATION',
+          'android.permission.FOREGROUND_SERVICE',
+          'android.permission.FOREGROUND_SERVICE_LOCATION',
+        ]
+      : []),
+  ];
+}
+
+function withAndroidPermissions(config, opts) {
   return withAndroidManifest(config, (cfg) => {
-    AndroidConfig.Permissions.ensurePermissions(cfg.modResults, [
-      'android.permission.CAMERA',
-      'android.permission.INTERNET',
-      ...(nfc ? ['android.permission.NFC'] : []),
-    ]);
+    AndroidConfig.Permissions.ensurePermissions(cfg.modResults, androidPermissionsFor(opts));
+    return cfg;
+  });
+}
+
+/** iOS side of the always-on tier: the Always usage string plus the location
+ *  background mode, without which a geofence wake is refused. */
+function withIosBackgroundLocation(config, customMessage) {
+  return withInfoPlist(config, (cfg) => {
+    if (!cfg.modResults.NSLocationAlwaysAndWhenInUseUsageDescription) {
+      cfg.modResults.NSLocationAlwaysAndWhenInUseUsageDescription =
+        customMessage || LOCATION_USAGE;
+    }
+    const modes = Array.isArray(cfg.modResults.UIBackgroundModes)
+      ? cfg.modResults.UIBackgroundModes
+      : [];
+    if (!modes.includes('location')) modes.push('location');
+    cfg.modResults.UIBackgroundModes = modes;
     return cfg;
   });
 }
 
 /**
  * @param {object} config
- * @param {{ cameraPermission?: string, nfc?: boolean, nfcPermission?: string }} [props]
+ * @param {{ cameraPermission?: string, nfc?: boolean, nfcPermission?: string,
+ *           location?: boolean | 'always', locationPermission?: string }} [props]
  */
 function withMyazaKyc(config, props = {}) {
+  const location = props.location !== false;
+  // `location: 'always'` opts into the background presence tier. Explicit on
+  // purpose: it changes the app's Play/App Store review posture, so it must
+  // never arrive as a side effect of a default.
+  const backgroundLocation = props.location === 'always';
   config = withIosCameraUsage(config, props.cameraPermission);
-  config = withAndroidPermissions(config, { nfc: props.nfc === true });
+  config = withAndroidPermissions(config, {
+    nfc: props.nfc === true,
+    location,
+    backgroundLocation,
+  });
+  if (location) {
+    config = withIosLocationUsage(config, props.locationPermission);
+  }
+  if (backgroundLocation) {
+    config = withIosBackgroundLocation(config, props.locationPermission);
+  }
   if (props.nfc === true) {
     config = withIosNfc(config, props.nfcPermission);
   }
@@ -141,4 +221,5 @@ module.exports = createRunOncePlugin(withMyazaKyc, pkg.name, pkg.version);
 // consumers' app.json entries are unaffected.
 module.exports.applyNfcInfoPlist = applyNfcInfoPlist;
 module.exports.applyNfcEntitlements = applyNfcEntitlements;
+module.exports.androidPermissionsFor = androidPermissionsFor;
 module.exports.EMRTD_AID = EMRTD_AID;

package/ios/HybridMyazaFaceDetector.swift

@@ -303,8 +303,13 @@ final class HybridMyazaFaceDetector: HybridMyazaFaceDetectorSpec {
     return min(max(v, 0.0), 1.0)
   }
 
-  /// Smile from outer-lip width relative to the face. Input band (0.40→0.50):
-  /// a neutral mouth sits near 0, a clear smile lands well above the threshold.
+  /// Smile from outer-lip width relative to the face box. Input band
+  /// (0.36→0.46): the shared detector passes above 0.5, so the pass line sits
+  /// at a lip width of 0.41 of the box. It was 0.40→0.50 (pass at 0.45), which
+  /// on device needed a full grin — a modest, natural smile never crossed it.
+  /// ML Kit on Android returns a classifier probability instead, so this band
+  /// is the iOS half of one shared threshold: tune it here, not in
+  /// detectSmile, or Android loosens with it.
   private static func smileProbability(_ landmarks: VNFaceLandmarks2D?) -> Double {
     guard let pts = landmarks?.outerLips?.normalizedPoints, pts.count >= 4 else {
       return 0.0
@@ -315,7 +320,7 @@ final class HybridMyazaFaceDetector: HybridMyazaFaceDetectorSpec {
       minX = min(minX, Double(p.x)); maxX = max(maxX, Double(p.x))
     }
     let width = maxX - minX
-    let score = (width - 0.40) / (0.50 - 0.40)
+    let score = (width - 0.36) / (0.46 - 0.36)
     return min(max(score, 0.0), 1.0)
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myazahq/kyc-sdk-react-native",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Myaza KYC SDK for React Native (Expo) — ID verification, liveness detection, and document capture",
   "author": "Flitstack Technologies Inc.",
   "repository": {
@@ -49,6 +49,8 @@
   "license": "MIT",
   "peerDependencies": {
     "expo": ">=56",
+    "expo-task-manager": ">=14",
+    "react-native-webview": ">=13",
     "react": ">=19",
     "react-native": ">=0.83",
     "react-native-nitro-image": ">=0.15",
@@ -58,6 +60,14 @@
     "react-native-vision-camera-worklets": ">=5",
     "react-native-worklets": ">=0.8"
   },
+  "peerDependenciesMeta": {
+    "expo-task-manager": {
+      "optional": true
+    },
+    "react-native-webview": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "@expo-google-fonts/karla": "^0.4.2",
     "@expo-google-fonts/space-grotesk": "^0.4.1",
@@ -74,11 +84,13 @@
     "expo-image-manipulator": "~56.0.17",
     "expo-image-picker": "~56.0.16",
     "expo-localization": "~56.0.6",
+    "expo-location": "~56.0.24",
     "expo-speech": "~56.0.3",
     "lucide-react-native": "^1.17.0",
     "react-native-compressor": "^1.19.0",
     "react-native-vision-camera": "^5.0.11",
-    "zustand": "^5.0.2"
+    "zustand": "^5.0.2",
+    "expo-file-system": "~56.0.0"
   },
   "devDependencies": {
     "@types/jest": "^29.5.12",

package/src/MyazaBiometricAuth.tsx

@@ -0,0 +1,119 @@
+import React, { useCallback, useState } from 'react';
+import { Modal, Platform } from 'react-native';
+
+import { KycRuntimeProvider, MyazaThemeProvider } from './components/runtime';
+import { MyazaButton } from './components/MyazaButton';
+import { BiometricAuthFlow } from './screens/biometric/BiometricAuthFlow';
+import { primeFaceModel } from './liveness/visionCameraFaceDetector';
+import { defaultReauthLabel } from './lib/biometric-auth';
+import type { KYCAppearance, ResolvedKYCConfig, SupportedCountry } from './types/config';
+import type { KYCError } from './types/verification';
+import type { BiometricAuthResponse } from './services/api-types-biometric';
+
+// ---------------------------------------------------------------------------
+// MyazaBiometricAuth — returning-user face re-authentication ("prove it's
+// still you"). Mirrors the web SDK's MyazaBiometricAuth: a verified user
+// re-authenticates with a live selfie matched 1:1 against their enrollment
+// reference (no gov-DB call, no re-KYC). Self-contained: its own trigger +
+// modal, hosting the SDK's real liveness step inside a scoped runtime.
+// ---------------------------------------------------------------------------
+
+export interface MyazaBiometricAuthProps {
+  /** Publishable API key (`pk_…`). The environment is derived from its prefix. */
+  apiKey: string;
+  /** Dev-only base-URL override for `pk_dev_` keys. */
+  devUrl?: string;
+  /** The org's user reference (Entity.externalUserId) to re-authenticate. */
+  externalUserId: string;
+  /** Presence Intelligence method (default 'gestures'). */
+  livenessMode?: 'gestures' | 'flash' | 'both';
+  flashSequenceLength?: number;
+  appearance?: KYCAppearance;
+  disableClose?: boolean;
+  /** Open the modal on mount (no trigger button is rendered). */
+  defaultOpen?: boolean;
+  /** Custom trigger label (default "Verify it's you"). */
+  children?: string;
+  disabled?: boolean;
+  onOpen?: () => void;
+  /** The user re-authenticated. `token` is a single-use proof — verify it from
+   *  your backend with a secret key at `/biometric/verify-proof`. */
+  onAuthenticated?: (result: { attemptId: string; confidence: number | null; token?: string }) => void;
+  /** The check ran but the user did not pass (no match / liveness failed). */
+  onFailed?: (result: { status: BiometricAuthResponse['status']; attemptId: string; confidence: number | null }) => void;
+  /** A technical error (network, not enrolled, insufficient credits, …). */
+  onError?: (error: KYCError) => void;
+  onClose?: () => void;
+}
+
+const MODAL_PRESENTATION = Platform.OS === 'ios' ? 'pageSheet' : 'fullScreen';
+
+export function MyazaBiometricAuth(props: MyazaBiometricAuthProps): React.ReactElement {
+  const { children, disabled, defaultOpen, onOpen, onAuthenticated, onFailed, onError, onClose } = props;
+  const [open, setOpen] = useState(defaultOpen === true);
+
+  // The liveness step reads exactly the keys a KYC flow's config carries; the
+  // scope parks the step order on consent → liveness → submitted, and the
+  // flow only ever mounts the middle one. `country` is required by the
+  // resolved shape but nothing on this path reads it.
+  const config: ResolvedKYCConfig = {
+    apiKey: props.apiKey,
+    devUrl: props.devUrl,
+    country: 'NG' as SupportedCountry,
+    scope: 'biometric-authentication',
+    enableSelfie: true,
+    livenessMode: props.livenessMode ?? 'gestures',
+    flashSequenceLength: props.flashSequenceLength,
+    appearance: props.appearance,
+    disableClose: props.disableClose,
+    userId: props.externalUserId,
+    onError,
+  };
+
+  const openFlow = useCallback(() => {
+    void primeFaceModel();
+    setOpen(true);
+    onOpen?.();
+  }, [onOpen]);
+  const close = useCallback(() => {
+    setOpen(false);
+    onClose?.();
+  }, [onClose]);
+  const blockDismiss = props.disableClose === true;
+
+  return (
+    <MyazaThemeProvider appearance={props.appearance}>
+      {defaultOpen !== true && (
+        <MyazaButton
+          label={children ?? defaultReauthLabel(props.appearance?.companyName)}
+          disabled={disabled}
+          fullWidth={false}
+          onPress={openFlow}
+        />
+      )}
+      <Modal
+        visible={open}
+        animationType="slide"
+        presentationStyle={blockDismiss ? 'fullScreen' : MODAL_PRESENTATION}
+        statusBarTranslucent
+        navigationBarTranslucent
+        onRequestClose={blockDismiss ? () => undefined : close}
+        onDismiss={blockDismiss ? undefined : close}
+      >
+        {open ? (
+          // A fresh store per open: the runtime provider creates it once per
+          // mount, and the modal's children mount once per open.
+          <KycRuntimeProvider config={config}>
+            <BiometricAuthFlow
+              externalUserId={props.externalUserId}
+              onAuthenticated={(r) => onAuthenticated?.({ attemptId: r.attemptId, confidence: r.confidence, token: r.token })}
+              onFailed={(r) => onFailed?.({ status: r.status, attemptId: r.attemptId, confidence: r.confidence })}
+              onError={onError}
+              onClose={close}
+            />
+          </KycRuntimeProvider>
+        ) : null}
+      </Modal>
+    </MyazaThemeProvider>
+  );
+}

package/src/components/CountryField.tsx

@@ -21,6 +21,8 @@ export function CountryField({
   value,
   options,
   onChange,
+  geoCountry,
+  grouped,
   placeholder = 'Select a country',
   searchPlaceholder = 'Search country',
 }: {
@@ -29,6 +31,10 @@ export function CountryField({
   /** The pickable countries — all ISO, or a workflow's registry subset. */
   options: DialCodeOption[];
   onChange: (code: string) => void;
+  /** The visitor's inferred country, pinned on top of the sheet as "Your location". */
+  geoCountry?: string | null;
+  /** Region headers between the rows, the country-select step's way. */
+  grouped?: boolean;
   placeholder?: string;
   searchPlaceholder?: string;
 }): React.ReactElement {
@@ -75,6 +81,8 @@ export function CountryField({
         visible={open}
         options={options}
         selected={value ?? ''}
+        pinned={geoCountry}
+        grouped={grouped}
         searchPlaceholder={searchPlaceholder}
         onPick={(code) => {
           setOpen(false);