fix(sw): reload on a controller change only when the build really changed

The previous commit reloaded on any controller change, and three E2E shards
said no. A controller changing is routine: the vendored editor registers a
worker of its own into this scope, ours is re-installed and left waiting on
ordinary loads, and the browser activates it by itself at the next navigation
-- same build, same caches, nothing behind it. Measured at 80ms into a plain
reload of a fresh profile, which is why sw-vendor-cache-first died with
"Execution context was destroyed" in the middle of its probe.

So the condition is two things, and both are load-bearing:

  - the new controller is a build this browser has not been running, judged
    the way healStaleController judges it -- by the runtime cache, named after
    the vendor tree's content. The cache names are snapshotted at boot: read
    them when the swap happens and the incoming worker has already created its
    own, and asking the outgoing worker instead is asking something a swap may
    already have terminated;
  - and there are no unsaved edits.

Not "is a document open", which is what left a torn page unrepaired, and not
"did this tab ask for the swap", which misses the cases that actually happen.

Reverse-verified in both directions, locally, which the earlier attempts could
not manage: pinning isNewBuild false turns sw-silent-update red, pinning it
true turns sw-vendor-cache-first red. With the real value, sw-silent-update,
sw-vendor-cache-first, sw-warm, autosave-recovery and font-cache pass -- eight
cases.

Tried and dropped: having sw.js skip its install-time takeover when a core
cache under this build's name already exists, so that a same-build re-install
stops swapping the controller mid-load. Its unit case reverse-verified, but
the local suite is green with and without it, and it has a real cost -- a
rollback to a build this browser has run would no longer be delivered, which
is the font revert's own scenario. Unproven benefit, delicate path, out.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: chaxus

CHANGELOG.md

@@ -102,9 +102,9 @@ notes. Entries describe what users experience, not internal refactors.
 - **An update could leave the editor blank.** When a new version took over
   while the page was still starting up, the request for the editor itself was
   cancelled mid-flight and nothing asked for it again -- an empty white page
-  that reloading was the only way out of. The page now reloads itself whenever
-  the version serving it changes, which is what repairs it -- unless you have
-  unsaved edits, which nothing is allowed to reload over.
+  that reloading was the only way out of. The page now reloads itself when the
+  version serving it really has changed, which is what repairs it -- unless you
+  have unsaved edits, which nothing is allowed to reload over.
 - The four home-screen buttons ("View/Edit Document", "New Word"...) no longer
   flash behind the spinner while a document named in the URL is loading.
 - Chinese, Japanese and Korean text in an exported PDF came out blank. The

CLAUDE.md

@@ -535,16 +535,18 @@ docs/explorations/2026-08-19-ci-e2e-sharding.md。
    `DEPLOY_COUPLED`（由 `hosting-contract.test.ts` / `sw-routing.test.ts` 钉住）。
    `open-local.js` / `landing-prefetch.js` 同理，2026-08-20 起补齐——它们从路由
    拆分起一直漏在 SWR 上，改这两个文件的部署，落地页会一直跑旧的那份。
-   **controller 一换就 reload，唯一的否决是未保存改动**（2026-08-23）：激活新 worker
-   会终止旧 worker，它手上 in-flight 的 fetch 全部失败——其中就有编辑器 iframe 自己的
-   文档请求，没人重试，标签页永远白屏。拒绝刷新撤不回那次交接，只会把人留在白屏上。
-   **别再把"有没有文档打开"或"是不是本页请求的交接"加回判据**：换人的有三个来源，
-   只有一个跟本页面有关（`sw.js` 自己 install 里 skipWaiting、别的标签页经落地页提升、
-   **浏览器在旧 worker 的客户端全没了时自动激活**——一次 reload 正好安排了这件事，
-   实测交接落在 reload 之后 50ms、比它杀掉的请求早 170ms）。另一半是
-   `documentIsExpected`（`?new=` / `?file=` / `?src=` / `?open=` / `?saved=` / `?embed=`）：
-   正在开文档的页面**不要提升**，那种等待交给静默自愈，它会先 `isUnseenBuild()`
-   确认真是新构建。见
+   **controllerchange 的 reload 判据只有两条：是不是新构建 + 有没有未保存改动**
+   （2026-08-23）。激活新 worker 会终止旧 worker，它手上 in-flight 的 fetch 全部失败——
+   其中就有编辑器 iframe 自己的文档请求，没人重试，标签页永远白屏；拒绝刷新撤不回那次
+   交接。所以**别把"有没有文档打开"加回判据**。但也**别只按"换了就刷"**：controller
+   变更是常态（厂商 worker 的来回切换让我们的 sw.js 在普通加载里就被重装并 waiting，
+   浏览器下一次导航自己激活它），实测一次普通 reload 之后 80ms 就换人，无差别刷新会把
+   `sw-vendor-cache-first` 打成 `Execution context was destroyed`。新构建的判据是
+   `isUnseenBuild`，**缓存名快照必须在启动时取**（交接时再读，新 worker 已经建好自己的
+   那个了）。另有 `documentIsExpected`（`?new=` / `?file=` / `?src=` / `?open=` /
+   `?saved=` / `?embed=`）：正在开文档的页面**不要提升**。**别去改 `sw.js` 的 install
+   让它对同一构建不接管**——试过，本地证不出必要性，却会让"回滚到本机跑过的构建"不再
+   自动投递。见
    docs/explorations/2026-08-23-promotion-without-reload-blank-editor.md。
    落地页那侧的提升要覆盖三种到达方式：已经 `waiting`、`installing` 中途、
    以及 `updatefound` 时已经 `installed`（`statechange` 只报此后的迁移，

