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

package/src/config/businessSteps.ts

@@ -87,8 +87,14 @@ export type BusinessSectionStep =
 export function businessSectionSteps(
   business: WorkflowBusinessConfig | undefined,
   withQuestionnaire = false,
-): (BusinessSectionStep | 'questionnaire')[] {
-  const steps: (BusinessSectionStep | 'questionnaire')[] = ['business-details'];
+  withAddressCollection = false,
+): (BusinessSectionStep | 'questionnaire' | 'address-collection')[] {
+  const steps: (BusinessSectionStep | 'questionnaire' | 'address-collection')[] = [
+    'business-details',
+  ];
+  // The premises pin follows the company details it is about — before the
+  // paperwork, and long before the application hands over to other people.
+  if (withAddressCollection) steps.push('address-collection');
   // Documents BEFORE key people: they are about the company the applicant has
   // just identified, so they follow that thread, and the register's officer
   // list - which the key-people step is a confirmation of - is what should

package/src/config/consentStep.ts

@@ -0,0 +1,19 @@
+import type { KYCStep } from '../types/config';
+
+// ─── The consent screen switch (`consentStep`) ──────────────────────────────
+//
+// A workflow can switch the opening consent (welcome) screen off, for a host
+// app that has already asked: the flow then opens on its first real step.
+// Mirrors the server's `WorkflowConfigSchema.consentStep` and the web /
+// Flutter helpers of the same name; keep the default in lockstep.
+
+/** Whether the flow opens on the consent screen. Absent = yes. */
+export function hasConsentStep(config: { consentStep?: boolean | null }): boolean {
+  return config.consentStep !== false;
+}
+
+/** The step a built order opens on; 'consent' for an empty order, which no
+ *  flow produces. */
+export function openingStepOf(order: readonly KYCStep[]): KYCStep {
+  return order[0] ?? 'consent';
+}

package/src/config/proofOfAddress.ts

@@ -8,12 +8,13 @@
 // server is going to make anyway.
 // ---------------------------------------------------------------------------
 
-import type { PoaDocumentType, ProofOfAddressConfig } from '../types/workflow';
+import type { PoaDocumentType, PoaNameRule, ProofOfAddressConfig } from '../types/workflow';
 
 export const POA_TYPE_LABELS: Record<PoaDocumentType, string> = {
   utility_bill: 'Utility bill',
   bank_statement: 'Bank statement',
   tenancy_agreement: 'Tenancy agreement',
+  government_document: 'Government-issued document',
   other: 'Other document',
 };
 
@@ -21,9 +22,15 @@ const ALL_POA_TYPES: PoaDocumentType[] = [
   'utility_bill',
   'bank_statement',
   'tenancy_agreement',
+  'government_document',
   'other',
 ];
 
+/** A kind THIS build can label and draw. A newer kind the dashboard offers
+ *  before the SDK ships is hidden rather than rendered as a blank row. */
+const knownKinds = (kinds: readonly string[] | undefined): PoaDocumentType[] =>
+  (kinds ?? []).filter((k): k is PoaDocumentType => (ALL_POA_TYPES as string[]).includes(k));
+
 /** Default recency window the server checks the document date against. */
 export const DEFAULT_POA_MAX_AGE_DAYS = 90;
 
@@ -32,10 +39,52 @@ export function hasProofOfAddressStep(poa: ProofOfAddressConfig | undefined | nu
   return poa?.enabled === true;
 }
 
-/** The document kinds on offer. An absent or empty list means all of them. */
-export function poaDocumentTypes(poa: ProofOfAddressConfig | undefined): PoaDocumentType[] {
-  const configured = poa?.documentTypes;
-  return configured && configured.length > 0 ? configured : ALL_POA_TYPES;
+/**
+ * The document kinds on offer for `country` (mirror of the web SDK's
+ * `poaOfferedKinds` — keep the three in lockstep): that country's override
+ * when the workflow declares one, else the global list, else all four.
+ */
+export function poaDocumentTypes(
+  poa: ProofOfAddressConfig | undefined,
+  country?: string | null,
+): PoaDocumentType[] {
+  const override = knownKinds(country ? poa?.countryDocuments?.[country.toUpperCase()] : undefined);
+  if (override.length > 0) return override;
+  const configured = knownKinds(poa?.documentTypes);
+  return configured.length > 0 ? configured : ALL_POA_TYPES;
+}
+
+/**
+ * The name rule the server judges THIS document under — the country's per-kind
+ * exception, else the workflow default, else `required`. Mirror of the web
+ * SDK's `poaNamePolicy` and the server's `resolvePoaNamePolicy` — keep in
+ * lockstep. Read only to word the step: under `off` the header stops asking
+ * for the applicant's name.
+ */
+export function poaNamePolicy(
+  poa: ProofOfAddressConfig | undefined | null,
+  country: string | undefined | null,
+  kind: PoaDocumentType | undefined | null,
+): PoaNameRule {
+  const exception = country && kind ? poa?.countryNameMatch?.[country.toUpperCase()]?.[kind] : undefined;
+  if (exception === 'required' || exception === 'optional' || exception === 'off') return exception;
+  const def = poa?.nameMatch;
+  return def === 'optional' || def === 'off' ? def : 'required';
+}
+
+/**
+ * Whether the org's accepted-country list admits `country`. An empty list
+ * accepts everyone; an unknown country is not refused here (the server is the
+ * gate, and it is soft on full flows).
+ */
+export function poaCountryAccepted(
+  poa: ProofOfAddressConfig | undefined | null,
+  country: string | undefined | null,
+): boolean {
+  const accepted = poa?.countries;
+  if (!accepted?.length || !country) return true;
+  const code = country.toUpperCase();
+  return accepted.some((c) => c.toUpperCase() === code);
 }
 
 /**
@@ -63,12 +112,6 @@ export const POA_ACCEPTED_MIME_TYPES = [
   'application/pdf',
 ] as const;
 
-/**
- * Local size cap, matching the web SDK. The server allows more, but rejecting
- * here gives an immediate, specific message instead of a slow 413.
- */
-export const POA_MAX_BYTES = 20 * 1024 * 1024;
-
 export function isAcceptedPoaMimeType(mimeType: string | undefined): boolean {
   const base = (mimeType?.split(';')[0] ?? '').trim().toLowerCase();
   return (POA_ACCEPTED_MIME_TYPES as readonly string[]).includes(base);

package/src/config/regions.ts

@@ -116,3 +116,27 @@ export function groupCountriesByRegion(codes: string[]): RegionGroup[] {
     countries: buckets.get(region)!.sort((a, b) => a.name.localeCompare(b.name)),
   }));
 }
