cross-tab-worker-databus 0.20.70 → 0.20.85

package/docs/zh/release-checklist.md

@@ -2,16 +2,39 @@
 
 每个 1.0.0 之前的版本都按此清单执行。仓库不由助手执行发布；完成打包验证并人工审阅后，再手动运行 npm 命令。
 
+## 公共 API 稳定性与弃用策略（1.0 之前）
+
+- 根导出面由 `tests/dual-format.test.ts`（冻结测试）与 `scripts/verify-version-compat.mjs`（tag 间兼容门禁）钉住。新增或删除导出是经过评审的刻意变更；同一提交中必须同步更新 `docs/api.md` 与 CHANGELOG。
+- 1.0 前的破坏性变更仅在走完弃用周期后才允许：legacy 别名至少保留一个小版本，首次使用时 `console.warn` 提示，且只在 CHANGELOG 明确标注移除的小版本中删除。
+- 协议别名（worker/cluster/transport 消息形态）遵循同一规则：弃用后至少一个小版本继续解析 legacy 帧，保证混版本 peer 兼容（见 `getDiagnostics().protocol` 的协议版本诊断）。
+- 晋升 `1.0.0` 要求公共 API 与协议弃用策略正式冻结，并发布迁移指南（见 `docs/roadmap.md` 的 0.13.0 candidates）。
+
+## 自动化门禁（CI）
+
+`CI` 工作流的 `verify` job 在每次 push 与 pull request 上运行 `pnpm check`、`pnpm lint`、`pnpm test:coverage`（`vitest.config.ts` 中的下限：语句 85% / 分支 80% / 函数 90% / 行 85%）、`pnpm verify:compat`、`pnpm verify:pack`、`pnpm bench` 与 `pnpm audit`；`browser` job 运行 Playwright E2E 套件。`Release` 工作流在发布前重跑 `verify:compat` 与 `verify:pack`，随后执行阻塞式 `verify:published` 门禁。两个工作流的 checkout 均使用 `fetch-depth: 0` + `fetch-tags: true`，因为 `verify:compat` 需要从最近的发布 tag 解析基线。
+
+只有 `pnpm bench:browser` / `pnpm bench:compare` 保持仅本地执行：共享 runner 的计时噪声会让数值型 CI 门禁不可靠。
+
 ## 打 tag 前
 
 1. 更新 `package.json`、`CHANGELOG.md` 和中英文 roadmap。
-2. 运行 `pnpm check`、`pnpm lint`、`pnpm bench`、`pnpm test:e2e`、`pnpm bench:browser`、`pnpm verify:pack` 以及 `git diff --check`。
-3. 用 `npm pack --dry-run --json` 确认发布包只包含预期文件。
-4. 提交、给精确版本打 tag，并推送 `main --tags`。
+2. 运行 `pnpm check`、`pnpm lint`、`pnpm test:coverage`、`pnpm bench`、`pnpm test:e2e`、`pnpm bench:browser`、`pnpm verify:pack`、`pnpm verify:compat` 以及 `git diff --check`（`verify:compat` 断言 `COMPAT_BASE_TAG` 基线中的 package `exports` 子路径与类型字段仍然存在；`verify:pack` 从打包产物冒烟导入完整根公共面与全部子路径的 ESM/CJS。`verify:compat` 从最近的发布 tag 解析基线，因此浅克隆或缺少 tag 的克隆需先执行 `git fetch --tags`，否则会以 "no version tag found" 失败）。
+3. 依赖安全门禁：`pnpm audit --registry=https://registry.npmjs.org`（配置的镜像 registry 缺少 audit 端点；CI 在 verify job 中于公共 registry 运行）。任一已知漏洞公告即视为发布失败；`pnpm-workspace.yaml` overrides 钉住补丁版本。
+4. 浏览器基准回归门禁：运行两次 `pnpm bench:browser` 后执行 `pnpm bench:compare --fail-above-pct 50`（50% 上限用于吸收共享 runner 的无关噪声，参见已知的共享 runner 抖动说明）；基线迁移（例如某指标从空操作变为真实路径）属预期内的一次性失败。用 `pnpm bench:trend` 刷新长期趋势文档，表格变化时一并提交。
+5. 用 `npm pack --dry-run --json` 确认发布包只包含预期文件。
+6. 提交、给精确版本打 tag，并推送 `main --tags`。
+
+## 安全与依赖扫描
+
+仓库配置了 CodeQL（`javascript-typescript`，push/PR/每周）与 Dependabot（npm + GitHub Actions 每周更新）。CodeQL 告警会作为 PR check 暴露；Dependabot PR 在合并前必须通过其 verify（全量 check）与 CodeQL 检查，浏览器 E2E 的已知共享 runner 抖动按既有处理方式重跑确认。
+
+## 打 tag 的发布工作流
+
+推送版本 tag 会触发 `Release` GitHub Action：先跑 `pnpm check` 与 `pnpm lint`（tag 可能指向从未通过 CI lint 步骤的提交），再跑 `verify:compat` 与 `verify:pack`，从 `CHANGELOG` 对应章节生成 GitHub release，配置了 `NPM_TOKEN` 时自动发布到 npm，然后运行与手动执行相同预算的**阻塞式**消费者验证（`PUBLISHED_VERIFY_ATTEMPTS=24`、`PUBLISHED_VERIFY_DELAY_MS=5000`）。已发布包若无法被干净消费者导入，工作流即失败——任何 `verify:published` 失败都应视为发布失败，修复后重新发布该 tag。未配置 token 时跳过发布步骤，但验证仍会针对 npm 上已有的版本（例如手动发布的）通过。
 
