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

package/src/lib/captureRing.ts

@@ -0,0 +1,83 @@
+import type { LivenessPhase } from '../liveness/types';
+
+// The liveness ring's arithmetic — a MIRROR of the web SDK's
+// components/CaptureRing.tsx and hooks/useLiveness.ts updateLivenessProgress
+// (and of the Flutter SDK's liveness/capture_ring.dart). Change a rule in one
+// and change it in all three in the same commit.
+//
+// Two numbers. The TARGET is where the test has actually got to and only ever
+// moves forward. The DISPLAY eases toward it on real elapsed time, critically
+// damped, so a gesture landing (a whole segment in one go) and the detector's
+// own frame rate both arrive as motion rather than cuts.
+
+/** Time constant of the display's approach, seconds. ~95% of a gap in three. */
+export const TAU = 0.09;
+
+/** How far a challenge segment may fill on its clock alone: time running out
+ *  is not progress, so the clock never completes a segment — the gesture
+ *  landing does. */
+export const CHALLENGE_SEGMENT_CAP = 0.85;
+
+/** The native still takes a beat after `capturing` begins; its segment fills
+ *  across this window. It never CLOSES on it: the clock is capped like a
+ *  challenge's, and only `complete` (the still in hand) reaches 1. On this
+ *  SDK the still is settle → native photo → compress, seconds on a slow
+ *  phone, and the ring used to sit closed for all of it. */
+export const CAPTURE_WINDOW_SEC = 0.4;
+
+const clamp01 = (n: number): number => (n < 0 ? 0 : n > 1 ? 1 : Number.isFinite(n) ? n : 0);
+
+export function advanceTarget(target: number, real: number): number {
+  return Math.max(target, clamp01(real));
+}
+
+export function easeToward(shown: number, target: number, dt: number): number {
+  if (dt <= 0) return shown;
+  return shown + (target - shown) * (1 - Math.exp(-dt / TAU));
+}
+
+export interface LivenessProgressInput {
+  phase: LivenessPhase;
+  /** Steps passed so far. On this SDK the count is bumped at
+   *  `challenge_passed` — read off the hook, not assumed. */
+  completedCount: number;
+  /** Every step the user performs: the gestures, plus the flash when it runs. */
+  totalCount: number;
+  /** Seconds since the current phase began. */
+  elapsedInPhase: number;
+  /** The running challenge's timeout, seconds. */
+  challengeTimeout: number;
+}
+
+/**
+ * Where the WHOLE test has got to, 0..1, in equal segments: positioning, each
+ * step, the capture. Each segment is measured by what actually gates it here —
+ * this SDK advances out of positioning the instant the face is framed and lit
+ * (no steady-frame counter), so that segment fills on the transition; a
+ * challenge fills on its clock; the capture fills across the still's window.
+ */
+export function livenessProgress(s: LivenessProgressInput): number {
+  const seg = 1 / (s.totalCount + 2);
+  const done = s.completedCount; // steps whose segments are complete
+  switch (s.phase) {
+    case 'challenge':
+    case 'flash':
+      return seg * (1 + done + Math.min(CHALLENGE_SEGMENT_CAP, s.elapsedInPhase / Math.max(s.challengeTimeout, 1)));
+    case 'challenge_passed':
+      return seg * (1 + done + 0);
+    case 'capturing':
+      return seg * (1 + s.totalCount + Math.min(CHALLENGE_SEGMENT_CAP, s.elapsedInPhase / CAPTURE_WINDOW_SEC));
+    case 'complete':
+      return 1;
+    default:
+      return 0;
+  }
+}
+
+/** Linear mix of two #rrggbb colours, for the close-to-green beat. */
+export function mixHex(a: string, b: string, t: number): string {
+  const k = clamp01(t);
+  const ch = (h: string, i: number) => parseInt(h.slice(i, i + 2), 16);
+  const out = [1, 3, 5].map((i) => Math.round(ch(a, i) + (ch(b, i) - ch(a, i)) * k));
+  return '#' + out.map((v) => v.toString(16).padStart(2, '0')).join('');
+}

package/src/lib/contact-recovery.ts

