@nextclaw/ui 0.25.4 → 0.26.1

package/src/shared/lib/i18n/locales/en-US/core.json

@@ -13,7 +13,9 @@
   "advanced": "Advanced",
   "settings": "Settings",
   "settingsGroupBasic": "Basic Configuration",
-  "settingsGroupAdvanced": "Advanced Configuration",
+  "settingsGroupCommon": "Common Settings",
+  "settingsGroupSecurity": "Security & Privacy",
+  "settingsGroupSystem": "System & Extensions",
   "appearance": "Appearance",
   "keyboardShortcuts": "Keyboard shortcuts",
   "keyboardShortcutsDesktopOnly": "Keyboard shortcuts can be configured on desktop. Use the microphone button on mobile.",

package/src/shared/lib/i18n/locales/en-US/desktop-update.json

@@ -63,6 +63,7 @@
   "desktopUpdatesDownloadProgressUnknown": "Downloading",
   "desktopUpdatesBlockedTitle": "Update Blocked",
   "desktopUpdatesBlockedDescription": "Resolve the current installation requirement before continuing the update.",
+  "desktopUpdatesManualPortableDownload": "Download Latest Portable Edition",
   "desktopUpdatesBlockedRootCause.signature-verification-unavailable": "Root cause: missing update public key; install a configured build or ask the maintainer to set the key.",
   "desktopUpdatesBlockedRootCause.host-too-old": "Root cause: the host is too old for this runtime bundle; upgrade the NextClaw launcher first.",
   "desktopUpdatesBlockedRootCause.unsupported-installation": "Root cause: this installation or update source does not support auto-update; use a configured build.",

package/src/shared/lib/i18n/locales/en-US/doc-browser.json

@@ -18,7 +18,7 @@
   "docBrowserCloseTab": "Close Tab",
   "docBrowserTabUntitled": "Untitled",
   "docBrowserTabMoreActions": "More tab actions",
-  "docBrowserAddToChat": "Add to Chat",
+  "docBrowserAddToChat": "Add to chat",
   "sideDockPinCurrent": "Pin to SideDock",
   "sideDockUnpinCurrent": "Remove from SideDock",
   "sideDockBuiltInDocked": "Built-in shortcut",

package/src/shared/lib/i18n/locales/zh-CN/chat.json

