fix(pwa): 離線時沒快取的頁面掉到瀏覽器錯誤畫面，不是站台的離線頁 (#270)

「清除所有離線內容」把 Cache Storage 整個清光，離線提示頁本身也在裡面。清完之後
自動預快取是關的，所以那一頁不會被補回來，於是任何沒快取過的網址在離線時都會一路
走到 networkFirst 最後的 throw，respondWith 跟著 reject，讀者看到的是瀏覽器自己的
網路錯誤畫面。

同一個狀況也發生在「讀者自己把自動存下核心章節關掉」的情況，那時整個站在離線時
都沒有說明頁可看。

改法是把「沒有網路時至少要有的那一小批」拉出來，不受那個開關管：離線提示頁本身，
加上撐得起它的 app shell（含頁面索引與管理頁的程式）。共 10 個 URL、0.51 MB，
相對於完整章節的十 MB 是可以接受的底線。

留這一批的理由不只是體面。那一頁就是離線內容管理頁，讀者想清掉裝置上的東西、或想
知道自己還有哪些內容可讀，往往正好是連不上網的時候，那一頁進不去的話整個功能等於
不存在。

precacheFor 現在自己判斷開關要抓多少，install 與 PRECACHE_LANG 兩個呼叫端不再各自
檢查。三語系的管理頁文案與 offline.md 都說明了這一批的存在與大小。
check_precache.mjs 多報一行，數字有工具可查。

測試從 26 項加到 32 項。原本 networkFirst 的 fallback 鏈一項都沒測到，這次補上四項
（離線落到離線頁、有快取就不落、各語系落到自己那份、連離線頁都沒有才丟錯誤），
清除相關的兩項改成驗證底線會補回而章節不會。反向驗證確認拿掉離線提示頁會讓兩項變紅。

端到端另外用 headless Chrome 走過一遍：清除、重新上站（precache 補回 10 筆）、
關掉本機 server、導覽到從未造訪的網址，拿到的是「離線閱讀」頁。

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: toomore

docs/en/offline.md

@@ -26,7 +26,9 @@ Scenario pages for journalists, activists, LGBTQ+ readers and survivors of domes
 
 The reading language you pick from the language menu is stored in the same place. The site uses it to decide which language version to open when you arrive at the home page next time, and for nothing else. The language your browser reports is never read: on Tor Browser that value is always English, so acting on it would send readers in Taiwan to the English version.
 
-"Clear all offline content" above removes both what the site stored and what you picked, and stops the site from storing anything new. Turn the switch back on above to resume automatic storage.
+"Clear all offline content" above removes both what the site stored and what you picked, and stops the site from storing new chapters. Turn the switch back on above to resume.
+
+This page itself and the styles it needs are outside that switch, and come back the next time you are online (about 0.5 MB). They stay because the moment you want to clear what is on the device, or check what is still readable, is often the moment you have no connection, and without this page all that is left is the browser error screen.
 
 What that button does not cover: browsing history, DNS cache, and files you downloaded from the site. Handle those in your browser or system settings. In Chrome this is Clear browsing data. In Firefox it is Clear recent history with "Cookies and site data" ticked under the details. Selecting only "Cached images and files" does not remove site storage.
 

docs/zh-CN/offline.md

@@ -26,7 +26,9 @@ hide:
 
 你在语言菜单选过的阅读语言也存在同一个地方，站台用它决定下次从首页进来时打开哪一个语言版本，除此之外不会拿去做别的事。站台不会读取浏览器报告的语言，那个值在 Tor Browser 上一律是英文，照着判断会把台湾读者带去英文版。
 
-上面的「清除所有离线内容」会把站台存的与你自己选的一起清掉，并停止自动存新的东西。要恢复自动存，回到上面把开关打开即可。
+上面的「清除所有离线内容」会把站台存的与你自己选的一起清掉，并停止自动存新的章节。要恢复，回到上面把开关打开即可。
+
+这一页本身与它需要的样式不受那个开关管，下次连上网时会补回来（约 0.5 MB）。留着它是因为想清掉设备上的东西、或想看还有哪些内容可读的时候，往往正好是连不上网的时候，那时这一页进不去的话就只剩浏览器的错误画面。
 
 那颗按钮清不掉的东西：浏览记录、DNS 缓存，以及你从站上下载过的文件。那些要在浏览器或系统设置里处理。Chrome 是设置的「清除浏览数据」，Firefox 是「清除最近的历史记录」并展开细项勾选「Cookie 和网站数据」。只勾「缓存的图片和文件」清不掉网站存储这一类。
 

docs/zh-TW/js/offline-library.js

@@ -110,13 +110,13 @@
       usage: "本站在這台裝置上佔用 {used}",
       usageFree: "本站在這台裝置上佔用 {used}，可用空間還有 {free}",
       autoLabel: "自動存下目前語言的核心章節",
-      autoHint: "關掉之後，站台不會再自動存任何東西，只保留你自己勾選的。",
+      autoHint: "關掉之後就不再自動存章節。這一頁本身與它需要的樣式仍會留著（約 0.5 MB），沒有網路時你才進得來。你自己勾的頁面不受影響。",
       refresh: "更新已存的內容",
       refreshing: "更新中",
       clear: "清除所有離線內容",
       clearAgain: "再按一次就清除",
       clearing: "清除中",
-      cleared: "已清除。瀏覽記錄、DNS 快取與你下載過的檔案不在清除範圍內，那些要在瀏覽器或系統裡處理。",
+      cleared: "已清除，自動存下章節也一併關掉了。下次連上網時會補回這一頁本身與它需要的樣式（約 0.5 MB），讓你在沒有網路時仍進得來。瀏覽記錄、DNS 快取與你下載過的檔案不在清除範圍內，那些要在瀏覽器或系統裡處理。",
       apply: "套用變更",
       applying: "處理中",
       pending: "待新增 {add} 頁，待移除 {remove} 頁",
@@ -139,13 +139,13 @@
       usage: "本站在这台设备上占用 {used}",
       usageFree: "本站在这台设备上占用 {used}，可用空间还有 {free}",
       autoLabel: "自动存下当前语言的核心章节",
-      autoHint: "关掉之后，站台不会再自动存任何东西，只保留你自己勾选的。",
+      autoHint: "关掉之后就不再自动存章节。这一页本身与它需要的样式仍会留着（约 0.5 MB），没有网络时你才进得来。你自己勾的页面不受影响。",
       refresh: "更新已存的内容",
       refreshing: "更新中",
       clear: "清除所有离线内容",
       clearAgain: "再按一次就清除",
       clearing: "清除中",
-      cleared: "已清除。浏览记录、DNS 缓存与你下载过的文件不在清除范围内，那些要在浏览器或系统里处理。",
+      cleared: "已清除，自动存下章节也一并关掉了。下次连上网时会补回这一页本身与它需要的样式（约 0.5 MB），让你在没有网络时仍进得来。浏览记录、DNS 缓存与你下载过的文件不在清除范围内，那些要在浏览器或系统里处理。",
       apply: "应用变更",
       applying: "处理中",
       pending: "待新增 {add} 页，待移除 {remove} 页",
@@ -168,13 +168,13 @@
       usage: "This site uses {used} on this device",
       usageFree: "This site uses {used} on this device, with {free} still available",
       autoLabel: "Automatically store the core chapters for the current language",
-      autoHint: "Turn this off and the site stores nothing on its own. Only what you tick stays.",
+      autoHint: "Turning this off stops the site from storing chapters. This page itself and the styles it needs stay (about 0.5 MB), so you can still get here without a network. Pages you ticked are unaffected.",
       refresh: "Update what is stored",
       refreshing: "Updating",
       clear: "Clear all offline content",
       clearAgain: "Press again to clear",
       clearing: "Clearing",
-      cleared: "Cleared. Browsing history, DNS cache and files you downloaded are not covered here. Handle those in your browser or system settings.",
+      cleared: "Cleared, and automatic storage of chapters is off. Next time you are online, this page itself and the styles it needs come back (about 0.5 MB) so you can still reach it without a network. Browsing history, DNS cache and files you downloaded are not covered here. Handle those in your browser or system settings.",
       apply: "Apply changes",
       applying: "Working",
       pending: "{add} to add, {remove} to remove",

docs/zh-TW/offline.md

@@ -26,7 +26,9 @@ hide:
 
 你在語言選單選過的閱讀語言也存在同一個地方，站台用它決定下次從首頁進來時開哪一個語言版本，除此之外不會拿去做別的事。站台不會讀取瀏覽器回報的語言，那個值在 Tor Browser 上一律是英文，照著判斷會把台灣讀者帶去英文版。
 
-上面的「清除所有離線內容」會把站台存的與你自己選的一起清掉，並停止自動存新的東西。要恢復自動存，回到上面把開關打開即可。
+上面的「清除所有離線內容」會把站台存的與你自己選的一起清掉，並停止自動存新的章節。要恢復，回到上面把開關打開即可。
+
+這一頁本身與它需要的樣式不受那個開關管，下次連上網時會補回來（約 0.5 MB）。留著它是因為想清掉裝置上的東西、或想看還有哪些內容可讀的時候，往往正好是連不上網的時候，那時這一頁進不去的話就只剩瀏覽器的錯誤畫面。
 
 那顆按鈕清不掉的東西：瀏覽記錄、DNS 快取，以及你從站上下載過的檔案。那些要在瀏覽器或系統設定裡處理。Chrome 是設定的「清除瀏覽資料」，Firefox 是「清除近期歷史」並展開細項勾選「Cookie 和網站資料」。只勾「快取的圖片和檔案」清不掉網站儲存這一類。
 

docs/zh-TW/sw.js

@@ -328,6 +328,22 @@ function precacheUrlsFor(prefix) {
   return urls;
 }
 
+// 沒有網路時至少要有的那一小批：離線提示頁本身，加上撐得起它的 app shell。
+//
+// 為什麼不受「自動存下核心章節」的開關管：那一頁就是離線內容管理頁。讀者想清掉
+// 裝置上的東西、或想知道自己還有哪些內容可讀，往往正好是連不上網的時候，那一頁
+// 進不去的話整個功能等於不存在。少了它，沒快取過的網址在離線時會一路走到
+// networkFirst 最後的 throw，讀者看到的是瀏覽器自己的網路錯誤畫面。
+//
+// 這一批約 0.5 MB，相對於完整章節的十 MB 是可以接受的底線。
+function essentialUrlsFor(prefix) {
+  const urls = [SCOPE_PATH + prefix + "offline/"];
+  for (const asset of SHELL_ASSETS) {
+    urls.push(SCOPE_PATH + prefix + asset);
+  }
+  return urls;
+}
+
 // 這個 SW 生命週期內已經補過的語系。每次導覽 client 都會送 PRECACHE_LANG 過來，
 // 沒有這層就要對七十幾個網址各做一次 cache.match 才知道沒事可做。SW 被瀏覽器終止
 // 後清空，下次重跑一輪也只是白查一次，不會抓重複的東西。
@@ -336,12 +352,15 @@ const precachedPrefixes = new Set();
 // 補齊某個語系的預快取。已經在快取裡的跳過，所以換語系時只會抓新的那一份，作品
 // 本體與抓過的東西不重來。
 async function precacheFor(prefix) {
-  if (precachedPrefixes.has(prefix)) return;
-  precachedPrefixes.add(prefix);
+  // 讀者關掉自動存或清空過內容時只補底線那一批，不抓完整章節
+  const full = await autoPrecacheEnabled();
+  const done = prefix + (full ? " full" : " essential");
+  if (precachedPrefixes.has(done)) return;
+  precachedPrefixes.add(done);
   const cache = await caches.open(PRECACHE);
   // 逐一快取並容忍個別失敗（本地開發只有單一語系，其他語系路徑會 404）
   await Promise.allSettled(
-    precacheUrlsFor(prefix).map(async (url) => {
+    (full ? precacheUrlsFor(prefix) : essentialUrlsFor(prefix)).map(async (url) => {
       if (await cache.match(url)) return;
       const response = await fetch(url, { credentials: "same-origin" });
       if (response.ok) await cache.put(url, response);
@@ -386,7 +405,6 @@ async function guessLangPrefix() {
 self.addEventListener("install", (event) => {
   event.waitUntil(
     (async () => {
-      if (!(await autoPrecacheEnabled())) return;
       const prefix = await guessLangPrefix();
       if (prefix !== null) await precacheFor(prefix);
       // 這裡刻意不呼叫 skipWaiting。原本一裝好就搶著接管，讀者正在讀的分頁會在毫無
@@ -537,11 +555,7 @@ self.addEventListener("message", (event) => {
   if (data.type === "PRECACHE_LANG" && typeof data.url === "string") {
     const prefix = langPrefixOf(new URL(data.url));
     if (prefix !== null) {
-      event.waitUntil(
-        (async () => {
-          if (await autoPrecacheEnabled()) await precacheFor(prefix);
-        })()
-      );
+      event.waitUntil(precacheFor(prefix));
     }
     return;
   }

tools/check_precache.mjs

@@ -57,12 +57,14 @@ const harness = `
   ${grab(/^const GAME_APPS = \[[\s\S]*?\n\];/m)}
   ${grab(/^const CORE_PAGES_BY_PREFIX = \{[\s\S]*?\n\};/m)}
   ${grab(/^function precacheUrlsFor\(prefix\) \{[\s\S]*?\n\}/m)}
+  ${grab(/^function essentialUrlsFor\(prefix\) \{[\s\S]*?\n\}/m)}
   ${grab(/^function cacheKeyCandidates\(pathname\) \{[\s\S]*?\n\}/m)}
   // 執行期一次只預快取一個語系，檢查要涵蓋全部，所以逐一跑過再合併
   const byPrefix = LANG_PREFIXES.map((prefix) => [prefix, precacheUrlsFor(prefix)]);
-  return { byPrefix, games: GAME_APPS.length, cacheKeyCandidates };
+  const essential = essentialUrlsFor("");
+  return { byPrefix, essential, games: GAME_APPS.length, cacheKeyCandidates };
 `;
-const { byPrefix, games, cacheKeyCandidates } = new Function(harness)();
+const { byPrefix, essential, games, cacheKeyCandidates } = new Function(harness)();
 // 作品本體每個語系的清單裡都有，合併時去重
 const urls = [...new Set(byPrefix.flatMap(([, list]) => list))];
 
@@ -98,6 +100,9 @@ for (const [prefix, list] of byPrefix) {
 // 作品本體單獨報一次，那是最容易漏補的一批
 const gameUrls = urls.filter((u) => u.startsWith('/docs/games/') && !u.endsWith('/games/'));
 console.log(`  其中三件互動作品 ${mb(sizeOf(gameUrls))}（${games} 個檔案，三語共用）`);
+// 讀者關掉自動存或清空過內容時只會有這一批。少了它離線就沒有站台的說明頁可看，
+// 落到瀏覽器自己的錯誤畫面，所以它不受那個開關管。
+console.log(`  關掉自動存時仍保留的底線 ${mb(sizeOf(essential))}（${essential.length} 個 URL）`);
 console.log(`  全部語系去重後 ${mb(bytes)}，這是底下兩道檢查涵蓋的範圍`);
 
 // 索引頁連出去的網址形狀，要能命中預快取的 key

tools/test_sw_offline.mjs

@@ -108,6 +108,7 @@ const harness = `
   ${grab(/^const GAME_APPS = \[[\s\S]*?\n\];/m)}
   ${grab(/^const CORE_PAGES_BY_PREFIX = \{[\s\S]*?\n\};/m)}
   ${grab(/^function precacheUrlsFor\(prefix\) \{[\s\S]*?\n\}/m)}
+  ${grab(/^function essentialUrlsFor\(prefix\) \{[\s\S]*?\n\}/m)}
   ${grab(/^const precachedPrefixes = .*$/m)}
   ${grab(/^async function precacheFor\(prefix\) \{[\s\S]*?\n\}/m)}
   ${grab(/^function langPrefixOf\(url\) \{[\s\S]*?\n\}/m)}
@@ -131,12 +132,14 @@ const harness = `
   ${grab(/^function offlinePathFor\(url\) \{[\s\S]*?\n\}/m)}
   ${grab(/^async function trimCache\(cacheName, maxEntries\) \{[\s\S]*?\n\}/m)}
   ${grab(/^async function migrateLegacyRuntime\(\) \{[\s\S]*?\n\}/m)}
+  ${grab(/^function keepAlive\(event, promise\) \{[\s\S]*?\n\}/m)}
+  ${grab(/^async function networkFirst\(request, event\) \{[\s\S]*?\n\}/m)}
   return {
     RUNTIME_PAGES, RUNTIME_ASSETS, PAGES_MAX_ENTRIES, PRECACHE, LIBRARY, SETTINGS,
     cacheKeyCandidates, matchCachedPage, offlinePathFor, migrateLegacyRuntime,
-    langPrefixOf, precacheUrlsFor, precacheFor, guessLangPrefix,
+    langPrefixOf, precacheUrlsFor, essentialUrlsFor, precacheFor, guessLangPrefix,
     autoPrecacheEnabled, setAutoPrecache, libraryEntries, addToLibrary,
-    removeFromLibrary, clearAllOffline, handleLibraryMessage,
+    removeFromLibrary, clearAllOffline, handleLibraryMessage, networkFirst,
   };
 `;
 
@@ -149,8 +152,10 @@ const harness = `
 const load = (opts = {}) => {
   const caches = new FakeCacheStorage();
   const fetched = [];
+  const net = { offline: !!opts.offline };
   const fetchStub = async (url) => {
     fetched.push(url);
+    if (net.offline) throw new TypeError("Failed to fetch");
     return { ok: !(opts.notFound || []).includes(url), url };
   };
   const selfStub = {
@@ -162,7 +167,7 @@ const load = (opts = {}) => {
   const sw = new Function('caches', 'SCOPE_PATH', 'fetch', 'self', 'navigator', harness)(
     caches, SCOPE_PATH, fetchStub, selfStub, navigatorStub
   );
-  return { sw, caches, fetched };
+  return { sw, caches, fetched, net };
 };
 
 const req = (pathname) => ({ url: ORIGIN + pathname });
@@ -453,19 +458,44 @@ test('清除會清光所有快取，並把自動預快取關掉', async (load) =
   assert.equal(await sw.autoPrecacheEnabled(), false);
 });
 
-test('清除之後不會馬上被自動下載回來', async (load) => {
+test('清除之後只補離線提示頁那一批，章節不會整包抓回來', async (load) => {
   const { sw, fetched } = load();
   await sw.clearAllOffline();
   fetched.length = 0;
 
   // 模擬下一次導覽送 PRECACHE_LANG 過來
-  if (await sw.autoPrecacheEnabled()) await sw.precacheFor('');
-  assert.deepEqual(fetched, []);
+  await sw.precacheFor('');
+  assert.deepEqual(fetched.slice().sort(), sw.essentialUrlsFor('').slice().sort());
+  assert.ok(fetched.length < sw.precacheUrlsFor('').length);
+  assert.ok(!fetched.includes('/docs/tools/what-is-tor/'));
 
-  // 讀者自己在管理頁打開才恢復
+  // 讀者自己在管理頁把開關打開才恢復完整
   await sw.setAutoPrecache(true);
-  if (await sw.autoPrecacheEnabled()) await sw.precacheFor('');
-  assert.ok(fetched.length > 0);
+  fetched.length = 0;
+  await sw.precacheFor('');
+  assert.ok(fetched.includes('/docs/tools/what-is-tor/'));
+});
+
+test('清除過的裝置離線時仍看得到離線提示頁', async (load) => {
+  // 這一批底線存在的理由。少了它，沒快取過的網址在離線時會一路走到 networkFirst
+  // 最後的 throw，讀者看到的是瀏覽器自己的網路錯誤畫面，不是站台的說明，而那一頁
+  // 正好就是離線內容管理頁，想清東西的人往往正好連不上網。
+  const { sw, net } = load();
+  await sw.clearAllOffline();
+  await sw.precacheFor('');
+  net.offline = true;
+
+  const response = await sw.networkFirst(req('/docs/tools/what-is-tor/'), null);
+  assert.equal(response.url, '/docs/offline/');
+});
+
+test('關掉自動存之後，離線提示頁照樣留著', async (load) => {
+  const { sw, net } = load();
+  await sw.setAutoPrecache(false);
+  await sw.precacheFor('');
+  net.offline = true;
+
+  assert.equal((await sw.networkFirst(req('/docs/basics/metadata/'), null)).url, '/docs/offline/');
 });
 
 test('狀態查詢回得出已存的、站台存的與空間用量', async (load) => {
@@ -509,6 +539,41 @@ test('認不得的指令會回錯誤，不會靜靜沒反應', async (load) => {
   assert.equal(replies[0].type, 'error');
 });
 
+test('離線時沒快取過的頁面會落到離線頁', async (load) => {
+  const { sw, caches } = load({ offline: true });
+  const precache = await caches.open(sw.PRECACHE);
+  await precache.put('/docs/offline/', 'ZH-OFFLINE');
+
+  const response = await sw.networkFirst(req('/docs/basics/metadata/'), null);
+  // 走到這裡代表 networkFirst 沒有把錯誤往外丟。丟出去的話 respondWith 會 reject，
+  // 讀者看到的是瀏覽器自己的網路錯誤畫面，站台的離線頁等於白做。
+  assert.equal(response, 'ZH-OFFLINE');
+});
+
+test('離線時快取過的頁面直接回快取，不落到離線頁', async (load) => {
+  const { sw, caches } = load({ offline: true });
+  const precache = await caches.open(sw.PRECACHE);
+  await precache.put('/docs/offline/', 'ZH-OFFLINE');
+  await precache.put('/docs/tools/what-is-tor/', 'TOR');
+
+  assert.equal(await sw.networkFirst(req('/docs/tools/what-is-tor/'), null), 'TOR');
+});
+
+test('離線時各語系落到自己的離線頁', async (load) => {
+  const { sw, caches } = load({ offline: true });
+  const precache = await caches.open(sw.PRECACHE);
+  await precache.put('/docs/offline/', 'ZH-OFFLINE');
+  await precache.put('/docs/en/offline/', 'EN-OFFLINE');
+
+  assert.equal(await sw.networkFirst(req('/docs/en/basics/metadata/'), null), 'EN-OFFLINE');
+  assert.equal(await sw.networkFirst(req('/docs/basics/metadata/'), null), 'ZH-OFFLINE');
+});
+
+test('連離線頁都沒快取到時才把錯誤丟出去', async (load) => {
+  const { sw } = load({ offline: true });
+  await assert.rejects(() => sw.networkFirst(req('/docs/basics/metadata/'), null));
+});
+
 for (const [name, fn] of tests) {
   try {
     await fn(load);