+
+/**
+ * Lift the visitor's IP country out of its alphabetical or regional place to
+ * the top of a picker, so the one country most likely to be theirs is the
+ * first thing they see rather than something to scroll for.
+ *
+ * Takes the ALREADY-FILTERED list: the pin stays subject to the search, so
+ * typing narrows to what was asked for rather than keeping a row that does
+ * not match it. Generic over the row shape because the country-select step
+ * pins bare ISO codes and the dial-code sheet pins option objects; one rule,
+ * two callers. Mirrors the web SDK's CountryRegionPicker + PhoneNumberInput
+ * and Flutter's `pinGeoRow`.
+ */
+export function pinGeoRow<T>(
+  visible: readonly T[],
+  geoCountry: string | null | undefined,
+  codeOf: (item: T) => string,
+): { pinned: T | null; rest: T[] } {
+  const geo = geoCountry?.trim().toUpperCase();
+  if (!geo) return { pinned: null, rest: [...visible] };
+  const hit = visible.find((item) => codeOf(item).toUpperCase() === geo);
+  if (hit === undefined) return { pinned: null, rest: [...visible] };
+  return { pinned: hit, rest: visible.filter((item) => item !== hit) };
+}

package/src/config/stepOrder.ts

@@ -21,19 +21,37 @@
 import type { WorkflowBusinessConfig } from '../types/business';
 import type { KYCStep } from '../types/config';
 import { applyResubmitSteps, type ResubmitConfig } from '../lib/resubmit';