@@ -0,0 +1,44 @@
+// Recovery from a submit refused over contact proofs. Mirrors the web SDK's
+// steps/contact-recovery.ts — keep the two in lockstep.
+//
+// Contact proof tokens are SINGLE-USE and expire ~30 minutes after the OTP is
+// checked, but they ride session progress and are restored on resume. A
+// resumed attempt therefore carries a proof the server will (rightly)
+// validate-and-drop at submit, while the contact step still shows "verified"
+// — and a plain retry resubmits the same dead token forever.
+//
+// The 422 is recoverable in-flow: clear the stale proofs, walk the person
+// back to the contact step (their data is untouched), and once re-verified
+// the step routes straight back to 'submitted', which auto-submits with the
+// fresh token.
+import { KYCApiError } from '../services/api';
+import type { KYCStep } from '../types/config';
+
+export type ContactChannel = 'email' | 'phone';
+
+/** The channels a 422 `contact_verification_required` names as missing. */
+export function expiredContactChannels(err: unknown): ContactChannel[] {
+  if (!(err instanceof KYCApiError) || err.code !== 'contact_verification_required') return [];
+  const missing = Array.isArray(err.body?.missing) ? (err.body.missing as unknown[]) : [];
+  return missing.filter((c): c is ContactChannel => c === 'email' || c === 'phone');
+}
+
+export function contactStepFor(channel: ContactChannel): KYCStep {
+  return channel === 'email' ? 'email-verification' : 'phone-verification';
+}
+
+/**
+ * Where the step routes once this channel is verified. Normally the ordinary
+ * forward step; in recovery it returns to 'submitted' (which auto-submits
+ * with the fresh proof) via any OTHER still-refused channel first — the
+ * person never re-walks steps they already completed.
+ */
+export function stepAfterContactVerified(opts: {
+  recovery: boolean;
+  expired: ContactChannel[];
+  channel: ContactChannel;
+}): KYCStep | null {
+  if (!opts.recovery) return null;
+  const remaining = opts.expired.find((c) => c !== opts.channel);
+  return remaining ? contactStepFor(remaining) : 'submitted';
+}

package/src/lib/country-adoption.ts

@@ -0,0 +1,89 @@
+// ---------------------------------------------------------------------------
+// Declared-country adoption.
+//
+// ONE table decides when evidence about where the applicant IS may change the
+// country they are DECLARING: a reverse-geocoded pin or current-location fix
+// (a geocode), or the address they picked from search (explicit). A mirror of
+// the web SDK's steps/address/country-adoption.ts and Flutter's
+// config/country_adoption.dart; the three run the shared vectors in
+// kyc-sdk-flutter/test/country_adoption_vectors.json, so a drift in any one
+// fails there.
+//
+// The rules, and why each exists:
+//  - GEOCODED EVIDENCE outranks every GUESS. The address scope's default is
+//    the IP country, and on a dev box that once declared US while the device
+//    sat in Calabar (the search returned California), so the fix's own
+//    geocode corrects a guess the moment it resolves.
+//  - An EXPLICIT declaration is never overridden by a geocode; a PICKED
+//    address replaces even that, since the pick is the applicant's newer and
+//    more specific statement, and is then itself explicit.
+//  - Outside the address scope `selectedCountry` is the ID-VERIFICATION
+//    country, and changing it resets the ID choice, so only a guessed value
+//    is ever corrected there, picked address or not.
+//  - The org's accepted list (proofOfAddress.countries) gates every path: a
+//    value the submission gate would refuse never becomes the declaration.
+// ---------------------------------------------------------------------------
+
+const ISO2 = /^[A-Z]{2}$/;
+
+/** A trimmed, upper-cased ISO-2, or null for anything that is not one. */
+export function normaliseIso2(raw: string | null | undefined): string | null {
+  const code = raw?.trim().toUpperCase();
+  return code && ISO2.test(code) ? code : null;
+}
+
+/** Whether the org's accepted-country list admits `code`. Null or empty
+ *  accepts everyone. */
+export function countryAccepted(accepted: readonly string[] | null | undefined, code: string): boolean {
+  if (!accepted?.length) return true;
+  return accepted.some((c) => c.trim().toUpperCase() === code);
+}
+
+export interface AdoptionInput {
+  /** The country the evidence named (a geocode's `parts.country`, a pick's own). */
+  country: string | null | undefined;
+  selectedCountry: string | null | undefined;
+  countryAutoPicked: boolean;
+  /** The workflow scope; null is a full verification. */
+  scope: string | null | undefined;
+  accepted: readonly string[] | null | undefined;
+  /** The country came from an address the applicant PICKED. */
+  explicit?: boolean;
+}
+
+export interface CountryAdoption {
+  /** The normalised ISO-2 to declare. */
+  country: string;
+  /** Declare it as a GUESS (later evidence may correct it) rather than as
+   *  the applicant's own explicit statement. */
+  auto: boolean;
+}
+
+/** The adoption rule. See the file header for what each guard is for. */
+export function adoptionDecision(input: AdoptionInput): CountryAdoption | null {
+  const code = normaliseIso2(input.country);
+  if (!code) return null;
+  const onAddressScope = input.scope === 'address';
+  const guessed = input.countryAutoPicked || (onAddressScope && input.selectedCountry == null);
+  if (!guessed && !(input.explicit && onAddressScope)) return null;
+  if (code === normaliseIso2(input.selectedCountry)) return null;
+  if (!countryAccepted(input.accepted, code)) return null;
+  return { country: code, auto: !input.explicit };
+}
+
+/**
+ * The address scope's default: the visitor's IP country, once, while nothing
+ * is declared, and only when the accepted list admits it. A full flow never
+ * defaults from the IP (there the country is the ID's).
+ */
+export function geoDefaultCountry(input: {
+  geoCountry: string | null | undefined;
+  selectedCountry: string | null | undefined;
+  scope: string | null | undefined;
+  accepted: readonly string[] | null | undefined;
+}): string | null {
+  if (input.scope !== 'address' || input.selectedCountry != null) return null;
+  const code = normaliseIso2(input.geoCountry);
+  if (!code || !countryAccepted(input.accepted, code)) return null;
+  return code;
+}

