觀察

電子書庫總覽 Chrome 擴充功能（book_overview_v1，Manifest V3 — Chrome 擴充平台的現行規格版本）的提取流程：popup 觸發 content script 擷取書目、寫入 storage、回報結果。實機測試中 content script 成功提取 96 本且 storage 已寫入，popup UI 卻顯示「提取失敗 / 未知錯誤」。

根因在訊息通道語意（commit 97c24b2b6）：橋接模組的 message listener 宣告成 async。收到非它負責的訊息型別時函式體直接結束，async 函式回傳 Promise.resolve(undefined) — Manifest V3 把「listener 回傳 Promise」解讀為「此 listener 負責回應」，把 undefined 搶先送回 popup，與真正處理該訊息的 listener 競爭。popup 拿到 undefined、走 else 分支拋「未知錯誤」。

修復：listener 改為同步函式，非處理訊息回傳 undefined（不搶通道）、async 邏輯抽成 fire-and-forget handler。

同一條鏈路的另一個斷點（commit a62ce00d8）：訊息路由的 handler 沒被注入、事件協調器沒被啟動，EXTRACTION.COMPLETED 事件沒有任何訂閱者 — 提取完成但資料未儲存、popup 連線失敗。鏈路斷的位置不同（組裝遺漏 vs 通道語意），使用者看到的都是「操作沒有結果」。

判讀

1. 結果通知有一個隱含前提：結果會正確到達 UI。回饋設計通常聚焦「到達之後怎麼呈現」（訊息形式、通知元件），但 popup / content script / service worker 是三個獨立 context，結果要跨兩次訊息通道才到 UI — 每一跳都是回饋鏈路的一部分，通道語意錯誤等於回饋設計全部白做。

2. 成功誤報失敗比沒有回饋更糟。零回饋讓使用者困惑；誠實度反轉讓使用者採取錯誤行動 — 重做一次提取（資料重複）、回報 bug、放棄使用。UI 的宣告與系統實際狀態相反時，使用者對介面的每一個訊息都會失去信任。

3. 通道語意是平台契約、不是實作細節。「listener 回傳 Promise = 認領回應權」是 Manifest V3 在較新版 Chrome 的行為（更早版本會忽略回傳的 Promise、通道靜默關閉 — 兩種行為下，共享通道上的 async listener 都是錯的），混用 async 語法糖與訊息協定就會觸發。這類契約在單元測試中不可見（mock 掉通道）、只有整合層才會現形。

策略

1. 結果通知鏈路要有端對端驗證：「操作成功 → UI 顯示成功」作為整合測試斷言，涵蓋跨 context 的完整鏈路，不只測 UI 元件收到資料後的呈現。

2. 通道上的每個 listener 明確宣告回應權：負責回應的同步回傳 true 保持通道、不負責的不回傳 — async listener 在共享通道上是候選錯誤。

3. 事件鏈路的組裝有清單：事件的發佈者與訂閱者在啟動時逐一核對（handler 已注入、coordinator 已啟動），組裝遺漏讓事件無聲消失。

下一步路由

• 結果通知該呈現什麼 → 互動回饋三層模型
• 類似案例（UI 未接線、三層回饋全缺）→ U.C5 匯出按鈕零回饋
• 完成宣告的證據強度 → U.C11 抓到 96/928 本就顯示完成

觀察

電子書庫總覽 Chrome 擴充功能（book_overview_v1）的 popup 開啟時向 background service worker 查詢狀態。Manifest V3 的 service worker 是事件驅動、閒置即卸載 — popup 開啟的瞬間 SW 可能正在冷啟動、初始化未完成、不回應 GET_STATUS。popup 等待期間顯示「正在檢查狀態…」，2 秒 timeout 後轉為「離線」且不再自動恢復 — 冷啟動偶爾超過 2 秒（極端 I/O、低階裝置，低頻但真實發生過）時，系統實際正常、使用者看到的卻是永久離線（src/background/background.js:272-284，ticket 1.1.0-W1-019）。

修復採雙管：查詢端加握手重試，加上被查詢端在初始化期間就回應 baseline 的 initializing 狀態 — popup 據此顯示「初始化中」而非落入 timeout 判離線。