-## 发布
+## 发布（手动场景）
 
-从对应 tag 的工作树运行 `npm publish --access public`。已经存在于 npm 的版本不能重复发布；npm 缺失的历史版本必须从对应 git tag 重建并逐个审阅，不能把当前工作树伪装成旧版本发布。
+未在工作流配置 `NPM_TOKEN` 时，从对应 tag 的工作树手动运行 `npm publish --access public`。已经存在于 npm 的版本不能重复发布；npm 缺失的历史版本必须从对应 git tag 重建并逐个审阅，不能把当前工作树伪装成旧版本发布。
 
 ## 发布后
 
@@ -19,4 +42,4 @@
 2. 在干净消费者中安装已发布版本或 tarball，并导入主入口及所有公开子路径。
 3. 将结果记录到发布说明。在公开 API 和协议弃用策略明确冻结前，不进入 `1.0.0`。
 
-npm 发布后运行 `PUBLISHED_VERSION=0.20.8 pnpm verify:published`。验证器会在 registry 传播 tarball 时自动重试；只有遇到异常慢的镜像才需要调整 `PUBLISHED_VERIFY_ATTEMPTS` 和 `PUBLISHED_VERIFY_DELAY_MS`。
+打 tag 的发布工作流已自动执行上述消费者验证；仅在需要离线复验时才手动运行 `PUBLISHED_VERSION=<version> pnpm verify:published`。只有遇到异常慢的镜像才需要调整 `PUBLISHED_VERIFY_ATTEMPTS` 和 `PUBLISHED_VERIFY_DELAY_MS`。

package/docs/zh/roadmap.md

@@ -1,6 +1,79 @@
 # 路线图
 