+import { addressFlowSteps, type AddressFlowOptions } from '../lib/address-flow';
 import { businessSectionSteps, hasApplicantVerification } from './businessSteps';
 
 export interface StepOrderOptions {
   isBusiness: boolean;
+  /** Scoped flows: no identity section — each scope's headline step is the
+   *  flow (see lib/scope.ts). */
+  scope?: import('../lib/scope').WorkflowScope | null;
   /** Business (KYB) configuration — drives the application-section steps. */
   business?: WorkflowBusinessConfig;
   hasDocCapture: boolean;
   hasNfc: boolean;
   hasLiveness: boolean;
   hasCountrySelect: boolean;
+  /**
+   * Whether the flow opens on the consent screen. Absent = yes. `false` is the
+   * workflow's `consentStep: false`: the host app has already asked, so the
+   * flow opens on its first real step instead (config/consentStep.ts).
+   */
+  hasConsent?: boolean;
   hasEmailVerification: boolean;
   hasPhoneVerification: boolean;
   hasPoa: boolean;
+  hasAddressCollection: boolean;
+  /**
+   * Which address screens the flow has, from the ONE `addressFlowFor` call.
+   * The list is built by `addressFlowSteps`, the same builder the address
+   * steps navigate by, so the progress bar and the flow cannot disagree.
+   * Absent falls back to the default shape (no search, entrance offered).
+   */
+  addressFlow?: AddressFlowOptions;
   hasQuestionnaire: boolean;
   /**
    * A reviewer sent this back to redo specific steps.
@@ -68,6 +86,11 @@ export function buildStepOrder(o: StepOrderOptions): KYCStep[] {
   return applyResubmitSteps(fullStepOrder(o), o.resubmit);
 }
 
+/** The flow's opening screen: consent, unless the workflow switched it off. */
+function openingSteps(o: StepOrderOptions): KYCStep[] {
+  return o.hasConsent === false ? [] : ['consent'];
+}
+
 /** The flow as configured, before any reviewer narrowing. */
 function fullStepOrder(o: StepOrderOptions): KYCStep[] {
   // Business (KYB) flow — the application section, then (when the workflow
@@ -77,9 +100,9 @@ function fullStepOrder(o: StepOrderOptions): KYCStep[] {
     // its questions are about the company, so it stays with the company form
     // rather than trailing the applicant's own capture leg.
     const steps: KYCStep[] = [
-      'consent',
+      ...openingSteps(o),
       ...contactSteps(o),
-      ...businessSectionSteps(o.business, o.hasQuestionnaire),
+      ...businessSectionSteps(o.business, o.hasQuestionnaire, o.hasAddressCollection),
     ];
     if (hasApplicantVerification(o.business)) {
       // The applicant may hold an ID issued anywhere the org can verify —
@@ -93,11 +116,52 @@ function fullStepOrder(o: StepOrderOptions): KYCStep[] {
     return steps;
   }
 
+  // Scoped flows: the scope's headline section IS the flow.
+  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 },
+      ),
+    );
+    if (o.hasQuestionnaire) steps.push('questionnaire');
+    steps.push('submitted');
+    return steps;
+  }
+  if (o.scope === 'biometric-authentication' || o.scope === 'biometric-enrollment') {
+    const steps: KYCStep[] = [...openingSteps(o), ...contactSteps(o), 'liveness'];
+    if (o.hasQuestionnaire) steps.push('questionnaire');
+    steps.push('submitted');
+    return steps;
+  }
+  if (o.scope === 'questionnaire') {
+    return [...openingSteps(o), ...contactSteps(o), 'questionnaire', 'submitted'];
+  }
+  if (o.scope === 'contact') {
+    return [...openingSteps(o), ...contactSteps(o), 'submitted'];
+  }
+
   const middle: KYCStep[] = [...captureLeg(o)];
   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
