diff --git a/CHANGELOG.md b/CHANGELOG.md
index 23444570..acdcc3e3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -82,6 +82,14 @@ notes. Entries describe what users experience, not internal refactors.
   document can reference still resolves; it just lands on a face that may be
   shared freely.
 
+### Changed
+
+- **Search engines and AI assistants now see one editor, not one per page.**
+  Every page described the application from scratch, so a site of 154 pages
+  looked like 154 unrelated tools that happened to share a name. The pages now
+  all point at the same one, and say which of the seven languages they are in.
+  Nothing on the pages themselves changed.
+
 ### Fixed
 
 - **A new version now reaches you by itself.** An update used to wait until no
@@ -91,6 +99,12 @@ notes. Entries describe what users experience, not internal refactors.
   broken. A tab still on an older build now moves onto the new one on its next
   load, without asking and without interrupting anything: it happens while the
   page is still loading, once, and never over unsaved edits.
+- **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 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
diff --git a/CLAUDE.md b/CLAUDE.md
index 5e91e62e..24a8b6e6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -283,7 +283,15 @@ fetchFonts 字体竞态，修复见 `lib/onlyoffice-editor.ts` 的 `prepareEdito
 超时）都属于这一层；`test/unit/hosting-contract.test.ts` 钉住 `_headers` 关键
 规则；`test/unit/landing-pages.test.ts` 钉住全部 SEO 落地页（public/**/*.html +
 index.html）的 canonical/hreflang/JSON-LD/sitemap/双语互指契约——新增落地页必须
-同时补 en+zh、sitemap、llms.txt、首页卡片，否则该测试先红。**线上冒烟** `.github/workflows/prod-smoke.yml`：每次 push main 等部署
+同时补 en+zh、sitemap、llms.txt、首页卡片，否则该测试先红。
+**结构化数据是一张有 `@id` 的图，不是每页一份副本**（2026-08-23，学 apple.com）：
+`Organization` / `WebSite` / `WebApplication` / `SoftwareSourceCode` 用固定 `@id`
+（`/#organization` / `/#website` / `/#app` / `/#source`）每页重复出现并互相引用，
+`WebPage` / `FAQPage` / `HowTo` / `BreadcrumbList` 用 `<页面 url>#webpage` 这类
+页面级 id。**app 节点的 `url` 恒为站点根**，语言写在 `WebPage.inLanguage`；
+改成当前页 URL 就等于宣称七种语言是七个产品。文档页只发 app 的 stub（`appStub()`），
+落地页才发完整节点。上面那个测试会拒绝重复 `@id` 与解析不到定义的 `@id` 引用。
+见 docs/explorations/2026-08-23-entity-graph-from-apple.md。**线上冒烟** `.github/workflows/prod-smoke.yml`：每次 push main 等部署
 上线后即跑 + 每日；`E2E_BASE_URL=<站点>` 可把任意 spec 打到部署站。CF 面板里
 的 Cache Rules 等不在仓库、CI 复现不了，只能靠冒烟兜底。
 