package/src/lib/inferred-country.ts

@@ -0,0 +1,65 @@
+import { tryRequire } from '../services/fingerprint-sources';
+
+// ---------------------------------------------------------------------------
+// The visitor's most likely country, for DEFAULTS only (never evidence). A
+// mirror of the web SDK's lib/inferred-country.ts — keep the three in
+// lockstep.
+//
+// Two tiers: the server's IP-derived `geoCountry` when it exists, else the
+// device's own locale region (en-NG → NG). The second tier is what makes
+// inference work where the IP cannot answer at all — a dev server on a
+// loopback address, a carrier GeoLite2 cannot place — from a signal the
+// device already carries. Both are guesses a person can correct; nothing
+// recorded branches on them.
+// ---------------------------------------------------------------------------
+
+const ISO2 = /^[A-Z]{2}$/;
+
+interface LocalizationLike {
+  getLocales?: () => Array<{ regionCode?: string | null; languageTag?: string | null }>;
+}
+
+/** The region subtag of a BCP-47 tag (`en-NG`, `en_NG`, `yo-Latn-NG`). The
+ *  first subtag is the LANGUAGE ("en"), never a region, so it is skipped. */
+export function regionOfLocaleTag(tag: string | null | undefined): string | null {
+  if (!tag) return null;
+  const [, ...rest] = tag.split(/[-_]/);
+  const region = rest.find((part) => /^[A-Za-z]{2}$/.test(part))?.toUpperCase();
+  return region && ISO2.test(region) ? region : null;
+}
+
+/** The device's locale tags, best first. expo-localization when the host
+ *  installed it (it carries an explicit region), else the JS runtime's. */
+export function deviceLocaleTags(): string[] {
+  const tags: string[] = [];
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const localization = tryRequire<LocalizationLike>(() => require('expo-localization'));
+  try {
+    for (const locale of localization?.getLocales?.() ?? []) {
+      if (locale.regionCode) tags.push(`und-${locale.regionCode}`);
+      else if (locale.languageTag) tags.push(locale.languageTag);
+    }
+  } catch {
+    // A partial module; fall through to the runtime.
+  }
+  try {
+    const runtime = Intl.DateTimeFormat().resolvedOptions().locale;
+    if (runtime) tags.push(runtime);
+  } catch {
+    // No Intl on this runtime.
+  }
+  return tags;
+}
+
+export function inferredCountry(
+  geoCountry?: string | null,
+  localeTags: string[] = deviceLocaleTags(),
+): string | null {
+  const geo = geoCountry?.trim().toUpperCase();
+  if (geo && ISO2.test(geo)) return geo;
+  for (const tag of localeTags) {
+    const region = regionOfLocaleTag(tag);
+    if (region) return region;
+  }
+  return null;
+}