docs/explorations/2026-08-23-promotion-without-reload-blank-editor.md

@@ -112,9 +112,23 @@ CLAUDE.md 里记着这条路径上相反方向的那个 bug（"打开流程排
 所以"这一页有没有请求过这次交接"是个错的判据，它恰好漏掉了真正会发生的那几种。
 `promotedFromThisTab` 与 `onPromoted` 这套管线一起删掉了。
 
-**真正的判据只有一条：有没有未保存的改动。** 交接已经发生，拒绝刷新撤不回它，
-只会把人留在白屏上；而真正不能被刷新盖掉的东西就是未保存的工作。两者不会撞车——
-被撕成两半的页面根本没加载完，里面没有任何未保存的东西。
+**判据有两条，缺一条都会立刻出事。**
+
+第一条：**必须是另一个构建**。"controller 换了"是常态——厂商 worker 的来回切换让我们的
+sw.js 在普通加载里就被重装并留在 waiting，浏览器会在下一次导航时自己把它激活，
+同一个构建、同一批缓存、没有任何事情发生。只按"换了就刷"做，等于每隔一次页面浏览就刷一次
+（实测：一次普通 reload 之后 80 毫秒就换了人，`sw-vendor-cache-first` 当场
+`Execution context was destroyed`）。判据用的还是 `isUnseenBuild` 那一条：
+运行时缓存按 vendor 内容哈希命名，**在启动时**拍一张缓存名快照（不是等交接发生时再读，
+那时新 worker 已经建好自己的那个了；也不去问旧 worker，它可能已经被终止）。
+
+第二条：**不能盖掉未保存的工作**。除此之外没有别的拒绝理由。原先那条"有文档打开就不刷"
+听着谨慎，其实不是：交接已经发生，拒绝刷新撤不回它，只会把人留在白屏上；
+而被撕成两半的页面根本没加载完，里面没有任何未保存的东西——两者不会撞车。
+
+**谁请求的交接不是判据**，这是第一版栽的地方：能换人的有三个，只有一个跟本页面有关
+（`sw.js` 自己在 install 里 skipWaiting、别的标签页经落地页提升、
+浏览器在旧 worker 的客户端全没了时自动激活）。
 
 `documentIsExpected` 留着，它另有其用：不要往一个正在开文档的页面里塞提升（嵌入模式
 理由更硬，宿主随时可能推文档进来）。
@@ -133,6 +147,21 @@ CLAUDE.md 里记着这条路径上相反方向的那个 bug（"打开流程排
 与 `documentIsExpected` 三条分别变红。E2E `autosave-recovery`（三条）+
 `sw-silent-update` + `sw-warm` 本地全绿。
 