同專案的另一起同型事故（commit 86216c37f）：popup 的書籍偵測數硬編「檢測中…」、從未讀取健康查詢回應中的實際數字 — 過渡狀態的顯示寫死了、永遠停在過渡態。兩個事故一體兩面：一個把「還不知道」誤顯示成終態（離線）、一個把終態永遠顯示成「還不知道」。

判讀

1. 「還不知道」與「不可用」是不同狀態。離線 / 錯誤是查詢得到的答案，initializing 是還沒得到答案。合併兩者的畫面會把「這次醒得慢」定格成永久離線 — 頻率低不減輕代價，使用者據此做錯誤決策：放棄操作、重裝、回報故障。

2. 查詢對象的生命週期決定 initializing 是否必要。查詢對象與畫面同生命週期（同 process 的本地狀態）時不需要；查詢對象獨立生死（service worker、遠端服務、另一個 process、外部裝置）時，畫面開啟瞬間對方「還沒醒」是常態而非邊角 — initializing 必須是狀態矩陣裡的一行，有自己的顯示、操作與退出路徑。

3. timeout 是 initializing 的退出路徑。「初始化中」不能無限停留 — 超過合理時間仍無回應才轉入離線 / 錯誤狀態。順序是 initializing → (回應) 正常態 / (timeout) 離線，而非直接顯示離線等回應來救。

策略

1. 列狀態時多問一句：這個畫面查詢的對象，跟畫面同生命週期嗎？不同 → 補 initializing 狀態進矩陣。

2. 被查詢方在初始化期間就能回應 baseline 狀態 — 「我在、還沒準備好」與「沒有回應」對查詢方是完全不同的資訊。

3. 過渡狀態的顯示必須有資料來源與退出條件 — 硬編的「檢測中…」沒有讀任何回應、也永遠不會離開，等於把過渡態寫成死胡同。

下一步路由

• 狀態矩陣的四欄與填寫步驟 → 畫面狀態矩陣的定義與填寫方法
• 等待多久該顯示什麼指示 → 時間感知與回應策略
• 類似案例（狀態設計遺漏）→ U.C1 五個狀態零個退出路徑

觀察

電子書庫總覽 Chrome 擴充功能（book_overview_v1）從 lazy-load 書庫頁提取書目。提取器的兩種載入策略（捲動容器 / 點擊「更多…」按鈕）設計成二擇一，實機上容器 selector 恆先命中，「更多…」按鈕分支永不執行；首批 96 本載入後 count 連續 3 輪不變，觸發 count_stable 條件判定完成 — 實際書庫有 928 本，提取器在 96 本就宣告成功結束（commit 9d0556e1b，W1-030 / W1-040）。

修復：每輪同時捲動＋點擊按鈕（不再二擇一），涵蓋率從 96/928 提升到 928/928 — 可見書目全數取得（全書庫 944 本、其餘為封存借出、不在可見清單）。

判讀

1. count 穩定是「沒有變化」、不是「沒有更多」。lazy-load 頁面的內容增長依賴特定觸發動作（捲動、點按鈕）— 觸發動作缺失時 count 永遠穩定，穩定訊號分不出「真的到底了」和「載入通道根本沒打開」。完成判定缺一個獨立的窮盡證據：頁面宣告的總數、終止標記（「沒有更多了」元素）、載入觸發器消失、或 API 側的窮盡宣告（分頁 cursor 耗盡、has_more=false）。

2. 誤報完成比報錯更難察覺。提取失敗使用者會重試；「成功提取 96 本」看起來一切正常，使用者帶著殘缺資料做下游決策（統計、匯出、比對），錯誤在離開這個畫面很久之後才浮現、且很難回溯到提取階段。

3. 有總數可對照時，缺口是可偵測的。頁面顯示 928 本、提取到 96 本 — 10 倍差距在有對照數字時一眼可見。判定邏輯沒有利用這個訊號，是證據源的遺漏、不是證據不存在。

策略

1. 完成判定列出證據清單：宣告完成前問「終止條件是『確認沒有更多』還是『暫時沒變化』」。只有停滯訊號時，完成宣告降級為「已取得 N 筆、可能還有更多」的誠實表達。降級的適用邊界：下游需要全量的操作（備份、匯出、合規留存）不適用部分結果 — 這類場景把不完整按失敗處理、阻止下游動作。

2. 利用對照數字做完整性檢查：來源有總數（頁面計數、API total）時，提取數與總數的比對是最便宜的誤報偵測 — 差距大時不宣告完成、改報部分結果與原因。

