visionA/local-tool/.autoflow/04-architecture/v2/web-ui-offline-overlay.md

# v2/web-ui-offline-overlay.md — Web UI Server Offline Overlay

> 所屬：TDD v2 §2.6
> 版本：v2.1（2026-04-14 吸收 Minor 4 WebSocket shutdown-imminent 廣播）
> 決策依據：R5-2（關閉 Wails 視窗 = server 停，瀏覽器顯示 offline overlay）、三方共識 #14（boot-id + retry）、PM Minor 4（WebSocket 廣播即時觸發 overlay，消除 race condition）
> 對應 milestone：M8-7
> 相關文件：`v2/server-lifecycle.md` §8.3（Wails 端 WebSocket 廣播時機）、§9（server 端 boot-id API）

---

## 1. 目的

當瀏覽器 tab 偵測到 server 連不上（Wails app 被關了、使用者按 Stop、server crash）時，顯示一個全域的覆蓋層告訴使用者「Server 已離線」，並提供重試機制。同時實作 boot-id polling 讓 server 重啟後瀏覽器自動 reload。

---

## 2. UI 設計

```
┌─────────────────────────────────────────────────────┐
│                                                     │
│                    ⚠️                               │
│                                                     │
│              Server 已離線                           │
│                                                     │
│   visionA Local 的本機伺服器沒有回應。                 │
│   可能原因：                                           │
│   • 你關閉了 visionA Local 控制台                     │
│   • Server 被手動停止                                 │
│   • Server 發生錯誤                                   │
│                                                     │
│   請重新開啟 visionA Local 應用程式後按「重試」。        │
│                                                     │
│         [重試]        [關閉這個頁面]                   │
│                                                     │
└─────────────────────────────────────────────────────┘
```

- 全螢幕半透明 backdrop（`rgba(0,0,0,0.65)`）
- 中央卡片（`max-w-md`）
- 中英文隨現有 i18n locale
- 不擋 devtools、不擋 keyboard（使用者可用 devtools 檢查 network 看是不是真連不上）

---

## 3. 偵測機制

### 3.1 偵測參數定版（v2.1 Architect 二次審閱補齊）

**Polling 間隔與失敗門檻（定版）**：

| 參數 | 值 | 說明 |
|------|-----|------|
| Health check 間隔（正常模式） | **10 秒** | server 正常時的 boot-id polling 間隔 |
| Health check 間隔（active retry 模式）| **3 秒** | overlay 顯示後自動重試的 polling 間隔 |
| 連續失敗門檻 | **2 次**（約 20 秒）| 避免偶發網路抖動誤觸發 |
| fetch 單次 timeout | 3 秒 | `AbortSignal.timeout(3000)` |

**Active retry 模式定義**：使用者第一次看到 overlay 後（或主動點 Retry 按鈕），前端**自動**每 3 秒重打一次 `/api/system/boot-id`，不需要使用者持續按按鈕。只要任一次成功 → 立即 `resetFailures()` → overlay 消失（若 bootId 變了則 `window.location.reload()`）。

**觸發管道**：Overlay 顯示由三個獨立管道觸發，任一觸發即顯示（優先序由高到低）：

1. **WebSocket close event（v2.1 新增）**：瀏覽器端 WebSocket 收到 `onclose` → **立即**顯示 overlay（不等 polling）；理由：close 事件代表 server 端已斷，polling 也一定會失敗，不需要等 20 秒
2. **WebSocket `server:shutdown-imminent` 事件（Minor 4）**：收到廣播訊息 → **立即**顯示 overlay，並依 `reason` 欄位決定文案：
    - `reason="app-closing"` / `reason="manual-stop"` / `reason="quit"` → 立即顯示
    - `reason="restart"` → 延遲 10 秒顯示（給 boot-id 變化 → `window.location.reload()` 的時間）
3. **被動偵測（polling fallback）**：連續 2 次 boot-id polling 失敗 → 顯示 overlay（當 WebSocket 已斷線或從未建立時生效）