-0.20.70 正在推进。项目会先持续完成可靠性与协议兼容性的中版本迭代，再进入 1.0.0 稳定性冻结。
+0.20.85 正在推进。项目会先持续完成可靠性与协议兼容性的中版本迭代，再进入 1.0.0 稳定性冻结。
+
+## 0.20.85 已完成范围
+
+- 新增固定种子的属性测试套件（`tests/property.test.ts`）：针对纯热路径函数与有状态管理器，覆盖有限性/全函数性、与顺序无关的选择、循环安全的大小估算、publication topic/元数据有效性、`serializeError` 可克隆性，以及长时间随机操作序列下的 dedup/replay 上界。
+- `effectiveWorkerLoad` 对损坏的存储基础负载保持全函数性——非有限值（JSON `1e999` → `Infinity`）不再泄漏进 owner 选择并重新引入数组顺序依赖。
+- `approximatePayloadBytes` 增加深度上界，循环 payload（structured clone 会保留循环）不再使回放字节占用或自适应负载采样栈溢出。
+- `serializeError` 始终产出可结构化克隆的结果；不可克隆的 context（函数/Symbol）会被丢弃，而不是让错误上报本身抛出 `DataCloneError`。
+- 当 `pruneStrategy: 'age'` 未配置 `retentionMs` 时，回放历史重新受上界约束：内存环与 IndexedDB 记录均应用数量上限。
+
+## 0.20.84 已完成范围
+
+- 发布/CI 门禁由“文档约定”变为强制执行：`pnpm test:coverage`、`pnpm verify:compat`、`pnpm verify:pack` 进入 CI verify job，Release 工作流在发布前重跑 lint + compat + pack，两个 checkout 均拉取完整历史与 tag 以便解析 compat 基线。
+- 协调恢复加固：交接 ACK 丢失、owner 崩溃或前任 owner 退出后，均由 worker-TTL 门禁的重新选举恢复，采用单写者与投影负载分摊；每次路由确认 / 迁移 / 恢复都会发出有界的 `reliability` trace 事件。
+- 三个真实正确性修复：Vue `useCrossTabDataBus` 卸载泄漏（pending start 可能创建无人拥有的 bus）、自适应 dedup TTL 未在热路径生效，以及 `effectiveWorkerLoad` 会把损坏的存储 load 造成的非有限评分泄漏回 owner 选择。
+- 产品 demo 可观测性：事件流渲染 reliability / subscription / coordination trace 事件，混沌开关在真实浏览器中演练丢 ACK 与崩溃恢复路径，配置面板显示当前混沌模式。
+- 覆盖与工具链：`ReplayManager` / `DedupManager` 直接测试套件、transport 错误隔离与部分元数据覆盖、vitest 5（基准 API 已迁移）与 eslint 10 lint 配置；TypeScript 7 因 typescript-eslint 未支持而继续递延。
+
+## 0.20.83 已完成范围
+
+- 健康钩子的适配器边界用例、可归档对比的浏览器基准、与当前能力对齐的 README 特性清单。
+- 一次大规模内部清理：全部运行时字符串字面量集中到 `utils/constants.ts` 并由之派生字面量类型，回放与去重从 `CrossTabDataBus` 拆分为自包含的 `ReplayManager` / `DedupManager`。
+- demo 的「批量 10」publishBatch 按钮与 `/debug/wsstats` 帧计数及单帧 E2E，`asyncSink: true` 投递语义文档，以及与阻塞式发布消费者校验对齐的发布检查清单。
+
+## 0.20.82 已完成范围
+
+- E2E 默认断言上限提升至 20 秒；结构化克隆拒收（Symbol）与 cause 保留覆盖；共享模式会话生命周期经示例服务的连接数端点端到端验证。
+
+## 0.20.81 已完成范围
+
+- 浏览器基准新增 data-bus 热路径矩阵，健康摘要纳入 E2E 端到端断言，storage-event 通道与传输层批量进入 API 文档与能力矩阵。
+
+## 0.20.80 已完成范围
+
+- E2E 可靠性治理：失败 trace/视频与更长保留期、reload 类用例的先收敛后发布模式、符合文档保证的错峰突发模式，以及架构文档中的丢失与恢复矩阵。
+
+## 0.20.79 已完成范围
+
+- 已发布包消费自检成为 release 阻塞门禁（重试预算提升至 24 × 5 秒）；丢失 ACK 交接的恢复链（TTL 清理 + 恢复后重选举）由回归固化。
+
+## 0.20.78 已完成范围
+
+- E2E 逐 Tab 断言真实 transport 后端；延迟关闭不变量由回归测试固化并写入架构文档；getting-started 覆盖健康摘要与协调降级。
+
+## 0.20.77 已完成范围
+
+- 修复无 factory 时静默降级本地会话的缺陷（打包的 Worker 现在真正被使用）；补充默认后端与通道丢失恢复覆盖；demo 展示协调通道诊断与降级开关。
+
+## 0.20.76 已完成范围
+
+- 面向无 BroadcastChannel 环境的 opt-in storage-event 协调降级通道，含降级通道上的 owner 选举集成测试，并同步降级文档与能力矩阵。
+
+## 0.20.75 已完成范围
+
+- 单测套件新增热路径性能门禁（宽松阈值防灾难性退化，真实基准仍在 `pnpm bench`）；IndexedDB replay 持久化新增脚本化故障注入，覆盖 invalidate 与恢复错误路径；审计确认 Release workflow 已集成已发布包消费自检。
+
+## 0.20.74 已完成范围
+
+- 可选的 `DataBusTransport.publishBatch`：WebSocket transport 单帧批量发送，demo server 支持批量帧，无批量能力的 transport 自动回退逐条发送；React/Vue 新增 `useCrossTabHealth` 绑定；健康判定纳入 transport 实时状态。
+
+## 0.20.73 已完成范围
+
+- IndexedDB replay 持久化适配器纳入单测（基于 `fake-indexeddb`）：覆盖裁剪策略、批量分组、并发串行化、清理语义与瞬时打开失败恢复。
+- 真实浏览器 E2E 新增三 Tab 并发发布突发与整连接重构建（stop/start）重入集群两个场景；architecture 文档新增稳定性不变量参考（中英文）。
+
+## 0.20.72 已完成范围
+
+- 扩展基准矩阵，覆盖 `publishBatch`、wildcard routing、dedup、replay prune、批量持久化与异步 trace sink。
+- 长时稳定性加固：补齐 handoff ACK 世代校验、BFCache 往返、恢复耗尽重置、存储写退避恢复与 replay 持久化清理竞态的回归测试；修复反向的 stale-ACK 世代比较与批量 flush 复活清理历史两处缺陷。
+- 生产能力：`getHealthSummary()` 就绪判定、`getPersistenceStats()`、diagnostics 中 transport 状态细化（status/suspended），以及构建时注入的 SDK 版本。
+
+## 0.20.71 已完成范围
+
+- 新增可选 `appendBatch` replay 持久化接口；IndexedDB 对发布突发进行事务合并，旧适配器保持兼容。
 
 ## 0.20.70 已完成范围
 
