feat(clients): favorite / pinned locations

Pin the countries you use most with a star; favorites sort to the top of the
picker. Matters once 12+ countries are deployed.

- mobile: a star per picker row (persisted favorites), favorites-first ordering.
- desktop: same, with a star in each row (stopPropagation so it doesn't select).
- Persisted in storage / localStorage; surfaced through useVpn / useConnection.

tsc / eslint / prettier / tests green on both clients.

Author: TheTrunk

clients/desktop/src/App.tsx

@@ -152,6 +152,8 @@ export function App(): JSX.Element {
           onPick={picker === 'exit' ? conn.selectExit : conn.select}
           onClose={() => setPicker(null)}
           onRefresh={conn.refresh}
+          favorites={conn.favorites}
+          onToggleFavorite={conn.toggleFavorite}
         />
       )}
 

clients/desktop/src/components/CountryPicker.tsx

@@ -11,6 +11,10 @@ interface Props {
   readonly onClose: () => void;
   /** Re-discover the fleet (re-test node load/quality). */
   readonly onRefresh: () => Promise<void>;
+  /** Favorited country codes (surfaced first). */
+  readonly favorites: readonly string[];
+  /** Pin/unpin a country. */
+  readonly onToggleFavorite: (code: string) => void;
 }
 
 /** Quality-tone → CSS colour var (green best … red busiest). */