WebSocket 管道的優勢：
- **零延遲**：Wails 開始 SIGTERM 的瞬間就發廣播（在實際 shutdown 完成前），瀏覽器 tab 幾乎同時看到 overlay
- **消除 race condition**：原 v2.0 設計下，使用者關 Wails 視窗到瀏覽器 tab 看到 overlay 有 0.5-20 s 的 window（取決於 polling 時機），這段期間使用者可能對著一個「已失效但看起來正常」的頁面操作
- **回退**：若 WebSocket 已斷線或從未建立（極罕見，例如 Next.js 載入失敗），polling fallback 仍有效

### 3.2 Polling 策略（v2.1 定版）

```
瀏覽器 tab 載入
  ↓
initial fetch /api/system/boot-id
  ↓
成功 → 記錄 initialBootId + startedAt，進 normal polling（10 s interval）
  ↓
下一次 poll：
  ├─ 成功 → 比對 bootId
  │    ├─ 相同 → 無事
  │    └─ 不同 → window.location.reload()（server 重啟，強制 reload）
  └─ 失敗 → consecutiveFailures++
       ├─ < 2 → 不顯示 overlay（避免偶發網路 glitch）
       └─ ≥ 2（連續 ~20 s）→ 顯示 <ServerOfflineOverlay>
                             + 切 polling interval 為 3 s（active retry 模式）
  ↓
Active retry 模式下：
  每 3 s 自動重打 /api/system/boot-id
  ├─ 成功（bootId 相同）→ resetFailures() + 切回 10 s interval → overlay 消失
  └─ 成功（bootId 不同）→ window.location.reload()
```

### 3.2a WebSocket `server:shutdown-imminent` 偵測

```
瀏覽器 tab 已連上 WebSocket（例如 /ws/server-logs 或新增的 /ws/system）
  ↓
server 收到 Wails 的 ctrl.Stop() 呼叫
  ↓
server 對 WebSocket hub 廣播：
  {
    "type": "server:shutdown-imminent",
    "reason": "app-closing" | "manual-stop" | "restart",
    "ts": 1744656180123
  }
  ↓
瀏覽器收到 message → store.forceShowOverlay()
  ↓
<ServerOfflineOverlay> 立即顯示（不等 polling 失敗）
  ↓
後續 SIGTERM、server 真的停止、polling 失敗 → 疊加在 overlay 上不重複觸發
```

**reason 欄位用途（v2.1 定版）**：
- `app-closing`：Wails OnShutdown 觸發，應用即將退出 → 立即顯示 overlay，文案「visionA Local 已關閉」
- `manual-stop`：使用者按控制台的 Stop → 立即顯示 overlay，文案「Server 已停止，請在控制台按 Start」
- `quit`：使用者從 Wails 選單選 Quit（macOS Cmd+Q 等）→ 立即顯示 overlay，文案同 `app-closing`
- `restart`：使用者按控制台的 Restart → **延遲 10 秒**再顯示 overlay（給 boot-id 變化 → `window.location.reload()` 的時間）；若 10 s 內 server 回來 + boot-id 變 → reload → overlay 不會真的顯示

### 3.3 失敗計數策略（polling 管道，v2.1 定版）

- **Normal 模式**：10 s poll interval，連續 2 次失敗（= 覆蓋 ~20 s 容忍期）才觸發 overlay
- **Active retry 模式**：overlay 顯示後切 3 s poll interval，自動重試至 server 回來
- Wails 關閉視窗的 `StopServer` 過程約 0.5-1 s，瀏覽器 polling 通常靠 WebSocket close 事件或 `server:shutdown-imminent` 廣播立即顯示 overlay，而非等 polling 失敗
- 使用者正常 Restart（透過控制台）約 2-3 s，boot-id 會變但也不會連續 2 次失敗 → 下一次成功 poll 偵測 boot-id 變化 → force reload
- 網路偶發抖動（< 10 s 單次 glitch）→ 最多 1 次 failure，下一次 poll 成功即清零，不觸發 overlay

### 3.3 Page Visibility API（R-v2-6）

瀏覽器背景 tab 的 setInterval 會被降頻到 1 次/分鐘，會讓「server 重啟後使用者切回 tab」體驗不好。

解決：

