fix(pwa,landing): survive deploys in the service worker; restore per-format create entries

Production broke after deploy for returning visitors: the SW-cached stale
index.html referenced hashed assets that no longer exist, and the 404's HTML
body was handed to the CSS parser ("Refused to apply style… text/html") —
layout collapsed (body height 100% gone → editor iframe at 0px) while the
still-cached JS kept working.

sw.js rewrite:
- HTML navigations fetch with cache: 'no-cache' (revalidate with the server;
  a stale HTTP-cache HTML is exactly what pinned old asset hashes)
- Split core (precached shell + HTML, never trimmed) from runtime cache
  (SWR, 600-item cap — the old single 100-cap cache was evicted constantly
  by OnlyOffice's hundreds of assets, including its own shell)
- /assets/* 404s return Response.error() instead of an HTML body, and
  re-fetch a fresh shell so the next navigation self-heals
- activate() clears every previous version's caches

Guards & gaps:
- lang-select change handler only navigates on a real locale switch — a
  same-locale (or init-time) change no longer reloads the page and wipes
  ?new=/?locale= deep links
- Homepage regained create entries for every format: a quiet mono
  "start blank: Word · Excel · PowerPoint" row under the CTAs (EN + zh-CN),
  using the existing ?new= deep links (the FAB menu only exists once a
  document is open, so xlsx/pptx creation had no homepage entry at all)

Verified: ?new=xlsx boots the spreadsheet editor at full height; clean-env
production check confirms current deploy is intact (the breakage is the old
SW's cache state, which this sw.js version replaces on next visit);
format/lint/240 tests/build green.

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

Author: chaxus

docs/explorations/2026-07-11-sw-cache-and-create-entries.md

@@ -0,0 +1,53 @@
+# 线上三问题：SW 跨部署缓存混乱、语言切换假 change、新建入口缺失
+
+## 问题一：部署后页面样式全塌（用户报告，附控制台报错）
+
+**症状**：线上打开/新建文档后，控制面板按钮无样式堆在左上角、编辑器画布高度
+塌陷（PPT 显示 Zoom 5%）。控制台：`Refused to apply style from
+'/assets/index-<hash>.css' because its MIME type ('text/html')`。
+
+**根因**：旧 Service Worker 时代缓存的旧版 index.html 引用上一次部署的
+hashed 资产；新部署后该文件已不存在，请求 404 回退成 HTML 页面，被当作
+CSS 解析拒绝。JS 恰好还能命中缓存（所以按钮能点、能开文档），CSS 拿不到
+（`html,body{height:100%}` 丢失 → #app/iframe 高度塌陷；r-button 样式全无）。
+两处放大器：
+1. 旧 SW 的 HTML network-first 用裸 `fetch(event.request)`，可能命中 HTTP
+   缓存里的旧 HTML（状态 200，被当"最新"缓存下来）；
+2. 单缓存 100 条上限，OnlyOffice 一次加载几百个资产，precache 的外壳文件
+   （index.html 等）被 LRU 挤出，离线兜底随机失效。
+
+**修复**（public/sw.js 重写）：
+- HTML 导航请求 `fetch(request, { cache: 'no-cache' })` 强制与服务器再验证，
+  永远拿到当前部署的 HTML → hashed 引用永远匹配；
+- 拆双缓存：core（precache 外壳 + HTML，不参与修剪）与 runtime（SWR，上限
+  600）；activate 清理所有旧版本缓存；
+- `/assets/*` hashed 资产网络 404 时返回 `Response.error()`（绝不把 HTML
+  体交给 CSS/JS 解析器），并顺手用 no-cache 重取 index.html 刷新外壳，下次
+  导航自愈。
+- 用户侧恢复路径：新 sw.js 部署后（文件名固定），浏览器导航时检查到更新 →
+  install(skipWaiting) → activate(清旧缓存+claim) → 下一次导航即恢复正常，
+  无需用户手动清缓存。
+
+## 问题二：语言切换假 change 冲掉深链参数（防御性修复）
+
+在带状态的环境观察到 `/?locale=zh-CN&new=docx` 被跳回 `/`。index.ts 的
+lang-select change 监听器只要收到事件就整页跳转——任何来源的初始化/同值
+change 都会把 `?new=` `?locale=` 深链冲掉。修复：与当前页面语言相同的值不
+跳转（en 页收到 'en' 忽略、zh 页收到 'zh-CN' 忽略）。已核查 ranui select
+源码：`syncSelectedFromValue`/`setDefaultValue` 都以 shouldDispatch=false
+调用，初始化不派发 change——防御仍保留，成本为零、对任何回归免疫。
+（顺带发现 CLAUDE.md 里的 lib/i18n.ts 已不存在，文档待刷新。）
+
+## 问题三：首页缺新建 Excel/PPT 入口（用户报告的功能缺失）
+
+改版后 hero 只有 "New document"（仅 docx）；新建 xlsx/pptx 的入口只在文档
+打开后的 FAB 菜单里——首页彻底没有。修复：CTA 下加一行安静的 mono 快捷行
+"start blank: Word · Excel · PowerPoint"（zh："新建空白：…"），走已有的
+`?new=docx|xlsx|pptx` 深链（EN 直链，zh 带 `locale=zh-CN`）。样式
+`.new-row`（12.5px mono，链接用 accent 蓝）。
+
+## 验证
+
+- 干净环境实测线上：静态页组件/样式正常（问题一确系用户浏览器旧 SW 状态）；
+- 本地 `?new=xlsx` 深链：URL 保持、landing 隐藏、编辑器 iframe 全高；
+- format/lint/240 单测/生产构建全绿。

index.html

@@ -206,6 +206,12 @@ <h1 class="reveal d2">
               <r-button type="contrast" id="hero-open">Open a file</r-button>
               <r-button id="hero-new">New document</r-button>
             </div>
+            <!-- Every format keeps a create entry on the homepage (the FAB menu
+                 only exists once a document is open) — ?new= deep-links. -->
+            <p class="new-row reveal d5">
+              start blank: <a href="/?new=docx">Word</a><span class="sep">·</span><a href="/?new=xlsx">Excel</a
+              ><span class="sep">·</span><a href="/?new=pptx">PowerPoint</a>
+            </p>
             <div class="trust reveal d5">
               <span>0 bytes uploaded</span><span class="sep">·</span><span>no account</span><span class="sep">·</span
               ><span>works offline</span><span class="sep">·</span><span>.docx .xlsx .pptx .csv</span>

index.ts

@@ -84,8 +84,12 @@ const langSelect = document.querySelector('#landing-hero r-select.lang-select');
 if (langSelect) {
   langSelect.addEventListener('change', (event) => {
     const value = (event as CustomEvent<{ value?: string }>).detail?.value;
-    if (value === 'zh-CN') location.href = '/zh-CN/';
-    else if (value === 'en') location.href = '/';
+    // Guard: r-select can emit `change` while initializing its value on load.
+    // Navigating on a same-as-current-locale event reloads the page and wipes
+    // deep-link params (?new=docx, ?locale=…), so only act on a real switch.
+    const onZhPage = location.pathname.startsWith('/zh-CN');
+    if (value === 'zh-CN' && !onZhPage) location.href = '/zh-CN/';
+    else if (value === 'en' && onZhPage) location.href = '/';
   });
 }
 

public/home.css

@@ -248,6 +248,23 @@
   gap: var(--ran-space-3);
   margin-top: clamp(24px, 2.8vw, 36px);
 }
+/* quiet per-format create row under the CTAs (the FAB menu only exists once
+   a document is open, so the homepage keeps an entry for every format) */
+#landing-hero .new-row {
+  margin: var(--ran-space-3) 0 0;
+  font: 500 12.5px/1.6 var(--mono);
+  color: var(--muted);
+}
+#landing-hero .new-row a {
+  color: var(--accent);
+}
+#landing-hero .new-row a:hover {
+  text-decoration: underline;
+}
+#landing-hero .new-row .sep {
+  margin: 0 var(--ran-space-2);
+  color: var(--rule);
+}
 #landing-hero .trust {
   margin-top: var(--ran-space-6);
   font: 500 12.5px/1.6 var(--mono);

