fix(web): recover the home screen when the bundle never runs

2026-09-22 12:13:17 +08:00
parent 6ac61be07d
commit 337d820076
18 changed files with 882 additions and 22 deletions
@@ -0,0 +1,38 @@
+# PROGRESS · 首页加载失败可恢复性（2026-09-22）
+
+工作树：`.worktrees/home-bootstrap-reliability-20260922`
+分支：`codex/home-bootstrap-reliability-20260922`
+开工时 `origin/staging` = `10baeb2fa865743c428806e115ac92ca9d92fb71`。未 push。未改 `page.tsx`。
+
+既有 `TASK-first-paint-dead-screen-fallback-20260917.md` 尚未合入。本分支按它的未完成项做了唯一一套内联兜底，并完成断句后行断言清理。不另写一份 first-paint 进度。
+
+## T1 兜底
+
+- 根 layout 在主题脚本旁增加 `firstPaintFallbackBootScript()`。生成结果是经典 `<script>`：无 `type="module"`，无 `=>` / `const ` / `let ` / `class ` / 模板串 / `?.` / `??`。
+- 触发：`setTimeout` **13000ms**（大于 `page.tsx` 的 8000 与准备揭幕的 4000）。回调里仍有 `.app-loading` 且 `documentElement` 的 `data-hydrated` 不是 `"1"` 时，替换 `.app-loading-content`。
+- 文案：标题「这个页面没能加载完」，正文说明网络中断或浏览器过旧，并提示清除 Safari 本站数据或升级到 iOS 16.4 以上。唯一按钮「重新加载」，只在点击时 `location.reload()`。
+- 揭幕标记写在 `useHomeShellRegistration`：`hydrated` 为真时设 `document.documentElement.dataset.hydrated = "1"`。`Home()` 未加 `useState` / `useRef`，`page.tsx` 未改。
+- 复用 `.app-loading-error` 卡片，没有第二套转圈或骨架。
+
+## T2 分流
+
+六类不并成「接口慢」：`hydrate-timeout`、`chunk-404`、`chunk-parse`、`stale-cache`、`weak-network`、`api-error`。前五类可以由内联脚本在 bundle 没跑起来时标记；`api-error` 仍是 bundle 里的「连接云端服务超时」那一屏。匿名对象只有 `category`、`buildId`、`durationMs`。
+
+真人清单：`docs/testing/home-bootstrap-reliability-20260922.md`。BUG-936 改为「兜底已补、根因待分流」，未标 resolved。低版本 Safari 与真实 chunk 失败未在浏览器验收。
+
+## T3 后行断言
+
+`frontend/src` 已无 `(?<=`。共用 `splitAfterSentencePunctuation`。表驱动用例覆盖中文句号、问号、叹号、分号、英文标点、换行、连续标点、结尾无标点，并与旧正则逐字对照。既有校正与报告断言未改。另立 BUG-998（不占用 996 / 997 / 999）。
+
+## 验证
+
+定向测试（未跑全量 `npm test`，未跑 `next build`）：
+
+| 命令 | 结果 |
+| --- | --- |
+| `npx tsx --test tests/sentence-split.test.ts tests/first-paint-fallback-contract.test.ts` | 6 pass / 0 fail |
+| `npx tsx --test tests/home-shell-growth-contract.test.ts tests/agent-voice-copy-contract.test.ts tests/rectification-collect-prompt.test.ts tests/rectification-adopt-narration-20260904.test.ts` | 48 pass / 0 fail |
+| `.\node_modules\.bin\tsc --noEmit` | 0 错 |
+| `npm run lint` | 0 error / 119 warning（既有 warning，未顺手改） |
+
+`home-shell-growth-contract` 通过，因此 `Home()` 的 `useState` / `useRef` 没有超过现有上限，行数也没有超过粗护栏。