@@ -1,4 +1,34 @@
 {
+  "pageLayoutActions": "布局与位置",
+  "pagePinLeft": "固定到左侧页面",
+  "pageUnpinLeft": "从左侧页面移除",
+  "pageCopyUri": "复制资源链接",
+  "pageCopyFailed": "无法复制链接，请重试",
+  "pageActions": "页面操作",
+  "pageSidebar": "页面",
+  "resourcePageTitle": "资源",
+  "resourceRetry": "重试",
+  "resourceNotFound": "资源已删除或不存在",
+  "resourceInvalid": "此资源类型尚未接入，或 URI 格式不正确",
+  "resourceLoadFailed": "资源暂时加载失败，请重试",
+  "pageUnavailable": "页面不可用或链接不受支持",
+  "workbenchOpenMain": "在主区域打开",
+  "workbenchDock": "停靠到侧栏",
+  "workbenchFloatGroup": "悬浮此视图组",
+  "workbenchExpand": "展开视图",
+  "workbenchCollapse": "收起视图",
+  "workbenchRestoreSize": "还原大小",
+  "workbenchMaximize": "最大化",
+  "workbenchCloseView": "关闭视图",
+  "workbenchHideGroup": "隐藏视图组",
+  "workbenchResize": "调整侧栏宽度",
+  "workbenchGlobalGroup": "全局工作区",
+  "workbenchSessionGroup": "会话工作台",
+  "workbenchMoveGlobal": "移动到全局右侧栏",
+  "workbenchFloatView": "在悬浮窗中打开",
+  "workbenchCloseTab": "关闭标签",
+  "workbenchFileUnavailable": "此文件视图不可用，请从原会话重新打开。",
+  "chatSidebarCloseSearch": "关闭搜索",
   "chatPageTitle": "Agent 对话",
   "chatPageDescription": "在 UI 内直接与 Agent 交互，支持多会话与多 Agent 切换。",
   "chatRefresh": "刷新",
@@ -252,7 +282,12 @@
   "chatHistoryLoadFailed": "较早消息加载失败",
   "chatHistoryRetry": "重试",
   "chatProcessSummaryProcessed": "已处理",
-  "chatProcessSummaryToolCalls": "{count} 次工具调用",
+  "chatProcessSummaryError": "处理失败",
+  "chatProcessSummaryStopped": "已停止",
+  "chatProcessDurationHoursMinutes": "{hours}小时{minutes}分钟",
+  "chatProcessDurationHours": "{hours}小时",
+  "chatProcessDurationMinutesSeconds": "{minutes}分钟{seconds}秒",
+  "chatProcessDurationSeconds": "{seconds}秒",
   "chatToolPayloadLoading": "正在加载详情",
   "chatToolPayloadLoadFailed": "详情加载失败，点击重试",
   "chatToolActivityShowMore": "继续显示 {count} 项（剩余 {remaining} 项）",
@@ -610,6 +645,15 @@
   "chatBackgroundReplyFallbackTitle": "有新回复",
   "chatBackgroundReplyFallbackPreview": "回复已完成，点击查看。",
   "chatBackgroundReplyOpenAriaLabel": "打开“{title}”的新回复",
+  "chatFloatingExpand": "在悬浮窗中对话",
+  "chatFloatingConversation": "悬浮会话",
+  "chatFloatingMinimize": "收起会话",
+  "chatFloatingRestore": "展开会话",
+  "chatFloatingOpenMain": "转到主会话",
+  "chatFloatingClose": "关闭悬浮会话",
+  "chatPanelDock": "停靠到右侧栏",
+  "chatPanelOpen": "在右侧栏中对话",
+  "chatPanelUnavailable": "无法打开此会话，请从会话列表重新打开。",
   "chatWelcomeTitle": "今天想完成什么？",
   "chatWelcomeContextLabel": "任务上下文",
   "chatWelcomeProjectPickerLabel": "选择工作目录",
@@ -654,6 +698,7 @@
   "chatInputVoiceNoDevice": "没有检测到麦克风。请连接或启用输入设备，再检测重试。",
   "chatInputVoiceDeviceBusy": "麦克风无法读取，可能被其他应用占用或被系统限制。请关闭其他录音应用，检查输入设备后重试。",
   "chatInputVoiceServiceDenied": "浏览器拒绝了语音识别服务。请检查浏览器的语音服务设置或组织策略，或使用支持语音识别的浏览器。",
+  "chatInputVoiceInsecureContext": "当前页面通过不安全的 HTTP 地址打开，浏览器会禁用麦克风。请为 VPS 配置 HTTPS；仅在本机访问时可使用 localhost 或 127.0.0.1。",
   "chatInputVoiceUnsupported": "当前浏览器不支持语音输入。",
   "chatInputVoiceNoSpeech": "没有听清，请再试一次。",
   "chatInputVoiceFailed": "语音输入失败，请重试。",

package/src/shared/lib/i18n/locales/zh-CN/core.json

@@ -3,7 +3,7 @@
   "model": "模型",
   "searchChannels": "搜索渠道",
   "providers": "提供商",
-  "extensions": "Extensions",
+  "extensions": "扩展",
   "channels": "渠道",
   "cron": "定时任务",
   "secrets": "密钥管理",
@@ -13,7 +13,9 @@
   "advanced": "高级",
   "settings": "设置",
   "settingsGroupBasic": "基础配置",
-  "settingsGroupAdvanced": "高级配置",
+  "settingsGroupCommon": "常用设置",
+  "settingsGroupSecurity": "安全与隐私",
+  "settingsGroupSystem": "系统与扩展",
   "appearance": "外观",
   "keyboardShortcuts": "快捷键",
   "keyboardShortcutsDesktopOnly": "请在桌面端配置键盘快捷键。手机可使用麦克风按钮输入。",
@@ -139,15 +141,15 @@
   "providersDefaultDescription": "为你的智能体配置 AI 服务",
   "providersEmptyTitle": "尚未配置提供商",
   "providersEmptyDescription": "添加一个 AI 提供商后即可开始使用。",
-  "extensionsPageTitle": "Extensions 管理",
-  "extensionsPageDescription": "查看已发现的 Extension、能力和当前运行状态。",
+  "extensionsPageTitle": "扩展管理",
+  "extensionsPageDescription": "查看已发现的扩展、能力和当前运行状态。",
   "extensionsRefresh": "刷新",
-  "extensionsLifecycleDescription": "Extension 由运行时按渠道和会话持续关注关系按需启停；这里集中查看全局能力和运行状态。",
-  "extensionsLoading": "正在加载 Extensions…",
-  "extensionsLoadFailed": "Extensions 加载失败。",
+  "extensionsLifecycleDescription": "扩展由运行时按渠道和会话持续关注关系按需启停；这里集中查看全局能力和运行状态。",
+  "extensionsLoading": "正在加载扩展…",
+  "extensionsLoadFailed": "扩展加载失败。",
   "extensionsRetry": "重试",
-  "extensionsEmpty": "暂无已发现的 Extension",
-  "extensionsEmptyDescription": "安装或放置 Extension 后，重新刷新此页面。",
+  "extensionsEmpty": "暂无已发现的扩展",
+  "extensionsEmptyDescription": "安装或放置扩展后，重新刷新此页面。",
   "extensionsTotal": "全部",
   "extensionsRunning": "运行中",
   "extensionsWithObservations": "支持持续关注",

package/src/shared/lib/i18n/locales/zh-CN/desktop-update.json

@@ -63,6 +63,7 @@
   "desktopUpdatesDownloadProgressUnknown": "正在下载",
   "desktopUpdatesBlockedTitle": "更新暂时无法继续",
   "desktopUpdatesBlockedDescription": "当前安装环境需要先处理阻塞项，之后才能继续更新。",
+  "desktopUpdatesManualPortableDownload": "下载最新 Portable Edition",
   "desktopUpdatesBlockedRootCause.signature-verification-unavailable": "根因：缺少更新签名公钥，无法验证更新包来源；请安装包含正确更新配置的新版本，或由维护者配置更新公钥。",
   "desktopUpdatesBlockedRootCause.host-too-old": "根因：当前宿主版本太旧，不满足新运行包的最低宿主版本要求；请先升级 NextClaw 启动器。",
   "desktopUpdatesBlockedRootCause.unsupported-installation": "根因：当前安装形态或更新源配置不支持自动更新；请安装支持自动更新的版本，或由维护者补齐更新源配置。",

package/src/shared/lib/navigation-history/index.ts

@@ -1,2 +1,3 @@
 export * from './navigation-history.utils';
 export * from './scroll-restoration.manager';
+export { ViewMemoryStorage } from './view-memory-storage.store';

package/src/shared/lib/navigation-history/navigation-history.utils.ts

@@ -40,7 +40,7 @@ export function pushNavigationHistoryEntry<Entry>(
       index: normalizedIndex,
     };
   }