+  // is ordinary step navigation. KYB keeps the single premises step, inserted
+  // by businessSectionSteps above.
+  if (o.hasAddressCollection) {
+    middle.push(
+      ...addressFlowSteps(
+        o.addressFlow ?? {
+          searchAvailable: false,
+          photoMode: 'optional',
+          streetViewOffered: false,
+        },
+      ),
+    );
+  }
   if (o.hasQuestionnaire) middle.push('questionnaire');
   return [
-    'consent',
+    ...openingSteps(o),
     ...contactSteps(o),
     ...(o.hasCountrySelect ? (['country-select'] as KYCStep[]) : []),
     'id-type',
@@ -129,10 +193,20 @@ export function nextStepInOrder(step: KYCStep, o: StepOrderOptions): KYCStep {
   return order[index + 1] ?? order[order.length - 1]!;
 }
 
-/** The step before `step` — what the back button goes to. */
+/**
+ * The step before `step` — what the back button goes to.
+ *
+ * A step not in the order stands still, for the same reason `nextStepInOrder`
+ * refuses to guess at one: it has no predecessor in a flow that does not
+ * contain it. This used to fall through to `order[0]`, so an applicant resumed
+ * onto a step the flow had since dropped was thrown all the way back to consent
+ * by a single back-press, discarding everything they had done. Standing still
+ * is recoverable; that was not.
+ */
 export function previousStepInOrder(step: KYCStep, o: StepOrderOptions): KYCStep {
   const order = buildStepOrder(o);
   const index = order.indexOf(step);
-  if (index <= 0) return order[0]!;
+  if (index < 0) return step;
+  if (index === 0) return order[0]!;
   return order[index - 1]!;
 }

package/src/config/uploadLimits.ts

@@ -0,0 +1,35 @@
+// ---------------------------------------------------------------------------
+// Upload size limits.
+//
+// One rule for every document the applicant attaches (proof of address, the
+// KYB company documents, the entrance photo): images up to 5 MB, PDFs up to
+// 15 MB (user decision 2026-09-06). The server's own cap is higher, so refusing
+// here gives an immediate, specific message instead of a slow 413. A THREE-WAY
+// MIRROR with the web SDK's `lib/upload-limits.ts` and Flutter's
+// `config/upload_limits.dart`, pinned to
+// `kyc-sdk-flutter/test/upload_limits_vectors.json`.
+// ---------------------------------------------------------------------------
+
+export const IMAGE_MAX_BYTES = 5 * 1024 * 1024;
+export const PDF_MAX_BYTES = 15 * 1024 * 1024;
+
+/** The line under every drop zone: what is accepted, and how big. */
+export const UPLOAD_HINT = 'PDF, JPG, PNG · PDF max 15 MB, images max 5 MB';
+
+export function isPdfMime(mime: string | null | undefined): boolean {
+  return (mime?.split(';')[0] ?? '').trim().toLowerCase() === 'application/pdf';
+}
+
+/**
+ * The refusal for a file over its cap, or null when it fits. An unknown size
+ * also passes: the server still judges the bytes at its own cap, and a picker
+ * that reports no size must not block a good file.
+ */
+export function uploadSizeError(
+  mime: string | null | undefined,
+  size: number | null | undefined,
+): string | null {
+  if (typeof size !== 'number' || !Number.isFinite(size)) return null;
+  if (isPdfMime(mime)) return size > PDF_MAX_BYTES ? 'PDF is too large (max 15 MB).' : null;
+  return size > IMAGE_MAX_BYTES ? 'Image is too large (max 5 MB).' : null;
+}

package/src/config/workflowMerge.ts

@@ -16,6 +16,7 @@
  */
 export const WORKFLOW_KEYS = [
   'subjectType',
+  'scope',
   'business',
   'country',
   'countries',
@@ -27,8 +28,10 @@ export const WORKFLOW_KEYS = [
   'enableLiveness',
   'livenessMode',
   'flashSequenceLength',
+  'biometric',
   'deviceIntelligence',
   'keyPeopleLinkRecovery',
+  'consentStep',
   'requireMobileDevice',
   'voiceGuidance',
   'showThemeToggle',
@@ -41,6 +44,7 @@ export const WORKFLOW_KEYS = [
   'phoneVerification',
   'questionnaire',
   'proofOfAddress',
+  'addressCollection',
   'nfc',
   // Set only on a session a reviewer sent back, never on a published flow.
   'resubmit',
@@ -53,8 +57,10 @@ export type WorkflowKey = (typeof WORKFLOW_KEYS)[number];
  * key it DEFINES; an absent key leaves the prop alone (which is how a flow that
  * only sets, say, `livenessMode` doesn't wipe a prop-supplied `userId`).
  *
- * `appearance` merges shallowly with flow keys winning per-field, so a flow
- * that only sets `primaryColor` doesn't wipe a prop-supplied `logo`.
+ * `appearance` and `biometric` merge shallowly with flow keys winning
+ * per-field, so a flow that only sets `primaryColor` doesn't wipe a
+ * prop-supplied `logo`, and a flow that only switches the selfie review on
+ * doesn't wipe a host app's `doneButton: false`.
  *
  * Pure and side-effect free.
  */
@@ -67,10 +73,10 @@ export function mergeWorkflowConfig<P extends Record<string, unknown>>(
   for (const key of WORKFLOW_KEYS) {
     const value = flowConfig[key];
     if (value === undefined) continue;
-    if (key === 'appearance') {
-      const propAppearance = props['appearance'];
+    if (key === 'appearance' || key === 'biometric') {
+      const propBlock = props[key];
       merged[key] = {
-        ...(typeof propAppearance === 'object' && propAppearance !== null ? propAppearance : {}),
+        ...(typeof propBlock === 'object' && propBlock !== null ? propBlock : {}),
         ...(value as Record<string, unknown>),
       };
     } else {

package/src/index.ts

@@ -11,6 +11,16 @@
 export { MyazaKYC, useMyazaKYC } from './MyazaKYC';
 export type { MyazaKYCProps, UseMyazaKYCReturn } from './MyazaKYC';
 
+// Returning-user face re-authentication (the web SDK's MyazaBiometricAuth).
+export { MyazaBiometricAuth } from './MyazaBiometricAuth';
+export type { MyazaBiometricAuthProps } from './MyazaBiometricAuth';
+export type {
+  BiometricAuthRequest,
+  BiometricAuthResponse,
+  BiometricStatusResponse,
+  BiometricLivenessClaim,
+} from './services/api-types-biometric';
+
 // Public config + callback types
 export type {
   MyazaKYCConfig,
@@ -32,6 +42,7 @@ export type {
   PhoneVerificationConfig,
   ProofOfAddressConfig,
   PoaDocumentType,
+  AddressCollectionConfig,
   QuestionnaireConfig,
   QuestionnaireField,
   QuestionnaireFieldOption,
@@ -56,7 +67,8 @@ export type {
   WorkflowBusinessDocumentTypeConfig,
   WorkflowBusinessApplicantConfig,
 } from './types/business';
-export type { KYCSubmission, KYCErrorCode, KYCErrorDetails } from './types/verification';
+export type { KYCSubmission, KYCResult, KYCErrorCode, KYCErrorDetails } from './types/verification';
+export type { BiometricFlowConfig, BiometricCopy, BiometricCopyText } from './config/biometricOptions';
 export { KYCError } from './types/verification';
 
 // ID-type matrix + helpers
@@ -107,6 +119,47 @@ export {
 export { hasActiveQuestionnaire, questionnaireAnswerKeys } from './config/questionnaire';
 export { hasEmailVerificationStep, hasPhoneVerificationStep } from './config/contact';
 export { hasProofOfAddressStep, poaDocumentTypes, poaTypeLabel } from './config/proofOfAddress';
+export { hasAddressCollectionStep } from './config/addressCollection';
+// Presence verification (Address Intelligence Phase 2): the foreground
+// reporter the HOST APP calls on app open, plus the on-device pin store.
+export {
+  reportAddressPresence,
+  type ReportPresenceOptions,
+  type ReportPresenceResult,
+} from './presence/report';
+// The background (OS geofence) tier — the always-on model. register* must run
+// at app-root module scope; enable* asks for the background permission.
+export {
+  PRESENCE_GEOFENCE_TASK,
+  disableBackgroundPresence,
+  enableBackgroundPresence,
+  registerBackgroundPresence,
+  type EnableBackgroundResult,
+} from './presence/background';
+// The Android foreground-service tier (the OkHi reliability move): a
+// persistent notification keeps the process alive on phones whose battery
+// managers drop geofence transitions. Opt-in; the host words the notification.
+export {
+  PRESENCE_LOCATION_TASK,
+  disableForegroundService,
+  enableForegroundService,
+  foregroundServiceRunning,
+  type EnableForegroundServiceResult,
+  type PresenceNotification,
+} from './presence/foreground-service';
+export {
+  openLocationSettings,
+  presenceStatus,
+  type PresenceStatus,
+  type PresenceTier,
+} from './presence/status';
+export { resolvePresenceTier, type PermissionState, type TierInputs } from './presence/tier';
+// savePresencePin is the org-side handoff for STANDALONE address verification:
+// when capture happened on a hosted web link (or the org's own backend already
+// holds the address), the host app hands the SDK the pin so the foreground and
+// background presence tiers can run — the pin otherwise only ever exists where
+// OUR capture step stored it.
+export { clearPresencePin, savePresencePin } from './presence/store';
 
 // Country grouping for multi-region flows
 export { groupCountriesByRegion, regionCountryName, type Region } from './config/regions';

package/src/lib/address-current-location.ts

@@ -0,0 +1,171 @@
+import type { AddressParts } from '../services/api';
+import type { LocationFailure } from '../services/location';
+
+// ---------------------------------------------------------------------------
+// The device's current location, fetched ONCE per verification and shared by
+// every address step.
+//
+// Module-level on purpose: the steps mount and unmount as the person walks the
+// flow, and re-prompting or re-fixing on every screen is exactly the hesitation
+// this exists to remove. Every address step starts the prefetch on mount, so
+// the GPS warms up while the person is still reading the SEARCH screen; by the
+// pin step the fix — and its reverse-geocoded line — are usually already in
+// hand, and the map lands right first time instead of showing a default view
+// and then jumping.
+//
+// A MIRROR of the web SDK's steps/address/current-location.ts, with one
+// deliberate difference: web scopes the cache to a PAGE session, which ends at
+// the next reload. An app session spans many opens of the SDK, so a fix cached
+// an hour ago would drop the pin at yesterday's address. Store CREATION clears
+// it (one store per modal launch), making "this verification" the mobile
+// equivalent of that scope. Clearing it only from the store's reset() is not
+// enough: reset() is a consumer-facing restart, not part of the open path.
+// ---------------------------------------------------------------------------
+
+export interface CurrentFix {
+  lat: number;
+  lng: number;
+  accuracy: number | null;
+  /** The reverse-geocoded line ("11 Bassey Street, Calabar"), when known. */
+  label: string | null;
+  parts: AddressParts | null;
+}
+
+/** A GPS read: the fix, or WHY there is none (services/location.ts). */
+export type FixOutcome =
+  | { fix: { lat: number; lng: number; accuracy: number | null } }
+  | { failure: LocationFailure };
+
+/**
+ * What the cache needs to produce a fix.
+ *
+ * The GPS reader is INJECTED rather than imported: the store's reset clears
+ * this cache, and importing expo-location here would drag a native module into
+ * the store's graph for the sake of resetting three variables.
+ */
+export interface FixSource {
+  takeFix(): Promise<FixOutcome>;
+  addressReverse(
+    lat: number,
+    lng: number,
+  ): Promise<{ line: string | null; parts?: AddressParts | null }>;
+}
+
+let resolved: CurrentFix | null = null;
+let inflight: Promise<CurrentFix | null> | null = null;
+let failed = false;
+let lastFailure: LocationFailure | null = null;
+
+/** Why the last attempt failed, so the message can say something true. */
+export function currentFixFailure(): LocationFailure | null {
+  return lastFailure;
+}
+
+/**
+ * The message for a failed read. A refused permission, a phone that cannot
+ * place itself, and a fix that took too long are three different problems
+ * with three different remedies, and one line telling everybody to "allow
+ * location access" sent people to a permission that was already granted.
+ * Placing the pin by hand always works, so every line says so. Mirrors the
+ * web SDK's locationFailureMessage and Flutter's.
+ */
+export function locationFailureMessage(reason: LocationFailure | null): string {
+  switch (reason) {
+    case 'denied':
+      return "Location access is blocked for this app. Allow it in your phone's Settings, then try again, or place the pin yourself.";
+    case 'unavailable':
+      return 'Your phone could not work out where it is right now. Check that location is switched on, then try again, or place the pin yourself.';
+    case 'timeout':
+      return 'Finding your location took too long. Try again, or place the pin yourself.';
+    default:
+      return 'This device cannot share its location. Place the pin yourself.';
+  }
+}
+
+/** The fix, when one has already resolved for this verification. */
+export function currentFix(): CurrentFix | null {
+  return resolved;
+}
+
+/** Is a fix attempt still running? */
+export function locating(): boolean {
+  return inflight !== null && resolved === null;
+}
+
+/**
+ * Start (or JOIN) the one location attempt. Safe to call from every address
+ * step's mount: the OS permission prompt fires at most once, and a second
+ * caller waits on the first attempt rather than starting its own.
+ *
+ * Resolves null on a denied or failed read — callers fall back to the manual
+ * pin, which is what every address failure degrades to.
+ */
+export function prefetchCurrentFix(
+  source: FixSource,
+  opts?: { retry?: boolean },
+): Promise<CurrentFix | null> {
+  if (resolved) return Promise.resolve(resolved);
+  // A failed attempt (denied prompt, no fix) is never retried AUTOMATICALLY.
+  // Every step mount calls this, so re-arming on failure left the location row
+  // spinning forever and re-fired the OS prompt on each screen. An explicit
+  // TAP passes `retry` and gets a fresh attempt, since the person may have
+  // granted permission in the meantime.
+  if (failed && !inflight && !opts?.retry) return Promise.resolve(null);
+  if (!inflight) {
+    inflight = (async () => {
+      // No builder-preview branch: the preview is a web-only surface, and a
+      // canned fix here would be a code path no mobile caller can reach.
+      const outcome = await source.takeFix().catch((): FixOutcome => ({ failure: 'unsupported' }));
+      if (!('fix' in outcome)) {
+        inflight = null;
+        failed = true;
+        lastFailure = outcome.failure;
+        return null;
+      }
+      const fix = outcome.fix;
+      lastFailure = null;
+      let label: string | null = null;
+      let parts: AddressParts | null = null;
+      try {
+        const r = await source.addressReverse(fix.lat, fix.lng);
+        label = r.line ?? null;
+        parts = r.parts ?? null;
+      } catch {
+        /* the coordinates alone are still a fix */
+      }
+      resolved = { lat: fix.lat, lng: fix.lng, accuracy: fix.accuracy, label, parts };
+      failed = false;
+      return resolved;
+    })();
+  }
+  return inflight;
+}
+
+/** Forget the fix so the next verification takes its own. Called from the
+ *  store's reset, beside the step log. */
+export function resetCurrentFix(): void {
+  resolved = null;
+  inflight = null;
+  failed = false;
+  lastFailure = null;
+}
+
+// ── The pin step's automatic first locate ───────────────────────────────────
+//
+// Most people are verifying from home, so the map should land on them rather
+// than a country-centre default. It fires ONCE: a dismissed or denied prompt
+// must not re-fire every time the person passes back through the pin step, and
+// the explicit control is there for retries.
+
+let autoLocateAttempted = false;
+
+/** True the FIRST time it is called for a verification, false after. */
+export function claimAutoLocate(): boolean {
+  if (autoLocateAttempted) return false;
+  autoLocateAttempted = true;
+  return true;
+}
+
+export function resetAutoLocate(): void {
+  autoLocateAttempted = false;
+}