3. 多策略遍歷用並行不用二擇一：載入觸發方式不確定時每輪全部嘗試，單一策略的 selector 誤命中不會關閉其他通道。

下一步路由

• 進度指示與假進度反模式 → 時間感知與回應策略
• 結果通知的呈現（部分成功的摘要 + 明細）→ 互動回饋三層模型
• 類似案例（結果通知鏈路錯誤）→ U.C9 提取成功卻誤報失敗

觀察

電子書庫總覽 Chrome 擴充功能（book_overview_v1）的匯入功能有覆蓋 / 合併兩種模式；覆蓋模式的語意是「以檔案內容取代現有書庫」— 該模式下匯入空檔等於清空全部資料。設計（src/overview/import-flow-controller.js，W1-049）：

1. 覆蓋模式下偵測到匯入內容為空時，彈出專屬確認 Modal 描述後果（現有書庫非空時文案帶具體數字「將清空現有 N 本書」）、使用者明確確認才執行；合併模式不觸發這道確認。
2. Modal 帶 aria-labelledby / aria-describedby，螢幕閱讀器使用者能取得完整的後果描述。
3. 關鍵設計：確認 Modal 的 DOM 元件缺失時，視為使用者未確認、預設不清空。確認機制故障不會讓破壞性操作靜默通過。

判讀

1. 破壞性操作 gate 是 gate 的一個獨立類型。認證 / 網路 / 權限 gate 攔「使用者能不能繼續」，破壞性操作 gate 攔「使用者是否理解後果」— 觸發條件不是身分或環境、是操作的破壞半徑（不可逆、影響既有資料、影響範圍大於使用者的直覺預期）。「匯入」聽起來是加法、覆蓋模式的實際語意是取代 — 語意與直覺預期的落差越大、越需要確認。

2. 確認機制本身有故障模式。元件沒渲染、事件沒綁上、動態載入失敗 — 確認 UI 故障時系統要選一個預設方向：執行（把故障當同意）或不執行（把故障當拒絕）。安全預設的原則是倒向不可逆性低的那邊：不清空可以重試匯入、清空無法還原。這與「fail-open vs fail-closed」的安全設計同構。

3. 確認對話框的可及性是 gate 有效性的一部分。看不到後果描述的確認（螢幕閱讀器讀不出 Modal 內容）等於沒有確認 — 使用者按了「確定」但不知道確定了什麼。

策略

1. 識別破壞性操作：列出所有會覆蓋 / 刪除 / 取代既有資料的操作，語意與直覺預期有落差的是高風險項（匯入的覆蓋模式 = 取代、同步 = 可能覆蓋、重設 = 清空）。

2. 確認 UI 描述後果、不只問「確定嗎」：帶上具體數字（「將清空現有 N 本書」）讓使用者對照自己的預期。

3. 為確認機制設計故障預設：確認元件不存在 / 事件未觸發 / 回應逾時，一律視為未確認。程式碼層的檢查訊號：確認邏輯的 else / null 分支走向哪邊。

下一步路由

• Gate 的必答問題與類型 → Gate 分類與三問設計法
• 確認機制故障的預設方向 → Fail-safe 預設
• 通知形式的干擾程度判準（Dialog 的阻斷性是設計需求）→ 通知模式選擇
• 對照案例（gate 缺 fallback）→ U.C2 biometricOnly 無 fallback

觀察

電子書庫總覽 Chrome 擴充功能（book_overview_v1）的匯入功能出錯時（檔案格式錯誤、內容不合法），錯誤顯示複用了 popup 的通用 errorContainer — 這個容器是為擴充功能執行層錯誤設計的，帶「重新載入擴充功能」按鈕。使用者回饋指出：Chrome Web Store 上架版對「匯入錯誤」不該出現 reload extension 按鈕（commit 72cd5f370）。

修復：建匯入專屬的 importErrorContainer，只有「關閉」按鈕（沒有 retry / reload）— 匯入錯誤的正確下一步是換一個檔案再試，不是重載執行環境；同時把文案集中到 IMPORT_MESSAGES 常數、移除對通用錯誤處理器的依賴。

判讀