```typescript
const BOOT_ID_POLL_MS = 5000;
let intervalHandle: number | null = null;

function startPolling() {
    if (intervalHandle !== null) return;
    intervalHandle = window.setInterval(pollOnce, BOOT_ID_POLL_MS);
}

function stopPolling() {
    if (intervalHandle !== null) {
        clearInterval(intervalHandle);
        intervalHandle = null;
    }
}

document.addEventListener('visibilitychange', () => {
    if (document.visibilityState === 'visible') {
        pollOnce();  // 立刻 probe 一次
        startPolling();
    } else {
        stopPolling();  // 背景 tab 不 poll，回來再說
    }
});

// 初始：tab 可見時才啟動
if (document.visibilityState === 'visible') {
    startPolling();
}
```

---

## 4. 實作

### 4.1 檔案清單

| 檔案 | 狀態 | 說明 |
|------|------|------|
| `frontend/src/stores/system-store.ts` | **新增** | Zustand store：`serverOnline / bootId / forcedOffline / lastError` |
| `frontend/src/hooks/use-boot-id-watcher.ts` | **新增** | React hook：掛 useEffect 啟動 polling + visibility handling |
| `frontend/src/hooks/use-shutdown-watcher.ts` | **新增**（v2.1）| React hook：訂閱 WebSocket `server:shutdown-imminent` 事件（Minor 4）|
| `frontend/src/components/server-offline-overlay.tsx` | **新增** | 全域覆蓋層 UI（shadcn Dialog / Card） |
| `frontend/src/components/boot-id-watcher-mount.tsx` | **新增** | Client wrapper 掛 `useBootIdWatcher()` + `useShutdownWatcher()` |
| `frontend/src/app/layout.tsx` | **修改** | 在 root layout 掛 `<ServerOfflineOverlay />` 和 `<BootIdWatcherMount />` |
| `frontend/src/lib/i18n/types.ts` | **修改** | 新增 `serverOffline` 區塊的 i18n key 定義（含 3 種 reason 文案）|
| `frontend/src/lib/i18n/zh-TW.ts` | **修改** | 新增繁體中文字串 |
| `frontend/src/lib/i18n/en.ts` | **修改** | 新增英文字串 |

### 4.2 `frontend/src/stores/system-store.ts`

```typescript
import { create } from 'zustand';

interface SystemState {
    serverOnline: boolean;
    bootId: string | null;
    consecutiveFailures: number;
    lastProbeAt: number | null;
    // Minor 4：由 WebSocket shutdown-imminent 事件強制設定，讓 overlay 立即顯示
    forcedOffline: boolean;
    forcedOfflineReason: 'app-closing' | 'manual-stop' | 'restart' | 'quit' | null;

    setOnline: (bootId: string) => void;
    recordFailure: () => void;
    shouldShowOverlay: () => boolean;
    resetFailures: () => void;
    forceOffline: (reason: 'app-closing' | 'manual-stop' | 'restart' | 'quit') => void;
}

const FAILURE_THRESHOLD = 2; // v2.1 定版：2 次失敗（約 20 s）即觸發

export const useSystemStore = create<SystemState>((set, get) => ({
    serverOnline: true,
    bootId: null,
    consecutiveFailures: 0,
    lastProbeAt: null,
    forcedOffline: false,
    forcedOfflineReason: null,

    setOnline: (bootId) => set({
        serverOnline: true,
        bootId,
        consecutiveFailures: 0,
        lastProbeAt: Date.now(),
        // 注意：recover 時不自動清 forcedOffline，要走 resetFailures（使用者點「重試」）
    }),

    recordFailure: () => set((s) => ({
        consecutiveFailures: s.consecutiveFailures + 1,
        serverOnline: s.consecutiveFailures + 1 < FAILURE_THRESHOLD,
        lastProbeAt: Date.now(),
    })),

    shouldShowOverlay: () => {
        const s = get();
        return s.forcedOffline || s.consecutiveFailures >= FAILURE_THRESHOLD;
    },

    // Active retry 模式：overlay 顯示中時，前端自動切 3 s interval 重試
    isActiveRetryMode: () => {
        const s = get();
        return s.forcedOffline || s.consecutiveFailures >= FAILURE_THRESHOLD;
    },

    resetFailures: () => set({
        consecutiveFailures: 0,
        serverOnline: true,
        forcedOffline: false,
        forcedOfflineReason: null,
    }),

    forceOffline: (reason) => {
        // Minor 4：restart 情境不立即顯示 overlay，給 10 s 等 boot-id 變化 reload
        if (reason === 'restart') {
            setTimeout(() => {
                const s = get();
                if (s.consecutiveFailures < FAILURE_THRESHOLD && s.bootId !== null) {
                    // 10 s 內 server 沒回來才強制顯示
                    set({ forcedOffline: true, forcedOfflineReason: 'restart' });
                }
            }, 10_000);
            return;
        }
        set({ forcedOffline: true, forcedOfflineReason: reason });
    },
}));
```

