remo-cli 2.2.0rc12__tar.gz → 2.2.0rc13__tar.gz

{remo_cli-2.2.0rc12 → remo_cli-2.2.0rc13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remo-cli
-Version: 2.2.0rc12
+Version: 2.2.0rc13
 Summary: Remote development environment CLI
 License-Expression: MIT
 License-File: LICENSE

{remo_cli-2.2.0rc12 → remo_cli-2.2.0rc13}/docs/web-session-interface.md

@@ -137,13 +137,16 @@ they can be stale until something else fetches. Git glyphs only appear on instan
 `remo-host` new enough to report git status; see [Upgrade compatibility](#upgrade-compatibility).
 
 **Settings** (⚙, top bar; stored in this browser only, FR-034): accent color, terminal font, font
-size, program ligatures, grid display mode (actual-size vs scale-to-fit), and a **Nerd Font uploader**.
-Because a browser can't read fonts installed on the instance, uploading a patched Nerd Font once
-registers it via the `FontFace` API (persisted in IndexedDB) and offers it as a terminal font — that's
-how Powerline/Git/devicon glyphs in a prompt or Zellij status bar render. Font changes apply live to
-every open terminal. The top bar also shows a health indicator (from `GET /api/v1/ready`) and an
-offline overlay if the service becomes unreachable (terminals reattach automatically when it returns).
-Press **?** for the keyboard-shortcut reference.
+size, program ligatures, grid display mode (actual-size vs scale-to-fit), **focus dwell** (how long the
+pointer rests before focus-follows-mouse fires), terminal engine, a **Nerd Font uploader**, and **Pair
+CLI to sync** (mint a re-sync pairing code). Because a browser can't read fonts installed on the
+instance, uploading a patched Nerd Font once registers it via the `FontFace` API (persisted in
+IndexedDB) and offers it as a terminal font — that's how Powerline/Git/devicon glyphs in a prompt or
+Zellij status bar render. Font changes apply live to every open terminal. The top bar shows the
+**WebSocket round-trip latency** (median across open terminals, with the dot green/yellow/red by
+latency), falling back to the service health status when no terminal is connected; an offline overlay
+appears if the service becomes unreachable (terminals reattach automatically when it returns). Press
+**?** for the keyboard-shortcut reference.
 
 All fonts are self-hosted (bundled `@fontsource` assets), never fetched from a CDN, so the restrictive
 same-origin CSP (`default-src 'self'`) is satisfied.

{remo_cli-2.2.0rc12 → remo_cli-2.2.0rc13}/frontend/src/components/AppShell.tsx

@@ -8,6 +8,7 @@ import type { SessionTarget } from "../api/client";
 import { exitBrowserFullscreen } from "../lib/fullscreen";
 import { useDiscovery } from "../state/discovery";
 import { useHealth } from "../state/health";
+import { useLatency } from "../state/latency";
 import { settingsActions, useSettings } from "../state/settings";
 import { useConsoleKeyboard } from "../state/useConsoleKeyboard";
 import { useWorkspace } from "../state/workspace";
@@ -25,6 +26,7 @@ const NARROW_BREAKPOINT = 820;
 export function AppShell(): JSX.Element {
   const discovery = useDiscovery();
   const health = useHealth();
+  const latency = useLatency();
   const settings = useSettings();
   const workspace = useWorkspace();
 
@@ -192,6 +194,7 @@ export function AppShell(): JSX.Element {
         openCount={workspace.attached.length}
         health={health.status}
         healthDetail={health.detail}
+        latencyMs={latency.rttMs}
         refreshing={discovery.isRefreshing}
         onRefresh={() => void discovery.refresh()}
         onSettings={() => setSettingsOpen(true)}

remo_cli-2.2.0rc13/frontend/src/components/PairToSync.css

@@ -0,0 +1,71 @@
+/* "Pair CLI to sync" — rendered inline inside a Settings section (no longer a
+ * top-bar popover), so the minted-code panel expands in place below the button. */
+.pairsync {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 10px;
+}
+
+.pairsync-btn {
+  padding: 7px 12px;
+  border-radius: 7px;
+  border: 1px solid var(--border-strong, #444);
+  background: var(--bg-btn, #24262c);
+  color: var(--text-1, #e6e8ec);
+  font-size: 13px;
+  font-family: inherit;
+  cursor: pointer;
+}
+.pairsync-btn:hover {
+  background: var(--bg-btn-hover, #2c2f36);
+}
+.pairsync-btn:disabled {
+  opacity: 0.6;
+  cursor: default;
+}
+
+.pairsync-popover {
+  width: 100%;
+  max-width: 380px;
+  padding: 12px;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  background: var(--bg-header, #1b1d22);
+  border: 1px solid var(--border-soft, #333);
+  border-radius: 8px;
+}
+
+.pairsync-body {
+  margin: 0;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--text-dim, #b8bcc4);
+}
+
+.pairsync-body code {
+  font-family: var(--font-mono, monospace);
+  color: var(--text, #e6e8ec);
+}
+
+.pairsync-error {
+  margin: 0;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--danger, #e06c6c);
+}
+
+.pairsync-close {
+  align-self: flex-end;
+  background: none;
+  border: none;
+  color: var(--text-dim, #b8bcc4);
+  font-size: 12px;
+  cursor: pointer;
+  padding: 2px 4px;
+}
+
+.pairsync-close:hover {
+  color: var(--text, #e6e8ec);
+}

{remo_cli-2.2.0rc12 → remo_cli-2.2.0rc13}/frontend/src/components/PairToSync.tsx

@@ -1,10 +1,11 @@
-// Dashboard "Pair CLI to sync" affordance (012-web-adopt-pairing, US4 / FR-017).
+// "Pair CLI to sync" affordance (012-web-adopt-pairing, US4 / FR-017), shown in
+// Settings once the service has been adopted.
 //
 // Mints a fresh pairing code (origin="resync") through the same lifecycle and
 // operator-auth gate as the awaiting-adoption page, and offers a Copy button.
 // The code value is held only in a ref and is NEVER rendered into the DOM
-// (FR-015/FR-016); opening the popover mints, closing it ends the session
-// best-effort (the idle TTL is the backstop).
+// (FR-015/FR-016); opening mints, closing (or unmounting, e.g. leaving Settings)
+// ends the session best-effort (the idle TTL is the backstop).
 
 import { useCallback, useEffect, useRef, useState } from "react";
 import { ApiError, endPairing, mintPairingCode } from "../api/client";
@@ -19,6 +20,9 @@ export function PairToSync(): JSX.Element {
   const [copyState, setCopyState] = useState<"idle" | "copied" | "failed">("idle");
   const codeRef = useRef<string | null>(null);
   const copyResetHandle = useRef<ReturnType<typeof setTimeout>>();
+  // Track "open" for the unmount cleanup below without stale-closure issues.
+  const openRef = useRef(false);
+  openRef.current = open;
 
   const close = useCallback(() => {
     setOpen(false);
@@ -46,6 +50,12 @@ export function PairToSync(): JSX.Element {
   }, []);
 
   useEffect(() => () => clearTimeout(copyResetHandle.current), []);
+  // End the pairing session if Settings is closed with a code still live.
+  useEffect(() => () => {
+    if (openRef.current) {
+      endPairing();
+    }
+  }, []);
 
   const onCopy = useCallback(() => {
     const code = codeRef.current;
@@ -64,12 +74,12 @@ export function PairToSync(): JSX.Element {
     <div className="pairsync">
       <button
         type="button"
-        className="topbar-btn"
+        className="pairsync-btn"
         onClick={open ? close : openAndMint}
         data-testid="pair-to-sync"
         title="Mint a pairing code to run `remo web push` from your workstation"
       >
-        Pair CLI to sync
+        {open ? "Cancel" : "Mint pairing code"}
       </button>
 
       {open && (
@@ -88,7 +98,7 @@ export function PairToSync(): JSX.Element {
           ) : (
             <button
               type="button"
-              className="topbar-btn"
+              className="pairsync-btn"
               onClick={onCopy}
               disabled={mintState !== "ready"}
               data-testid="pairsync-copy"

{remo_cli-2.2.0rc12 → remo_cli-2.2.0rc13}/frontend/src/components/SettingsPage.tsx

@@ -7,13 +7,16 @@ import { listUploadedFonts, registerUploadedFont } from "../state/fonts";
 import {
   ACCENT_OPTIONS,
   FONT_OPTIONS,
+  MAX_FOCUS_DWELL_MS,
   MAX_TERM_SIZE,
+  MIN_FOCUS_DWELL_MS,
   MIN_TERM_SIZE,
   RENDERER_OPTIONS,
   settingsActions,
   useSettings,
   type FontOption,
 } from "../state/settings";
+import { PairToSync } from "./PairToSync";
 import "./SettingsPage.css";
 
 interface SettingsPageProps {
@@ -156,6 +159,30 @@ export function SettingsPage({ onClose }: SettingsPageProps): JSX.Element {
             </div>
           </section>
 
+          {/* Focus-follows-mouse dwell */}
+          <section>
+            <div className="settings-row2-head">
+              <span className="settings-heading">Focus dwell</span>
+              <span className="settings-value">
+                {settings.focusDwellMs === 0 ? "instant" : `${settings.focusDwellMs} ms`}
+              </span>
+            </div>
+            <p className="settings-sub">
+              In a grid, how long the pointer must rest on a tile before it takes focus
+              (focus-follows-mouse). Lower is snappier; higher is calmer. 0 = instant.
+            </p>
+            <input
+              type="range"
+              min={MIN_FOCUS_DWELL_MS}
+              max={MAX_FOCUS_DWELL_MS}
+              step={20}
+              value={settings.focusDwellMs}
+              onChange={(e) => settingsActions.setFocusDwell(Number(e.target.value))}
+              className="settings-range"
+              data-testid="focus-dwell-range"
+            />
+          </section>
+
           {/* Size + ligatures */}
           <section className="settings-row2">
             <div className="settings-col">
@@ -244,6 +271,17 @@ export function SettingsPage({ onClose }: SettingsPageProps): JSX.Element {
               })}
             </div>
           </section>
+
+          {/* Pair CLI to sync (post-adoption re-sync) */}
+          <section>
+            <div className="settings-heading">Pair CLI to sync</div>
+            <p className="settings-sub">
+              Mint a one-time code to run <code>remo web push &lt;url&gt;</code> from your
+              workstation and push registry / host-key updates to this service. The code is copied
+              to your clipboard — it is never shown.
+            </p>
+            <PairToSync />
+          </section>
         </div>
       </div>
     </div>

{remo_cli-2.2.0rc12 → remo_cli-2.2.0rc13}/frontend/src/components/TerminalCard.tsx

@@ -19,6 +19,7 @@ import {
   type SettingsState,
   type TerminalFontOptions,
 } from "../state/settings";
+import { removeLatency, reportLatency } from "../state/latency";
 import type { RendererAdapter } from "../terminal/RendererAdapter";
 import { createDefaultRenderer } from "../terminal/defaultRenderer";
 import { TerminalConnection, type TerminalConnectionState } from "../terminal/TerminalConnection";
@@ -28,9 +29,6 @@ const DEFAULT_COLS = 80;
 const DEFAULT_ROWS = 24;
 /** How much to shrink the terminal font in a grid tile when "scale to fit". */
 const GRID_FIT_SCALE = 0.8;
-/** Focus-follows-mouse dwell: the pointer must REST on a tile this long before
- * it takes focus, so passing through tiles (or a small drift) doesn't steal it. */
-const HOVER_FOCUS_DELAY_MS = 220;
 
 const STATE_LABELS: Record<TerminalConnectionState, string> = {
   connecting: "Connecting…",
@@ -124,6 +122,9 @@ export function TerminalCard({
   const lastSentDimsRef = useRef<{ cols: number; rows: number } | null>(null);
   // Pending focus-follows-mouse dwell timer (cleared if the pointer leaves first).
   const hoverTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // Latest focus-dwell setting, read inside the timer without re-creating the handler.
+  const dwellMsRef = useRef(settings.focusDwellMs);
+  dwellMsRef.current = settings.focusDwellMs;
 
   const [connectionState, setConnectionState] = useState<TerminalConnectionState>("connecting");
   const [needsManualReconnect, setNeedsManualReconnect] = useState(false);
@@ -244,7 +245,12 @@ export function TerminalCard({
       onStateChange: (state) => {
         setConnectionState(state);
         setNeedsManualReconnect(connectionRef.current?.needsManualReconnect ?? false);
+        // Only a connected terminal contributes to the header latency median.
+        if (state !== "ready") {
+          removeLatency(target.id);
+        }
       },
+      onLatency: (rttMs) => reportLatency(target.id, rttMs),
     });
     connectionRef.current = connection;
 
@@ -272,6 +278,7 @@ export function TerminalCard({
         fitRafRef.current = null;
       }
       lastSentDimsRef.current = null;
+      removeLatency(target.id);
       unsubscribeInput();
       unsubscribeSelection();
       resizeObserver.disconnect();
@@ -343,7 +350,7 @@ export function TerminalCard({
     hoverTimerRef.current = setTimeout(() => {
       hoverTimerRef.current = null;
       onHoverFocus();
-    }, HOVER_FOCUS_DELAY_MS);
+    }, dwellMsRef.current);
   }, [onHoverFocus, clearHoverTimer]);
 
   // Cancel a pending dwell when the pointer leaves or the card unmounts.

{remo_cli-2.2.0rc12 → remo_cli-2.2.0rc13}/frontend/src/components/TopBar.tsx

@@ -2,7 +2,6 @@
 // health indicator, refresh, settings, and shortcuts.
 
 import type { HealthStatus } from "../state/health";
-import { PairToSync } from "./PairToSync";
 import "./TopBar.css";
 
 // "unconfigured" is included for Record exhaustiveness, but in practice the
@@ -32,11 +31,24 @@ interface TopBarProps {
   health: HealthStatus;
   healthDetail: string | null;
   refreshing: boolean;
+  /** Median WS round-trip latency (ms) across open terminals, or null if none. */
+  latencyMs: number | null;
   onRefresh: () => void;
   onSettings: () => void;
   onShortcuts: () => void;
 }
 
+/** Latency → dot color: good (green) / so-so (yellow) / poor (red). */
+function latencyColor(ms: number): string {
+  if (ms < 100) {
+    return "var(--ok)";
+  }
+  if (ms < 300) {
+    return "var(--warn)";
+  }
+  return "var(--danger)";
+}
+
 export function TopBar({
   showRailToggle,
   railCollapsed,
@@ -45,10 +57,19 @@ export function TopBar({
   health,
   healthDetail,
   refreshing,
+  latencyMs,
   onRefresh,
   onSettings,
   onShortcuts,
 }: TopBarProps): JSX.Element {
+  // Prefer live WS latency (the real data-path measure); fall back to the
+  // health status when no terminal is connected to measure.
+  const showLatency = latencyMs != null;
+  const dotColor = showLatency ? latencyColor(latencyMs) : HEALTH_COLOR[health];
+  const statusLabel = showLatency ? `${Math.round(latencyMs)} ms` : HEALTH_LABEL[health];
+  const statusTitle = showLatency
+    ? "WebSocket round-trip latency (median across open terminals)"
+    : (healthDetail ?? HEALTH_LABEL[health]);
   return (
     <header className="topbar">
       {showRailToggle && (
@@ -82,17 +103,15 @@ export function TopBar({
         {openCount} open
       </span>
 
-      <span className="topbar-health" title={healthDetail ?? HEALTH_LABEL[health]}>
-        <span className="topbar-health-dot" style={{ background: HEALTH_COLOR[health] }} />
-        <span>{HEALTH_LABEL[health]}</span>
+      <span className="topbar-health" title={statusTitle} data-testid="topbar-status">
+        <span className="topbar-health-dot" style={{ background: dotColor }} />
+        <span>{statusLabel}</span>
       </span>
 
       <button type="button" className="topbar-btn" onClick={onRefresh} data-testid="refresh-button">
         <span className={refreshing ? "rail-spin" : undefined}>⟳</span> Refresh
       </button>
 
-      <PairToSync />
-
       <button
         type="button"
         className="topbar-icon-btn"

remo_cli-2.2.0rc13/frontend/src/state/latency.test.ts

@@ -0,0 +1,35 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { getLatencySnapshot, removeLatency, reportLatency } from "./latency";
+
+describe("latency store", () => {
+  beforeEach(() => {
+    // Clear any samples left by a prior test (module singleton).
+    for (const id of ["a", "b", "c", "d"]) {
+      removeLatency(id);
+    }
+  });
+
+  it("reports the median across connected terminals", () => {
+    reportLatency("a", 40);
+    reportLatency("b", 80);
+    reportLatency("c", 120);
+    const snap = getLatencySnapshot();
+    expect(snap.rttMs).toBe(80);
+    expect(snap.count).toBe(3);
+  });
+
+  it("updates a terminal's latest sample in place", () => {
+    reportLatency("a", 40);
+    reportLatency("a", 300);
+    expect(getLatencySnapshot()).toEqual({ rttMs: 300, count: 1 });
+  });
+
+  it("drops a terminal's sample on removal; null when none remain", () => {
+    reportLatency("a", 40);
+    reportLatency("b", 80);
+    removeLatency("a");
+    expect(getLatencySnapshot()).toEqual({ rttMs: 80, count: 1 });
+    removeLatency("b");
+    expect(getLatencySnapshot()).toEqual({ rttMs: null, count: 0 });
+  });
+});

remo_cli-2.2.0rc13/frontend/src/state/latency.ts

@@ -0,0 +1,69 @@
+// WebSocket latency store (header indicator).
+//
+// Each connected terminal measures its WS round-trip (ping→pong in
+// TerminalConnection) and reports it here keyed by session-target id. The header
+// shows the MEDIAN across open terminals — since every terminal's WebSocket
+// terminates at the same remo-web service, they all measure the same
+// browser↔service path, so the median is a robust single number. Terminals
+// remove their sample when they disconnect/unmount, so the store only ever holds
+// currently-healthy connections (no freshness timer needed).
+//
+// The cached-snapshot pattern keeps `getSnapshot()` referentially stable between
+// mutations (returning a fresh object each call would loop useSyncExternalStore).
+
+import { useSyncExternalStore } from "react";
+
+const samples = new Map<string, number>();
+const listeners = new Set<() => void>();
+
+export interface LatencySnapshot {
+  /** Median WS round-trip in ms across open terminals, or null if none. */
+  rttMs: number | null;
+  /** How many terminals are currently reporting. */
+  count: number;
+}
+
+let snapshot: LatencySnapshot = { rttMs: null, count: 0 };
+
+function recompute(): void {
+  if (samples.size === 0) {
+    snapshot = { rttMs: null, count: 0 };
+    return;
+  }
+  const sorted = [...samples.values()].sort((a, b) => a - b);
+  const median = sorted[Math.floor(sorted.length / 2)];
+  snapshot = { rttMs: median, count: sorted.length };
+}
+
+function emit(): void {
+  for (const listener of listeners) {
+    listener();
+  }
+}
+
+export function reportLatency(id: string, rttMs: number): void {
+  samples.set(id, rttMs);
+  recompute();
+  emit();
+}
+
+export function removeLatency(id: string): void {
+  if (samples.delete(id)) {
+    recompute();
+    emit();
+  }
+}
+
+/** Test/inspection accessor for the current aggregate. */
+export function getLatencySnapshot(): LatencySnapshot {
+  return snapshot;
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function useLatency(): LatencySnapshot {
+  return useSyncExternalStore(subscribe, getLatencySnapshot, getLatencySnapshot);
+}

{remo_cli-2.2.0rc12 → remo_cli-2.2.0rc13}/frontend/src/state/settings.ts

@@ -69,6 +69,10 @@ export const MAX_TERM_SIZE = 18;
 export const MIN_RAIL_WIDTH = 262;
 export const MAX_RAIL_WIDTH = 520;
 const DEFAULT_RAIL_WIDTH = 320;
+/** Focus-follows-mouse dwell (ms): 0 = instant, higher = calmer. */
+export const MIN_FOCUS_DWELL_MS = 0;
+export const MAX_FOCUS_DWELL_MS = 1000;
+const DEFAULT_FOCUS_DWELL_MS = 220;
 
 export interface SettingsState {
   accent: string;
@@ -83,6 +87,8 @@ export interface SettingsState {
   nerdFontName: string | null;
   /** Browser terminal engine to back each terminal. */
   renderer: RendererChoice;
+  /** Focus-follows-mouse dwell in ms (how long the pointer rests before focus). */
+  focusDwellMs: number;
 }
 
 export interface TerminalFontOptions {
@@ -101,6 +107,7 @@ const DEFAULTS: SettingsState = {
   railCollapsed: false,
   nerdFontName: null,
   renderer: "xterm",
+  focusDwellMs: DEFAULT_FOCUS_DWELL_MS,
 };
 
 function clamp(n: number, lo: number, hi: number): number {
@@ -137,6 +144,10 @@ function loadPersisted(): SettingsState {
       railCollapsed: typeof c.railCollapsed === "boolean" ? c.railCollapsed : DEFAULTS.railCollapsed,
       nerdFontName: typeof c.nerdFontName === "string" ? c.nerdFontName : null,
       renderer: c.renderer === "ghostty" || c.renderer === "xterm" ? c.renderer : DEFAULTS.renderer,
+      focusDwellMs:
+        typeof c.focusDwellMs === "number"
+          ? clamp(Math.round(c.focusDwellMs), MIN_FOCUS_DWELL_MS, MAX_FOCUS_DWELL_MS)
+          : DEFAULTS.focusDwellMs,
     };
   } catch (error) {
     console.error("settings: failed to restore from localStorage", error);
@@ -214,6 +225,10 @@ export const settingsActions = {
   toggleRailCollapsed: () => setState({ railCollapsed: !state.railCollapsed }),
   setNerdFontName: (nerdFontName: string | null) => setState({ nerdFontName }),
   setRenderer: (renderer: RendererChoice) => setState({ renderer }),
+  setFocusDwell: (focusDwellMs: number) =>
+    setState({
+      focusDwellMs: clamp(Math.round(focusDwellMs), MIN_FOCUS_DWELL_MS, MAX_FOCUS_DWELL_MS),
+    }),
 };
 
 export function useSettings(): SettingsState {

{remo_cli-2.2.0rc12 → remo_cli-2.2.0rc13}/frontend/src/terminal/GhosttyRenderer.ts

@@ -78,9 +78,20 @@ export class GhosttyRenderer implements RendererAdapter {
     return true;
   }
 
+  // Native `copy` event (⌘C, Edit▸Copy, right-click▸Copy): write the selection
+  // synchronously via clipboardData — reliable in Safari (see XtermRenderer).
+  private readonly handleCopyEvent = (e: ClipboardEvent): void => {
+    const selection = this.getSelection();
+    if (selection && e.clipboardData) {
+      e.clipboardData.setData("text/plain", selection);
+      e.preventDefault();
+    }
+  };
+
   open(container: HTMLElement): void {
     this.container = container;
     this.terminal.open(container);
+    container.addEventListener("copy", this.handleCopyEvent);
   }
 
   write(data: Uint8Array | string): void {
@@ -149,6 +160,7 @@ export class GhosttyRenderer implements RendererAdapter {
   }
 
   dispose(): void {
+    this.container?.removeEventListener("copy", this.handleCopyEvent);
     this.terminal.dispose();
   }
 }

{remo_cli-2.2.0rc12 → remo_cli-2.2.0rc13}/frontend/src/terminal/TerminalConnection.ts

@@ -38,6 +38,8 @@ interface ControlMessage {
 
 const MAX_AUTO_RECONNECT_ATTEMPTS = 3;
 const RECONNECT_BACKOFF_MS = [500, 1500, 3500];
+/** How often to ping the WS to measure round-trip latency (also a keepalive). */
+const PING_INTERVAL_MS = 4000;
 
 export interface TerminalConnectionCallbacks {
   onData?: (data: Uint8Array) => void;
@@ -45,6 +47,8 @@ export interface TerminalConnectionCallbacks {
   onExit?: (code: number) => void;
   onError?: (error: TypedError) => void;
   onStateChange?: (state: TerminalConnectionState) => void;
+  /** WS round-trip time in ms, from each ping→pong while connected. */
+  onLatency?: (rttMs: number) => void;
 }
 
 /**
@@ -72,6 +76,9 @@ export class TerminalConnection {
   /** Bumped each attach() so a slow, superseded attach can't assign a socket. */
   private attachGen = 0;
   private wakeListenersBound = false;
+  private pingTimer: ReturnType<typeof setInterval> | undefined;
+  /** performance.now() when the outstanding ping was sent (null if none). */
+  private pingSentAt: number | null = null;
 
   constructor(
     sessionTargetId: string,
@@ -130,6 +137,7 @@ export class TerminalConnection {
   async close(): Promise<void> {
     this.clientInitiatedClose = true;
     this.removeWakeListeners();
+    this.stopPinging();
     this.clearReconnectTimer();
     const socket = this.socket;
     const terminalId = this.terminalId;
@@ -278,6 +286,7 @@ export class TerminalConnection {
 
     socket.onclose = (event: CloseEvent) => {
       this.socket = null;
+      this.stopPinging();
       if (this.clientInitiatedClose || event.code === 1000) {
         this.setState("closed");
         return;
@@ -286,6 +295,28 @@ export class TerminalConnection {
     };
   }
 
+  /** Begin (or restart) the latency ping loop; call once per fresh connection. */
+  private startPinging(): void {
+    this.stopPinging();
+    const sendMeasuredPing = (): void => {
+      if (this.socket?.readyState !== WebSocket.OPEN) {
+        return;
+      }
+      this.pingSentAt = performance.now();
+      this.sendPing();
+    };
+    sendMeasuredPing(); // one immediately, for a fast first sample
+    this.pingTimer = setInterval(sendMeasuredPing, PING_INTERVAL_MS);
+  }
+
+  private stopPinging(): void {
+    if (this.pingTimer !== undefined) {
+      clearInterval(this.pingTimer);
+      this.pingTimer = undefined;
+    }
+    this.pingSentAt = null;
+  }
+
   private handleControlMessage(raw: string): void {
     let message: ControlMessage;
     try {
@@ -306,6 +337,7 @@ export class TerminalConnection {
         // so re-send them now to size the remote terminal to the real surface.
         this.sendControl({ v: 1, type: "resize", cols: this.cols, rows: this.rows });
         this.callbacks.onReady?.();
+        this.startPinging();
         break;
       case "exit":
         this.callbacks.onExit?.(message.code ?? 0);
@@ -320,6 +352,11 @@ export class TerminalConnection {
         this.setState("error");
         break;
       case "pong":
+        if (this.pingSentAt !== null) {
+          const rtt = performance.now() - this.pingSentAt;
+          this.pingSentAt = null;
+          this.callbacks.onLatency?.(rtt);
+        }
         break;
     }
   }