From 4ff3279abb3fd3b5d8a64674668262469a02d893 Mon Sep 17 00:00:00 2001
From: James Risbey <james@sunnn.co>
Date: Thu, 6 Aug 2026 19:28:36 +1000
Subject: [PATCH] fix(desktop): say "Reconnecting" while the client is
 auto-reconnecting
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The sidebar relay card renders "Can't reach the relay" / "Click to
connect" for every degraded state, including `reconnecting` — the state
the relay client sets while its own backoff loop is actively retrying.
So a transient drop that the app is already recovering from unassisted
is presented as a dead connection the user has to go fix by hand.

The card had no way to tell the two apart: it only receives
`isReconnectPending`, which tracks a *manual* reconnect the user asked
for via `useReconnectRelay`, and is false during the background loop.
`ConnectionState` already distinguishes `reconnecting` from
`disconnected`/`stalled`; the card just never saw it.

Thread that through as `isAutoReconnecting` and use it for the
no-user-action-needed case only:

  reconnecting            -> "Reconnecting" + spinner, role=status
  disconnected / stalled  -> unchanged alarm copy, role=alert

The action button stays enabled while auto-reconnecting so anyone who
does not want to wait out the backoff can still force an attempt.

`stalled` deliberately keeps the alarm copy: the socket is open but no
frames are arriving, so the client is not making progress on its own.

Also point `relay-connectivity.spec.ts`'s local `settle()` at the shared
`waitForAnimations` helper. The card now renders a looping spinner in
this state, and a looping animation's `.finished` never resolves, so the
old unbounded `Promise.allSettled(getAnimations())` hung until Playwright
aborted the evaluate. The shared helper races the wait against a ceiling
for exactly this reason.

Verified: desktop `pnpm check`, `pnpm test` (3923 pass), and the
`relay-connectivity` + `sidebar-relay-card` smoke specs (6 pass).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Signed-off-by: James Risbey <james@sunnn.co>
---
 desktop/src/app/RelayConnectionOverlay.tsx    |  1 +
 .../src/features/sidebar/ui/AppSidebar.tsx    |  1 +
 .../sidebar/ui/SidebarRelayConnectionCard.tsx | 32 +++++++++++++----
 .../ui/useSidebarRelayConnectionCard.ts       |  3 ++
 desktop/tests/e2e/relay-connectivity.spec.ts  | 36 ++++++++++---------
 5 files changed, 50 insertions(+), 23 deletions(-)

