feat(clients): node health/quality rating in the location picker

Answers "is this node healthy, fast, and not crowded?" — a shared quality
rating shown per country in both pickers.

- core: gatewayQuality(latencyMs, load) → { tone, label, loadPct, score }.
  Load-weighted (bandwidth on a shared exit matters most), latency as a
  tiebreaker; a near-full node is always "Busy". 6 unit tests.
- mobile picker: each row now shows a coloured quality dot + label
  (Excellent/Good/Fair/Busy) and "<latency> ms · <load>% load". (Search was
  already present.)
- desktop picker: each row shows the quality label + coloured dot + load %.

Verified via a headless render of the desktop picker (all 12 countries with
quality + load). tsc / eslint / prettier / 54 core tests green.

Author: TheTrunk

clients/core-ts/src/index.ts

@@ -15,6 +15,8 @@ export { discoverGateways, directoryVerify } from './discovery.js';
 export { enroll, status } from './enroll.js';
 export { buildWgConfig } from './wgconfig.js';
 export { selectHops, buildMultihopConfig } from './multihop.js';
+export { gatewayQuality } from './quality.js';
+export type { GatewayQuality, QualityTone } from './quality.js';
 export type {
   RouteStyle,
   Hop,

clients/core-ts/src/quality.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { gatewayQuality } from './quality.js';
+
+describe('gatewayQuality', () => {
+  it('rates a fast, empty node Excellent', () => {
+    const q = gatewayQuality(40, 0.1);
+    expect(q.tone).toBe('excellent');
+    expect(q.loadPct).toBe(10);
+    expect(q.score).toBeGreaterThanOrEqual(78);
+  });
+
+  it('rates a near-full node Busy regardless of latency', () => {
+    expect(gatewayQuality(30, 0.9).tone).toBe('busy');
+    expect(gatewayQuality(500, 0.95).tone).toBe('busy');
+  });
+
+  it('clamps load to a 0..100 percentage', () => {
+    expect(gatewayQuality(100, 1.5).loadPct).toBe(100);
+    expect(gatewayQuality(100, -0.2).loadPct).toBe(0);
+  });
+
+  it('scores an unmeasured latency neutrally rather than failing', () => {
+    const q = gatewayQuality(null, 0.3);
+    expect(q.score).toBeGreaterThan(0);
+    expect(['excellent', 'good', 'fair']).toContain(q.tone);
+  });
+
+  it('ranks a lighter node above a heavier one at equal latency', () => {
+    expect(gatewayQuality(120, 0.2).score).toBeGreaterThan(gatewayQuality(120, 0.7).score);
+  });
+
+  it('degrades toward Fair as latency climbs', () => {
+    expect(gatewayQuality(600, 0.3).tone).toBe('fair');
+  });
+});

clients/core-ts/src/quality.ts

@@ -0,0 +1,71 @@
+/**
+ * Node quality rating — turns a gateway's live signals (measured round-trip
+ * latency + reported load) into a single human-facing quality so the clients can
+ * show "which node is healthy, fast, and not crowded" at a glance.
+ *
+ * Load is weighted a little more than latency: on a shared exit node the load is
+ * what determines the bandwidth you actually get, while latency mostly affects
+ * responsiveness. A node reporting near-full load is always surfaced as "Busy"
+ * regardless of latency.
+ */
+
+/** Coarse quality bucket, for colour + label. */
+export type QualityTone = 'excellent' | 'good' | 'fair' | 'busy';
+
+/** A gateway's connection quality, derived from latency + load. */
+export interface GatewayQuality {
+  /** Coarse tone for colour + label. */
+  readonly tone: QualityTone;
+  /** Human label, e.g. `"Excellent"`. */
+  readonly label: string;
+  /** Load as a 0..100 percentage (how full the node is). */
+  readonly loadPct: number;
+  /** 0..100 composite score (higher is better); good for ranking ties. */
+  readonly score: number;
+}
+
+const LABELS: Record<QualityTone, string> = {
+  excellent: 'Excellent',
+  good: 'Good',
+  fair: 'Fair',
+  busy: 'Busy',
+};
+
+/**
+ * Rate a gateway from its measured round-trip latency (ms, or `null` if not yet
+ * measured) and its reported `load` (0..1 utilisation from `/v1/info`).
+ *
+ * @param latencyMs - Measured RTT in ms, or `null` when unknown (scored neutral).
+ * @param load - Reported utilisation, 0 (idle) .. 1 (full). Clamped.
+ * @returns A {@link GatewayQuality} with tone, label, load %, and a 0..100 score.
+ */
+export function gatewayQuality(latencyMs: number | null, load: number): GatewayQuality {
+  const l = Math.min(1, Math.max(0, load));
+  const loadPct = Math.round(l * 100);
+
+  // Sub-scores in 0..1 (1 = best). Latency: <=60ms is ideal, >=400ms is poor.
+  const loadScore = 1 - l;
+  const latScore =
+    latencyMs == null
+      ? 0.5
+      : latencyMs <= 60
+        ? 1
+        : latencyMs >= 400
+          ? 0
+          : 1 - (latencyMs - 60) / 340;
+
+  const score = Math.round((0.6 * loadScore + 0.4 * latScore) * 100);
+
+  let tone: QualityTone;
+  if (l >= 0.85) {
+    tone = 'busy';
+  } else if (score >= 78) {
+    tone = 'excellent';
+  } else if (score >= 55) {
+    tone = 'good';
+  } else {
+    tone = 'fair';
+  }
+
+  return { tone, label: LABELS[tone], loadPct, score };
+}

clients/desktop/src/components/CountryPicker.tsx

@@ -1,5 +1,7 @@
 import { useMemo, useState } from 'react';
 import type { JSX } from 'react';
+import { gatewayQuality } from '@cumulusvpn/core';
+import type { QualityTone } from '@cumulusvpn/core';
 import type { CountryOption } from '../lib/session.js';
 
 interface Props {
@@ -9,16 +11,13 @@ interface Props {
   readonly onClose: () => void;
 }
 
-/** Map a 0..1 load into a latency-dot severity class. */
-function pingClass(load: number): string {
-  if (load < 0.4) {
-    return 'ping';
-  }
-  if (load < 0.75) {
-    return 'ping mid';
-  }
-  return 'ping far';
-}
+/** Quality-tone → CSS colour var (green best … red busiest). */
+const TONE_VAR: Record<QualityTone, string> = {
+  excellent: 'var(--green)',
+  good: 'var(--cyan)',
+  fair: 'var(--amber)',
+  busy: 'var(--red)',
+};
 
 /** Full-window country sheet with search — map-flavoured picker per the mockup. */
 export function CountryPicker({ countries, selectedCode, onPick, onClose }: Props): JSX.Element {
@@ -44,21 +43,27 @@ export function CountryPicker({ countries, selectedCode, onPick, onClose }: Prop
         autoFocus
       />
       <div className="clist">
-        {filtered.map((c) => (
-          <button
-            key={c.code}
-            className={`crow ${c.code === selectedCode ? 'sel' : ''}`}
-            onClick={() => {
-              onPick(c.code);
-              onClose();
-            }}
-          >
-            <span className="flag">{c.flag}</span>
-            <span className="cn">{c.name}</span>
-            <span className={pingClass(c.load)} />
-            <span className="lat">{Math.round(c.load * 100)}%</span>
-          </button>
-        ))}
+        {filtered.map((c) => {
+          const q = gatewayQuality(null, c.load);
+          return (
+            <button
+              key={c.code}
+              className={`crow ${c.code === selectedCode ? 'sel' : ''}`}
+              onClick={() => {
+                onPick(c.code);
+                onClose();
+              }}
+            >
+              <span className="flag">{c.flag}</span>
+              <span className="cn">{c.name}</span>
+              <span className="qlabel" style={{ color: TONE_VAR[q.tone] }}>
+                {q.label}
+              </span>
+              <span className="qdot" style={{ background: TONE_VAR[q.tone] }} />
+              <span className="lat">{q.loadPct}%</span>
+            </button>
+          );
+        })}
         {filtered.length === 0 && (
           <div className="lat" style={{ padding: '12px 4px' }}>
             No matching locations.

clients/desktop/src/styles.css

@@ -613,6 +613,16 @@ button {
   font-size: 11px;
   color: var(--ink-3);
 }
+.crow .qlabel {
+  font-size: 12px;
+  font-weight: 600;
+}
+.crow .qdot {
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  flex-shrink: 0;
+}
 .sheet .close {
   margin-top: 12px;
   text-align: center;

clients/mobile/src/screens/CountryPickerScreen.tsx

@@ -5,11 +5,19 @@
  */
 import { useMemo, useState } from 'react';
 import { FlatList, Pressable, StyleSheet, Text, TextInput, View } from 'react-native';
+import { gatewayQuality } from '@cumulusvpn/core';
+import type { QualityTone } from '@cumulusvpn/core';
 import type { Country } from '../lib/gateways';
-import { latencyBand } from '../lib/gateways';
-import { LatencyDot } from '../components/LatencyDot';
 import { color, font, radius, space } from '../theme/tokens';
 
+/** Quality-tone → accent colour (green best … red busiest). */
+const TONE_COLOR: Record<QualityTone, string> = {
+  excellent: color.green,
+  good: color.cyan,
+  fair: color.amber,
+  busy: color.red,
+};
+
 interface Props {
   readonly countries: readonly Country[];
   readonly selectedCode: string | null;
@@ -61,30 +69,36 @@ export function CountryPickerScreen({
         ListEmptyComponent={
           <Text style={styles.empty}>No gateways reachable — pull to refresh.</Text>
         }
-        renderItem={({ item }) => (
-          <Pressable
-            style={[styles.row, item.code === selectedCode && styles.rowSelected]}
-            onPress={() => {
-              onSelect(item.code);
-              onClose();
-            }}
-            accessibilityRole="button"
-          >
-            <Text style={styles.flag}>{item.flag}</Text>
-            <View style={styles.meta}>
-              <Text style={styles.name}>{item.name}</Text>
-              <Text style={styles.sub}>
-                {item.nodeCount} {item.nodeCount === 1 ? 'node' : 'nodes'} · {item.city}
-              </Text>
-            </View>
-            <View style={styles.ping}>
-              <LatencyDot band={latencyBand(item.latencyMs)} />
-              <Text style={styles.pingText}>
-                {item.latencyMs === null ? '—' : `${item.latencyMs} ms`}
-              </Text>
-            </View>
-          </Pressable>
-        )}
+        renderItem={({ item }) => {
+          const q = gatewayQuality(item.latencyMs, item.best.load);
+          return (
+            <Pressable
+              style={[styles.row, item.code === selectedCode && styles.rowSelected]}
+              onPress={() => {
+                onSelect(item.code);
+                onClose();
+              }}
+              accessibilityRole="button"
+            >
+              <Text style={styles.flag}>{item.flag}</Text>
+              <View style={styles.meta}>
+                <Text style={styles.name}>{item.name}</Text>
+                <Text style={styles.sub}>
+                  {item.nodeCount} {item.nodeCount === 1 ? 'node' : 'nodes'} · {item.city}
+                </Text>
+              </View>
+              <View style={styles.qual}>
+                <View style={styles.qualTop}>
+                  <View style={[styles.qualDot, { backgroundColor: TONE_COLOR[q.tone] }]} />
+                  <Text style={[styles.qualLabel, { color: TONE_COLOR[q.tone] }]}>{q.label}</Text>
+                </View>
+                <Text style={styles.qualSub}>
+                  {item.latencyMs === null ? '— ms' : `${item.latencyMs} ms`} · {q.loadPct}% load
+                </Text>
+              </View>
+            </Pressable>
+          );
+        }}
       />
     </View>
   );
@@ -129,7 +143,10 @@ const styles = StyleSheet.create({
   meta: { flex: 1 },
   name: { color: color.ink, fontSize: 15, fontWeight: '600' },
   sub: { color: color.inkDim, fontSize: 12, marginTop: 2 },
-  ping: { flexDirection: 'row', alignItems: 'center' },
-  pingText: { fontFamily: font.mono, fontSize: 12, color: color.inkMuted },
+  qual: { alignItems: 'flex-end' },
+  qualTop: { flexDirection: 'row', alignItems: 'center', gap: 5 },
+  qualDot: { width: 7, height: 7, borderRadius: 4 },
+  qualLabel: { fontSize: 12.5, fontWeight: '600' },
+  qualSub: { fontFamily: font.mono, fontSize: 10.5, color: color.inkFaint, marginTop: 2 },
   empty: { color: color.inkDim, textAlign: 'center', marginTop: 40, fontSize: 14 },
 });