@@ -381,19 +454,31 @@
 - publication metadata 做兼容性归一化：只接受非空 ID 与有限 timestamp。
 - 补充 legacy、嵌套、fallback topic 和坏 metadata 协议夹具测试。
 
+## 0.11.0 已完成范围
+
+- 当持久化适配器支持 `clearBefore` 时，通过 `replay.retentionMs` 自动执行持久化回放留存。
+- 周期性 trace 指标中加入去重接受/抑制计数。
+- 覆盖 WebSocket、Centrifuge、Worker 边界与浏览器 E2E 的 publication metadata 兼容性测试。
+- Service Worker transport 决策：在目标浏览器具备稳定的连接生命周期契约前，刻意保持不实现。
+
 ## 0.20.68 已交付
 
 - 为集群帧和 worker snapshot 增加协议版本元数据，并保持旧版本缺失字段时的兼容处理。
 
 ## 0.20.69 候选
 
-1. 增加 peer 能力矩阵，并在 diagnostics 暴露 SDK、后端与 transport 身份；
-2. 统一 replay、dedup、trace、recovery 与 cluster 健康指标；
-3. 优化 IndexedDB 并发 append 与清理路径；
-4. 增加 adaptive dedup、async trace、prune 和长时多 Tab 性能基线。
+1. ~~增加 peer 能力矩阵，并在 diagnostics 暴露 SDK、后端与 transport 身份。~~ 已交付：`getDiagnostics()` 携带协议版本、未知消息统计、peer 协议版本与 transport 身份；`getHealthSummary()`/`getMetrics()` 现在也会随单一对象输出实时 trace 指标与 sink 状态。
+2. ~~统一 replay、dedup、trace、recovery 与 cluster 健康指标。~~ 已交付：`getDiagnostics()` + `getMetrics()` + `getHealthSummary()` 在单一快照中覆盖生命周期、恢复、dedup、replay、持久化、协议、transport、cluster、trace 指标与 sink 背压。
+3. ~~优化 IndexedDB 并发 append 与清理路径。~~ 已交付：相邻 `appendBatch` 变更合并为单事务；`clear`/`clearTopic`/`clearBefore` 顺序保持。
+4. ~~增加 adaptive dedup、async trace、prune 和长时多 Tab 性能基线。~~ 部分交付：bench 覆盖负载加权评分、`getMetrics`、publishBatch 批次敏感性，以及既有 dedup/async-sink/persistence 用例。
 
 ## 0.13.0 候选
 
