cross-tab-worker-databus 0.20.85 → 0.20.87

package/docs/zh/benchmarks.md

@@ -2,20 +2,20 @@
 
 # 浏览器基准趋势
 
-> 数据截至 2026-09-11，基于 12 份归档的 `bench-results/browser-*.json` 报告（运行 `pnpm bench:browser` 追加一份；用 `node scripts/bench-trend.mjs` 重新生成本文档）。
+> 数据截至 2026-09-12，基于 14 份归档的 `bench-results/browser-*.json` 报告（运行 `pnpm bench:browser` 追加一份；用 `node scripts/bench-trend.mjs` 重新生成本文档）。
 
 发布门禁的对比基线是最近两份报告之间的 `pnpm bench:compare --fail-above-pct 50`（50% 上限用于吸收共享 runner 的噪声）。本文记录长期趋势：数值为逐指标延迟，越低越好；历史最优为本机观察到的最健康一次运行。
 
 <!-- BENCH-TREND:BEGIN (machine-generated table) -->
 | 指标 | 上次 (ms) | 本次 (ms) | Δ | 历史最优 (ms) |
 |---|---|---|---|---|
-| publish per-message (ms, lower is better) — dedicated | 43.8388 | 40.8227 | -3.02 | 40.8227 |
-| publish per-message (ms, lower is better) — shared | 34.2105 | 35.4339 | +1.22 | 33.8206 |
-| wildcard dispatch ×1000 (ms, lower is better) | 6.5 | 6.7 | +0.20 | 0.1 |
-| publishBatch ×1000 (ms, lower is better) | 4.2 | 4 | -0.20 | 0.4 |
-| dedup ×1000 (ms, lower is better) | 15.5 | 13.9 | -1.60 | 0 |
-| trace + publish ×1000 (ms, lower is better) | 5.8 | 5.3 | -0.50 | 4.8 |
-| first-packet cold dispatch (ms, lower is better) | 0 | 0 | +0.00 | 0 |
+| publish per-message (ms, lower is better) — dedicated | 61.1276 | 58.888 | -2.24 | 40.8227 |
+| publish per-message (ms, lower is better) — shared | 38.5784 | 45.0451 | +6.47 | 33.8206 |
+| wildcard dispatch ×1000 (ms, lower is better) | 6.5 | 7.5 | +1.00 | 0.1 |
+| publishBatch ×1000 (ms, lower is better) | 4.5 | 5.1 | +0.60 | 0.4 |
+| dedup ×1000 (ms, lower is better) | 13.4 | 14.5 | +1.10 | 0 |
+| trace + publish ×1000 (ms, lower is better) | 5.3 | 5.2 | -0.10 | 4.8 |
+| first-packet cold dispatch (ms, lower is better) | 0.1 | 0 | -0.10 | 0 |
 <!-- BENCH-TREND:END -->
 
 说明：

package/docs/zh/configuration.md