diff --git a/desktop/src/app/RelayConnectionOverlay.tsx b/desktop/src/app/RelayConnectionOverlay.tsx
index 07c6933d04..246e1a1191 100644
--- a/desktop/src/app/RelayConnectionOverlay.tsx
+++ b/desktop/src/app/RelayConnectionOverlay.tsx
@@ -72,6 +72,7 @@ export function RelayConnectionOverlay({
         >
           <div className="pointer-events-auto rounded-xl bg-background shadow-md">
             <SidebarRelayConnectionCard
+              isAutoReconnecting={card.isRelayAutoReconnecting}
               isConnected={card.isRelayConnectionSuccess}
               isReconnectPending={card.isRelayReconnectPending}
               isWaitingOnReconnectHook={card.isWaitingOnReconnectHook}
diff --git a/desktop/src/features/sidebar/ui/AppSidebar.tsx b/desktop/src/features/sidebar/ui/AppSidebar.tsx
index 55f467f215..fa58a5c6b2 100644
--- a/desktop/src/features/sidebar/ui/AppSidebar.tsx
+++ b/desktop/src/features/sidebar/ui/AppSidebar.tsx
@@ -872,6 +872,7 @@ export function AppSidebar({
             (isMobile ? openMobile : sidebarOpen) ? (
               <SidebarRelayConnectionCard
                 className="mb-2"
+                isAutoReconnecting={relayConnectionCard.isRelayAutoReconnecting}
                 isConnected={relayConnectionCard.isRelayConnectionSuccess}
                 isReconnectPending={relayConnectionCard.isRelayReconnectPending}
                 isWaitingOnReconnectHook={
diff --git a/desktop/src/features/sidebar/ui/SidebarRelayConnectionCard.tsx b/desktop/src/features/sidebar/ui/SidebarRelayConnectionCard.tsx
index 57f59dc788..072eabc5d8 100644
--- a/desktop/src/features/sidebar/ui/SidebarRelayConnectionCard.tsx
+++ b/desktop/src/features/sidebar/ui/SidebarRelayConnectionCard.tsx
@@ -10,6 +10,12 @@ type SidebarRelayConnectionCardProps = {
   isActionDisabled?: boolean;
   actionTestId?: string;
   className?: string;
+  /**
+   * The client's own backoff loop is already retrying — no user action is
+   * needed. Distinct from `isReconnectPending`, which tracks a *manual*
+   * reconnect the user asked for.
+   */
+  isAutoReconnecting?: boolean;
   isConnected?: boolean;
   isReconnectPending: boolean;
   isWaitingOnReconnectHook?: boolean;
@@ -23,6 +29,7 @@ export function SidebarRelayConnectionCard({
   actionTestId,
   className,
   isActionDisabled = false,
+  isAutoReconnecting = false,
   isConnected = false,
   isReconnectPending,
   isWaitingOnReconnectHook = false,
@@ -35,6 +42,7 @@ export function SidebarRelayConnectionCard({
       actionTestId={actionTestId ?? "sidebar-reconnect"}
       className={className}
       isActionDisabled={isActionDisabled}
+      isAutoReconnecting={isAutoReconnecting}
       isConnected={isConnected}
       isReconnectPending={isReconnectPending}
       isWaitingOnReconnectHook={isWaitingOnReconnectHook}
@@ -50,6 +58,7 @@ export function SidebarRelayConnectionCompactCard({
   actionTestId,
   className,
   isActionDisabled = false,
+  isAutoReconnecting = false,
   isConnected = false,
   isReconnectPending,
   isWaitingOnReconnectHook = false,
@@ -64,10 +73,15 @@ export function SidebarRelayConnectionCompactCard({
   const reconnectDescription = isWaitingOnReconnectHook
     ? "Complete any prompts opened by the reconnect helper to continue."
     : "Reconnecting";
+  // A manual reconnect the user asked for outranks the background loop.
+  const isRetryingWithoutUser = isAutoReconnecting && !isReconnectPending;
+  const isBusy = isReconnectPending || isRetryingWithoutUser;
 
   return (
     <SidebarCompactActionCard
       actionAriaLabel={isConnected ? "Connected" : "Connect to relay"}
+      // The background loop still yields the button: a user who does not want
+      // to wait out the backoff can force an attempt now.
       actionDisabled={isActionDisabled || isReconnectPending || isConnected}
       actionTestId={actionTestId}
       description={
@@ -75,16 +89,16 @@ export function SidebarRelayConnectionCompactCard({
           ? undefined
           : isReconnectPending
             ? reconnectDescription
-            : "Click to connect"
+            : isRetryingWithoutUser
+              ? "Trying to restore the connection"
+              : "Click to connect"
       }
       dismissLabel="Dismiss relay notification"
-      iconKey={
-        isConnected ? "connected" : isReconnectPending ? "pending" : "idle"
-      }
+      iconKey={isConnected ? "connected" : isBusy ? "pending" : "idle"}
       icon={
         isConnected ? (
           <Check aria-hidden="true" className="h-5 w-5" />
-        ) : isReconnectPending ? (
+        ) : isBusy ? (
           <Spinner aria-hidden="true" className="h-5 w-5 border-2" />
         ) : (
           <CloudOff aria-hidden="true" className="h-5 w-5" />
@@ -93,7 +107,9 @@ export function SidebarRelayConnectionCompactCard({
       className={className}
       onAction={onReconnect}
       onDismiss={onDismiss}
-      role={isConnected ? "status" : "alert"}
+      // Recovering on its own is a status, not an alarm — only escalate to
+      // `alert` once the connection needs the user.
+      role={isConnected || isRetryingWithoutUser ? "status" : "alert"}
       surface={surface}
       testId={testId}
       title={
@@ -101,7 +117,9 @@ export function SidebarRelayConnectionCompactCard({
           ? "Connected"
           : isReconnectPending
             ? reconnectTitle
-            : "Can't reach the relay"
+            : isRetryingWithoutUser
+              ? "Reconnecting"
+              : "Can't reach the relay"
       }
       tone={isConnected ? "success" : "neutral"}
     />
diff --git a/desktop/src/features/sidebar/ui/useSidebarRelayConnectionCard.ts b/desktop/src/features/sidebar/ui/useSidebarRelayConnectionCard.ts
index 11f2bd1064..3f59f0979a 100644
--- a/desktop/src/features/sidebar/ui/useSidebarRelayConnectionCard.ts
+++ b/desktop/src/features/sidebar/ui/useSidebarRelayConnectionCard.ts
@@ -234,6 +234,9 @@ export function useSidebarRelayConnectionCard(
 
   return {
     hasRelayUnreachableError,
+    // The relay client's own backoff loop is mid-retry. The card uses this to
+    // say so instead of implying the user has to click something.
+    isRelayAutoReconnecting: relayConnectionState === "reconnecting",
     isRelayConnectionSuccess,
     isRelayReconnectPending,
     isWaitingOnReconnectHook,
diff --git a/desktop/tests/e2e/relay-connectivity.spec.ts b/desktop/tests/e2e/relay-connectivity.spec.ts
index dbe2b5d77c..9972dfe3a6 100644
--- a/desktop/tests/e2e/relay-connectivity.spec.ts
+++ b/desktop/tests/e2e/relay-connectivity.spec.ts
@@ -1,5 +1,6 @@
 import { expect, test } from "@playwright/test";
 
+import { waitForAnimations } from "../helpers/animations";
 import { installMockBridge } from "../helpers/bridge";
 
 const RELAY_UNREACHABLE = "relay unreachable: connection refused";
@@ -13,15 +14,12 @@ const MOCK_PUBKEY = "deadbeef".repeat(8);
 const MOCK_RELAY_URL = "ws://localhost:3000";
 const SELF_PROFILE_CACHE_KEY = `buzz-self-profile.v1:${MOCK_RELAY_URL}:${MOCK_PUBKEY}`;
 
-async function settle(page: import("@playwright/test").Page) {
-  await page.evaluate(() =>
-    // Tolerate cancelled animations: a SkeletonReveal animation cancelled
-    // mid-flight (skeleton → live content swap) rejects `.finished` with an
-    // AbortError. allSettled lets the animations that DO finish settle instead
-    // of aborting the whole wait on the first cancel.
-    Promise.allSettled(document.getAnimations().map((a) => a.finished)),
-  );
-}
+// Defer to the shared bounded helper. The degraded relay card now renders a
+// looping spinner while the client auto-reconnects, and a looping animation's
+// `.finished` never resolves — an unbounded wait here hangs until Playwright
+// aborts the evaluate. `waitForAnimations` races the settle against a ceiling
+// and also tolerates animations cancelled mid-flight.
+const settle = waitForAnimations;
 
 type ConnectionState =
   | "idle"
@@ -103,8 +101,11 @@ test.describe("relay connectivity", () => {
     await expect(relayCard).toBeVisible({
       timeout: 5_000,
     });
-    await expect(relayCard).toContainText("Can't reach the relay");
-    await expect(relayCard).toContainText("Click to connect");
+    // The backoff loop is retrying on its own — the card reports that rather
+    // than asking the user to click.
+    await expect(relayCard).toContainText("Reconnecting");
+    await expect(relayCard).toContainText("Trying to restore the connection");
+    await expect(relayCard).not.toContainText("Click to connect");
     await expect(page.getByTestId("sidebar-reconnect")).toBeVisible();
     await settle(page);
 
@@ -124,8 +125,9 @@ test.describe("relay connectivity", () => {
     await expect(relayCard).toBeVisible({
       timeout: 5_000,
     });
-    await expect(relayCard).toContainText("Can't reach the relay");
-    await expect(relayCard).toContainText("Click to connect");
+    await expect(relayCard).toContainText("Reconnecting");
+    await expect(relayCard).toContainText("Trying to restore the connection");
+    await expect(relayCard).not.toContainText("Click to connect");
     await expect(page.getByTestId("sidebar-reconnect")).toBeVisible();
     await settle(page);
 
@@ -218,13 +220,15 @@ test.describe("relay connectivity", () => {
     await expect(relayCard).toBeVisible({
       timeout: 5_000,
     });
-    await expect(relayCard).toContainText("Can't reach the relay");
-    await expect(relayCard).toContainText("Click to connect");
+    await expect(relayCard).toContainText("Reconnecting");
+    await expect(relayCard).toContainText("Trying to restore the connection");
 
     await driveConnectionDegraded(page, "connected");
 
     await expect(relayCard).toContainText("Connected");
-    await expect(relayCard).not.toContainText("Click to connect");
+    await expect(relayCard).not.toContainText(
+      "Trying to restore the connection",
+    );
     await page.waitForTimeout(3_000);
     await expect(relayCard).toContainText("Connected");
     await expect(relayCard).toBeHidden({