+1. 冻结公共导出面与 transport 无关的 publication 信封。
+2. 精确记录 at-least-once 投递与去重保证。
+3. 增加长时浏览器浸泡覆盖：replay 留存、重连、BFCache 与 owner 迁移。
+4. 为 1.0 前的协议别名发布迁移指南与弃用策略。
+
 ## 更长期候选
 
 1. **Replay 生命周期与留存**：增加持久化 `clear`/`clearTopic`，退订/替换时清理旧历史，并通过 trace 与 error handler 暴露持久化失败；

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cross-tab-worker-databus",
-  "version": "0.20.70",
+  "version": "0.20.85",
   "description": "Framework-agnostic cross-tab data bus with Dedicated/Shared Worker clustering and Centrifuge support.",
   "type": "module",
   "license": "MIT",
@@ -24,9 +24,29 @@
   ],
   "files": [
     "dist",
-    "docs",
+    "docs/api.md",
+    "docs/architecture.md",
+    "docs/benchmarks.md",
+    "docs/capabilities.md",
+    "docs/configuration.md",
+    "docs/getting-started.md",
+    "docs/release-checklist.md",
+    "docs/roadmap.md",
+    "docs/transports.md",
+    "docs/README.md",
+    "docs/zh/api.md",
+    "docs/zh/architecture.md",
+    "docs/zh/benchmarks.md",
+    "docs/zh/capabilities.md",
+    "docs/zh/configuration.md",
+    "docs/zh/getting-started.md",
+    "docs/zh/release-checklist.md",
+    "docs/zh/roadmap.md",
+    "docs/zh/transports.md",
+    "docs/zh/README.md",
     "CHANGELOG.md",
     "README.md",
+    "README.zh.md",
     "LICENSE"
   ],
   "main": "./dist/cjs/index.cjs",
@@ -77,6 +97,8 @@
     "test:coverage": "vitest run --coverage",
     "bench": "vitest bench --run",
     "bench:browser": "pnpm build && node scripts/bench-browser.mjs",
+    "bench:compare": "node scripts/bench-compare.mjs",
+    "bench:trend": "node scripts/bench-trend.mjs",
     "verify:pack": "node scripts/verify-packed-consumer.mjs",
     "verify:compat": "node scripts/verify-version-compat.mjs",
     "verify:published": "node scripts/verify-published-consumer.mjs",
@@ -101,21 +123,22 @@
     }
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.5",
-    "@playwright/test": "^1.62.1",
+    "@eslint/js": "^10.0.1",
+    "@playwright/test": "^1.63.0",
     "@testing-library/react": "^16.3.3",
-    "@types/node": "^24.0.0",
-    "@types/react": "^18.3.31",
-    "@vitest/coverage-v8": "^3.2.7",
-    "esbuild": "^0.25.0",
-    "eslint": "^9.39.4",
-    "globals": "^17.11.0",
-    "jsdom": "^25.0.1",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "typescript": "^5.9.0",
-    "typescript-eslint": "^8.68.0",
-    "vitest": "^3.2.0",
+    "@types/node": "^26.5.0",
+    "@types/react": "^19.3.0",
+    "@vitest/coverage-v8": "^5.0.0",
+    "esbuild": "^0.28.2",
+    "eslint": "^10.10.0",
+    "fake-indexeddb": "^6.2.5",
+    "globals": "^17.12.0",
+    "jsdom": "^30.0.1",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.70.0",
+    "vitest": "^5.0.0",
     "vue": "^3.5.42"
   },
   "engines": {