-  const entries = [...history.entries.slice(0, normalizedIndex + 1), entry];
+  const entries = [...history.entries.slice(0, normalizedIndex + 1), entry].slice(-100);
   return {
     entries,
     index: entries.length - 1,

package/src/shared/lib/navigation-history/scroll-restoration.manager.test.ts

@@ -35,3 +35,14 @@ describe("ScrollRestorationManager", () => {
     expect(manager.read("second")).toBeNull();
   });
 });
+
+it("restores reading memory after reload without reviving deleted entries", () => {
+  sessionStorage.clear();
+  const first = new ScrollRestorationManager(2, sessionStorage);
+  first.save('file:one', { x: 2, y: 200 });
+  first.save('file:two', { x: 0, y: 300 });
+  const reloaded = new ScrollRestorationManager(2, sessionStorage);
+  expect(reloaded.read('file:one')).toEqual({ x: 2, y: 200 });
+  reloaded.delete('file:one');
+  expect(new ScrollRestorationManager(2, sessionStorage).read('file:one')).toBeNull();
+});

package/src/shared/lib/navigation-history/scroll-restoration.manager.ts

@@ -15,15 +15,37 @@ function normalizeKey(key: string): string | null {
   return normalized ? normalized : null;
 }
 
-/** Owns bounded, in-memory scroll positions for app-internal return navigation. */
+/** Shared, bounded reading memory; optional session storage survives a page reload. */
 export class ScrollRestorationManager {
   private readonly positions = new Map<string, ScrollRestorationPosition>();
 
   public constructor(
     private readonly capacity = DEFAULT_SCROLL_RESTORATION_CAPACITY,
-  ) {}
+    private readonly storage?: Storage,
+  ) {
+    try {
+      const saved: unknown = JSON.parse(storage?.getItem('nextclaw.view-memory.v1') ?? 'null');
+      if (Array.isArray(saved)) for (const entry of saved.slice(-capacity)) {
+        if (!Array.isArray(entry) || typeof entry[0] !== 'string') continue;
+        const value = entry[1];
+        if (value && typeof value.x === 'number' && typeof value.y === 'number' && Number.isFinite(value.x) && Number.isFinite(value.y)) this.positions.set(entry[0], value);
+      }
+    } catch { /* Private mode, stale data or quota cannot block navigation. */ }
+  }
+
+  private persist = (): void => {
+    try {
+      const entries = [...this.positions];
+      let json = JSON.stringify(entries);
+      while (json.length > 512_000 && entries.length > 0) {
+        entries.shift();
+        json = JSON.stringify(entries);
+      }
+      this.storage?.setItem('nextclaw.view-memory.v1', json);
+    } catch { /* Keep the in-memory position when browser storage is unavailable. */ }
+  }
 