@@ -60,10 +60,10 @@ const bus = new CrossTabDataBus({
 
 | 配置 | 类型 | 默认值 | 说明 |
 |---|---|---|---|
-| `maxPerTopic` | `number` | `100` | 每个 topic 最多缓冲的 publication 数；超出时先淘汰最旧条目（正安全整数） |
+| `maxPerTopic` | `number` | `100` | `count`/`both` 下每个 topic 最多缓冲的 publication 数；超出时先淘汰最旧条目。`age` 下带时间戳条目按 retention 窗口有界，无时间戳的 legacy 条目仍受该值限制（正安全整数） |
 | `persistence` | `DataBusReplayPersistence` | — | 可选持久化后端（`createIndexedDbReplayPersistence`）；省略则历史仅存内存 |
 | `retentionMs` | `number` | — | 生产者时间戳保留窗口；早于 cutoff 的历史通过适配器的 `clearBefore` 清理 |
-| `pruneStrategy` | `'count' \| 'age' \| 'both'` | `'count'` | `count` 按 `maxPerTopic` 截断；`age` 按 `retentionMs` 清理；`both` 两者都应用。`age` 未配置 `retentionMs` 时无 age 可依，回退为数量上限 |
+| `pruneStrategy` | `'count' \| 'age' \| 'both'` | `'count'` | `count` 按 `maxPerTopic` 截断；`age` 按 `retentionMs` 清理带时间戳历史，并以 `maxPerTopic` 限制无时间戳的 legacy 条目；`both` 两者都应用。`age` 未配置 `retentionMs` 时无 age 可依，回退为数量上限 |
 | `retentionSweepMs` | `number` | — | 面向安静 topic 的周期性 durable retention sweep；需要 `retentionMs` 与实现 `clearBefore` 的适配器 |
 | `persistenceRetry` | `{ maxAttempts, backoffMs }` | `1` / `50` | 瞬时持久化失败的有界重试；延迟指数增长并封顶 |
 

package/docs/zh/roadmap.md

@@ -1,6 +1,20 @@
 # 路线图
 
-0.20.85 正在推进。项目会先持续完成可靠性与协议兼容性的中版本迭代，再进入 1.0.0 稳定性冻结。
+0.20.87 正在推进。项目会先持续完成可靠性与协议兼容性的中版本迭代，再进入 1.0.0 稳定性冻结。
+
+## 0.20.87 已完成范围
+
+- transport 恢复与就绪加固：原生 WebSocket 后端现在遵守 `DataBusTransport.start()` 契约（仅在 `open` 后 resolve，握手失败或超过 `connectTimeoutMs` 时 reject），自动恢复会真正创建替代 socket，`getHealthSummary()` 跟随 live transport 状态而不是 `transportReady` 诊断标记。
+- 不再把操作写进已经消失的连接：恢复门会把 `subscribe()` / `publish()` 停放在自动与按需重开之后（包括自动尝试失败但仍保留预算的情况）；在真实连接之后出现的干净 `disconnected` 现在会触发一次按需重开，而不是交给已关闭的 socket；而异步上报连接状态的 worker 型后端仍保有其「尚未连接」窗口，不会被动重开。
+- 生命周期与 `ready()` 边界修复：BFCache 挂起期间 `ready()` 会 reject；transport 自身 `stop()` reject 或抛错时 `stop()` 仍能 resolve；一次打开失败在两个恢复账本中只打一次时间戳；运行期 transport 错误会进入恢复账本；被取代的异步打开不再拆除更新的 suspend/resume 转换。
+- 适配器与工具链：React/Vue `useCrossTabHealth` 在 `intervalMs` 变化时无需重建 bus 即可生效；`vitest` 及其 coverage-v8 provider 升级到 5.0.1 补丁版。
+
+## 0.20.86 已完成范围
+
+- 加固显式 stop/start 边界的生命周期：排队重启与进行中的 stop 串行化，并会被更新的 stop 取消，可通过 `ready()` 观测；被取代的异步开启不再拆除更新的 suspend/resume 转换；stop 期间调用的 `subscribe()` 与非空 `publish()`/`publishBatch()` 改为通过 `onError` 上报，不再修改 teardown 状态或被静默丢弃。
+- 显式 `start()` 在自动恢复预算耗尽后，现在会执行文档所述的手动恢复，同时保留 cluster 状态、订阅与回放历史。
+- IndexedDB replay 持久化在事务 abort（包括连接丢失导致的 abort）时结算全部 mutation，串行队列不再永久阻塞；replay AGE 裁剪改为内存与持久化历史共用同一套位置无关策略。
+- 配置参考在中英文中完整记录 replay/dedup 公共选项，并新增从声明派生的文档守卫；固定种子属性不变量覆盖 active-worker 选择与 rebalance target。
 
 ## 0.20.85 已完成范围
 

package/docs/zh/transports.md

@@ -32,6 +32,10 @@ interface DataBusTransportHandlers<TData = unknown> {
 三个回调。连接状态变化时调 `onStatus`；收到 publication 时调 `onMessage`；
 非致命错误调 `onError`（DataBus 有恢复冷却窗口，避免抖动连接死循环重试）。
 
+`start()` MUST 在后端真正连接后才 settle 返回的 Promise；尝试失败时必须 reject。
+DataBus 把这个 settlement 当作就绪与恢复边界：处于 `CONNECTING` 的 socket 不算
+就绪，握手成功前不能释放排队操作。可能长期卡住的后端应自行设置握手超时并 reject。
+
 ## 架构分层
 
 ```
@@ -141,9 +145,17 @@ Centrifuge session 遵循同一个传输无关契约：不带 metadata 的 paylo
 形状；带 metadata 的 publish 使用 `{ data, messageId?, timestamp? }`，入站还接受
 标准嵌套 `DataBusPublicationEnvelope`。
 
+`start()` 只在 `open` 后 resolve；握手前发生 error、close，或超过
+`connectTimeoutMs` 时 reject（默认 `30000` ms；`0` / `Infinity` 表示无限等待）。
+超时的 socket 会被关闭，该尝试之后迟到的 `open` 会被忽略。
+
 生命周期映射：`open` → `connected`，`close` → `disconnected`，`error` → `error`
-（触发 DataBus 自动恢复）。socket 原地重连时自动重发订阅帧。支持 pattern 的
-服务器可以以具体 topic 标注发布——见 [api.md](../api.md) 中的通配符订阅。
+（触发 DataBus 自动恢复）。socket 原地重连时自动重发订阅帧。成功的重开既可以
+复用同一个 socket 对象，也可以通过工厂创建替代 socket；被取代 socket 的迟到
+回调会被忽略，因此失败连接的 close 或 message 不会污染恢复后的连接。干净的
+`disconnected` 不会调度后台自动恢复，但下一次 `subscribe()` / `publish()` 会触发
+一次按需重开并在其后 flush，因此关闭后的操作不会被写进已关闭的 socket。支持
+pattern 的服务器可以以具体 topic 标注发布——见 [api.md](../api.md) 中的通配符订阅。
 
 ## 工厂入口
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cross-tab-worker-databus",
-  "version": "0.20.85",
+  "version": "0.20.87",
   "description": "Framework-agnostic cross-tab data bus with Dedicated/Shared Worker clustering and Centrifuge support.",
   "type": "module",
   "license": "MIT",
@@ -126,9 +126,9 @@
     "@eslint/js": "^10.0.1",
     "@playwright/test": "^1.63.0",
     "@testing-library/react": "^16.3.3",
-    "@types/node": "^26.5.0",
+    "@types/node": "^26.5.1",
     "@types/react": "^19.3.0",
-    "@vitest/coverage-v8": "^5.0.0",
+    "@vitest/coverage-v8": "^5.0.1",
     "esbuild": "^0.28.2",
     "eslint": "^10.10.0",
     "fake-indexeddb": "^6.2.5",
@@ -138,7 +138,7 @@
     "react-dom": "^19.3.0",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.70.0",
-    "vitest": "^5.0.0",
+    "vitest": "^5.0.1",
     "vue": "^3.5.42"
   },
   "engines": {