### 4.3 `frontend/src/hooks/use-boot-id-watcher.ts`

```typescript
'use client';

import { useEffect } from 'react';
import { useSystemStore } from '@/stores/system-store';
import { getBackendUrl } from '@/lib/api';

const POLL_INTERVAL_NORMAL_MS = 10_000; // v2.1 定版：正常模式 10 s
const POLL_INTERVAL_ACTIVE_RETRY_MS = 3_000; // v2.1 定版：overlay 顯示後自動每 3 s 重試

interface BootIdResponse {
    success: boolean;
    data: {
        bootId: string;
        startedAt: number;
    };
}

async function pollOnce(): Promise<void> {
    const store = useSystemStore.getState();
    try {
        const res = await fetch(`${getBackendUrl()}/api/system/boot-id`, {
            cache: 'no-store',
            // 短 timeout：若 server 假死要快速失敗
            signal: AbortSignal.timeout(3000),
        });
        if (!res.ok) {
            store.recordFailure();
            return;
        }
        const json = (await res.json()) as BootIdResponse;
        if (!json.success || !json.data?.bootId) {
            store.recordFailure();
            return;
        }
        const newBootId = json.data.bootId;
        if (store.bootId !== null && store.bootId !== newBootId) {
            // Server 重啟：force reload
            window.location.reload();
            return;
        }
        store.setOnline(newBootId);
    } catch {
        store.recordFailure();
    }
}

export function useBootIdWatcher(): void {
    useEffect(() => {
        let intervalHandle: number | null = null;
        let currentMode: 'normal' | 'active-retry' = 'normal';

        const intervalFor = (mode: 'normal' | 'active-retry') =>
            mode === 'active-retry' ? POLL_INTERVAL_ACTIVE_RETRY_MS : POLL_INTERVAL_NORMAL_MS;

        const start = (mode: 'normal' | 'active-retry') => {
            if (intervalHandle !== null && currentMode === mode) return;
            if (intervalHandle !== null) clearInterval(intervalHandle);
            currentMode = mode;
            intervalHandle = window.setInterval(pollOnce, intervalFor(mode));
        };

        const stop = () => {
            if (intervalHandle !== null) {
                clearInterval(intervalHandle);
                intervalHandle = null;
            }
        };

        // 監聽 store 變化，overlay 顯示 ↔ 隱藏時切換 polling 模式
        const unsubscribe = useSystemStore.subscribe((state) => {
            const shouldActiveRetry = state.forcedOffline || state.consecutiveFailures >= 2;
            const targetMode = shouldActiveRetry ? 'active-retry' : 'normal';
            if (intervalHandle !== null && targetMode !== currentMode) {
                start(targetMode); // 自動切換 interval
            }
        });

        const onVisibilityChange = () => {
            if (document.visibilityState === 'visible') {
                void pollOnce(); // 立即 probe
                const s = useSystemStore.getState();
                const mode = s.forcedOffline || s.consecutiveFailures >= 2 ? 'active-retry' : 'normal';
                start(mode);
            } else {
                stop();
            }
        };

        // 初次載入時執行一次 probe + 啟動 normal 輪詢
        void pollOnce();
        if (document.visibilityState === 'visible') {
            start('normal');
        }

        document.addEventListener('visibilitychange', onVisibilityChange);
        return () => {
            document.removeEventListener('visibilitychange', onVisibilityChange);
            unsubscribe();
            stop();
        };
    }, []);
}
```

### 4.3a `frontend/src/hooks/use-shutdown-watcher.ts`（Minor 4 新增）

訂閱 server 的 WebSocket 廣播，接收 `server:shutdown-imminent` 事件後立即設 `forcedOffline`。