@@ -28,6 +32,8 @@ export function CountryPicker({
   onPick,
   onClose,
   onRefresh,
+  favorites,
+  onToggleFavorite,
 }: Props): JSX.Element {
   const [q, setQ] = useState('');
   const [refreshing, setRefreshing] = useState(false);
@@ -41,13 +47,16 @@ export function CountryPicker({
   };
   const filtered = useMemo(() => {
     const needle = q.trim().toLowerCase();
-    if (!needle) {
-      return countries;
-    }
-    return countries.filter(
-      (c) => c.name.toLowerCase().includes(needle) || c.code.toLowerCase().includes(needle),
-    );
-  }, [countries, q]);
+    const matched = needle
+      ? countries.filter(
+          (c) => c.name.toLowerCase().includes(needle) || c.code.toLowerCase().includes(needle),
+        )
+      : countries;
+    // Favorites first, then the rest in their existing order.
+    const fav = matched.filter((c) => favorites.includes(c.code));
+    const rest = matched.filter((c) => !favorites.includes(c.code));
+    return [...fav, ...rest];
+  }, [countries, q, favorites]);
 
   return (
     <div className="sheet">
@@ -76,6 +85,17 @@ export function CountryPicker({
                 onClose();
               }}
             >
+              <span
+                className={`star ${favorites.includes(c.code) ? 'on' : ''}`}
+                role="button"
+                aria-label={favorites.includes(c.code) ? 'Unpin' : 'Pin'}
+                onClick={(e) => {
+                  e.stopPropagation();
+                  onToggleFavorite(c.code);
+                }}
+              >
+                {favorites.includes(c.code) ? '★' : '☆'}
+              </span>
               <span className="flag">{c.flag}</span>
               <span className="cn">{c.name}</span>
               <span className="qlabel" style={{ color: TONE_VAR[q.tone] }}>

clients/desktop/src/hooks/useConnection.ts

@@ -72,6 +72,10 @@ export interface ConnectionModel {
   readonly connectedSince: number | null;
   /** Re-discover the fleet (re-test node load/quality); keeps the selection. */
   readonly refresh: () => Promise<void>;
+  /** Favorited (pinned) country codes, surfaced first in the picker. */
+  readonly favorites: readonly string[];
+  /** Pin/unpin a country. */
+  readonly toggleFavorite: (code: string) => void;
 }
 
 const DOWN: TunnelStatus = {
@@ -121,6 +125,9 @@ export function useConnection(): ConnectionModel {
   // whether we ever reached 'connected' this session (for auto-reconnect).
   const [connectedSince, setConnectedSince] = useState<number | null>(null);
   const wasConnectedRef = useRef(false);
+  const [favorites, setFavorites] = useState<readonly string[]>(() =>
+    (localStorage.getItem('cvpn.favorites') ?? '').split(',').filter(Boolean),
+  );
 
   // Bootstrap: discover the fleet and restore the last-selected country.
   useEffect(() => {
@@ -196,6 +203,14 @@ export function useConnection(): ConnectionModel {
     localStorage.setItem('cvpn.autoConnect', on ? '1' : '0');
   }, []);
 
+  const toggleFavorite = useCallback((code: string) => {
+    setFavorites((prev) => {
+      const next = prev.includes(code) ? prev.filter((c) => c !== code) : [...prev, code];
+      localStorage.setItem('cvpn.favorites', next.join(','));
+      return next;
+    });
+  }, []);
+
   /** Poll chain entitlement from the metering gateway; never drops the tunnel. */
   const refreshEntitlement = useCallback(
     async (gatewayIp: string, signPubKey: string) => {
@@ -340,5 +355,7 @@ export function useConnection(): ConnectionModel {
     setAutoConnect,
     connectedSince,
     refresh,
+    favorites,
+    toggleFavorite,
   };
 }

clients/desktop/src/styles.css

@@ -718,6 +718,15 @@ button {
   font-size: 11px;
   color: var(--ink-3);
 }
+.crow .star {
+  font-size: 15px;
+  color: var(--ink-3);
+  cursor: pointer;
+  flex-shrink: 0;
+}
+.crow .star.on {
+  color: var(--amber);
+}
 .crow .qlabel {
   font-size: 12px;
   font-weight: 600;

clients/mobile/App.tsx

@@ -54,6 +54,8 @@ function App(): React.JSX.Element {
               onSelect={(code) => void vpn.selectCountry(code)}
               onClose={() => setRoute('connect')}
               onRefresh={() => vpn.refresh()}
+              favorites={vpn.favorites}
+              onToggleFavorite={(code) => void vpn.toggleFavorite(code)}
             />
           ) : route === 'entry' ? (
             <CountryPickerScreen
@@ -62,6 +64,8 @@ function App(): React.JSX.Element {
               onSelect={(code) => void vpn.selectEntryCountry(code)}
               onClose={() => setRoute('connect')}
               onRefresh={() => vpn.refresh()}
+              favorites={vpn.favorites}
+              onToggleFavorite={(code) => void vpn.toggleFavorite(code)}
             />
           ) : route === 'exit' ? (
             <CountryPickerScreen
@@ -70,6 +74,8 @@ function App(): React.JSX.Element {
               onSelect={(code) => void vpn.selectExitCountry(code)}
               onClose={() => setRoute('connect')}
               onRefresh={() => vpn.refresh()}
+              favorites={vpn.favorites}
+              onToggleFavorite={(code) => void vpn.toggleFavorite(code)}
             />
           ) : route === 'upgrade' ? (
             <UpgradeScreen

clients/mobile/src/screens/CountryPickerScreen.tsx

@@ -33,6 +33,10 @@ interface Props {
   readonly onClose: () => void;
   /** Re-run discovery + an active latency re-test of the fleet. */
   readonly onRefresh: () => Promise<void>;
+  /** Favorited country codes (surfaced first). */
+  readonly favorites: readonly string[];
+  /** Pin/unpin a country. */
+  readonly onToggleFavorite: (code: string) => void;
 }
 
 export function CountryPickerScreen({
@@ -41,6 +45,8 @@ export function CountryPickerScreen({
   onSelect,
   onClose,
   onRefresh,
+  favorites,
+  onToggleFavorite,
 }: Props): React.JSX.Element {
   const [query, setQuery] = useState('');
   const [refreshing, setRefreshing] = useState(false);
@@ -56,13 +62,16 @@ export function CountryPickerScreen({
 
   const filtered = useMemo(() => {
     const q = query.trim().toLowerCase();
-    if (!q) {
-      return countries;
-    }
-    return countries.filter(
-      (c) => c.name.toLowerCase().includes(q) || c.city.toLowerCase().includes(q),
-    );
-  }, [countries, query]);
+    const matched = q
+      ? countries.filter(
+          (c) => c.name.toLowerCase().includes(q) || c.city.toLowerCase().includes(q),
+        )
+      : countries;
+    // Favorites first, otherwise keep the incoming (latency-sorted) order.
+    const fav = matched.filter((c) => favorites.includes(c.code));
+    const rest = matched.filter((c) => !favorites.includes(c.code));
+    return [...fav, ...rest];
+  }, [countries, query, favorites]);
 
   return (
     <View style={styles.root}>
@@ -105,6 +114,7 @@ export function CountryPickerScreen({
         }
         renderItem={({ item }) => {
           const q = gatewayQuality(item.latencyMs, item.best.load);
+          const pinned = favorites.includes(item.code);
           return (
             <Pressable
               style={[styles.row, item.code === selectedCode && styles.rowSelected]}
@@ -114,6 +124,14 @@ export function CountryPickerScreen({
               }}
               accessibilityRole="button"
             >
+              <Pressable
+                onPress={() => onToggleFavorite(item.code)}
+                accessibilityRole="button"
+                accessibilityLabel={pinned ? 'Unpin' : 'Pin'}
+                hitSlop={8}
+              >
+                <Text style={[styles.star, pinned && styles.starOn]}>{pinned ? '★' : '☆'}</Text>
+              </Pressable>
               <Text style={styles.flag}>{item.flag}</Text>
               <View style={styles.meta}>
                 <Text style={styles.name}>{item.name}</Text>
@@ -175,6 +193,8 @@ const styles = StyleSheet.create({
     borderColor: 'rgba(52,228,218,0.4)',
     borderWidth: 1,
   },
+  star: { fontSize: 17, color: color.inkFaint },
+  starOn: { color: color.amber },
   flag: { fontSize: 24 },
   meta: { flex: 1 },
   name: { color: color.ink, fontSize: 15, fontWeight: '600' },

clients/mobile/src/state/storage.ts

@@ -77,6 +77,17 @@ export async function saveAutoConnect(enabled: boolean): Promise<void> {
   mem.set('autoConnect', enabled ? '1' : '0');
 }
 
+/** Load the set of favorited (pinned) country codes. */
+export async function loadFavorites(): Promise<string[]> {
+  const raw = mem.get('favorites');
+  return raw ? raw.split(',').filter(Boolean) : [];
+}
+
+/** Persist the favorited country codes. */
+export async function saveFavorites(codes: readonly string[]): Promise<void> {
+  mem.set('favorites', codes.join(','));
+}
+
 /** Load the multi-hop entry country code, or null for auto-pick. */
 export async function loadEntryCountry(): Promise<string | null> {
   return mem.get('entryCountry') ?? null;

clients/mobile/src/state/useVpn.ts

@@ -33,13 +33,15 @@ import {
   loadAutoConnect,
   loadEntryCountry,
   loadExitCountry,
+  loadFavorites,
   loadKeypair,
   loadKillSwitch,
   loadRouteStyle,
   loadSelectedCountry,
   saveAutoConnect,
   saveEntryCountry,
   saveExitCountry,
+  saveFavorites,
   saveKeypair,
   saveKillSwitch,
   saveRouteStyle,
@@ -81,6 +83,8 @@ export interface VpnModel {
   readonly autoConnect: boolean;
   /** Unix-ms when the active session connected, or null when not connected. */
   readonly connectedSince: number | null;
+  /** Favorited (pinned) country codes, surfaced first in the picker. */
+  readonly favorites: readonly string[];
 }
 
 /** Chain-payment identity derived from the device key + last enrollment. */
@@ -111,6 +115,8 @@ export interface VpnActions {
   setKillSwitch(enabled: boolean): Promise<void>;
   /** Toggle auto-connect on launch (persisted). */
   setAutoConnect(enabled: boolean): Promise<void>;
+  /** Pin/unpin a country as a favorite (persisted). */
+  toggleFavorite(code: string): Promise<void>;
   /** Open the OS VPN settings (Android lockdown hand-off; no-op on iOS). */
   openVpnSettings(): Promise<void>;
 }
@@ -132,6 +138,7 @@ export function useVpn(): VpnModel & VpnActions {
   const [exitCode, setExitCode] = useState<string | null>(null);
   const [killSwitch, setKillSwitchState] = useState(false);
   const [autoConnect, setAutoConnectState] = useState(false);
+  const [favorites, setFavorites] = useState<readonly string[]>([]);
   const autoConnectedRef = useRef(false);
   // Unix-ms when the current session connected, for the session timer.
   const [connectedSince, setConnectedSince] = useState<number | null>(null);
@@ -210,6 +217,7 @@ export function useVpn(): VpnModel & VpnActions {
         setExitCode(await loadExitCountry());
         setKillSwitchState(await loadKillSwitch());
         setAutoConnectState(await loadAutoConnect());
+        setFavorites(await loadFavorites());
         await refresh();
       } catch (e) {
         if (alive) {
@@ -423,6 +431,15 @@ export function useVpn(): VpnModel & VpnActions {
     await saveAutoConnect(enabled);
   }, []);
 
+  const toggleFavorite = useCallback(async (code: string): Promise<void> => {
+    let next: string[] = [];
+    setFavorites((prev) => {
+      next = prev.includes(code) ? prev.filter((c) => c !== code) : [...prev, code];
+      return next;
+    });
+    await saveFavorites(next);
+  }, []);
+
   const openVpnSettings = useCallback(async (): Promise<void> => {
     await CumulusTunnel.openVpnSettings();
   }, []);
@@ -444,6 +461,7 @@ export function useVpn(): VpnModel & VpnActions {
     killSwitch,
     autoConnect,
     connectedSince,
+    favorites,
     connect,
     disconnect,
     selectCountry,
@@ -453,6 +471,7 @@ export function useVpn(): VpnModel & VpnActions {
     selectExitCountry,
     setKillSwitch,
     setAutoConnect,
+    toggleFavorite,
     openVpnSettings,
   };
 }