-**诚实说一句**：这个白屏在本地从来没复现过——三版实现本地都是绿的，红只发生在 CI。
-所以 E2E 这一侧算不上反向验证，判据是上面那条时间轴，以及"无论谁换了 controller
-都会修"这个更强的不变式。
+E2E 这一侧两个方向都验过，**都在本地**（前几版复现不了，是因为它们碰巧没触发；
+把判据写死才逼出来）：
+
+- `isNewBuild` 恒为 `false`（等于旧的"不刷"）→ `sw-silent-update` 变红；
+- 恒为 `true`（等于"换了就刷"）→ `sw-vendor-cache-first` 变红
+  （`Execution context was destroyed`）。
+
+两条都恢复正常值时，`sw-silent-update` / `sw-vendor-cache-first` / `sw-warm` ×2 /
+`autosave-recovery` ×3 / `font-cache` 共 8 条全绿。
+
+## 试过又撤掉的：让 sw.js 别为同一个构建接管
+
+中途改过 `public/sw.js`：install 时先问 `caches.has(CORE_CACHE)`，已经装过这个构建
+就不 `skipWaiting()`——理由是同一构建的接管什么也不换，却会终止旧 worker、打断它手上
+的请求。单测反向验证是过的，但**本地整套 SW 用例在有没有它的情况下都全绿**，证不出必要性；
+而它有一处真实代价：**回滚到这台浏览器跑过的构建**（vendor 未变那种）会因为核心缓存
+同名而不再自动接管，投递就哑了——那正是字体那次 revert 踩过的场景。证不出收益、
+却动了投递路径，所以撤掉。

index.ts