```typescript
'use client';

import { useEffect } from 'react';
import { useSystemStore } from '@/stores/system-store';
import { getBackendUrl } from '@/lib/api';

interface ShutdownImminentMessage {
    type: 'server:shutdown-imminent';
    reason: 'app-closing' | 'manual-stop' | 'restart' | 'quit';
    ts: number;
}

export function useShutdownWatcher(): void {
    useEffect(() => {
        const wsUrl = getBackendUrl().replace(/^http/, 'ws') + '/ws/system';
        let ws: WebSocket | null = null;
        let reconnectTimer: number | null = null;

        const connect = () => {
            try {
                ws = new WebSocket(wsUrl);
            } catch {
                scheduleReconnect();
                return;
            }
            ws.onmessage = (ev) => {
                try {
                    const msg = JSON.parse(String(ev.data));
                    if (msg?.type === 'server:shutdown-imminent') {
                        const reason = (msg as ShutdownImminentMessage).reason;
                        useSystemStore.getState().forceOffline(reason);
                    }
                } catch {
                    // 非 JSON 或格式錯誤，忽略
                }
            };
            ws.onclose = (ev) => {
                ws = null;
                // v2.1：WebSocket close 事件也視為 server 已斷，立即顯示 overlay
                // （比等 polling 失敗 20 s 更即時；若 server 正常重啟，成功 poll 後會自動清 overlay）
                // 只在「曾經連上」的前提下才觸發，避免初次連線就失敗導致誤觸發
                if (ev && ev.wasClean === false) {
                    const reason: 'app-closing' | 'manual-stop' | 'restart' | 'quit' = 'manual-stop';
                    useSystemStore.getState().forceOffline(reason);
                }
                scheduleReconnect();
            };
            ws.onerror = () => {
                // 忽略 — 後續 onclose 會處理
            };
        };

        const scheduleReconnect = () => {
            if (reconnectTimer !== null) return;
            reconnectTimer = window.setTimeout(() => {
                reconnectTimer = null;
                if (document.visibilityState === 'visible') {
                    connect();
                }
            }, 3000);
        };

        connect();

        return () => {
            if (reconnectTimer !== null) {
                clearTimeout(reconnectTimer);
                reconnectTimer = null;
            }
            if (ws) {
                ws.onclose = null;
                ws.onerror = null;
                ws.close();
                ws = null;
            }
        };
    }, []);
}
```

**server 端配合（server-lifecycle.md §8）**：`ctrl.Stop()` 開始時透過 server 的 WebSocket hub（建議新增 `/ws/system` endpoint 或沿用現有 `/ws/server-logs`）廣播該事件。

**注意**：此 hook 的 WebSocket 是從瀏覽器連到 server，與 Wails IPC 無關。Wails 端只需要在 `ctrl.Stop()` 時透過 HTTP / gRPC / 直接從 server 內呼叫 `hub.Broadcast(...)` 即可（具體做法視 server 內部 API 而定）。

### 4.4 `frontend/src/components/server-offline-overlay.tsx`

```tsx
'use client';

import { useSystemStore } from '@/stores/system-store';
import { useTranslation } from '@/lib/i18n';
import { Button } from '@/components/ui/button';
import { AlertTriangle } from 'lucide-react';

async function retryOnce() {
    // 重試 = 立即打一次 boot-id，若成功會自動清 failures
    try {
        const res = await fetch('/api/system/boot-id', { cache: 'no-store' });
        if (res.ok) {
            const json = await res.json();
            if (json.success && json.data?.bootId) {
                useSystemStore.getState().setOnline(json.data.bootId);
                return;
            }
        }
        useSystemStore.getState().recordFailure();
    } catch {
        useSystemStore.getState().recordFailure();
    }
}

export function ServerOfflineOverlay() {
    const show = useSystemStore((s) => s.forcedOffline || s.consecutiveFailures >= 2);
    const reason = useSystemStore((s) => s.forcedOfflineReason);
    const { t } = useTranslation();

    if (!show) return null;

    return (
        <div
            role="alertdialog"
            aria-labelledby="server-offline-title"
            className="fixed inset-0 z-[9999] flex items-center justify-center bg-black/65 backdrop-blur-sm"
        >
            <div className="w-full max-w-md rounded-lg border bg-background p-6 shadow-2xl">
                <div className="flex items-start gap-4">
                    <AlertTriangle className="h-8 w-8 shrink-0 text-amber-500" />
                    <div className="flex-1">
                        <h2 id="server-offline-title" className="mb-2 text-xl font-semibold">
                            {t('serverOffline.title')}
                        </h2>
                        <p className="mb-4 text-sm text-muted-foreground">
                            {t('serverOffline.body')}
                        </p>
                        <ul className="mb-4 list-disc pl-5 text-sm text-muted-foreground">
                            <li>{t('serverOffline.reasons.appClosed')}</li>
                            <li>{t('serverOffline.reasons.manuallyStopped')}</li>
                            <li>{t('serverOffline.reasons.crashed')}</li>
                        </ul>
                        <p className="mb-4 text-sm text-muted-foreground">
                            {t('serverOffline.instruction')}
                        </p>
                        <div className="flex gap-2">
                            <Button onClick={retryOnce}>{t('serverOffline.retry')}</Button>
                            <Button
                                variant="outline"
                                onClick={() => window.close()}
                            >
                                {t('serverOffline.closeTab')}
                            </Button>
                        </div>
                    </div>
                </div>
            </div>
        </div>
    );
}
```