1. 錯誤有層級、行動也有層級。檔案格式錯誤是資料層、訊息通道斷線是通訊層、service worker 崩潰是執行環境層。行動同樣分層：換檔案重試（資料層）、重新連線（通訊層）、重載擴充功能（執行環境層）。對位原則：行動解決的層級 = 錯誤發生的層級。層級過重的行動不解決問題（重載擴充功能不會讓壞檔案變好）、還附帶代價（狀態遺失、流程中斷）。

2. 通用錯誤容器是不對位的結構性來源。為最嚴重錯誤設計的容器（帶最重的行動）被所有錯誤複用時，輕錯誤自動繼承重行動。錯誤 UI 的複用要以「行動相容」為邊界、不是以「都是錯誤」為邊界。

3. 使用者會照著按鈕走。錯誤畫面上的按鈕是系統給的行動建議，使用者傾向直接採納 — 不對位的按鈕等於系統主動引導使用者做無效且有代價的操作。

策略

1. 對每個錯誤 UI 的行動清單問一句：這個行動解決的層級，等於這個錯誤發生的層級嗎？過重（重載 / 重啟 / 重裝出現在資料層錯誤）與過輕（執行環境崩潰只給「關閉」）都是缺口。

2. 錯誤容器按行動分組：行動集合不同的錯誤用不同容器 / 元件，避免複用時行動一起被繼承。

3. 文案與行動集中管理：錯誤訊息散在 HTML 各處時，行動不對位很難被掃描發現；集中成常數表後「哪類錯誤配哪些行動」一眼可查。

下一步路由

• 錯誤訊息的診斷與行動職責 → 錯誤訊息撰寫原則
• 重試行動的設計 → Retry 機制 UX
• 對照案例（行動缺失 — 只有重試沒有退路）→ U.C1 五個狀態零個退出路徑

觀察

電子書庫總覽 Chrome 擴充功能（book_overview_v1）的 popup 顯示「目前所在的目標網站頁面」標籤。目標平台 Readmoo 是 hash-based SPA — 書庫頁的 URL 是 read.readmoo.com/#/library，路由資訊在 # 之後。popup 用 URL.pathname 取頁面路徑，pathname 永遠是 /，所有頁面都被顯示成根路徑、無法辨識使用者目前在哪一頁（commit a27de860e）。

修復：改用 pathname + hash 組合顯示；補三類 URL 的解析測試（hash SPA /#/library、根路徑 /、傳統 path /account）；並掃描全 codebase 確認 pathname-only 邏輯只影響顯示標籤、無 functional 用途。

判讀

1. web 路由有兩套並存的慣例。path-based（/library、伺服器路由或 History API）與 hash-based（/#/library、fragment 路由）。「目前在哪頁」的判斷邏輯只支援其中一套時，另一套的所有頁面都會塌縮成同一個值 — 塌縮是靜默的，pathname 讀 hash SPA 不會報錯、只會永遠回傳 /。

2. 跨 app 邊界讀 URL 時，對方的路由慣例是輸入規格。擴充功能、爬蟲、分析工具讀取宿主頁面的 URL — 宿主用哪套路由不受讀取方控制、還會隨對方改版變動。辨識邏輯要把「對方是哪種路由形態」當成必須確認的規格項，不能假設「URL 的頁面資訊都在 path」。

3. 顯示層的錯位是低嚴重度、但同一邏輯的 functional 用途是高嚴重度。這個案例只影響標籤顯示；同樣的 pathname-only 邏輯若用於「判斷是否在可提取頁面」，會讓功能在所有頁面都誤判。修復時的全 codebase 掃描（確認無 functional 用途）就是在排除這個升級風險。

策略

1. 依 URL 辨識頁面的功能，列出目標的路由形態：path-based / hash-based / 混合，測試各涵蓋一組 URL。

2. 取「完整路由」用 pathname + hash 組合，只在確認目標是純 path-based 時才省略 fragment；組合前先確認 fragment 承載的是路由還是頁內錨點 — path-based 站的 #section 是錨點、不是頁面。

3. 發現一處路由辨識錯誤時，掃描同 pattern 的所有用途 — 顯示用途與 functional 用途的嚴重度不同，修復範圍要以掃描結果為準、不是以回報的症狀為準。

下一步路由

• Deep link 的 URL 結構設計 → Deep link 設計
• 導航模式與宣告式路由 → Mobile 導航模式分類
• 類似案例（外部頁面結構是輸入規格 — 提取器對 lazy-load 的假設）→ U.C11 抓到 96/928 本就顯示完成