@@ -1,6 +1,7 @@
 import {
   documentIsExpected,
   healStaleController,
+  isUnseenBuild,
   onWaitingWorker,
   shouldReloadOnControllerChange,
   wireServiceWorkerUpdates,
@@ -240,18 +241,30 @@ if ('serviceWorker' in navigator) {
   // into the middle of its own load. The URL already knows.
   const hasOpenDocument = () => Boolean(getDocmentObj().fileName) || documentIsExpected(window.location.search);
 
+  // The runtime caches as they were before anything could have changed them.
+  // Read at boot rather than when a swap happens: by then the incoming worker
+  // has created its own, and the question is which builds this browser was
+  // running BEFORE. Taken from the cache rather than by asking the outgoing
+  // worker, which a swap may already have terminated.
+  const cachesAtBoot = typeof caches === 'undefined' ? Promise.resolve([]) : caches.keys();
+  const bootCacheNames = { keys: () => cachesAtBoot };
+
   navigator.serviceWorker.addEventListener('controllerchange', () => {
-    if (
-      !shouldReloadOnControllerChange({
-        hadController,
-        alreadyReloading: reloadingForUpdate,
-        hasUnsavedChanges: hasUnsavedChanges(),
-      })
-    ) {
-      return;
-    }
-    reloadingForUpdate = true;
-    window.location.reload();
+    void (async () => {
+      const isNewBuild = await isUnseenBuild(navigator.serviceWorker.controller, bootCacheNames);
+      if (
+        !shouldReloadOnControllerChange({
+          hadController,
+          alreadyReloading: reloadingForUpdate,
+          isNewBuild,
+          hasUnsavedChanges: hasUnsavedChanges(),
+        })
+      ) {
+        return;
+      }
+      reloadingForUpdate = true;
+      window.location.reload();
+    })();
   });
 
   // The script we register, absolute: the vendored editor registers one of its

lib/sw-update.ts

@@ -146,35 +146,42 @@ export function onWaitingWorker(
 /**
  * Whether a controllerchange should reload the page.
  *
- * The condition used to be "not while a document is open", and the reason it
- * was wrong is worth keeping: activating a worker terminates the outgoing one,
- * and every request it still had in flight fails. On the editor route the one
- * in flight is the vendored iframe's own document, which nothing retries -- so
- * refusing the reload leaves a blank editor that only a manual reload escapes.
- * By the time the event arrives the page has already been torn in half.
- * Refusing does not undo the swap.
+ * Two conditions, and the history of getting them wrong is the reason both are
+ * spelled out here.
  *
- * It is also not this page's business WHO swapped. Three different things do
- * it and only one of them is us: sw.js calls skipWaiting() itself when
- * activating would not discard vendor assets, the landing page promotes from
- * another tab, and the browser activates a waiting worker on its own once the
- * clients the old one controlled are gone -- which a reload arranges. Gating
- * the repair on "this tab asked for it" therefore missed the cases that
- * actually happen (measured: the swap landed 50ms into a reload, 170ms before
- * the iframe request it killed).
+ * **It has to be a different build.** A controller changing is routine: the
+ * vendored editor registers a worker of its own into this scope from inside
+ * its iframe, so ours is re-installed and left waiting on ordinary loads, and
+ * the browser activates it by itself at the next navigation -- same build,
+ * same caches, nothing to tell anyone. Reloading on every swap is a reload on
+ * every second page view (measured: 80ms into the load, on a plain reload of
+ * a fresh profile). The evidence for "different" is the runtime cache, named
+ * after the vendor tree's content: see isUnseenBuild.
  *
- * What genuinely must not be reloaded over is unsaved work, and that is the
- * condition. A torn page has nothing unsaved in it -- nothing finished
- * loading -- so the two never collide.
+ * **And it must not throw away unsaved work.** Nothing else is a reason to
+ * refuse. It used to be "not while a document is open", which sounds careful
+ * and is not: activating a worker terminates the outgoing one and every
+ * request it still had in flight fails -- on this route the vendored iframe's
+ * own document, which nothing retries. By the time this event arrives the page
+ * may already be torn in half, and refusing does not undo the swap; it only
+ * leaves the reader on a blank editor with no way out but a manual reload.
+ *
+ * Who asked for the swap is deliberately not a condition. Three things do it
+ * and only one is us: sw.js promotes itself on install, another tab promotes
+ * through the landing page, and the browser activates a waiting worker on its
+ * own.
  */
 export function shouldReloadOnControllerChange(state: {
   hadController: boolean;
   alreadyReloading: boolean;
+  /** The new controller is a build this browser has not been running. */
+  isNewBuild: boolean;
   hasUnsavedChanges?: boolean;
 }): boolean {
   // No controller at startup means this is the first install, not an update:
-  // nothing was being served by anyone, so nothing was torn.
+  // nobody was serving this page, so nothing was interrupted.
   if (!state.hadController || state.alreadyReloading) return false;
+  if (!state.isNewBuild) return false;
   return !state.hasUnsavedChanges;
 }
 

test/unit/sw-update.test.ts

@@ -122,14 +122,25 @@ describe('documentIsExpected', () => {
 });
 
 describe('shouldReloadOnControllerChange', () => {
+  const update = { hadController: true, alreadyReloading: false, isNewBuild: true };
   it('reloads once on an update', () => {
-    expect(shouldReloadOnControllerChange({ hadController: true, alreadyReloading: false })).toBe(true);
+    expect(shouldReloadOnControllerChange(update)).toBe(true);
   });
   it('does not reload on a first install, or twice', () => {
     // No controller at startup means nobody was serving this page, so nothing
     // was interrupted -- and reloading the first visit would be a stutter.
-    expect(shouldReloadOnControllerChange({ hadController: false, alreadyReloading: false })).toBe(false);
-    expect(shouldReloadOnControllerChange({ hadController: true, alreadyReloading: true })).toBe(false);
+    expect(shouldReloadOnControllerChange({ ...update, hadController: false })).toBe(false);
+    expect(shouldReloadOnControllerChange({ ...update, alreadyReloading: true })).toBe(false);
+  });
+
+  /**
+   * The routine case, and the one that made an earlier attempt reload every
+   * second page view: the vendored editor keeps our worker re-installing, the
+   * browser activates it at the next navigation, and the controller changes
+   * with nothing behind it. Measured at 80ms into a plain reload.
+   */
+  it('ignores a swap between two instances of the same build', () => {
+    expect(shouldReloadOnControllerChange({ ...update, isNewBuild: false })).toBe(false);
   });
 });
 
@@ -750,15 +761,23 @@ describe('shouldReloadOnControllerChange after a swap this page did not ask for'
     // `hasOpenDocument` was the old condition, and passing it is the point:
     // this exact input used to return false, which is how a reader ended up
     // on a blank page with no way out but a manual reload.
-    const state = { hadController: true, alreadyReloading: false, hasOpenDocument: true } as Parameters<
-      typeof shouldReloadOnControllerChange
-    >[0];
+    const state = {
+      hadController: true,
+      alreadyReloading: false,
+      isNewBuild: true,
+      hasOpenDocument: true,
+    } as Parameters<typeof shouldReloadOnControllerChange>[0];
     expect(shouldReloadOnControllerChange(state)).toBe(true);
   });
 
   it('never reloads over unsaved edits', () => {
     expect(
-      shouldReloadOnControllerChange({ hadController: true, alreadyReloading: false, hasUnsavedChanges: true }),
+      shouldReloadOnControllerChange({
+        hadController: true,
+        alreadyReloading: false,
+        isNewBuild: true,
+        hasUnsavedChanges: true,
+      }),
     ).toBe(false);
   });
 });