### 4.5 `frontend/src/app/layout.tsx` 修改

```diff
+import { ServerOfflineOverlay } from '@/components/server-offline-overlay';
+import { BootIdWatcherMount } from '@/components/boot-id-watcher-mount';

 export default function RootLayout({ children }: { children: React.ReactNode }) {
     return (
         <html ...>
             <body ...>
                 {/* 既有的 providers / sidebar / theme 等 */}
                 {children}
+                <BootIdWatcherMount />
+                <ServerOfflineOverlay />
             </body>
         </html>
     );
 }
```

`BootIdWatcherMount` 是一個空的 `'use client'` 元件，作用只是掛 `useBootIdWatcher()`（hook 不能直接在 layout 的 server component 呼叫）：

```tsx
// frontend/src/components/boot-id-watcher-mount.tsx
'use client';
import { useBootIdWatcher } from '@/hooks/use-boot-id-watcher';
import { useShutdownWatcher } from '@/hooks/use-shutdown-watcher';

export function BootIdWatcherMount() {
    useBootIdWatcher();
    useShutdownWatcher(); // Minor 4：WebSocket shutdown-imminent 訂閱
    return null;
}
```

### 4.6 i18n 字串

**`frontend/src/lib/i18n/types.ts`** 新增：

```typescript
serverOffline: {
    title: string;
    body: string;
    reasons: {
        appClosed: string;
        manuallyStopped: string;
        crashed: string;
    };
    instruction: string;
    retry: string;
    closeTab: string;
};
```

**`frontend/src/lib/i18n/zh-TW.ts`**：

```typescript
serverOffline: {
    title: 'Server 已離線',
    body: 'visionA Local 的本機伺服器沒有回應。可能的原因：',
    reasons: {
        appClosed: '你關閉了 visionA Local 應用程式',
        manuallyStopped: 'Server 被手動停止',
        crashed: 'Server 發生錯誤',
    },
    instruction: '請重新開啟 visionA Local 應用程式後按「重試」。',
    retry: '重試',
    closeTab: '關閉這個頁面',
},
```

**`frontend/src/lib/i18n/en.ts`**：

```typescript
serverOffline: {
    title: 'Server Offline',
    body: 'The visionA Local server is not responding. Possible reasons:',
    reasons: {
        appClosed: 'You closed the visionA Local app',
        manuallyStopped: 'Server was manually stopped',
        crashed: 'Server encountered an error',
    },
    instruction: 'Please relaunch visionA Local and click "Retry".',
    retry: 'Retry',
    closeTab: 'Close this tab',
},
```

---

## 5. SSR 相容性

Next.js 的 `static export` 會在 build 階段把頁面 render 成 HTML。以下程式碼都必須處理 SSR（`typeof window === 'undefined'` 情境）：

- `use-boot-id-watcher.ts` — 標 `'use client'`，只在瀏覽器 run，OK
- `server-offline-overlay.tsx` — 標 `'use client'`，OK
- `system-store.ts` — Zustand 不需 `'use client'`，但 store 只被 client component 使用，OK
- `boot-id-watcher-mount.tsx` — `'use client'`，OK