-  public save(key: string, position: ScrollRestorationPosition): void {
+  public save = (key: string, position: ScrollRestorationPosition): void => {
     const normalizedKey = normalizeKey(key);
     if (!normalizedKey) return;
 
@@ -38,23 +60,30 @@ export class ScrollRestorationManager {
       if (!oldestKey) return;
       this.positions.delete(oldestKey);
     }
+    this.persist();
   }
 
-  public read(key: string): ScrollRestorationPosition | null {
+  public read = (key: string): ScrollRestorationPosition | null => {
     const normalizedKey = normalizeKey(key);
     if (!normalizedKey) return null;
     const position = this.positions.get(normalizedKey);
     return position ? { ...position } : null;
   }
 
-  public delete(key: string): void {
+  public delete = (key: string): void => {
     const normalizedKey = normalizeKey(key);
     if (normalizedKey) this.positions.delete(normalizedKey);
+    this.persist();
   }
 
-  public clear(): void {
+  public clear = (): void => {
     this.positions.clear();
+    this.persist();
   }
 }
 
-export const scrollRestorationManager = new ScrollRestorationManager();
+function getReadingMemoryStorage(): Storage | undefined {
+  try { return typeof window === 'undefined' ? undefined : window.sessionStorage; } catch { return undefined; }
+}
+
+export const scrollRestorationManager = new ScrollRestorationManager(DEFAULT_SCROLL_RESTORATION_CAPACITY, getReadingMemoryStorage());

package/src/shared/lib/navigation-history/view-memory-storage.store.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it, vi } from "vitest";
+import { ViewMemoryStorage } from "./view-memory-storage.store";
+
+describe("best-effort view memory", () => {
+  it("tolerates access denial and quota failures without breaking view actions", () => {
+    const unavailable = new ViewMemoryStorage(() => {
+      throw new Error("denied");
+    });
+    expect(unavailable.getItem("view")).toBeNull();
+    expect(() => unavailable.setItem("view", "{}")).not.toThrow();
+    expect(() => unavailable.removeItem("view")).not.toThrow();
+    const quota = new ViewMemoryStorage(
+      () =>
+        ({
+          getItem: () => null,
+          setItem: () => {
+            throw new Error("quota");
+          },
+          removeItem: vi.fn(),
+        }) as unknown as Storage,
+    );
+    expect(() => quota.setItem("view", "{}")).not.toThrow();
+  });
+  it("preserves the existing storage key and serialized state", () => {
+    const storage = {
+      getItem: vi.fn(() => '{"version":1}'),
+      setItem: vi.fn(),
+      removeItem: vi.fn(),
+    };
+    const memory = new ViewMemoryStorage(() => storage as unknown as Storage);
+    expect(memory.getItem("view")).toBe('{"version":1}');
+    memory.setItem("view", "snapshot");
+    memory.removeItem("view");
+    expect(storage.setItem).toHaveBeenCalledWith("view", "snapshot");
+    expect(storage.removeItem).toHaveBeenCalledWith("view");
+  });
+});

package/src/shared/lib/navigation-history/view-memory-storage.store.ts

@@ -0,0 +1,21 @@
+import type { StateStorage } from 'zustand/middleware';
+
+/** Owns best-effort browser IO; denied storage never blocks view navigation. */
+export class ViewMemoryStorage implements StateStorage {
+  constructor(private readonly resolveStorage: () => Storage = () => window.localStorage) {}
+
+  getItem = (key: string): string | null => {
+    try { return this.resolveStorage().getItem(key); }
+    catch { return null; }
+  };
+
+  setItem = (key: string, value: string): void => {
+    try { this.resolveStorage().setItem(key, value); }
+    catch { /* Keep the active in-memory view usable. */ }
+  };
+
+  removeItem = (key: string): void => {
+    try { this.resolveStorage().removeItem(key); }
+    catch { /* Storage may be blocked or full. */ }
+  };
+}

package/src/shared/lib/transport/__tests__/browser-realtime-recovery.service.test.ts

@@ -1,12 +1,17 @@
-import { afterEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { BrowserRealtimeRecoveryService } from '@/shared/lib/transport/browser-realtime-recovery.service';
 
 describe('BrowserRealtimeRecoveryService', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
   afterEach(() => {
     vi.restoreAllMocks();
+    vi.useRealTimers();
   });
 
-  it('requests recovery only when the page can actively reconnect', () => {
+  it('requests recovery for every supported foreground lifecycle signal', () => {
     let visibilityState: DocumentVisibilityState = 'hidden';
     vi.spyOn(document, 'visibilityState', 'get').mockImplementation(() => visibilityState);
     const requestRecovery = vi.fn();
@@ -18,11 +23,19 @@ describe('BrowserRealtimeRecoveryService', () => {
 
     visibilityState = 'visible';
     document.dispatchEvent(new Event('visibilitychange'));
+    window.dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
+    window.dispatchEvent(new Event('focus'));
     window.dispatchEvent(new Event('online'));
+    expect(requestRecovery).toHaveBeenCalledTimes(1);
+
+    vi.advanceTimersByTime(250);
+    window.dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
     expect(requestRecovery).toHaveBeenCalledTimes(2);
 
     recovery.stop();
     document.dispatchEvent(new Event('visibilitychange'));
+    window.dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
+    window.dispatchEvent(new Event('focus'));
     expect(requestRecovery).toHaveBeenCalledTimes(2);
   });
 
@@ -39,4 +52,16 @@ describe('BrowserRealtimeRecoveryService', () => {
     recovery.stop();
     recovery.stop();
   });
+
+  it('does not replace the first connection for an ordinary initial pageshow', () => {
+    vi.spyOn(document, 'visibilityState', 'get').mockReturnValue('visible');
+    const requestRecovery = vi.fn();
+    const recovery = new BrowserRealtimeRecoveryService(requestRecovery);
+
+    recovery.start();
+    window.dispatchEvent(new PageTransitionEvent('pageshow', { persisted: false }));
+
+    expect(requestRecovery).not.toHaveBeenCalled();
+    recovery.stop();
+  });
 });

package/src/shared/lib/transport/__tests__/local-transport.service.test.ts

@@ -38,11 +38,13 @@ class MockWebSocket {
 describe('LocalAppTransport browser connection recovery', () => {
   beforeEach(() => {
     MockWebSocket.instances = [];
+    vi.useFakeTimers();
     vi.stubGlobal('WebSocket', MockWebSocket as unknown as typeof WebSocket);
   });
 
   afterEach(() => {
     vi.restoreAllMocks();
+    vi.useRealTimers();
     vi.unstubAllGlobals();
   });
 
@@ -70,6 +72,7 @@ describe('LocalAppTransport browser connection recovery', () => {
 
     expect(MockWebSocket.instances).toHaveLength(2);
     expect(handler).toHaveBeenLastCalledWith({ type: 'connection.open', payload: {} });
+    vi.advanceTimersByTime(250);
     window.dispatchEvent(new Event('online'));
     const secondReplacement = MockWebSocket.instances[2];
     secondReplacement?.open();
@@ -82,4 +85,21 @@ describe('LocalAppTransport browser connection recovery', () => {
     window.dispatchEvent(new Event('online'));
     expect(MockWebSocket.instances).toHaveLength(3);
   });
+
+  it('replaces a frozen connecting socket when the page regains focus', () => {
+    vi.spyOn(document, 'visibilityState', 'get').mockReturnValue('visible');
+    const transport = new LocalAppTransport({ apiBase: 'https://vps.example.com' });
+    const handler = vi.fn();
+    const unsubscribe = transport.subscribe(handler);
+    const frozenSocket = MockWebSocket.instances[0];
+
+    window.dispatchEvent(new Event('focus'));
+
+    expect(frozenSocket?.close).toHaveBeenCalledTimes(1);
+    expect(MockWebSocket.instances).toHaveLength(2);
+    expect(handler).toHaveBeenCalledWith({ type: 'connection.close', payload: {} });
+    MockWebSocket.instances[1]?.open();
+    expect(handler).toHaveBeenLastCalledWith({ type: 'connection.open', payload: {} });
+    unsubscribe();
+  });
 });

package/src/shared/lib/transport/__tests__/remote.transport.test.ts

@@ -185,6 +185,7 @@ describe('RemoteSessionMultiplexTransport request path', () => {
     await pendingFailure;
     await Promise.resolve();
     expect(replacementSocket?.sent).toHaveLength(0);
+    vi.advanceTimersByTime(250);
     window.dispatchEvent(new Event('online'));
     const secondReplacement = MockWebSocket.instances[2];
     secondReplacement?.open();
@@ -197,4 +198,29 @@ describe('RemoteSessionMultiplexTransport request path', () => {
     expect(MockWebSocket.instances).toHaveLength(3);
     unsubscribe();
   });
+
+  it('abandons a frozen connecting socket immediately when the page is shown again', async () => {
+    vi.spyOn(document, 'visibilityState', 'get').mockReturnValue('visible');
+    const transport = new RemoteSessionMultiplexTransport({
+      mode: 'remote',
+      protocolVersion: 1,
+      wsPath: '/_remote/ws'
+    }, 'https://remote.claw.cool');
+
+    const handler = vi.fn();
+    const unsubscribe = transport.subscribe(handler);
+    const frozenSocket = MockWebSocket.instances[0];
+
+    window.dispatchEvent(new PageTransitionEvent('pageshow', { persisted: true }));
+    await Promise.resolve();
+
+    expect(frozenSocket?.readyState).toBe(MockWebSocket.CLOSED);
+    expect(MockWebSocket.instances).toHaveLength(2);
+    expect(handler).toHaveBeenCalledWith({ type: 'connection.close', payload: {} });
+
+    MockWebSocket.instances[1]?.open();
+    await Promise.resolve();
+    expect(handler).toHaveBeenLastCalledWith({ type: 'connection.open', payload: {} });
+    unsubscribe();
+  });
 });

package/src/shared/lib/transport/browser-realtime-recovery.service.ts

@@ -1,5 +1,8 @@
+const RECOVERY_SIGNAL_COOLDOWN_MS = 250;
+
 export class BrowserRealtimeRecoveryService {
   private started = false;
+  private recoveryCooldownId: number | null = null;
 
   constructor(private readonly requestRecovery: () => void) {}
 
@@ -10,6 +13,8 @@ export class BrowserRealtimeRecoveryService {
     this.started = true;
     document.addEventListener('visibilitychange', this.handleVisibilityChange);
     window.addEventListener('online', this.handleOnline);
+    window.addEventListener('pageshow', this.handlePageShow);
+    window.addEventListener('focus', this.handleForegroundSignal);
   };
 
   stop = (): void => {
@@ -19,17 +24,39 @@ export class BrowserRealtimeRecoveryService {
     this.started = false;
     document.removeEventListener('visibilitychange', this.handleVisibilityChange);
     window.removeEventListener('online', this.handleOnline);
+    window.removeEventListener('pageshow', this.handlePageShow);
+    window.removeEventListener('focus', this.handleForegroundSignal);
+    if (this.recoveryCooldownId !== null) {
+      window.clearTimeout(this.recoveryCooldownId);
+      this.recoveryCooldownId = null;
+    }
   };
 
   private readonly handleVisibilityChange = (): void => {
-    if (document.visibilityState === 'visible') {
-      this.requestRecovery();
-    }
+    this.requestRecoveryIfVisible();
   };
 
   private readonly handleOnline = (): void => {
-    if (document.visibilityState === 'visible') {
-      this.requestRecovery();
+    this.requestRecoveryIfVisible();
+  };
+
+  private readonly handleForegroundSignal = (): void => {
+    this.requestRecoveryIfVisible();
+  };
+
+  private readonly handlePageShow = (event: PageTransitionEvent): void => {
+    if (event.persisted) {
+      this.requestRecoveryIfVisible();
+    }
+  };
+
+  private readonly requestRecoveryIfVisible = (): void => {
+    if (document.visibilityState !== 'visible' || this.recoveryCooldownId !== null) {
+      return;
     }
+    this.requestRecovery();
+    this.recoveryCooldownId = window.setTimeout(() => {
+      this.recoveryCooldownId = null;
+    }, RECOVERY_SIGNAL_COOLDOWN_MS);
   };
 }

package/src/shared/lib/transport/local-transport.service.ts

@@ -54,7 +54,6 @@ class LocalRealtimeGateway {
   private socket: WebSocket | null = null;
   private reconnectTimer: number | null = null;
   private manualClose = false;
-  private replacingAfterBrowserRecovery = false;
   private subscribers = new Set<EventHandler>();
   private readonly browserRecovery = new BrowserRealtimeRecoveryService(() => {
     this.replaceSocket();
@@ -95,7 +94,6 @@ class LocalRealtimeGateway {
     this.socket = socket;
 
     socket.onopen = () => {
-      this.replacingAfterBrowserRecovery = false;
       this.emit({ type: 'connection.open', payload: {} });
     };
 
@@ -113,7 +111,6 @@ class LocalRealtimeGateway {
     };
 
     socket.onclose = () => {
-      this.replacingAfterBrowserRecovery = false;
       this.emit({ type: 'connection.close', payload: {} });
       this.socket = null;
       if (!this.manualClose && this.subscribers.size > 0) {
@@ -133,10 +130,9 @@ class LocalRealtimeGateway {
   };
 
   private replaceSocket = (): void => {
-    if (this.subscribers.size === 0 || this.replacingAfterBrowserRecovery) {
+    if (this.subscribers.size === 0) {
       return;
     }
-    this.replacingAfterBrowserRecovery = true;
     if (this.reconnectTimer !== null) {
       window.clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
@@ -156,7 +152,6 @@ class LocalRealtimeGateway {
 
   private disconnect = (): void => {
     this.manualClose = true;
-    this.replacingAfterBrowserRecovery = false;
     if (this.reconnectTimer !== null) {
       window.clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;

package/src/shared/lib/transport/remote-transport.service.ts

@@ -87,9 +87,16 @@ function createId(prefix: string): string {
 
 const REMOTE_REQUEST_TIMEOUT_MS = 15_000;
 
+class RemoteBrowserRecoveryReplacementError extends Error {
+  constructor() {
+    super('Remote transport connection replaced after browser recovery.');
+  }
+}
+
 export class RemoteSessionMultiplexTransport implements AppTransport {
   private socket: WebSocket | null = null;
   private connectPromise: Promise<void> | null = null;
+  private rejectConnect: ((error: Error) => void) | null = null;
   private connectTimeoutId: number | null = null;
   private reconnectTimer: number | null = null;
   private manualClose = false;
@@ -221,6 +228,9 @@ export class RemoteSessionMultiplexTransport implements AppTransport {
     this.subscribers.add(handler);
     this.browserRecovery.start();
     void this.ensureSocket().catch((error) => {
+      if (error instanceof RemoteBrowserRecoveryReplacementError) {
+        return;
+      }
       handler({
         type: 'connection.error',
         payload: { message: error instanceof Error ? error.message : String(error) }
@@ -258,6 +268,7 @@ export class RemoteSessionMultiplexTransport implements AppTransport {
     const wsUrl = resolveTransportWebSocketUrl(this.apiBase, this.runtime.wsPath);
     this.manualClose = false;
     this.connectPromise = new Promise<void>((innerResolve, innerReject) => {
+        this.rejectConnect = innerReject;
         const socket = new WebSocket(wsUrl);
         this.socket = socket;
         let connectionOpened = false;
@@ -279,6 +290,7 @@ export class RemoteSessionMultiplexTransport implements AppTransport {
           connectionOpened = true;
           clearConnectTimeout();
           this.connectPromise = null;
+          this.rejectConnect = null;
           innerResolve();
           this.emit({ type: 'connection.open', payload: {} });
         };
@@ -304,6 +316,7 @@ export class RemoteSessionMultiplexTransport implements AppTransport {
           const wasConnecting = this.connectPromise !== null;
           this.socket = null;
           this.connectPromise = null;
+          this.rejectConnect = null;
           this.failPendingWork(new Error('Remote transport connection closed.'));
           this.emit({ type: 'connection.close', payload: {} });
           if (wasConnecting && !connectionOpened) {
@@ -330,21 +343,29 @@ export class RemoteSessionMultiplexTransport implements AppTransport {
   }
 
   private replaceSocket = (): void => {
-    if (this.subscribers.size === 0 || this.connectPromise !== null) {
+    if (this.subscribers.size === 0) {
       return;
     }
     if (this.reconnectTimer !== null) {
       window.clearTimeout(this.reconnectTimer);
       this.reconnectTimer = null;
     }
+    if (this.connectTimeoutId !== null) {
+      window.clearTimeout(this.connectTimeoutId);
+      this.connectTimeoutId = null;
+    }
     const staleSocket = this.socket;
+    const rejectStaleConnect = this.rejectConnect;
     this.socket = null;
+    this.connectPromise = null;
+    this.rejectConnect = null;
     if (staleSocket) {
       staleSocket.onopen = null;
       staleSocket.onmessage = null;
       staleSocket.onerror = null;
       staleSocket.onclose = null;
       staleSocket.close();
+      rejectStaleConnect?.(new RemoteBrowserRecoveryReplacementError());
       this.failPendingWork(new Error('Remote transport connection replaced after browser recovery.'));
       this.emit({ type: 'connection.close', payload: {} });
     }