package/src/lib/livenessLayout.ts

@@ -0,0 +1,49 @@
+import { spacing } from '../config/theme';
+
+// ─── How big the selfie circle and the gesture avatar may be ────────────────
+//
+// The circle used to be sized from the window's WIDTH alone (capped at 300),
+// which is the web SDK's rule and is right on a tall phone. On a Samsung S24
+// (360×780 dp, 176 dp shorter than an iPhone 16 Pro Max) the width still gave
+// 296, the circle owned most of the sheet, and the avatar demonstrating the
+// gesture sat below the fold — the one thing the step exists to show. So the
+// HEIGHT bounds it too: whatever the chrome, the instruction, the step dots,
+// the avatar and the footer leave over is what the circle may take, and when
+// it is the height that bound the circle, the avatar shrinks with it.
+//
+// Mirrored in Flutter's liveness/liveness_layout.dart; the real phones below
+// are the shared vectors. Change a number in one and change both.
+
+/** The web's phone circle is 256 and its desktop one 320; 300 is where this
+ *  SDK has always capped, and the tall phones keep it. */
+export const CIRCLE_MAX = 300;
+/** A face is still usable at 200; below that the ring and the oval guide start
+ *  to crowd it, so a very short screen scrolls a little instead. */
+export const CIRCLE_MIN = 200;
+/** Everything on the sheet that is NOT the circle, measured on device:
+ *  banner + brand row + title + step bar (~250), the instruction line, the
+ *  dots, the large avatar, three gaps, the step padding and the footer. */
+export const CIRCLE_HEIGHT_BUDGET = 540;
+/** The circle keeps the step's own side padding on both sides. */
+export const CIRCLE_SIDE_GUTTER = spacing.md * 4;
+
+const clamp = (n: number, lo: number, hi: number): number => Math.min(hi, Math.max(lo, n));
+
+export interface LivenessLayout {
+  /** Diameter of the camera circle, dp. */
+  circle: number;
+  /** Diameter of the gesture avatar badge, dp. */
+  avatar: number;
+  /** The fallback icon inside the avatar when the GIF cannot load. */
+  avatarIcon: number;
+}
+
+export function livenessLayout(window: { width: number; height: number }): LivenessLayout {
+  const byWidth = window.width - CIRCLE_SIDE_GUTTER;
+  const byHeight = window.height - CIRCLE_HEIGHT_BUDGET;
+  const circle = clamp(Math.min(byWidth, byHeight, CIRCLE_MAX), CIRCLE_MIN, CIRCLE_MAX);
+  // Only a SHORT screen shrinks the avatar: a narrow one that is tall enough
+  // has the room for it whatever the width did to the circle.
+  const large = byHeight >= CIRCLE_MAX;
+  return { circle, avatar: large ? 96 : 72, avatarIcon: large ? 40 : 30 };
+}

package/src/lib/map-frame.ts