**驗收**：`pnpm build` 在 frontend/ 目錄下要成功，沒有 `ReferenceError: window is not defined` 或其他 SSR 錯誤。

---

## 6. 與 ServerController 事件的關係（v2.1 更新）

Wails 控制台的 log panel 會收到 `server:state-change` 事件並更新狀態卡片；**瀏覽器 tab 無法收到 Wails event**（不同 context）。瀏覽器的真相來源有三個，優先序由高到低：

1. **WebSocket `server:shutdown-imminent`（最即時，v2.1 Minor 4 新增）**：Wails 的 `ctrl.Stop()` 在開始 SIGTERM 前透過 server 的 WebSocket hub 廣播，瀏覽器 tab 幾乎同時收到 → 立即顯示 overlay
2. **`GET /api/system/boot-id` polling**：
   - 成功 + bootId 變 → `window.location.reload()`（server 重啟後同 port）
   - 連續 2 次失敗 → 顯示 overlay（fallback，當 WebSocket 已斷或未建立）
3. **業務 API 呼叫的 network error**：次要，不當作 overlay 觸發器（避免單一 API 問題誤觸發）

Wails → server → WebSocket → 瀏覽器 的路徑：Wails 只與 server 進程通訊（透過 stdin/stdout 或 HTTP），server 再轉發到 WebSocket hub 廣播給所有連線 tab。這是單向 push，比 polling 更即時。

---

## 7. 驗收條件

| 檢查 | 操作 | 預期 |
|------|------|------|
| 正常啟動沒 overlay | 開 app → 點 Open in Browser → tab 載入 | overlay 不顯示 |
| 關 Wails → 立即顯示 overlay（WebSocket 管道）| 開 app → Open in Browser → 關 Wails 視窗 | < 1 s 內 tab 顯示 overlay（WebSocket `shutdown-imminent` 或 `onclose` 觸發）|
| 關 Wails → polling fallback | 同上但 WebSocket 未建立（mock） | 20 s 內 tab 顯示 overlay（連續 2 次 10 s poll 失敗）|
| 關 Wails → 瀏覽器 tab 顯示正確訊息 | 同上 | 看到 title「Server 已離線」 |
| Active retry 模式自動重試 | Overlay 顯示後 | 前端自動每 3 s 打 boot-id（非使用者手動按）|
| Overlay 重試按鈕 | server 關著時點「重試」 | failures +1 或維持（視結果），overlay 仍在 |
| 重試 → 成功 | 關 app → 等 overlay → 重開 app | Active retry 3 s 內自動 dismiss overlay；若 bootId 變則 reload |
| 控制台按 Restart → 自動 reload | server running → 在 Wails 按 Restart → 3 s 後 server 回來 | tab 自動 `window.location.reload()`，載入後正常；期間不顯示 overlay（`restart` reason 延遲 10 s）|
| 控制台按 Stop → 立即 overlay | Stop | WebSocket 廣播 `manual-stop` → 立即顯示 overlay |
| 背景 tab 不浪費資源 | 切到別的 tab → `chrome://performance-metrics` | tab 不在時 setInterval 停（visibility hidden） |
| 切回背景 tab → 立即 probe | 切回 tab | 立即打 boot-id，不等 10 s interval |
| 網路 glitch < 10 s 不顯示 | 人工用 DevTools Network → Offline 8 s → Online | overlay 不顯示（最多 1 次失敗，未達 2 次門檻） |

---

## 8. 待確認

1. **`window.close()` 在非 `window.open()` 開的 tab 不能用** — 使用者從 Wails Open in Browser 進來的 tab 確實是 browser 自己開的，不是 `window.open`，Chrome 會拒絕 `window.close()`。備案：把「關閉這個頁面」按鈕改為顯示「請手動關閉此分頁」提示。M8-7 執行者實測後決定 UI 文案。
2. **boot-id cache header** — 目前用 `cache: 'no-store'`，但某些 Chrome 版本會忽略。若發現 polling 拿到快取值（bootId 不變），改加 `?_=Date.now()` query 防快取。
3. **Overlay z-index 衝突** — 9999 高於 shadcn Dialog 的 50，應夠。若未來有其他「更上層」元件要放，確認 z-index layering。