@@ -527,6 +535,19 @@ 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 上，改这两个文件的部署，落地页会一直跑旧的那份。
+   **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` 只报此后的迁移，
    漏掉这一支等于整页生命周期内再没人提升它）。
diff --git a/bin/build-pages.mjs b/bin/build-pages.mjs
index d607b902..28baa1e9 100644
--- a/bin/build-pages.mjs
+++ b/bin/build-pages.mjs
@@ -32,6 +32,93 @@ const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const ORIGIN = 'https://edit.chaxus.com';
 const REPO = 'https://github.com/ranuts/document';
 
+/**
+ * Stable identities for the three things this site is about.
+ *
+ * Every page used to emit its own anonymous WebApplication / SoftwareSourceCode
+ * node, so 154 pages described 154 unrelated applications that happened to
+ * share a name. Naming them once and referring to the name instead is what
+ * turns a pile of pages into one entity described from many places -- the model
+ * apple.com uses (`#organization`, `#website`, `#brand`, then
+ * `manufacturer: { "@id": ... }` everywhere else). It matters more to the
+ * machines that answer questions about the site than to the ones that rank it:
+ * an assistant reading three of our pages should come away with one editor,
+ * not three.
+ */
+const ID = {
+  org: `${ORIGIN}/#organization`,
+  site: `${ORIGIN}/#website`,
+  app: `${ORIGIN}/#app`,
+  source: `${ORIGIN}/#source`,
+};
+const SITE_NAME = 'Online Document Editor';
+
+/** The publisher and the site, identical on every page so they merge into one. */
+const siteEntities = () => [
+  {
+    '@type': 'Organization',
+    '@id': ID.org,
+    name: 'ranuts',
+    url: ORIGIN + '/',
+    logo: `${ORIGIN}/img/pwa-512.png`,
+    sameAs: [REPO, 'https://github.com/ranuts', 'https://ran.chaxus.com'],
+  },
+  {
+    '@type': 'WebSite',
+    '@id': ID.site,
+    name: SITE_NAME,
+    url: ORIGIN + '/',
+    publisher: { '@id': ID.org },
+    // The site is one site in seven languages, which is a fact about the site
+    // and not about whichever page is being read. Each page states its own
+    // language on its WebPage node.
+    inLanguage: Object.keys(LOCALES),
+  },
+];
+
+/**
+ * The editor itself. One entity, `url` always the site root -- a per-page url
+ * here would make each translation look like a separate product.
+ */
+const appEntity = (extra = {}) => ({
+  '@type': 'WebApplication',
+  '@id': ID.app,
+  name: SITE_NAME,
+  url: ORIGIN + '/',
+  applicationCategory: 'BusinessApplication',
+  operatingSystem: 'Any (web browser)',
+  browserRequirements: 'Requires a modern browser with WebAssembly support',
+  isAccessibleForFree: true,
+  inLanguage: Object.keys(LOCALES),
+  offers: { '@type': 'Offer', price: '0', priceCurrency: 'USD' },
+  // The repository is the editor's other public identity, not the org's.
+  sameAs: [REPO],
+  publisher: { '@id': ID.org },
+  isPartOf: { '@id': ID.site },
+  ...extra,
+});
+
+/**
+ * The same entity, stated with just enough to be a definition rather than a
+ * dangling reference. A documentation page is a page ABOUT the editor, not a
+ * listing of it -- it should not carry a price and a category and become
+ * eligible for an app rich result. But `about: { "@id": ... }` pointing at
+ * nothing is silently dropped by the consumer, which puts the page back to
+ * describing an anonymous application. So: named, not detailed.
+ */
+const appStub = () => ({ '@type': 'WebApplication', '@id': ID.app, name: SITE_NAME, url: ORIGIN + '/' });
+
+/** The repository behind it, named so the node merges instead of repeating. */
+const sourceEntity = () => ({
+  '@type': 'SoftwareSourceCode',
+  '@id': ID.source,
+  name: SITE_NAME,
+  codeRepository: REPO,
+  programmingLanguage: 'TypeScript',
+  license: 'https://www.gnu.org/licenses/agpl-3.0.html',
+  about: { '@id': ID.app },
+});
+
 /** Locales the shell knows about. `prefix` is the URL directory; '' = root. */
 export const LOCALES = {
   en: { prefix: '', lang: 'en', label: 'EN', home: '/', dir: 'ltr', og: 'en_US' },
@@ -625,38 +712,37 @@ function renderHome({ locale, data, locales }) {
     .join('\n');
 
   const graph = [
-    {
-      '@type': 'WebApplication',
-      name: 'Online Document Editor',
-      url,
-      applicationCategory: 'BusinessApplication',
-      operatingSystem: 'Any (web browser)',
-      browserRequirements: 'Requires a modern browser with WebAssembly support',
+    ...siteEntities(),
+    appEntity({
       description: data.description,
-      inLanguage: L.lang,
-      isAccessibleForFree: true,
-      offers: { '@type': 'Offer', price: '0', priceCurrency: 'USD' },
       ...(data.featureList ? { featureList: data.featureList } : {}),
-      sameAs: [REPO, 'https://www.npmjs.com/package/@ranui/preview', 'https://ran.chaxus.com'],
       ...(data.ecosystem
-        ? { isPartOf: { '@type': 'SoftwareApplication', name: data.ecosystem.name, url: data.ecosystem.url } }
+        ? { isPartOf: [{ '@id': ID.site }, { '@type': 'SoftwareApplication', ...data.ecosystem }] }
         : {}),
+    }),
+    // This page: one homepage per language, each pointing at the same app.
+    {
+      '@type': 'WebPage',
+      '@id': `${url}#webpage`,
+      url,
+      name: data.title,
+      description: data.description,
+      inLanguage: L.lang,
+      isPartOf: { '@id': ID.site },
+      about: { '@id': ID.app },
+      primaryImageOfPage: `${ORIGIN}/img/pwa-512.png`,
     },
     {
       '@type': 'FAQPage',
+      '@id': `${url}#faq`,
+      inLanguage: L.lang,
       mainEntity: data.sections.faq.items.map(({ q, a }) => ({
         '@type': 'Question',
         name: q,
         acceptedAnswer: { '@type': 'Answer', text: a },
       })),
     },
-    {
-      '@type': 'SoftwareSourceCode',
-      name: 'Online Document Editor',
-      codeRepository: REPO,
-      programmingLanguage: 'TypeScript',
-      license: 'https://www.gnu.org/licenses/agpl-3.0.html',
-    },
+    sourceEntity(),
   ];
   const jsonLd = JSON.stringify({ '@context': 'https://schema.org', '@graph': graph }, null, 2)
     .split('\n')
@@ -737,7 +823,7 @@ function renderHome({ locale, data, locales }) {
     <title>${e(data.title)}</title>
     <meta name="description" content="${e(data.description)}" />
     <link rel="canonical" href="${url}" />
-    <meta name="robots" content="index, follow" />
+    <meta name="robots" content="index, follow, max-image-preview:large, max-snippet:-1, max-video-preview:-1" />
 ${alternates}
     <link rel="alternate" hreflang="x-default" href="${ORIGIN + LOCALES[DEFAULT_LOCALE].home}" />
     <!-- No-flash theme restore: apply a forced light/dark before first paint so a
@@ -958,36 +1044,24 @@ function renderPage({ page, locale, meta, body, headings, faq, steps, source })
   const isLanding = page.kind === 'landing';
   const cardDescription = meta.ogDescription || description;
   const graph = [
-    // A landing page is selling the app, and Google's rich results treat a
-    // WebApplication node accordingly (price, category, platform). A generated
-    // documentation page is a page about the product, not the product.
-    isLanding
-      ? {
-          '@type': 'WebApplication',
-          name: 'Online Document Editor',
-          url,
-          applicationCategory: 'BusinessApplication',
-          operatingSystem: 'Any (web browser)',
-          isAccessibleForFree: true,
-          inLanguage: L.lang,
-          description: meta.appDescription || description,
-          offers: { '@type': 'Offer', price: '0', priceCurrency: 'USD' },
-        }
-      : {
-          '@type': 'WebPage',
-          name: title,
-          url,
-          description,
-          inLanguage: L.lang,
-          isPartOf: { '@type': 'WebSite', name: 'Online Document Editor', url: ORIGIN + '/' },
-        },
+    ...siteEntities(),
+    // Every page is a page; a landing page additionally describes the app, and
+    // Google's rich results treat a WebApplication node accordingly (price,
+    // category, platform). The app node is the same entity everywhere, so a
+    // landing page adds to its description rather than declaring a new one.
     {
-      '@type': 'SoftwareSourceCode',
-      name: 'Online Document Editor',
-      codeRepository: REPO,
-      programmingLanguage: 'TypeScript',
-      license: 'https://www.gnu.org/licenses/agpl-3.0.html',
+      '@type': 'WebPage',
+      '@id': `${url}#webpage`,
+      url,
+      name: title,
+      description,
+      inLanguage: L.lang,
+      isPartOf: { '@id': ID.site },
+      about: { '@id': ID.app },
+      breadcrumb: { '@id': `${url}#breadcrumb` },
     },
+    isLanding ? appEntity({ description: meta.appDescription || description }) : appStub(),
+    sourceEntity(),
   ];
   // The steps a landing page already lists, as structured data. Taken from the
   // rendered list rather than written separately: the hand-written pages kept a
@@ -996,6 +1070,8 @@ function renderPage({ page, locale, meta, body, headings, faq, steps, source })
   if (isLanding && meta.howTo && steps.length >= 2) {
     graph.push({
       '@type': 'HowTo',
+      '@id': `${url}#howto`,
+      inLanguage: L.lang,
       name: meta.howTo,
       step: steps.map((text) => ({ '@type': 'HowToStep', text })),
     });
@@ -1003,6 +1079,8 @@ function renderPage({ page, locale, meta, body, headings, faq, steps, source })
   if (faq.length >= 2) {
     graph.push({
       '@type': 'FAQPage',
+      '@id': `${url}#faq`,
+      inLanguage: L.lang,
       mainEntity: faq.map(({ q, a }) => ({
         '@type': 'Question',
         name: q,
@@ -1015,7 +1093,7 @@ function renderPage({ page, locale, meta, body, headings, faq, steps, source })
     crumbs.push({ '@type': 'ListItem', position: 2, name: meta.parent.name, item: ORIGIN + meta.parent.href });
   }
   crumbs.push({ '@type': 'ListItem', position: crumbs.length + 1, name: meta.breadcrumb || title, item: url });
-  graph.push({ '@type': 'BreadcrumbList', itemListElement: crumbs });
+  graph.push({ '@type': 'BreadcrumbList', '@id': `${url}#breadcrumb`, itemListElement: crumbs });
 
   const translations = Object.keys(LOCALES).filter((l) => page.sources[l]);
   const alternates = translations
@@ -1101,7 +1179,7 @@ ${related}
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <link href="/img/64.png" rel="shortcut icon" />
     <link rel="icon" type="image/png" href="/img/64.png" />
-    <meta name="robots" content="index, follow" />
+    <meta name="robots" content="index, follow, max-image-preview:large, max-snippet:-1, max-video-preview:-1" />
     <meta name="theme-color" media="(prefers-color-scheme: light)" content="#ffffff" />
     <meta name="theme-color" media="(prefers-color-scheme: dark)" content="#000000" />
 
diff --git a/docs/explorations/2026-08-23-entity-graph-from-apple.md b/docs/explorations/2026-08-23-entity-graph-from-apple.md
new file mode 100644
index 00000000..48bf7853
--- /dev/null
+++ b/docs/explorations/2026-08-23-entity-graph-from-apple.md
@@ -0,0 +1,100 @@
+# 照着 apple.com 抄结构化数据：把 154 个页面收拢成一个实体
+
+日期：2026-08-23
+方法：抓 `www.apple.com/`、`/iphone/`、`/shop/buy-mac/macbook-air`、
+`/macbook-air/specs/`、`/iphone/compare/` 的原始 HTML，以及 robots.txt 与 sitemap，
+逐项比对本站生成器的输出。
+
+## 苹果做对的、且能搬过来的
+
+### 1. 稳定 `@id` + 互相引用（最值钱的一条）
+
+苹果不在每页重新定义"苹果公司"。它定义一次：
+
+```json
+{ "@id": "https://www.apple.com/#organization", "@type": "Organization", "name": "Apple", ... }
+```
+
+之后所有页面只写引用：`"manufacturer": { "@id": "https://www.apple.com/#organization" }`。
+`#website`、`#webpage`、`/mac/#brand` 同理。MacBook Air 规格页的 `Product` 节点
+里，manufacturer 和 brand 都只是两个 `@id`。
+
+本站原本反过来：每个页面各发一份匿名的 `WebApplication` 和 `SoftwareSourceCode`。
+**154 个页面 = 154 个碰巧同名的应用**。对排名影响有限，对回答问题的机器影响很大——
+读了三个页面的助手应该得出"一个编辑器"，而不是三个。
+
+改成：
+
+| 节点                                   | `@id`                                       | 出现在       |
+| -------------------------------------- | ------------------------------------------- | ------------ |
+| `Organization`                         | `/#organization`                            | 每页         |
+| `WebSite`                              | `/#website`                                 | 每页         |
+| `WebApplication`                       | `/#app`                                     | 每页         |
+| `SoftwareSourceCode`                   | `/#source`                                  | 每页         |
+| `WebPage`                              | `<页面 url>#webpage`                        | 每页（本页） |
+| `FAQPage` / `HowTo` / `BreadcrumbList` | `<页面 url>#faq` / `#howto` / `#breadcrumb` | 有则有       |
+
+`WebApplication` 的 `url` 恒为站点根，**不再是当前页面的 URL**——否则七种语言看起来
+就是七个不同的产品。语言这件事挪到了它该在的地方：`WebPage.inLanguage` 说这一页是
+什么语言，`WebSite.inLanguage` / `WebApplication.inLanguage` 是七种语言的数组，
+本身也是一条对 LLM 有用的事实（"这个编辑器有七种语言"）。
+
+落地页仍然发完整的 app 节点（价格、类别、平台，Google 的 rich result 要这些），
+**文档页只发一个 stub**（`@type` + `@id` + `name` + `url`）。理由是两头都要顾：
+`/help` 不该因为带了价格而去竞争应用类富媒体结果，但 `about: { "@id": ... }`
+指向一个图里不存在的 id 会被消费方直接丢掉，那样这一页又退回"描述一个匿名应用"。
+
+### 2. `max-image-preview:large`
+
+苹果每页都发 `<meta name="robots" content="max-image-preview:large">`。本站原本只有
+`index, follow`。补成
+`index, follow, max-image-preview:large, max-snippet:-1, max-video-preview:-1`——
+后两个不是苹果的做法，但它们放开的正是 AI 摘要与搜索摘要能引用的长度上限。
+
+### 3. `sameAs` 指向可核对的身份
+
+苹果的 Organization 指向 **Wikidata**（`Q312`）+ 各社交账号。这是把站点绑到知识图谱
+实体上的做法。本站没有 Wikidata 条目，用能核对的那几个：GitHub 组织、仓库、生态站点。
+`sameAs` 从 app 节点挪到 Organization（那是组织的身份），app 自己留仓库这一条。
+
+## 苹果做了但**不该**抄的
+
+- **没有 `x-default`**。137 条 hreflang，一条 x-default 都没有。本站有，保持。
+- **sitemap 只有 `<loc>`**，没有 lastmod/priority。本站按 git 提交日期发 lastmod，更好。
+- **规格页几乎不带正文 HTML**。`/macbook-air/specs/` 324 KB，`<h1>` 之后直到页脚
+  再没有正文标题——规格全靠 JS 渲染。对爬虫和 LLM 都是净损失，苹果的品牌撑得住，我们不行。
+- **没有 llms.txt**（404）。本站有 `/llms.txt` + `/llms-full.txt`。
+
+## 考虑过但决定不改的
+
+- **`hreflang="pt"` 改成 `pt-BR`**。本站的葡语内容确实是巴西葡语（og 已经是 `pt_BR`），
+  按苹果的做法应该声明 `pt-BR`。但苹果有 pt 和 br 两套站，我们只有一套：声明 `pt-BR`
+  会让葡萄牙读者落回 x-default 的英文。只有一个变体时，覆盖面胜过精确度，保持 `pt`。
+
+## 还没做的：`/specs/` 与 `/compare/` 这两种页型
+
+苹果给**每个**产品配一张规格页和一张对比页（sitemap 里 `/airpods-4/compare/`、
+`/airpods-4/specs/` 逐个都在）。这两种页型吃的正是高意图长尾词，也正是 LLM 最容易
+整段引用的密集事实。
+
+本站有 `/open/<格式>` 与 `/convert/<格式对>`，**没有**：
+
+- 一张"支持什么、限制是什么"的规格页：格式清单、大小上限、浏览器要求、
+  哪些功能只在 Chromium 上（写回原文件、剪贴板）、离线可用范围。
+- 任何对比页型：`docx vs pdf` 这类格式对比，或"和需要上传的在线编辑器相比"。
+
+这是一次内容项目（× 7 种语言），需要先定内容，没有在这次改动里做。
+
+## 用例与反向验证
+
+`test/unit/landing-pages.test.ts` 三条新契约，逐页跑（154 页 × 3）：
+
+1. 本页的 `WebPage` 节点 url/@id 必须是本页；
+2. 出现的 `WebApplication` 必须是共享实体（`@id` = `/#app`，`url` = 站点根）；
+3. **图里每一个 `@id` 引用都必须能解析到图里的定义**，且没有重复 `@id`。
+
+第 3 条当场就抓到一个真的悬空引用：文档页的 `WebPage.about` 与
+`SoftwareSourceCode.about` 指向 `/#app`，而那些页面根本没定义它——`appStub()`
+就是为此加的。
+
+反向验证：`git stash` 掉 `bin/build-pages.mjs`，441 条断言变红。
diff --git a/docs/explorations/2026-08-23-promotion-without-reload-blank-editor.md b/docs/explorations/2026-08-23-promotion-without-reload-blank-editor.md
new file mode 100644
index 00000000..8c1dc644
--- /dev/null
+++ b/docs/explorations/2026-08-23-promotion-without-reload-blank-editor.md
@@ -0,0 +1,167 @@
+# 谁提升了 worker，谁就得负责那次 reload
+
+日期：2026-08-23
+现场：CI run 32620431825，`E2E shard 1` 的 @serial 那趟挂在
+`sw-silent-update.spec.ts:92` 的 `settleEditor`，90s 超时。这条用例在本地 16s 通过，
+在 CI 已经是第二次红了。
+
+## 不是慢，是白屏
+
+失败截图是**纯白页**。把 trace 拆开看，时间轴很清楚：
+
+```
+24.1  page.reload()            ← 测试写完新 sw.js 之后的那次刷新
+24.2  console: SW registered
+24.3  console: Creating new editor instance
+24.35 GET /web-apps/apps/documenteditor/main/index.html  →  status -1（失败）
+...   之后 90 秒什么都没有
+114.3 超时
+```
+
+编辑器 iframe 自己的文档请求**失败了**，而且没有任何东西会重试它。页面就停在
+"创建了编辑器实例、iframe 永远空着"的半成品状态。
+
+请求为什么会失败：那一刻 service worker 换了人。激活新 worker 会终止旧 worker，
+旧 worker 手上所有 in-flight 的 fetch 事件一起失败——其中就有这个 iframe 的导航请求。
+
+**这本来不是问题**，因为换 worker 之后页面会 reload 一次，重新加载就好了。
+问题是那次 reload 没有发生。
+
+## 提升的判据和 reload 的判据，问的是同一个问题的两个时刻
+
+`index.ts` 里两件事：
+
+```ts
+wireServiceWorkerUpdates(registration, hasOpenDocument, ownScriptURL);
+// ...
+navigator.serviceWorker.addEventListener('controllerchange', () => {
+  if (!shouldReloadOnControllerChange({ ..., hasOpenDocument: hasOpenDocument() })) return;
+  window.location.reload();
+});
+```
+
+`promoteWaitingWorker` 在 `register()` 一 resolve 就跑，而在编辑器路由上，
+**那比编辑器实例存在早几百毫秒**（trace 里 SW registered 在 24.2、
+Creating new editor instance 在 24.3）。于是它看到"没有文档打开"，提升。
+
+等 `controllerchange` 真的到达时，文档已经打开了。`shouldReloadOnControllerChange`
+重新问一遍 `hasOpenDocument()`，答案变成了 true，于是**拒绝 reload**——
+可这时候页面早就被那次交接撕成两半了。
+
+`promoteWaitingWorker` 的返回值一直被 `wireServiceWorkerUpdates` 丢掉，
+所以页面从来不知道"是我自己让它换的"。
+
+CLAUDE.md 里记着这条路径上相反方向的那个 bug（"打开流程排在 SW 注册之前，
+`hasOpenDocument()` 永远为真，于是等待中的 worker 从不被提升"）。修好之后
+竞态翻了个面：注册有时候赢，提升发生了，而修复它的 reload 被拒。
+
+## 改法
+
+**谁提升谁负责 reload。** `wireServiceWorkerUpdates` 多一个 `onPromoted` 回调，
+真的发出 `SKIP_WAITING` 时通知调用方；`index.ts` 把标志位从 `healingStaleBuild`
+改名成 `promotedFromThisTab`，两条路径（普通更新提升、静默自愈）共用它；
+`shouldReloadOnControllerChange` 见到这个标志就 reload，**不再问有没有文档打开**——
+只有未保存改动仍然一票否决。
+
+理由不是偏好而是修复：交接已经发生了，拒绝 reload 不会把它撤回来，
+只会把标签页留在白屏上。
+
+## 只补第一半会变成"每次加载都刷新一次"
+
+第一版只做了上面那件事，`E2E (Cloudflare Pages semantics)` 的
+`autosave-recovery` "a reload comes back to the same document" 立刻红（重试也红，
+同一分片在没有这个改动的另一个 PR 上是绿的）。
+
+原因 CLAUDE.md 里其实写着：**"有 worker 在等"不等于"有新版本"**。厂商的编辑器 iframe
+会往同一个 scope 注册它自己的 worker，一个 scope 只有一个 registration，于是脚本在
+我们的 sw.js 与它之间来回换——**编辑器路由上我们的 worker 几乎每次加载都躺在
+`waiting` 里，跟有没有新构建无关**。原先那条"有文档打开就不 reload"顺带当了刹车；
+把它拆掉，每一次这种交接都变成一次刷新。
+
+所以第二半：**文档在路上的时候根本不要提升**。`hasOpenDocument()` 读的是 store，
+而 store 要等编辑器实例建好才有值——比 `register()` resolve 晚几百毫秒。URL 早就知道了：
+`?new=` / `?file=` / `?src=` / `?open=` / `?saved=` 任意一个在，就是"这一页要开文档"。
+`?embed=`／`?embedded=` 也算，而且理由更硬：嵌入模式下宿主随时可能推一个文档进来，
+那次 reload 扔掉的是宿主页面的东西。
+
+这些路由上等待的 worker 就老老实实等着——这不是丢失更新，正是静默自愈存在的那个场景，
+而自愈这条路**会先用 `isUnseenBuild()` 确认真的是另一个构建**才交接，不会被厂商 worker
+的来回切换骗到。
+
+## 前两版都只猜对了一半：换掉 controller 的根本不是我们
+
+补完上面两半，CI 还是红，同一条用例、同一处白屏。这次把网络时间轴对齐着看：
+
+```
+25.68  reload 的文档（旧 worker 服务的）
+25.74  GET /sw.js            ← 浏览器例行比对，字节变了，开始 install
+25.79  install 预缓存 / /index.html /editor /editor.html …
+25.83  测试问 controller 是谁 → 已经是 e2e-next（reload 完成后仅 50ms）
+25.96  GET .../documenteditor/main/index.html → -1
+```
+
+交接发生在 reload 之后 50 毫秒，比它杀掉的那个请求早 170 毫秒。而那时候
+`promoteWaitingWorker` 因为 `documentIsExpected('?new=docx')` 根本没跑——
+**换人的不是我们**。能换的有三个，只有一个跟本页面有关：
+
+1. `sw.js` 自己在 install 里 `skipWaiting()`（`wouldDiscardVendorAssets` 为假时）；
+2. 别的标签页经落地页提升；
+3. **浏览器自己**——等待中的 worker 会在旧 worker 控制的客户端全部消失时自动激活，
+   而一次 reload 正好安排了这件事。
+
+所以"这一页有没有请求过这次交接"是个错的判据，它恰好漏掉了真正会发生的那几种。
+`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` 留着，它另有其用：不要往一个正在开文档的页面里塞提升（嵌入模式
+理由更硬，宿主随时可能推文档进来）。
+
+## 用例与反向验证
+
+`test/unit/sw-update.test.ts`：`shouldReloadOnControllerChange` 现在只有两条
+（有文档打开也刷新、有未保存改动不刷新），另三条钉住 `documentIsExpected`
+（认得每个会挂文档的路由、把 embed 也算进去、没东西可开的页面照常接更新）。
+
+"有文档打开也刷新"那条**特意还是把 `hasOpenDocument: true` 传进去**（经一次 cast），
+因为那正是旧判据下返回 false 的那个输入——不传的话它在新旧两版实现下都是绿的，
+等于没测。
+
+反向验证：`git stash` 掉 `lib/sw-update.ts`，`shouldReloadOnControllerChange` 两条
+与 `documentIsExpected` 三条分别变红。E2E `autosave-recovery`（三条）+
+`sw-silent-update` + `sw-warm` 本地全绿。
+
+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 踩过的场景。证不出收益、
+却动了投递路径，所以撤掉。
diff --git a/index.html b/index.html
index 1b74f37f..59bff1e1 100644
--- a/index.html
+++ b/index.html
@@ -31,7 +31,7 @@
     <title>Open DOCX, XLSX &amp; PPTX in Your Browser — Free Document Viewer &amp; Editor</title>
     <meta name="description" content="Open and view Word (DOCX), Excel (XLSX), PowerPoint (PPTX) and CSV files directly in your browser — no Office installed, no upload, no sign-up. Edit and save them too. Free, privacy-first, works offline. Powered by OnlyOffice." />
     <link rel="canonical" href="https://edit.chaxus.com/" />
-    <meta name="robots" content="index, follow" />
+    <meta name="robots" content="index, follow, max-image-preview:large, max-snippet:-1, max-video-preview:-1" />
     <link rel="alternate" hreflang="en" href="https://edit.chaxus.com/" />
     <link rel="alternate" hreflang="zh-CN" href="https://edit.chaxus.com/zh-CN/" />
     <link rel="alternate" hreflang="ja" href="https://edit.chaxus.com/ja/" />
@@ -77,21 +77,76 @@
       {
         "@context": "https://schema.org",
         "@graph": [
+          {
+            "@type": "Organization",
+            "@id": "https://edit.chaxus.com/#organization",
+            "name": "ranuts",
+            "url": "https://edit.chaxus.com/",
+            "logo": "https://edit.chaxus.com/img/pwa-512.png",
+            "sameAs": [
+              "https://github.com/ranuts/document",
+              "https://github.com/ranuts",
+              "https://ran.chaxus.com"
+            ]
+          },
+          {
+            "@type": "WebSite",
+            "@id": "https://edit.chaxus.com/#website",
+            "name": "Online Document Editor",
+            "url": "https://edit.chaxus.com/",
+            "publisher": {
+              "@id": "https://edit.chaxus.com/#organization"
+            },
+            "inLanguage": [
+              "en",
+              "zh-CN",
+              "ja",
+              "de",
+              "es",
+              "ko",
+              "pt"
+            ]
+          },
           {
             "@type": "WebApplication",
+            "@id": "https://edit.chaxus.com/#app",
             "name": "Online Document Editor",
             "url": "https://edit.chaxus.com/",
             "applicationCategory": "BusinessApplication",
             "operatingSystem": "Any (web browser)",
             "browserRequirements": "Requires a modern browser with WebAssembly support",
-            "description": "Open and view Word (DOCX), Excel (XLSX), PowerPoint (PPTX) and CSV files directly in your browser — no Office installed, no upload, no sign-up. Edit and save them too. Free, privacy-first, works offline. Powered by OnlyOffice.",
-            "inLanguage": "en",
             "isAccessibleForFree": true,
+            "inLanguage": [
+              "en",
+              "zh-CN",
+              "ja",
+              "de",
+              "es",
+              "ko",
+              "pt"
+            ],
             "offers": {
               "@type": "Offer",
               "price": "0",
               "priceCurrency": "USD"
             },
+            "sameAs": [
+              "https://github.com/ranuts/document"
+            ],
+            "publisher": {
+              "@id": "https://edit.chaxus.com/#organization"
+            },
+            "isPartOf": [
+              {
+                "@id": "https://edit.chaxus.com/#website"
+              },
+              {
+                "@type": "SoftwareApplication",
+                "name": "ran ecosystem",
+                "url": "https://ran.chaxus.com"
+              }
+            ],
+            "description": "Open and view Word (DOCX), Excel (XLSX), PowerPoint (PPTX) and CSV files directly in your browser — no Office installed, no upload, no sign-up. Edit and save them too. Free, privacy-first, works offline. Powered by OnlyOffice.",
             "featureList": [
               "Open and view DOCX, XLSX, PPTX and CSV without Microsoft Office",
               "Edit DOCX, XLSX, PPTX and CSV files",
@@ -101,20 +156,27 @@
               "Installable PWA with offline support",
               "Embeddable via postMessage API",
               "Free and open source (AGPL-3.0)"
-            ],
-            "sameAs": [
-              "https://github.com/ranuts/document",
-              "https://www.npmjs.com/package/@ranui/preview",
-              "https://ran.chaxus.com"
-            ],
+            ]
+          },
+          {
+            "@type": "WebPage",
+            "@id": "https://edit.chaxus.com/#webpage",
+            "url": "https://edit.chaxus.com/",
+            "name": "Open DOCX, XLSX & PPTX in Your Browser — Free Document Viewer & Editor",
+            "description": "Open and view Word (DOCX), Excel (XLSX), PowerPoint (PPTX) and CSV files directly in your browser — no Office installed, no upload, no sign-up. Edit and save them too. Free, privacy-first, works offline. Powered by OnlyOffice.",
+            "inLanguage": "en",
             "isPartOf": {
-              "@type": "SoftwareApplication",
-              "name": "ran ecosystem",
-              "url": "https://ran.chaxus.com"
-            }
+              "@id": "https://edit.chaxus.com/#website"
+            },
+            "about": {
+              "@id": "https://edit.chaxus.com/#app"
+            },
+            "primaryImageOfPage": "https://edit.chaxus.com/img/pwa-512.png"
           },
           {
             "@type": "FAQPage",
+            "@id": "https://edit.chaxus.com/#faq",
+            "inLanguage": "en",
             "mainEntity": [
               {
                 "@type": "Question",
@@ -168,10 +230,14 @@
           },
           {
             "@type": "SoftwareSourceCode",
+            "@id": "https://edit.chaxus.com/#source",
             "name": "Online Document Editor",
             "codeRepository": "https://github.com/ranuts/document",
             "programmingLanguage": "TypeScript",
-            "license": "https://www.gnu.org/licenses/agpl-3.0.html"
+            "license": "https://www.gnu.org/licenses/agpl-3.0.html",
+            "about": {
+              "@id": "https://edit.chaxus.com/#app"
+            }
           }
         ]
       }
diff --git a/index.ts b/index.ts
index 19751fc2..e3e0f7ca 100644
--- a/index.ts
+++ b/index.ts
@@ -1,5 +1,7 @@
 import {
+  documentIsExpected,
   healStaleController,
+  isUnseenBuild,
   onWaitingWorker,
   shouldReloadOnControllerChange,
   wireServiceWorkerUpdates,
@@ -233,26 +235,36 @@ if ('serviceWorker' in navigator) {
   // no document is open, then takes over and the page reloads once.
   const hadController = !!navigator.serviceWorker.controller;
   let reloadingForUpdate = false;
-  // Set when this tab asked an older worker to step aside (see below): the
-  // reload that follows is the point, so it is not blocked by having a
-  // document open the way an ordinary update is.
-  let healingStaleBuild = false;
-  const hasOpenDocument = () => Boolean(getDocmentObj().fileName);
+  // "Is a document open?" is the wrong tense at boot: the store fills in a few
+  // hundred milliseconds after register() resolves, so a page opening a
+  // document answers "no" for exactly as long as it takes to promote a worker
+  // 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,
-        hasOpenDocument: hasOpenDocument(),
-        healingStaleBuild,
-        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
@@ -288,8 +300,6 @@ if ('serviceWorker' in navigator) {
               controller: navigator.serviceWorker.controller,
               hadController,
               storage: window.sessionStorage,
-            }).then((started) => {
-              if (started) healingStaleBuild = true;
             });
           },
           ownScriptURL,
diff --git a/lib/sw-update.ts b/lib/sw-update.ts
index 2e864b5e..9395f0d7 100644
--- a/lib/sw-update.ts
+++ b/lib/sw-update.ts
@@ -51,6 +51,32 @@ export function isOwnWorker(reg: RegistrationLike, worker: SwLike, ownScriptURL?
 
 export const SKIP_WAITING_MESSAGE = { type: 'SKIP_WAITING' } as const;
 
+/**
+ * Is this page going to have a document in it?
+ *
+ * `hasOpenDocument()` reads the store, which is empty until the editor
+ * instance exists -- a few hundred milliseconds after `register()` resolves.
+ * Asking it that early answers "nothing open" about a page whose whole purpose
+ * is to open something, and the promotion that follows lands in the middle of
+ * the editor booting.
+ *
+ * The URL knows sooner. Every route that mounts a document says so in its
+ * query string, and embed mode says the host may push one at any moment --
+ * which is also why an embedded editor must never promote: the reload that
+ * follows would throw away a document the host page owns.
+ *
+ * On these routes a waiting worker simply stays waiting. That is not a lost
+ * update: it is the ordinary case the silent heal exists for, and unlike this
+ * path the heal checks that the waiting worker is genuinely a different build
+ * before it swaps -- which matters, because the vendored editor registers a
+ * worker of its own into this scope from inside the iframe, so ours is left
+ * `waiting` on almost every editor load with no new build in sight.
+ */
+export function documentIsExpected(search: string): boolean {
+  const params = new URLSearchParams(search);
+  return ['new', 'file', 'src', 'open', 'saved', 'embed', 'embedded'].some((key) => params.has(key));
+}
+
 /** Tell a waiting worker to take over -- only if nothing is open. Returns whether it did. */
 export function promoteWaitingWorker(
   reg: RegistrationLike,
@@ -74,12 +100,15 @@ export function wireServiceWorkerUpdates(
   hasOpenDocument: () => boolean,
   ownScriptURL?: string,
 ): void {
-  promoteWaitingWorker(reg, hasOpenDocument, ownScriptURL);
+  const promote = (): void => {
+    promoteWaitingWorker(reg, hasOpenDocument, ownScriptURL);
+  };
+  promote();
   reg.addEventListener('updatefound', () => {
     const installing = reg.installing;
     if (!installing) return;
     installing.addEventListener('statechange', () => {
-      if (installing.state === 'installed') promoteWaitingWorker(reg, hasOpenDocument, ownScriptURL);
+      if (installing.state === 'installed') promote();
     });
   });
 }
@@ -115,21 +144,45 @@ export function onWaitingWorker(
 }
 
 /**
- * Whether a controllerchange should reload the page: only when a worker was
- * already in control at startup (so this is an update, not the first
- * install), only once, and never with a document open (unsaved edits).
+ * Whether a controllerchange should reload the page.
+ *
+ * Two conditions, and the history of getting them wrong is the reason both are
+ * spelled out here.
+ *
+ * **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.
+ *
+ * **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;
-  hasOpenDocument: boolean;
-  /** This tab asked an older worker to step aside; the reload is the point. */
-  healingStaleBuild?: 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:
+  // nobody was serving this page, so nothing was interrupted.
   if (!state.hadController || state.alreadyReloading) return false;
-  if (state.healingStaleBuild) return !state.hasUnsavedChanges;
-  return !state.hasOpenDocument;
+  if (!state.isNewBuild) return false;
+  return !state.hasUnsavedChanges;
 }
 
 /** How sw.js names the cache it keeps the vendored editor in. */
diff --git a/test/unit/landing-pages.test.ts b/test/unit/landing-pages.test.ts
index 0c514302..115e511b 100644
--- a/test/unit/landing-pages.test.ts
+++ b/test/unit/landing-pages.test.ts
@@ -20,6 +20,15 @@ const NOT_LANDING = new Set(['404.html', 'embed-demo.html']);
 const GENERATED = generate({ outDir: null }) as Array<{ rel: string; route: string; html: string }>;
 const isGeneratedFile = (file: string) => GENERATED.some((g) => resolve(PUBLIC, g.rel) === file);
 
+type LdNode = Record<string, any>;
+/** Every JSON-LD node a page ships, @graph flattened. */
+function jsonLdGraph(html: string): LdNode[] {
+  return [...html.matchAll(/<script type="application\/ld\+json">([\s\S]*?)<\/script>/g)].flatMap((m) => {
+    const doc = JSON.parse(m[1]);
+    return (doc['@graph'] ?? [doc]) as LdNode[];
+  });
+}
+
 function walkHtml(dir: string): string[] {
   const out: string[] = [];
   for (const name of readdirSync(dir)) {
@@ -120,20 +129,55 @@ describe('landing pages', () => {
         expect(attr(html, /property="og:url" content="([^"]+)"/)).toBe(ORIGIN + route);
       });
 
-      it('ships parseable JSON-LD whose primary node url is the page', () => {
-        const blocks = [...html.matchAll(/<script type="application\/ld\+json">([\s\S]*?)<\/script>/g)];
-        expect(blocks.length).toBeGreaterThan(0);
-        const graph = blocks.flatMap((m) => {
-          const doc = JSON.parse(m[1]);
-          return doc['@graph'] ?? [doc];
-        });
-        const app = graph.find((n: any) => ['WebApplication', 'WebPage', 'Article'].includes(n['@type']));
-        expect(app?.url).toBe(ORIGIN + route);
-        for (const faq of graph.filter((n: any) => n['@type'] === 'FAQPage')) {
+      it('ships parseable JSON-LD whose page node is this page', () => {
+        const graph = jsonLdGraph(html);
+        expect(graph.length).toBeGreaterThan(0);
+        const webPage = graph.find((n) => n['@type'] === 'WebPage');
+        expect(webPage?.url).toBe(ORIGIN + route);
+        expect(webPage?.['@id']).toBe(`${ORIGIN}${route}#webpage`);
+        for (const faq of graph.filter((n) => n['@type'] === 'FAQPage')) {
           expect(faq.mainEntity.length).toBeGreaterThan(2);
         }
       });
 
+      /**
+       * The editor is one thing described from 154 pages, not 154 things that
+       * share a name. It is the difference between an assistant reading three
+       * of our pages and coming away with one editor or with three -- and the
+       * only thing holding it together is that the node keeps the same @id and
+       * the same url everywhere (apple.com does this with #organization).
+       */
+      it('describes one shared app entity, never a per-page copy', () => {
+        const app = jsonLdGraph(html).find((n) => n['@type'] === 'WebApplication');
+        if (!app) return; // only landing pages carry it
+        expect(app['@id']).toBe(`${ORIGIN}/#app`);
+        expect(app.url).toBe(`${ORIGIN}/`);
+      });
+
+      /**
+       * A reference to an @id that is not in the graph is silently nothing --
+       * the consumer drops the edge and the page goes back to describing an
+       * anonymous app. Cheap to break by renaming one id, invisible afterwards.
+       */
+      it('resolves every @id reference it makes', () => {
+        const graph = jsonLdGraph(html);
+        const ids = new Set(graph.map((n) => n['@id']).filter(Boolean));
+        expect(ids.size, 'no duplicate @id in one graph').toBe(graph.filter((n) => n['@id']).length);
+        const refs: string[] = [];
+        const walk = (value: unknown): void => {
+          if (Array.isArray(value)) return value.forEach(walk);
+          if (!value || typeof value !== 'object') return;
+          const node = value as Record<string, unknown>;
+          // A bare { "@id": ... } with nothing else is a reference; a node that
+          // also carries a @type is a definition.
+          if (typeof node['@id'] === 'string' && !node['@type']) refs.push(node['@id']);
+          Object.entries(node).forEach(([key, v]) => key !== '@id' && walk(v));
+        };
+        graph.forEach((n) => Object.entries(n).forEach(([key, v]) => key !== '@id' && walk(v)));
+        expect(refs.length).toBeGreaterThan(0);
+        for (const ref of refs) expect(ids, `${ref} is defined in the graph`).toContain(ref);
+      });
+
       /**
        * A visitor who picked a language on the site must not land in an editor
        * that guesses one from browser settings. The app resolves `?locale=`
diff --git a/test/unit/sw-update.test.ts b/test/unit/sw-update.test.ts
index 7255e8de..6807c612 100644
--- a/test/unit/sw-update.test.ts
+++ b/test/unit/sw-update.test.ts
@@ -8,6 +8,7 @@ import {
   healStaleController,
   isUnseenBuild,
   onWaitingWorker,
+  documentIsExpected,
   promoteWaitingWorker,
   shouldReloadOnControllerChange,
   wireServiceWorkerUpdates,
@@ -95,22 +96,51 @@ describe('wireServiceWorkerUpdates', () => {
   });
 });
 
+/**
+ * The brake on the rule above. Promotion runs before the editor exists, so
+ * "nothing is open" is true on a page that is opening something -- and the
+ * vendored editor keeps our worker in `waiting` on almost every editor load
+ * without any new build existing, so treating each of those as a promotion
+ * worth reloading for is a reload on every load.
+ */
+describe('documentIsExpected', () => {
+  it('recognises every route that mounts a document', () => {
+    for (const search of ['?new=docx', '?file=https://x/a.docx', '?src=https://x/a.docx', '?open=local', '?saved=abc'])
+      expect(documentIsExpected(search), search).toBe(true);
+  });
+
+  it('counts embed mode, where the host can push one at any moment', () => {
+    // Reloading an embedded editor would throw away the host page's document.
+    expect(documentIsExpected('?embed=1')).toBe(true);
+    expect(documentIsExpected('?embedded=1')).toBe(true);
+  });
+
+  it('leaves a page with nothing to open free to take an update', () => {
+    expect(documentIsExpected('')).toBe(false);
+    expect(documentIsExpected('?locale=ja')).toBe(false);
+  });
+});
+
 describe('shouldReloadOnControllerChange', () => {
-  it('reloads once on an update with nothing open', () => {
-    expect(
-      shouldReloadOnControllerChange({ hadController: true, alreadyReloading: false, hasOpenDocument: false }),
-    ).toBe(true);
+  const update = { hadController: true, alreadyReloading: false, isNewBuild: true };
+  it('reloads once on an update', () => {
+    expect(shouldReloadOnControllerChange(update)).toBe(true);
   });
-  it('does not reload on first install, twice, or with a document open', () => {
-    expect(
-      shouldReloadOnControllerChange({ hadController: false, alreadyReloading: false, hasOpenDocument: false }),
-    ).toBe(false);
-    expect(
-      shouldReloadOnControllerChange({ hadController: true, alreadyReloading: true, hasOpenDocument: false }),
-    ).toBe(false);
-    expect(
-      shouldReloadOnControllerChange({ hadController: true, alreadyReloading: false, hasOpenDocument: true }),
-    ).toBe(false);
+  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({ ...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);
   });
 });
 
@@ -713,16 +743,31 @@ describe('healStaleController', () => {
   });
 });
 
-describe('shouldReloadOnControllerChange during a heal', () => {
-  it('reloads even with a document open -- the reload is the point', () => {
-    expect(
-      shouldReloadOnControllerChange({
-        hadController: true,
-        alreadyReloading: false,
-        hasOpenDocument: true,
-        healingStaleBuild: true,
-      }),
-    ).toBe(true);
+describe('shouldReloadOnControllerChange after a swap this page did not ask for', () => {
+  /**
+   * The blank editor. A worker taking over terminates the outgoing one and
+   * every request it still had in flight fails -- on the editor route that is
+   * the vendored iframe's own document, which nothing retries. Measured in CI:
+   * the swap landed 50ms into a reload, 170ms before it killed that request.
+   * Refusing the reload does not undo the swap, it only leaves the reader on
+   * a white page.
+   *
+   * And the page cannot tell who swapped: sw.js promotes itself when it would
+   * not discard vendor assets, another tab promotes through the landing page,
+   * and the browser activates a waiting worker on its own once the old one's
+   * clients are gone. Only the third of those involves this page at all.
+   */
+  it('reloads even with a document open -- the reload is the repair', () => {
+    // `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,
+      isNewBuild: true,
+      hasOpenDocument: true,
+    } as Parameters<typeof shouldReloadOnControllerChange>[0];
+    expect(shouldReloadOnControllerChange(state)).toBe(true);
   });
 
   it('never reloads over unsaved edits', () => {
@@ -730,8 +775,7 @@ describe('shouldReloadOnControllerChange during a heal', () => {
       shouldReloadOnControllerChange({
         hadController: true,
         alreadyReloading: false,
-        hasOpenDocument: true,
-        healingStaleBuild: true,
+        isNewBuild: true,
         hasUnsavedChanges: true,
       }),
     ).toBe(false);