cross-tab-worker-databus 0.10.0 → 0.20.6

package/docs/zh/configuration.md

@@ -46,7 +46,27 @@ const bus = new CrossTabDataBus({
 | `metricsIntervalMs` | `number` | `5000` | 聚合窗口，必须是大于 0 的有限数值 |
 | `sink` | `(event) => void` | 必填 | 由接入方决定 console、监控 SDK 或其他出口 |
 
-`message_metrics` 包含窗口时长、接收数、分发数、活跃 Topic 数量，以及接收 → 分发延迟的样本数、平均值、P50、P95 和最大值。延迟按 50ms 桶聚合，不包含单条消息 payload。订阅事件会带 Topic，便于接入方关联 owner 变化；仅 owner transport 的订阅集合实际变化时才输出，幂等 `CONTROL` 重试不会产生重复订阅事件。将 trace 写入 console 或外部监控前，应按业务 Topic 约定进行脱敏。Trace 不包含 URL、凭证、payload 或错误正文。sink 抛错会被隔离，不会中断消息分发，但会向 `console.warn` 输出错误，方便接入方发现诊断配置问题。
+`message_metrics` 包含窗口时长、接收数、分发数、活跃 Topic 数量，以及接收 → 分发延迟的样本数、平均值、P50、P95 和最大值，并包含同一窗口的 `dedupAccepted` 与 `dedupSuppressed` 计数。延迟按 50ms 桶聚合，不包含单条消息 payload。持久化失败会先输出带 `operation: persistence_cleanup` 的有界 `reliability` 事件，再交给 error handler；`dedup.now` 与 `trace.now` 均可注入，以便确定性测试 TTL、事件时间戳和 metrics 窗口。订阅事件会带 Topic，便于接入方关联 owner 变化；仅 owner transport 的订阅集合实际变化时才输出，幂等 `CONTROL` 重试不会产生重复订阅事件。将 trace 写入 console 或外部监控前，应按业务 Topic 约定进行脱敏。Trace 不包含 URL、凭证、payload 或错误正文。sink 抛错会被隔离，不会中断消息分发，但会向 `console.warn` 输出错误，方便接入方发现诊断配置问题。
+
+启用 `replay.retentionMs` 时，自动 durable cleanup 会在 publication burst 期间合并：复用进行中的清理，并在其完成后应用最新 cutoff。在不改变 retention 边界的前提下，这会限制 IndexedDB 清理事务数量。
+
+`replay.retentionSweepMs` 可选地按周期触发同一清理逻辑。它适合安静 topic 的 durable 旧记录也需要过期的场景；需要同时配置 `retentionMs` 和实现 `clearBefore()` 的持久化适配器。定时器遵循页面可见性和生命周期切换，默认关闭。
+
+`replay.persistenceRetry` 可选地控制瞬时持久化失败的恢复。`maxAttempts` 是总尝试次数（默认 `1`），`backoffMs` 是首次重试前的延迟（默认 `50`）；延迟会指数增长并封顶。最终失败仍沿用现有 `onError` 和 reliability 行为。
+
+启用 trace 后，每次在最终尝试之前发生的重试都会发出有界 `reliability` 事件：`operation: persistence_retry`，并包含 `persistenceOperation`（`load`、`append`、`clear`、`clearTopic` 或 `clearBefore`）和失败的尝试次数。不包含 payload、URL、凭证或错误正文。
+
+WebSocket 二进制帧可能以 `ArrayBuffer` 或浏览器 `Blob` 到达；两者使用相同的紧凑二进制 publication 格式。Blob 转换是异步的，转换失败会通过 transport error handler 报告。
+
+Retry 等待遵循生命周期：`stop()` 和 pagehide 挂起会取消待执行的 retry；之后的 `start()`/pageshow 会在新的生命周期代际中开始新工作。
+
+`dedup.sweepMs` 可选地在 bus started 且可见时执行 TTL 清理，默认关闭；无论是否开启，消息到达时清理和 `maxEntries` 上限仍然生效。
+
+Vue 适配层会串行化 bus 替换，并在 reactive 依赖快速变化时忽略过期的 stop 完成，确保组件始终绑定最新生命周期。
+
+React 适配层同样在 StrictMode 和依赖驱动的重建过程中使用 generation 保护，过期 effect 清理不会清除更新后的 bus。
+
+IndexedDB replay persistence 收到 `versionchange` 时会关闭连接，并在下一次操作时惰性重新打开，从而支持多 tab schema 升级后的恢复。
 
 `pagehide` 时聚合定时器会停止并丢弃未完成窗口，`pageshow` 后以新窗口恢复；永久 `stop()` 会清理定时器。这里节流的只是诊断输出，真实消息接收与分发不会被限速。
 

package/docs/zh/release-checklist.md

@@ -0,0 +1,20 @@
+# 发布检查清单
+
+每个 1.0.0 之前的版本都按此清单执行。仓库不由助手执行发布；完成打包验证并人工审阅后，再手动运行 npm 命令。
+
+## 打 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`。
+
+## 发布
+
+从对应 tag 的工作树运行 `npm publish --access public`。已经存在于 npm 的版本不能重复发布；npm 缺失的历史版本必须从对应 git tag 重建并逐个审阅，不能把当前工作树伪装成旧版本发布。
+
+## 发布后
+
+1. 用 `npm view cross-tab-worker-databus versions --json` 确认版本已出现。
+2. 在干净消费者中安装已发布版本或 tarball，并导入主入口及所有公开子路径。
+3. 将结果记录到发布说明。在公开 API 和协议弃用策略明确冻结前，不进入 `1.0.0`。

package/docs/zh/roadmap.md

@@ -1,8 +1,138 @@
 # 路线图
 
-0.6.0 已发布。下一阶段按 0.7.0 候选推进，先做可靠性与诊断，让新行为在扩展协议前可观测。
+0.20.6 正在推进。项目会先持续完成可靠性与协议兼容性的中版本迭代，再进入 1.0.0 稳定性冻结。
 
-## 0.7.0 候选
+## 0.20.6 已完成范围
+
+- 新增中英文发布检查清单，覆盖本地验证、打包消费者、打 tag、手动 npm 发布和发布后验证。
+- 明确 npm 历史版本不可覆盖；缺失的历史版本必须从对应 git tag 重建。
+
+## 0.20.5 已完成范围
+
+- 新增公开消费者冻结覆盖：主入口、hooks、Vue、Centrifuge 子路径的 ESM 与 CommonJS 双格式消费。
+- 校验发布包中的声明文件存在，并包含 replay、dedup 和 publication metadata 等关键类型。
+
+## 0.20.4 已完成范围
+
+- 新增真实 Chromium 多 Tab soak 场景，覆盖重复 fan-out、owner migration、BFCache 往返、reload 恢复和无重复投递。
+- 将浏览器生命周期转换串成一个连续会话，能够捕获孤立用例难以发现的 timer 与 route 清理回归。
+
+## 0.20.3 已完成范围
+
+- 新增 React 动态 topic 生命周期覆盖。
+- 验证 topic 替换会移除旧订阅后再接收新 topic，且通过 WebSocket hook 链路生效。
+
+## 0.20.2 已完成范围
+
+- 新增协议恢复回归：malformed binary/text frame 之后，合法 WebSocket publication 仍可继续投递。
+- 将二进制截断、JSON 解析失败、nested envelope 和错误隔离串成一个兼容性序列验证。
+
+## 0.20.1 已完成范围
+
+- 新增 persistence mutation sequence soak 覆盖：hydration、重试恢复、topic 清理、后续 append 和全量清理。
+- 验证串行 persistence 操作在瞬时失败后仍可继续使用。
+
+## 0.20.0 已完成范围
+
+- publication envelope 兼容性已覆盖 legacy、嵌套、fallback topic、原始 payload、metadata 和未知字段帧。
+- 缺失或空 topic 会统一拒绝，同时继续支持 transport 提供的 fallback channel。
+
+## 0.19.9 已完成范围
+
+- 新增 dedup 与 replay/persistence 组合回归覆盖。
+- 被 dedup 抑制的 publication 不会污染 replay 历史；TTL 到期后同一 message ID 可以再次被接受。
+
+## 0.19.8 已完成范围
+
+- IndexedDB replay adapter 在事务或请求失败后会使缓存连接失效。
+- 已关闭或不可用的连接可沿用现有 persistence retry 路径恢复，不需要重建 adapter。
+
+## 0.19.7 已完成范围
+
+- IndexedDB replay adapter 在 open 失败后会丢弃 rejected promise，下一次操作可重新打开并恢复。
+- 与既有跨 tab `versionchange` 连接重置行为保持兼容。
+
+## 0.19.6 已完成范围
+
+- IndexedDB replay adapter 遇到跨 tab `versionchange` 时会关闭旧连接，并在下一次操作时重新打开。
+- schema 变化后不会继续复用失效数据库连接。
+
+## 0.19.5 已完成范围
+
+- React bus effect 在 StrictMode 和快速依赖切换下使用 generation 保护。
+- 过期的异步清理不会覆盖最新的 active bus。
+
+## 0.19.4 已完成范围
+
+- Vue bus 在快速 reactive 依赖切换时使用 generation 保护重建流程。
+- 过期的异步生命周期完成不会重新挂回旧 bus 实例。
+
+## 0.19.3 已完成范围
+
+- 新增可选 `dedup.sweepMs`，在安静期间定时删除过期 message ID。
+- sweep 定时器遵循 DataBus 生命周期，默认关闭。
+
+## 0.19.2 已完成范围
+
+- `stop()` 和 pagehide 挂起边界会取消待执行的 persistence retry。
+- 已取消的 retry 不会再次调用 adapter，也不会被当作持久化失败上报。
+
+## 0.19.1 已完成范围
+
+- WebSocket 二进制 publication 除 `ArrayBuffer` 外，也支持浏览器常见的 `Blob` 帧。
+- Blob 转换失败会通过 transport error callback 隔离报告，不会打崩消息回调。
+
+## 0.19.0 已完成范围
+
+- persistence retry 会发出有界、可选开启的 `persistence_retry` reliability 事件，包含操作名和尝试次数。
+- 诊断覆盖 hydration、append、全量/Topic 清理以及 retention 清理，不暴露 payload 或错误正文。
+- 保持既有重试时序、默认单次尝试、adapter 契约和最终错误处理兼容。
+
+## 0.18.0 已完成范围
+
+- 新增可选 replay persistence retry，支持有限尝试次数和指数退避。
+- append、hydration、手动清理、topic 清理和 retention 清理统一使用恢复路径。
+- 导出公开 retry 配置类型，同时保持 persistence adapter 契约兼容。
+
+## 0.17.0 已完成范围
+
+- 新增可选的周期性 replay retention sweep，即使没有新 publication 也能清理 durable history。
+- sweep 定时器遵循 start/resume 与 pagehide/stop 生命周期边界。
+- 补充 fake-timer 覆盖，保护清理调度、销毁和非法配置行为。
+
+## 0.16.0 已完成范围
+
+- publication burst 期间会合并 retention cleanup，并以最新 cutoff 串行执行持久化 mutation。
+- WebSocket binary 协议边界新增截断帧和非法帧回归覆盖。
+- 继续保留并明确 legacy replay、JSON metadata 和手动清理的兼容保证。
+
+## 0.15.0 已完成范围
+
+- replay retention 会保留没有显式 timestamp 的 legacy 消息，只清理早于 cutoff 且带显式 timestamp 的记录。
+- trace 时间戳支持注入 `trace.now`，与已有的 dedup 时钟注入保持一致。
+- 补充 replay 清理、诊断和适配器行为的兼容性与生命周期回归覆盖。
+
+## 0.14.0 已完成范围
+
+- Vue composable 在同一个 bus 上切换 reactive topic 时会正确重绑。
+- 跨页面 replay mutation 顺序与生命周期保证已写入文档并有回归测试。
+
+## 0.13.0 已完成范围
+
+- IndexedDB replay mutation 按 adapter 串行化，避免并发 append 的读改写丢历史。
+- 完整 stop/restart 边界会清空 dedup 状态。
+- 补充持久化失败诊断和生命周期回归覆盖。
+
+## 0.12.0 已完成范围
+
+- dedup TTL 支持可注入时钟，生命周期与过期测试不再依赖墙上时间。
+- replay 持久化 append、hydration、退订和 retention 清理失败均有结构化诊断。
+- publication metadata 做兼容性归一化：只接受非空 ID 与有限 timestamp。
+- 补充 legacy、嵌套、fallback topic 和坏 metadata 协议夹具测试。
+
+## 0.13.0 候选
+
+## 更长期候选
 
 1. **Replay 生命周期与留存**：增加持久化 `clear`/`clearTopic`，退订/替换时清理旧历史，并通过 trace 与 error handler 暴露持久化失败；
 2. **可靠性诊断**：增加恢复/重试、owner ack、路由迁移结构化事件，元数据有界且默认关闭 trace；

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cross-tab-worker-databus",
-  "version": "0.10.0",
+  "version": "0.20.6",
   "description": "Framework-agnostic cross-tab data bus with Dedicated/Shared Worker clustering and Centrifuge support.",
   "type": "module",
   "license": "MIT",
@@ -77,6 +77,7 @@
     "test:coverage": "vitest run --coverage",
     "bench": "vitest bench --run",
     "bench:browser": "pnpm build && node scripts/bench-browser.mjs",
+    "verify:pack": "node scripts/verify-packed-consumer.mjs",
     "test:e2e": "pnpm build && playwright test",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "pnpm check"