public/sw.js

@@ -1,9 +1,12 @@
 const CACHE_VERSION = 'SW_VERSION_PLACEHOLDER'.includes('PLACEHOLDER') ? 'dev-' + Date.now() : 'SW_VERSION_PLACEHOLDER';
-const CACHE_NAME = `document-editor-${CACHE_VERSION}`;
+// Two caches: core (precached shell + HTML) survives trimming; runtime holds
+// the long tail (OnlyOffice sdkjs/web-apps assets — hundreds of files, so the
+// old single 100-item cache was constantly evicting its own shell).
+const CORE_CACHE = `document-editor-core-${CACHE_VERSION}`;
+const RUNTIME_CACHE = `document-editor-runtime-${CACHE_VERSION}`;
 const ASSETS_TO_CACHE = ['./', './index.html', './manifest.json', './img/64.png'];
 
-// Cache limits and clean-up configuration
-const MAX_CACHE_ITEMS = 100;
+const MAX_RUNTIME_ITEMS = 600;
 
 // Helper: Trim cache to a certain size
 const limitCacheSize = (name, maxItems) => {
@@ -19,20 +22,20 @@ const limitCacheSize = (name, maxItems) => {
 // Install event: Pre-cache core UI assets
 self.addEventListener('install', (event) => {
   event.waitUntil(
-    caches.open(CACHE_NAME).then((cache) => {
+    caches.open(CORE_CACHE).then((cache) => {
       return cache.addAll(ASSETS_TO_CACHE);
     }),
   );
   self.skipWaiting();
 });
 
-// Activate event: Clean up old caches
+// Activate event: Clean up caches from every previous version
 self.addEventListener('activate', (event) => {
   event.waitUntil(
     caches.keys().then((cacheNames) => {
       return Promise.all(
         cacheNames.map((cacheName) => {
-          if (cacheName !== CACHE_NAME) {
+          if (cacheName !== CORE_CACHE && cacheName !== RUNTIME_CACHE) {
             return caches.delete(cacheName);
           }
         }),
@@ -61,26 +64,33 @@ self.addEventListener('fetch', (event) => {
   // causes a crash in OnlyOffice v7.5's fallback font code path.
   if (/\.(ttf|woff2?|otf|eot)(\?.*)?$/.test(url.pathname)) return;
 
-  // 4. Determine Strategy
+  // 5. Determine Strategy
   const isHtml =
     event.request.mode === 'navigate' ||
     url.pathname.endsWith('.html') ||
     url.pathname === '/' ||
     url.pathname.endsWith('/');
 
+  // Hashed build outputs (/assets/index-<hash>.css|js). Their filenames change
+  // on every deploy, so a stale HTML + missing asset = broken page. Treat any
+  // non-OK answer for them as an error instead of handing an HTML 404 fallback
+  // to the CSS/JS parser ("Refused to apply style… MIME type text/html").
+  const isHashedAsset = url.pathname.startsWith('/assets/');
+
   if (isHtml) {
-    // Strategy: Network-First for HTML/Navigation
-    // Ensuring the user always gets the latest version if online,
-    // but can still access the app when offline.
+    // Strategy: Network-First for HTML/Navigation.
+    // `cache: 'no-cache'` forces revalidation with the server instead of
+    // accepting a possibly-stale HTTP-cache copy — a stale HTML references
+    // hashed assets that no longer exist after a deploy (the exact broken
+    // state this rewrite fixes). Offline still falls back to the SW cache.
     event.respondWith(
-      fetch(event.request)
+      fetch(event.request, { cache: 'no-cache' })
         .then((networkResponse) => {
           // If network is ok, cache and return
           if (networkResponse && networkResponse.status === 200) {
             const responseToCache = networkResponse.clone();
-            caches.open(CACHE_NAME).then((cache) => {
+            caches.open(CORE_CACHE).then((cache) => {
               cache.put(event.request, responseToCache);
-              limitCacheSize(CACHE_NAME, MAX_CACHE_ITEMS);
             });
             return networkResponse;
           }
@@ -101,10 +111,24 @@ self.addEventListener('fetch', (event) => {
             // Only cache valid 200 responses
             if (networkResponse && networkResponse.status === 200 && networkResponse.type === 'basic') {
               const responseToCache = networkResponse.clone();
-              caches.open(CACHE_NAME).then((cache) => {
+              caches.open(RUNTIME_CACHE).then((cache) => {
                 cache.put(event.request, responseToCache);
-                limitCacheSize(CACHE_NAME, MAX_CACHE_ITEMS);
+                limitCacheSize(RUNTIME_CACHE, MAX_RUNTIME_ITEMS);
+              });
+            } else if (isHashedAsset && networkResponse && networkResponse.status === 404) {
+              // A hashed asset that 404s means the page HTML is from another
+              // deploy. Surface a network error (never an HTML body) so the
+              // browser reports a clean failure, and refresh the cached shell
+              // so the next navigation picks up the current HTML.
+              caches.open(CORE_CACHE).then((cache) => {
+                fetch('./index.html', { cache: 'no-cache' }).then((fresh) => {
+                  if (fresh && fresh.status === 200) {
+                    cache.put('./index.html', fresh.clone());
+                    cache.put('./', fresh);
+                  }
+                });
               });
+              return Response.error();
             }
             return networkResponse;
           })

public/zh-CN/index.html

@@ -164,6 +164,12 @@ <h1 class="reveal d2">在浏览器里直接打开 Word、Excel 和 PPT,<span cla
               >
             </a>
           </div>
+          <!-- 每种格式在首页都保留新建入口（FAB 菜单要等文档打开后才出现）——走 ?new= 深链。 -->
+          <p class="new-row reveal d5">
+            新建空白：<a href="/?locale=zh-CN&amp;new=docx">Word</a><span class="sep">·</span
+            ><a href="/?locale=zh-CN&amp;new=xlsx">Excel</a><span class="sep">·</span
+            ><a href="/?locale=zh-CN&amp;new=pptx">PowerPoint</a>
+          </p>
           <div class="trust reveal d5">
             <span>不传服务器</span><span class="sep">·</span><span>免注册</span><span class="sep">·</span
             ><span>可离线</span><span class="sep">·</span><span>.docx .xlsx .pptx .csv</span>