@@ -0,0 +1,159 @@
+import type { LatLng } from './map-tiles';
+
+// The framed Google-map picker's client half, for a WebView (the OkHi model):
+// the SDK loads OUR hosted /embed/map page TOP-LEVEL in a WebView and talks to
+// it over the WebView's own bridge. A mirror of the web SDK's lib/map-frame.ts
+// and the Flutter SDK's config/map_frame.dart — keep the three in lockstep.
+//
+// Message shapes (add-only; the page mirrors them):
+//   page -> app: { source: 'myaza-map', type: 'ready' | 'failed' }
+//                { source: 'myaza-map', type: 'pin', lat, lng }
+//   app -> page: window.__myazaMapCommand(JSON of
+//                { source: 'myaza-sdk', type: 'center', lat, lng, zoom? })
+
+export const MAP_FRAME_SOURCE = 'myaza-map';
+export const MAP_PARENT_SOURCE = 'myaza-sdk';
+
+/** How long to wait for `ready` before falling back to the OSM picker.
+ *  Generous: the page loads Google's script on a cold cache. */
+export const MAP_FRAME_READY_TIMEOUT_MS = 8000;
+
+export interface MapFrameOptions {
+  center: LatLng;
+  zoom: number;
+  /** Recentre-and-zoom-in when the app already holds a pin. */
+  hasPin: boolean;
+  theme?: 'light' | 'dark';
+  primaryColor?: string;
+}
+
+/** The full page URL: the server-minted frame URL (which already carries the
+ *  signed APP grant and `mode=app`) plus the render-time parameters. There is
+ *  no `origin` — an app has none, and the page proves that instead. */
+export function buildMapFrameSrc(frameUrl: string, opts: MapFrameOptions): string {
+  const url = new URL(frameUrl);
+  url.searchParams.set('lat', String(opts.center.lat));
+  url.searchParams.set('lng', String(opts.center.lng));
+  url.searchParams.set('zoom', String(opts.hasPin ? 16 : opts.zoom));
+  if (opts.theme) url.searchParams.set('theme', opts.theme);
+  if (opts.primaryColor) url.searchParams.set('primary', opts.primaryColor);
+  return url.toString();
+}
+
+export type MapFrameMessage =
+  | { type: 'ready' }
+  | { type: 'failed' }
+  | { type: 'pin'; lat: number; lng: number };
+
+const finite = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+
+/** Validate-and-drop: the bridge delivers strings, so a JSON string is
+ *  accepted too; anything not shaped exactly like a frame message is null. */
+export function parseMapFrameMessage(data: unknown): MapFrameMessage | null {
+  let msg: unknown = data;
+  if (typeof data === 'string') {
+    try {
+      msg = JSON.parse(data);
+    } catch {
+      return null;
+    }
+  }
+  if (!msg || typeof msg !== 'object') return null;
+  const m = msg as Record<string, unknown>;
+  if (m.source !== MAP_FRAME_SOURCE) return null;
+  if (m.type === 'ready') return { type: 'ready' };
+  if (m.type === 'failed') return { type: 'failed' };
+  if (m.type === 'pin' && finite(m.lat) && finite(m.lng)) {
+    if (Math.abs(m.lat) > 90 || Math.abs(m.lng) > 180) return null;
+    return { type: 'pin', lat: m.lat, lng: m.lng };
+  }
+  return null;
+}
+
+/** The recentre command as the script the WebView injects (Use my location,
+ *  restored progress). Ends in `true` because injected scripts must resolve to
+ *  something serialisable on iOS. */
+export function centerCommandScript(pin: LatLng): string {
+  const command = JSON.stringify({ source: MAP_PARENT_SOURCE, type: 'center', lat: pin.lat, lng: pin.lng, zoom: 16 });
+  return `window.__myazaMapCommand && window.__myazaMapCommand(${JSON.stringify(command)}); true;`;
+}
+
+export function samePin(a: LatLng | null, b: LatLng): boolean {
+  return !!a && Math.abs(a.lat - b.lat) < 1e-7 && Math.abs(a.lng - b.lng) < 1e-7;
+}
+
+// ── The framed STREET VIEW page (the entrance framing) ──────────────────────
+//
+// Same origin, same APP grant, sibling page: /embed/street-view lives beside
+// /embed/map and the grant unlocks the key for either, so the SDK DERIVES its
+// URL from the server-minted mapsFrameUrl by swapping the path — the two
+// pages ship together with this SDK, and the coupling is recorded on both
+// sides. The page is deliberately dumb: it renders the panorama and streams
+// the current view (`sv-pov`) over the same bridge the map uses; the framing
+// chrome, the frame-subtended fov maths and the capture decision stay in the
+// SDK, so hosted, embedded and native applicants meet the identical
+// instrument. Mirror of the web SDK's street-view half; keep in lockstep.
+//
+//   page -> app: { source: 'myaza-map', type: 'sv-ready' | 'sv-unavailable' }
+//                { source: 'myaza-map', type: 'sv-pov', panoId, heading, pitch, viewFov }
+
+/** The street-view page's URL derived from the map frame's, or null when the
+ *  frame URL is not the page family this SDK knows. */
+export function streetViewFrameUrlOf(mapsFrameUrl: string): string | null {
+  try {
+    const url = new URL(mapsFrameUrl);
+    if (!url.pathname.endsWith('/embed/map')) return null;
+    url.pathname = url.pathname.replace(/\/embed\/map$/, '/embed/street-view');
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+
+/** The full page URL: the derived page (carrying the signed APP grant and
+ *  `mode=app`) plus the pin the panorama should look from. No `origin`: an
+ *  app has none, and the page proves that instead. */
+export function buildStreetViewFrameSrc(
+  frameUrl: string,
+  opts: { pin: LatLng; theme?: 'light' | 'dark' },
+): string {
+  const url = new URL(frameUrl);
+  url.searchParams.set('lat', String(opts.pin.lat));
+  url.searchParams.set('lng', String(opts.pin.lng));
+  if (opts.theme) url.searchParams.set('theme', opts.theme);
+  return url.toString();
+}
+
+export type StreetViewFrameMessage =
+  | { type: 'sv-ready' }
+  | { type: 'sv-unavailable' }
+  | { type: 'sv-pov'; panoId: string; heading: number; pitch: number; viewFov: number };
+
+/** Validate-and-drop for the street-view page's messages; a JSON string is
+ *  accepted too, since the bridge delivers strings. */
+export function parseStreetViewFrameMessage(data: unknown): StreetViewFrameMessage | null {
+  let msg: unknown = data;
+  if (typeof data === 'string') {
+    try {
+      msg = JSON.parse(data);
+    } catch {
+      return null;
+    }
+  }
+  if (!msg || typeof msg !== 'object') return null;
+  const m = msg as Record<string, unknown>;
+  if (m.source !== MAP_FRAME_SOURCE) return null;
+  if (m.type === 'sv-ready') return { type: 'sv-ready' };
+  if (m.type === 'sv-unavailable') return { type: 'sv-unavailable' };
+  if (
+    m.type === 'sv-pov' &&
+    typeof m.panoId === 'string' &&
+    m.panoId.length > 0 &&
+    finite(m.heading) &&
+    finite(m.pitch) &&
+    finite(m.viewFov)
+  ) {
+    return { type: 'sv-pov', panoId: m.panoId, heading: m.heading, pitch: m.pitch, viewFov: m.viewFov };
+  }
+  return null;
+}

package/src/lib/map-tiles.ts

@@ -0,0 +1,143 @@
+// Web Mercator math for the dependency-free map pin picker. Pure and
+// unit-tested — the picker is a thin gesture shell over these.
+//
+// Deliberately NOT react-native-maps: that means native modules, per-platform
+// setup and a Google Maps API key per org for what the picker needs — pan,
+// zoom, one pin. The standard slippy-map maths below is ~60 lines, fully
+// testable, and the tiles are plain <Image>s.
+//
+// A MIRROR of the web SDK's lib/map-tiles.ts — keep the two in lockstep.
+
+export const TILE_SIZE = 256;
+export const MIN_ZOOM = 3;
+export const MAX_ZOOM = 19;
+
+// Web Mercator's poles — beyond this the projection diverges.
+const MAX_LAT = 85.05112878;
+
+export interface LatLng {
+  lat: number;
+  lng: number;
+}
+
+export function clampLat(lat: number): number {
+  return Math.max(-MAX_LAT, Math.min(MAX_LAT, lat));
+}
+
+function wrapLng(lng: number): number {
+  let l = lng;
+  while (l > 180) l -= 360;
+  while (l < -180) l += 360;
+  return l;
+}
+
+/** World size in pixels at a zoom level. */
+export function worldSize(zoom: number): number {
+  return TILE_SIZE * 2 ** zoom;
+}
+
+/** Project a coordinate to world pixels at a zoom level. */
+export function latLngToWorld(point: LatLng, zoom: number): { x: number; y: number } {
+  const size = worldSize(zoom);
+  const lat = clampLat(point.lat);
+  const sin = Math.sin((lat * Math.PI) / 180);
+  // Clamped into the world: at the pole cap the log term lands a float
+  // epsilon outside [0, size], which would render as a phantom tile row.
+  const y = (0.5 - Math.log((1 + sin) / (1 - sin)) / (4 * Math.PI)) * size;
+  return {
+    x: ((wrapLng(point.lng) + 180) / 360) * size,
+    y: Math.min(size, Math.max(0, y)),
+  };
+}
+
+/** Unproject world pixels back to a coordinate. */
+export function worldToLatLng(x: number, y: number, zoom: number): LatLng {
+  const size = worldSize(zoom);
+  const n = Math.PI - (2 * Math.PI * y) / size;
+  return {
+    lat: (180 / Math.PI) * Math.atan(0.5 * (Math.exp(n) - Math.exp(-n))),
+    lng: wrapLng((x / size) * 360 - 180),
+  };
+}
+
+export interface TilePlacement {
+  key: string;
+  url: string;
+  /** CSS position relative to the viewport's top-left corner. */
+  left: number;
+  top: number;
+}
+
+/**
+ * The OSM tiles covering a viewport centred on `center`. Tiles outside the
+ * world (above/below the poles) are skipped; longitude wraps.
+ */
+export function visibleTiles(
+  center: LatLng,
+  zoom: number,
+  width: number,
+  height: number,
+): TilePlacement[] {
+  const world = latLngToWorld(center, zoom);
+  const tiles: TilePlacement[] = [];
+  const tileCount = 2 ** zoom;
+  const originX = world.x - width / 2;
+  const originY = world.y - height / 2;
+  const first = { x: Math.floor(originX / TILE_SIZE), y: Math.floor(originY / TILE_SIZE) };
+  const last = {
+    x: Math.floor((originX + width) / TILE_SIZE),
+    y: Math.floor((originY + height) / TILE_SIZE),
+  };
+  for (let ty = first.y; ty <= last.y; ty += 1) {
+    if (ty < 0 || ty >= tileCount) continue;
+    for (let tx = first.x; tx <= last.x; tx += 1) {
+      const wrappedX = ((tx % tileCount) + tileCount) % tileCount;
+      tiles.push({
+        key: `${zoom}/${tx}/${ty}`,
+        url: `https://tile.openstreetmap.org/${zoom}/${wrappedX}/${ty}.png`,
+        left: tx * TILE_SIZE - originX,
+        top: ty * TILE_SIZE - originY,
+      });
+    }
+  }
+  return tiles;
+}
+
+/** The centre after a drag of (dx, dy) viewport pixels. */
+export function panCenter(center: LatLng, zoom: number, dx: number, dy: number): LatLng {
+  const world = latLngToWorld(center, zoom);
+  const next = worldToLatLng(world.x - dx, world.y - dy, zoom);
+  return { lat: clampLat(next.lat), lng: next.lng };
+}
+
+/** Sensible starting views: gov-DB countries at country zoom, else a world view. */
+const COUNTRY_CENTERS: Record<string, LatLng> = {
+  NG: { lat: 9.06, lng: 8.68 },
+  GH: { lat: 7.95, lng: -1.02 },
+  KE: { lat: 0.02, lng: 37.9 },
+  ZA: { lat: -28.48, lng: 24.68 },
+  CI: { lat: 7.54, lng: -5.55 },
+};
+
+export function defaultMapView(country: string | undefined): { center: LatLng; zoom: number } {
+  const center = country ? COUNTRY_CENTERS[country.toUpperCase()] : undefined;
+  return center ? { center, zoom: 6 } : { center: { lat: 6.5, lng: 12 }, zoom: 3 };
+}
+
+/**
+ * The height of the map surface on the pin step, from the viewport.
+ *
+ * A phone gets 40% of its height, clamped to 240–360: on a phone the map
+ * owns every touch, so the taller it is the less page is left to scroll on,
+ * and Continue has to stay reachable. From a tablet-class width (the web
+ * SDK's `sm` breakpoint) it is a flat 420. Mirrors the web SDK's
+ * `h-[40vh] min-h-[240px] max-h-[360px] sm:h-[420px]` on AddressCollectionStep
+ * and the Flutter `mapSurfaceHeight`; keep the three in lockstep.
+ */
+export const MAP_SURFACE = { phoneFraction: 0.4, phoneMin: 240, phoneMax: 360, wideBreakpoint: 640, wide: 420 } as const;
+
+export function mapSurfaceHeight(viewport: { width: number; height: number }): number {
+  if (viewport.width >= MAP_SURFACE.wideBreakpoint) return MAP_SURFACE.wide;
+  const fraction = Math.round(viewport.height * MAP_SURFACE.phoneFraction);
+  return Math.min(MAP_SURFACE.phoneMax, Math.max(MAP_SURFACE.phoneMin, fraction));
+}