feat(mobile): persist state + serve a cached fleet on launch

The storage seam was an in-memory stub, so nothing survived a restart — the app
minted a NEW keypair every launch (losing the on-chain entitlement) and
re-discovered the whole fleet from cold every time. Wire real persistence and a
discovery cache so the app opens straight into a usable state.

- Add @react-native-async-storage/async-storage (3.1.1, exact) and back the whole
  storage seam with it: keypair, prefs, favorites now persist across restarts.
  (Private key is plain in AsyncStorage — already far better than the previous
  regenerate-every-launch; a later pass should move it to the Keychain/Keystore.)
- Fleet cache: persist the last good discovery (gateways + latency) via
  saveFleet, and on launch paint it immediately (loadFleet) before running live
  discovery in the background. Warm launches skip the splash entirely and show
  servers instantly; the cache is also a fallback when discovery is slow/fails.
- Surface the background refresh: a subtle "Updating servers…" line on Connect
  while cache is served, and the picker's spinner now reflects auto-discovery.
- Jest: mock AsyncStorage (jest.setup.js) + fleet-cache round-trip tests.

Author: TheTrunk

clients/mobile/App.tsx

@@ -60,6 +60,7 @@ function App(): React.JSX.Element {
               onSelect={(code) => void vpn.selectCountry(code)}
               onClose={() => setRoute('connect')}
               onRefresh={() => vpn.refresh()}
+              discovering={vpn.discovering}
               favorites={vpn.favorites}
               onToggleFavorite={(code) => void vpn.toggleFavorite(code)}
             />
@@ -70,6 +71,7 @@ function App(): React.JSX.Element {
               onSelect={(code) => void vpn.selectEntryCountry(code)}
               onClose={() => setRoute('connect')}
               onRefresh={() => vpn.refresh()}
+              discovering={vpn.discovering}
               favorites={vpn.favorites}
               onToggleFavorite={(code) => void vpn.toggleFavorite(code)}
             />
@@ -80,6 +82,7 @@ function App(): React.JSX.Element {
               onSelect={(code) => void vpn.selectExitCountry(code)}
               onClose={() => setRoute('connect')}
               onRefresh={() => vpn.refresh()}
+              discovering={vpn.discovering}
               favorites={vpn.favorites}
               onToggleFavorite={(code) => void vpn.toggleFavorite(code)}
             />

clients/mobile/jest.config.js

@@ -23,4 +23,6 @@ module.exports = {
   },
   testMatch: ['**/src/**/*.test.ts', '**/src/**/*.test.tsx'],
   moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  // Mock the native AsyncStorage module (see jest.setup.js).
+  setupFiles: ['<rootDir>/jest.setup.js'],
 };

clients/mobile/jest.setup.js

@@ -0,0 +1,27 @@
+/**
+ * Jest setup. Replaces the native AsyncStorage module with a tiny in-memory
+ * implementation so `storage.ts` runs under Node without a device bridge.
+ *
+ * We inline the mock (rather than require the library's own) because its mock
+ * subpath isn't a stable package export across versions — a self-contained fake
+ * of the handful of methods `storage.ts` uses is simpler and version-proof.
+ */
+jest.mock('@react-native-async-storage/async-storage', () => {
+  let store = {};
+  return {
+    __esModule: true,
+    default: {
+      getItem: jest.fn(async (key) => (key in store ? store[key] : null)),
+      setItem: jest.fn(async (key, value) => {
+        store[key] = value;
+      }),
+      removeItem: jest.fn(async (key) => {
+        delete store[key];
+      }),
+      clear: jest.fn(async () => {
+        store = {};
+      }),
+      getAllKeys: jest.fn(async () => Object.keys(store)),
+    },
+  };
+});

clients/mobile/package.json

@@ -16,6 +16,7 @@
   },
   "dependencies": {
     "@cumulusvpn/core": "file:../core-ts",
+    "@react-native-async-storage/async-storage": "3.1.1",
     "react": "19.2.7",
     "react-native": "0.86.0",
     "react-native-get-random-values": "1.11.0",

clients/mobile/src/screens/ConnectScreen.tsx

@@ -5,7 +5,15 @@
  * plus live down/up/ping stats when connected. Everything is driven by `useVpn`.
  */
 import { useEffect, useState } from 'react';
-import { Platform, Pressable, ScrollView, StyleSheet, Text, View } from 'react-native';
+import {
+  ActivityIndicator,
+  Platform,
+  Pressable,
+  ScrollView,
+  StyleSheet,
+  Text,
+  View,
+} from 'react-native';
 import type { RouteStyle } from '@cumulusvpn/core';
 import type { Country } from '../lib/gateways';
 import type { PaymentIdentity, VpnActions, VpnModel } from '../state/useVpn';
@@ -116,6 +124,14 @@ export function ConnectScreen({
             />
           </View>
         ) : null}
+
+        {/* Serving the cached fleet while a background refresh fetches fresh. */}
+        {vpn.discovering && vpn.countries.length > 0 ? (
+          <View style={styles.updating}>
+            <ActivityIndicator size="small" color={color.inkFaint} />
+            <Text style={styles.updatingText}>Updating servers…</Text>
+          </View>
+        ) : null}
       </View>
 
       {/* Fast / Multi-hop toggle — multi-hop is OFF by default (docs/11 §UX). */}
@@ -465,6 +481,8 @@ const styles = StyleSheet.create({
     paddingVertical: space.md,
   },
   loc: { alignItems: 'center' },
+  updating: { flexDirection: 'row', alignItems: 'center', gap: 6 },
+  updatingText: { color: color.inkFaint, fontSize: 11.5 },
   flag: { fontSize: 30, lineHeight: 34 },
   country: { fontSize: 21, fontWeight: '700', color: color.ink, marginTop: space.xs },
   ip: { fontFamily: font.mono, fontSize: 11.5, color: color.inkDim, marginTop: 3 },

clients/mobile/src/screens/CountryPickerScreen.tsx

@@ -33,6 +33,8 @@ interface Props {
   readonly onClose: () => void;
   /** Re-run discovery + an active latency re-test of the fleet. */
   readonly onRefresh: () => Promise<void>;
+  /** True while an automatic background discovery is in flight. */
+  readonly discovering?: boolean;
   /** Favorited country codes (surfaced first). */
   readonly favorites: readonly string[];
   /** Pin/unpin a country. */
@@ -45,11 +47,14 @@ export function CountryPickerScreen({
   onSelect,
   onClose,
   onRefresh,
+  discovering = false,
   favorites,
   onToggleFavorite,
 }: Props): React.JSX.Element {
   const [query, setQuery] = useState('');
   const [refreshing, setRefreshing] = useState(false);
+  // Spin for either a manual re-test or an automatic background refresh.
+  const busy = refreshing || discovering;
 
   const doRefresh = async (): Promise<void> => {
     setRefreshing(true);
@@ -79,11 +84,11 @@ export function CountryPickerScreen({
         <Text style={styles.title}>Choose location</Text>
         <View style={styles.headerRight}>
           <Pressable
-            onPress={refreshing ? undefined : () => void doRefresh()}
+            onPress={busy ? undefined : () => void doRefresh()}
             accessibilityRole="button"
             hitSlop={10}
           >
-            {refreshing ? (
+            {busy ? (
               <ActivityIndicator size="small" color={color.cyan} />
             ) : (
               <Text style={styles.retest}>↻ Re-test</Text>

clients/mobile/src/state/storage.test.ts

@@ -1,12 +1,11 @@
 /**
- * Unit tests for the persistence seam.
- *
- * The POC uses an in-memory Map behind the real async signatures, so these
- * tests exercise the observable contract every screen relies on: keypair
- * round-trips, route-style validation/defaulting, and the null-clears-auto-pick
- * behaviour of the entry/exit country setters.
+ * Unit tests for the persistence seam (AsyncStorage-backed; the native module is
+ * swapped for its in-memory jest mock in jest.setup.js). These exercise the
+ * observable contract every screen relies on: keypair round-trips, route-style
+ * validation/defaulting, the null-clears-auto-pick behaviour of the entry/exit
+ * setters, and the discovery (fleet) cache round-trip + corruption guard.
  */
-import type { Keypair } from '@cumulusvpn/core';
+import type { GatewayInfo, Keypair } from '@cumulusvpn/core';
 import {
   loadKeypair,
   saveKeypair,
@@ -18,10 +17,26 @@ import {
   saveEntryCountry,
   loadExitCountry,
   saveExitCountry,
+  loadFleet,
+  saveFleet,
 } from './storage';
 
 const KP: Keypair = { publicKey: 'pub-abc', privateKey: 'priv-xyz' };
 
+const GW: GatewayInfo = {
+  ip: '1.2.3.4',
+  controlUrl: 'http://1.2.3.4:51821',
+  country: 'DE',
+  region: 'EU',
+  city: 'Frankfurt',
+  load: 0.1,
+  capacity: 90,
+  version: '0.1.0',
+  min_client_version: '0.1.0',
+  server_pubkey: 'srv-pub',
+  sign_pubkey: 'sign-pub',
+};
+
 describe('keypair persistence', () => {
   it('returns null before anything is saved', async () => {
     // Reset the shared in-memory store by clearing the selected key too.
@@ -70,3 +85,22 @@ describe('multi-hop entry/exit country', () => {
     await expect(loadExitCountry()).resolves.toBeNull();
   });
 });
+
+describe('fleet cache', () => {
+  it('is null before anything is cached', async () => {
+    await expect(loadFleet()).resolves.toBeNull();
+  });
+
+  it('round-trips a saved snapshot with gateways + latency', async () => {
+    await saveFleet([GW], { [GW.ip]: 42 }, 1_700_000_000_000);
+    const got = await loadFleet();
+    expect(got?.gateways).toEqual([GW]);
+    expect(got?.latencyByIp).toEqual({ [GW.ip]: 42 });
+    expect(got?.savedAt).toBe(1_700_000_000_000);
+  });
+
+  it('treats an empty gateway list as no cache', async () => {
+    await saveFleet([], {}, 1_700_000_000_000);
+    await expect(loadFleet()).resolves.toBeNull();
+  });
+});