cross-tab-worker-databus 0.21.9 → 0.21.10

package/dist/index.js

@@ -20,7 +20,7 @@ import {
   selectRebalanceTarget,
   selectWorkerBackend,
   topicMatchesPattern
-} from "./chunk-75ZDU7VG.js";
+} from "./chunk-L5P66THO.js";
 import {
   DEFAULT_STORAGE_PREFIX,
   PRUNE_STRATEGY,

package/dist/workers/port-reaper.d.ts

@@ -44,9 +44,15 @@ export declare class PortReaper {
      * resurrect it in the reaper's tracking maps. */
     touch(port: MessagePort): void;
     /** Override a port's session timeout from its INIT heartbeat config.
-     * A non-finite or non-positive value falls back to the default so a bad
-     * payload cannot degenerate the reaper into a busy loop or silence it.
-     * No-op for untracked ports (e.g. setTimeout arrives after remove/STOP). */
+     * `Infinity` is the documented way to disable the PING heartbeat, and it means
+     * this port can never be judged silent: `startHeartbeat()` sends nothing at all
+     * once configured that way, so a timeout would be a death sentence with no
+     * possible appeal. A non-finite-or-non-positive *other* value falls back to the
+     * default so a bad payload cannot degenerate the reaper into a busy loop or
+     * silence it — those three (NaN, 0, negative) are rejected by
+     * `assertHeartbeatInterval` at the transport constructor and so can only arrive
+     * from a main thread that is not this library. No-op for untracked ports (e.g.
+     * setTimeout arrives after remove/STOP). */
     setTimeout(port: MessagePort, heartbeatIntervalMs: number): void;
     /** Remove a port (STOP message). The caller is responsible for closing the
      * port and stopping the session. No-op for untracked ports so a duplicate

package/dist/workers/port-reaper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"port-reaper.d.ts","sourceRoot":"","sources":["../../src/workers/port-reaper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAQH;;+DAE+D;AAC/D,MAAM,WAAW,UAAU;IACzB,MAAM,IAAI,IAAI,CAAC;IACf,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,IAAI,CAAC;CACd;AAED,KAAK,QAAQ,GAAG,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;AAC7D,KAAK,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;AAE3C,qBAAa,UAAU;IAQnB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAC9D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkC;IAC7D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAkC;IACnE,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,UAAU,CAAiC;gBAGhC,GAAG,GAAE,MAAM,MAAiB,EAC7C,QAAQ,GAAE,QAA2E,EACrF,UAAU,GAAE,UAA4C;IAM1D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IAExC;;;oEAGgE;IAChE,QAAQ,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI;IAOrD;;qDAEiD;IACjD,KAAK,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAK9B;;;gFAG4E;IAC5E,UAAU,CAAC,IAAI,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,GAAG,IAAI;IAShE;;4EAEwE;IACxE,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAQ/B;2EACuE;IACvE,OAAO,IAAI,IAAI;IAgBf;;;yEAGqE;IACrE,OAAO,CAAC,QAAQ;IAahB;;8DAE0D;IAC1D,OAAO,CAAC,mBAAmB;IAQ3B;;qEAEiE;IACjE,OAAO,CAAC,IAAI;CAoDb"}
+{"version":3,"file":"port-reaper.d.ts","sourceRoot":"","sources":["../../src/workers/port-reaper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAQH;;+DAE+D;AAC/D,MAAM,WAAW,UAAU;IACzB,MAAM,IAAI,IAAI,CAAC;IACf,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,IAAI,CAAC;CACd;AAED,KAAK,QAAQ,GAAG,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;AAC7D,KAAK,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;AAE3C,qBAAa,UAAU;IAQnB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsC;IAC9D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkC;IAC7D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAkC;IACnE,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,UAAU,CAAiC;gBAGhC,GAAG,GAAE,MAAM,MAAiB,EAC7C,QAAQ,GAAE,QAA2E,EACrF,UAAU,GAAE,UAA4C;IAM1D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IAExC;;;oEAGgE;IAChE,QAAQ,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI;IAOrD;;qDAEiD;IACjD,KAAK,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAK9B;;;;;;;;;gDAS4C;IAC5C,UAAU,CAAC,IAAI,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,GAAG,IAAI;IAWhE;;4EAEwE;IACxE,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAQ/B;2EACuE;IACvE,OAAO,IAAI,IAAI;IAgBf;;;yEAGqE;IACrE,OAAO,CAAC,QAAQ;IAahB;;8DAE0D;IAC1D,OAAO,CAAC,mBAAmB;IAQ3B;;qEAEiE;IACjE,OAAO,CAAC,IAAI;CAoDb"}

package/docs/api.md

@@ -362,7 +362,7 @@ Available options:
 
 - `workerMode`: `'dedicated'` (default), `'shared'`, or `'auto'`; the `auto` degradation chain is SharedWorker -> Dedicated Worker -> local mode
 - `transferable`: `boolean`, default `false`; when enabled, ArrayBuffer payloads use Transferable transport, while the object message API remains unchanged
-- `heartbeatIntervalMs`: `number`, default `10000`; SharedWorker PING heartbeat interval in ms. `Infinity` disables heartbeats. Must be a positive number or `Infinity` — `0`, a negative number, or `NaN` throws a `TypeError` in the transport constructor. See [configuration](./configuration.md#sharedworker-session-reaper) for details
+- `heartbeatIntervalMs`: `number`, default `10000`; SharedWorker PING heartbeat interval in ms. `Infinity` disables heartbeats and exempts that port from reaping. Must be a positive number or `Infinity` — `0`, a negative number, or `NaN` throws a `TypeError` in the transport constructor. See [configuration](./configuration.md#sharedworker-session-reaper) for details
 - `workerFactory`: custom Dedicated Worker loading method
 - `sharedWorkerFactory`: custom SharedWorker loading method
 

package/docs/benchmarks.md

@@ -2,19 +2,19 @@
 
 # Browser Benchmark Trend
 
-> Data through 2026-09-22, from the 69 archived `bench-results/browser-*.json` reports (run `pnpm bench:browser` to add one; regenerate this doc with `node scripts/bench-trend.mjs`).
+> Data through 2026-09-23, from the 71 archived `bench-results/browser-*.json` reports (run `pnpm bench:browser` to add one; regenerate this doc with `node scripts/bench-trend.mjs`).
 
 The comparison baseline for release gating is `pnpm bench:compare --fail-above-pct 50`, which compares the newest report against the median of the same metric in the preceding reports (50% ceiling absorbs shared-runner noise; a single previous report was a fragile baseline because the in-page hot-path metrics alternate between a fast and a slow mode on identical code). This doc records the long-run picture: values are per-metric latencies where lower is better, and the last column is the best run inside the most recent 5 reports — not an all-time record, because the in-page matrix changed measurement semantics in early September 2026 and older reports are not comparable.
 
 <!-- BENCH-TREND:BEGIN (machine-generated table) -->
 | Metric | Previous (ms) | Latest (ms) | Δ | Best of last 5 runs (ms) |
 |---|---|---|---|---|
-| publish per-message (ms, lower is better) — dedicated | 80.1971 | 63.1886 | -17.01 | 62.3503 |
-| publish per-message (ms, lower is better) — shared | 49.8516 | 54.1494 | +4.30 | 39.6914 |
-| wildcard dispatch ×1000 (ms, lower is better) | 7.9 | 6.6 | -1.30 | 6.5 |
-| publishBatch ×1000 (ms, lower is better) | 4.4 | 5 | +0.60 | 4.4 |
-| dedup ×1000 (ms, lower is better) | 14 | 15.6 | +1.60 | 14 |
-| trace + publish ×1000 (ms, lower is better) | 5.3 | 5.9 | +0.60 | 5.2 |
+| publish per-message (ms, lower is better) — dedicated | 55.4416 | 50.6133 | -4.83 | 50.6133 |
+| publish per-message (ms, lower is better) — shared | 58.2441 | 33.8955 | -24.35 | 33.8955 |
+| wildcard dispatch ×1000 (ms, lower is better) | 5.2 | 5.7 | +0.50 | 5.2 |
+| publishBatch ×1000 (ms, lower is better) | 3.5 | 3.7 | +0.20 | 3.5 |
+| dedup ×1000 (ms, lower is better) | 13 | 11 | -2.00 | 11 |
+| trace + publish ×1000 (ms, lower is better) | 4.6 | 4.7 | +0.10 | 4.6 |
 | first-packet cold dispatch (ms, lower is better) | 0 | 0 | +0.00 | 0 |
 <!-- BENCH-TREND:END -->
 

package/docs/configuration.md

@@ -162,7 +162,7 @@ Main configuration for `createCentrifugeDataBus<TData>(options)`:
 | `clusterKey` | `string` | `connection.url` | Manually isolate logical clusters |
 | `workerMode` | `'dedicated' \| 'shared' \| 'auto'` | `'dedicated'` | Worker transport runtime mode; `auto` degrades via SharedWorker -> Dedicated Worker -> local mode, explicit `dedicated` degrades via Dedicated Worker -> SharedWorker -> local mode |
 | `transferable` | `boolean` | `false` | When enabled, `publish(topic, ArrayBuffer)` uses Transferable transport; ArrayBuffer publications on the receiving side also follow the transfer path |
-| `heartbeatIntervalMs` | `number` | `10000` | SharedWorker PING heartbeat interval (see SharedWorker Session Reaper below); `Infinity` disables heartbeats entirely. Distinct from the Core cluster heartbeat (default 3000 ms) which tracks worker liveness via localStorage |
+| `heartbeatIntervalMs` | `number` | `10000` | SharedWorker PING heartbeat interval (see SharedWorker Session Reaper below); `Infinity` disables heartbeats entirely and exempts that port from reaping. Distinct from the Core cluster heartbeat (default 3000 ms) which tracks worker liveness via localStorage |
 | `workerFactory` | `() => Worker` | Built-in Worker | For testing or custom Worker loading |
 | `sharedWorkerFactory` | `() => SharedWorker` | Built-in SharedWorker | For testing or custom SharedWorker loading |
 | `credentialProvider` | `{ getToken?, getChannelToken? }` | `undefined` | Async credential refresh bridge: the Worker asks the main thread for each fresh token (`getToken` / `getChannelToken`) and this provider supplies it from application context. Required because function-valued Centrifuge options cannot be structured-cloned into the Worker |
@@ -210,13 +210,13 @@ Storage events are delivered to other documents only. Two bus runtimes in the *s
 
 A `MessagePort` has no `close` event, so the SharedWorker cannot know when a tab has crashed or been closed without sending a `STOP` message. To avoid leaking a `CentrifugeSession` (and its WebSocket) for a dead tab, the transport sends a periodic **PING heartbeat** to the SharedWorker, and the SharedWorker runs a **reaper** that closes any session whose port has been silent for longer than its timeout.
 
-- **Heartbeat interval**: `heartbeatIntervalMs` (default `10000` ms). The main thread sends a `PING` on this cadence. Pass `Infinity` to disable heartbeats entirely — use this only when the SharedWorker reaper is not needed (e.g. the SharedWorker is guaranteed to be torn down with the tab).
-- **Session timeout**: `3 × heartbeatIntervalMs` (default `30000` ms). A port silent for longer than its timeout is reaped: its session is stopped and its WebSocket closed. This is distinct from the Core cluster heartbeat (default `3000` ms) which tracks worker liveness via localStorage — see the note below.
+- **Heartbeat interval**: `heartbeatIntervalMs` (default `10000` ms). The main thread sends a `PING` on this cadence. Pass `Infinity` to disable heartbeats entirely: the transport sends no `PING` at all, and it tells the Worker so by carrying that same `Infinity` in its `INIT`, which **exempts the port from reaping** — nothing on that port can ever be judged silent. Use this only when the SharedWorker reaper is not needed (e.g. the tab always stops the bus itself, so every port leaves through `STOP`). The cost is symmetrical and worth stating: a tab configured this way and then *crashed* leaves its `CentrifugeSession` and its WebSocket in place, because the one thing that would have noticed was the heartbeat that was switched off.
+- **Session timeout**: `3 × heartbeatIntervalMs` (default `30000` ms). A port silent for longer than its timeout is reaped: its session is stopped and its WebSocket closed. A port whose `INIT` carried `heartbeatIntervalMs: Infinity` has no timeout and is never reaped. This is distinct from the Core cluster heartbeat (default `3000` ms) which tracks worker liveness via localStorage — see the note below.
 - **Adaptive cadence**: the reaper runs at the smallest configured heartbeat interval across active ports, so a port with a short heartbeat is reaped promptly. When the last port disconnects, the reaper interval is cleared so a long-lived SharedWorker does not run a perpetual no-op interval between connection bursts.
 - **The tab is told before the port goes**: a port that is being reclaimed receives one final `SESSION_REAPED` message, then is closed, then its session is stopped. The order is the point — a `MessagePort` has no close event, and posting into a port the other side closed succeeds while delivering nothing, so this is the only thing a starved tab can ever learn from. Without it a tab that was merely stalled rather than gone (a long synchronous task, or the throttling a backgrounded tab gets) kept its cluster role and its topic routes while every publication it sent vanished into the dead port, and `getHealthSummary()` went on reporting `healthy` / `connected`. On receiving the message the transport discards the backend and reports the failure through `onError` and an `error` status, which is what lets the normal recovery path rebuild the session on a fresh port. Measured in a real browser: after a 34 s stall the tab re-established its subscription on its own — no user gesture, no lifecycle event — and the replacement connection was under a second old when it was observed.
 - **Port closed before session stop**: when a port is reaped, the port is closed first and the session stopped after. Closing the port discards the session's `disconnected` status post (so it never reaches a live-but-slow main thread) and guarantees a closed port can never deliver a later message that would resurrect the session outside the reaper's tracking.
-- **Failure isolation**: both reaping and `dispose()` wrap `target.close()`/`target.stop()` in try-catch, so a single failing port cannot abort the reaping pass or leave subsequent dead tabs uncollected.
-- **Shutdown cleanup**: when the SharedWorker shuts down, `PortReaper.dispose()` stops the timer and closes/stops **every** still-tracked session, so no `CentrifugeSession` or WebSocket outlives the reaper. This complements per-port reaping, which only covers ports that went silent while the reaper was running.
+- **Failure isolation**: reaping wraps `target.notify()`/`close()`/`stop()` in try-catch and `dispose()` wraps `close()`/`stop()`, so a single failing port cannot abort the reaping pass or leave subsequent dead tabs uncollected. A step that throws does skip the steps after it — for that one port only.
+- **`dispose()` has no Worker-side caller**: it clears the reaper interval and closes/stops **every** still-tracked session, and the unit tests exercise it, but the shipped SharedWorker never invokes it — a `MessagePort` has no close event, so there is no "the SharedWorker is shutting down" signal for such a hook to hang on. Every port leaves tracking through its own `STOP` handler or through the reaper, and the interval the reaper runs on is cleared once the last tracked port is gone.
 
 This is the mechanism that recovers sessions for tabs that crash without sending `STOP`, and the announcement it makes is what lets a tab that did *not* crash notice and reconnect. Lower `heartbeatIntervalMs` to reap dead sessions faster, at the cost of more frequent PING messages on the port — and note that a value below roughly a third of the longest task your page runs will start reaping live tabs, each of which recovers by rebuilding its session.
 

package/docs/roadmap.md

@@ -1,6 +1,32 @@
 # Roadmap
 
-0.21.9 was released on September 23, 2026. The project is intentionally continuing through reliability-focused releases before a 1.0.0 stability freeze.
+0.21.10 was released on September 23, 2026. The project is intentionally continuing through reliability-focused releases before a 1.0.0 stability freeze.
+
+## 0.21.10 delivered scope
+
+- `heartbeatIntervalMs: Infinity` — the documented way to switch the SharedWorker PING
+  heartbeat off — was being read by the reaper as a malformed number. It fell through the
+  same `Number.isFinite` guard as `NaN`, `0` and negatives and took the default 10 s, so
+  the port was given a 30 s session timeout on the strength of being the one port that would
+  never send another message: the option whose stated purpose is "the reaper is not needed"
+  guaranteed a reap 30 s after connecting. `Infinity` now exempts that port from reaping,
+  while the three values the transport constructor rejects (and which therefore cannot come
+  from this library at all) keep the fallback. Pinned by one test that kills three mutants at
+  three different assertions, plus an assertion that the `INIT` actually carries the value —
+  the two halves of this defect were each covered by a green test, which is how it survived.
+- The shipped reaper documentation stopped promising things the code does not do, in both
+  languages: no `PortReaper.dispose()` shutdown hook runs "when the SharedWorker shuts down"
+  (nothing calls it — a `MessagePort` has no close event, so there is no such signal to hang a
+  hook on), and what disabling the heartbeat costs is stated next to what it disables (a tab
+  configured that way and then crashed keeps its session and its WebSocket).
+- A test that passed while breaking the gate: an IndexedDB replay assertion attached its
+  rejection handler after an await that a real 40 ms timer could overtake, so on a loaded
+  runner `pnpm test:coverage` exited 1 with `Unhandled Rejection` and every test green. The
+  handlers are created next to their promises now, measured in both directions by forcing the
+  round trip to 200 ms.
+- No wire-format, storage-layout or cluster-protocol change. The behaviour change is confined
+  to shared mode configured with `heartbeatIntervalMs: Infinity`, which could not work as
+  documented before.
 
 ## 0.21.9 delivered scope
 

package/docs/zh/api.md

@@ -361,7 +361,7 @@ const transport = new CentrifugeWorkerTransport({
 
 - `workerMode`：`'dedicated'`（默认）、`'shared'` 或 `'auto'`；`auto` 的降级链路为 SharedWorker → Dedicated Worker → 本地模式
 - `transferable`：`boolean`，默认 `false`；开启后 ArrayBuffer payload 使用 Transferable 传输，对象消息 API 不变
-- `heartbeatIntervalMs`：`number`，默认 `10000`；SharedWorker PING 心跳间隔（毫秒）。传 `Infinity` 完全禁用心跳。详见 [配置](./configuration.md#sharedworker-会话回收)
+- `heartbeatIntervalMs`：`number`，默认 `10000`；SharedWorker PING 心跳间隔（毫秒）。传 `Infinity` 完全禁用心跳，该端口也因此豁免于回收。详见 [配置](./configuration.md#sharedworker-会话回收)
 - `workerFactory`：自定义 Dedicated Worker 加载方式
 - `sharedWorkerFactory`：自定义 SharedWorker 加载方式
 

package/docs/zh/benchmarks.md

@@ -2,19 +2,19 @@
 
 # 浏览器基准趋势
 
-> 数据截至 2026-09-22，基于 69 份归档的 `bench-results/browser-*.json` 报告（运行 `pnpm bench:browser` 追加一份；用 `node scripts/bench-trend.mjs` 重新生成本文档）。
+> 数据截至 2026-09-23，基于 71 份归档的 `bench-results/browser-*.json` 报告（运行 `pnpm bench:browser` 追加一份；用 `node scripts/bench-trend.mjs` 重新生成本文档）。
 
 发布门禁的对比基线是 `pnpm bench:compare --fail-above-pct 50`：将最新报告与其之前若干报告中同一指标的中位数比较（50% 上限用于吸收共享 runner 的噪声；此前只看"上一份报告"并不稳定，因为页内热路径指标在同一份代码上会在快/慢两档之间来回跳）。本文记录长期趋势：数值为逐指标延迟，越低越好；最后一列是最近 5 份报告内的最优值，而不是历史纪录——页内基准矩阵在 2026 年 9 月初变更过测量语义，更早的报告不可比。
 
 <!-- BENCH-TREND:BEGIN (machine-generated table) -->
 | 指标 | 上次 (ms) | 本次 (ms) | Δ | 近 5 次最优 (ms) |
 |---|---|---|---|---|
-| publish per-message (ms, lower is better) — dedicated | 80.1971 | 63.1886 | -17.01 | 62.3503 |
-| publish per-message (ms, lower is better) — shared | 49.8516 | 54.1494 | +4.30 | 39.6914 |
-| wildcard dispatch ×1000 (ms, lower is better) | 7.9 | 6.6 | -1.30 | 6.5 |
-| publishBatch ×1000 (ms, lower is better) | 4.4 | 5 | +0.60 | 4.4 |
-| dedup ×1000 (ms, lower is better) | 14 | 15.6 | +1.60 | 14 |
-| trace + publish ×1000 (ms, lower is better) | 5.3 | 5.9 | +0.60 | 5.2 |
+| publish per-message (ms, lower is better) — dedicated | 55.4416 | 50.6133 | -4.83 | 50.6133 |
+| publish per-message (ms, lower is better) — shared | 58.2441 | 33.8955 | -24.35 | 33.8955 |
+| wildcard dispatch ×1000 (ms, lower is better) | 5.2 | 5.7 | +0.50 | 5.2 |
+| publishBatch ×1000 (ms, lower is better) | 3.5 | 3.7 | +0.20 | 3.5 |
+| dedup ×1000 (ms, lower is better) | 13 | 11 | -2.00 | 11 |
+| trace + publish ×1000 (ms, lower is better) | 4.6 | 4.7 | +0.10 | 4.6 |
 | first-packet cold dispatch (ms, lower is better) | 0 | 0 | +0.00 | 0 |
 <!-- BENCH-TREND:END -->
 

package/docs/zh/configuration.md

@@ -155,7 +155,7 @@ const bus = createCentrifugeDataBus({
 | `clusterKey` | `string` | `connection.url` | 手动隔离逻辑集群 |
 | `workerMode` | `'dedicated' \| 'shared' \| 'auto'` | `'dedicated'` | Worker transport 运行模式；`auto` 按 SharedWorker → Dedicated Worker → 本地模式降级，显式 `dedicated` 按 Dedicated Worker → SharedWorker → 本地模式降级 |
 | `transferable` | `boolean` | `false` | 开启后 `publish(topic, ArrayBuffer)` 使用 Transferable 传输，接收侧 ArrayBuffer publication 也走转移路径 |
-| `heartbeatIntervalMs` | `number` | `10000` | SharedWorker PING 心跳间隔（见下方 SharedWorker 会话回收）；传 `Infinity` 完全禁用心跳。与 Core 集群心跳（默认 3000 ms，通过 localStorage 跟踪 worker 存活）相互独立 |
+| `heartbeatIntervalMs` | `number` | `10000` | SharedWorker PING 心跳间隔（见下方 SharedWorker 会话回收）；传 `Infinity` 完全禁用心跳，该端口也因此豁免于回收。与 Core 集群心跳（默认 3000 ms，通过 localStorage 跟踪 worker 存活）相互独立 |
 | `workerFactory` | `() => Worker` | 内置 Worker | 测试或自定义 Worker 加载方式 |
 | `sharedWorkerFactory` | `() => SharedWorker` | 内置 SharedWorker | 测试或自定义 SharedWorker 加载方式 |
 | `credentialProvider` | `{ getToken?, getChannelToken? }` | `undefined` | 异步凭证刷新桥：Worker 向主线程请求每个新 token（`getToken` / `getChannelToken`），由该 provider 从应用上下文提供。必要原因：函数型 Centrifuge 选项无法 structured-clone 进 Worker |
@@ -203,13 +203,13 @@ storage 事件只在其他 document 中派发。因此同一 document 内共享
 
 `MessagePort` 没有 `close` 事件，因此 SharedWorker 无法在 Tab 崩溃或关闭时获知（除非收到 `STOP` 消息）。为避免泄漏已死 Tab 的 `CentrifugeSession`（及其 WebSocket），transport 定期向 SharedWorker 发送 **PING 心跳**，SharedWorker 运行一个**回收器**来关闭超过静默超时的端口会话。
 
-- **心跳间隔**：`heartbeatIntervalMs`（默认 `10000` ms）。主线程按此间隔发送 `PING`。传 `Infinity` 完全禁用心跳——仅在确保 SharedWorker 会随 Tab 一起销毁时使用。
-- **会话超时**：`3 × heartbeatIntervalMs`（默认 `30000` ms）。超过超时未收到消息的端口会被回收：其会话停止，WebSocket 关闭。这与 Core 集群心跳（默认 `3000` ms，通过 localStorage 跟踪 worker 存活）相互独立——见下方说明。
+- **心跳间隔**：`heartbeatIntervalMs`（默认 `10000` ms）。主线程按此间隔发送 `PING`。传 `Infinity` 即完全禁用心跳：transport 不再发送任何 `PING`，并在 `INIT` 里带上同一个 `Infinity`，因此**该端口被豁免于回收**——它永远不会被判定为静默。仅在确实不需要 SharedWorker 回收器时使用（例如 Tab 总会自行 `stop()`，每个端口都经由 `STOP` 离开）。代价同样值得说明：这样配置的 Tab 如果*崩溃*，它的 `CentrifugeSession` 与 WebSocket 会原地保留，因为本会察觉的那颗心跳已经被关掉了。
+- **会话超时**：`3 × heartbeatIntervalMs`（默认 `30000` ms）。超过超时未收到消息的端口会被回收：其会话停止，WebSocket 关闭。`INIT` 中携带 `heartbeatIntervalMs: Infinity` 的端口没有超时，永不被回收。这与 Core 集群心跳（默认 `3000` ms，通过 localStorage 跟踪 worker 存活）相互独立——见下方说明。
 - **自适应频率**：回收器以所有活动端口中最小的心跳间隔运行，使短心跳端口的会话能被及时回收。当最后一个端口断开时，回收器定时器清除，避免长时间存在的 SharedWorker 在连接爆发间隙运行永久的空循环。
 - **关闭端口前先通知 Tab**：被回收的端口会先收到最后一条 `SESSION_REAPED` 消息，然后才被关闭、其会话才被停止。顺序正是关键所在——`MessagePort` 没有 close 事件，而向一个对端已关闭的端口发送消息会“成功”却什么都不送达，这是被饿死的 Tab 唯一能得知真相的途径。此前，一个只是被长时间阻塞、并没有消失的 Tab（一个很长的同步任务，或后台 Tab 受到的定时器节流）会保留自己的集群角色与 topic 路由，而它发出的每条发布都消失在已关闭的端口里，`getHealthSummary()` 仍在报告 `healthy` / `connected`。收到该消息后，transport 会丢弃这个 backend，并通过 `onError` 与 `error` 状态报告失败，正常恢复路径随后在新端口上重建会话。真实浏览器实测：34 秒阻塞之后，Tab 自行重建了订阅——无需用户操作、无需生命周期事件——观察时这条替代连接建立尚不到一秒。
 - **先关闭端口再停止会话**：回收端口时，先关闭端口，再停止会话。关闭端口会丢弃会话的 `disconnected` 状态通知（使其不会到达可能仍在运行但缓慢的主线程），并保证已关闭的端口永远无法传递后续消息，从而在回收器追踪之外复活僵尸会话。
-- **失败隔离**：回收与 `dispose()` 都用 try-catch 包裹 `target.close()`/`target.stop()`，单个异常端口不会中断本轮回收，也不会让后续死 Tab 无人回收。
-- **关闭清理**：SharedWorker 关闭时，`PortReaper.dispose()` 停止定时器并关闭/停止**所有**仍被追踪的会话，确保没有任何 `CentrifugeSession` 或 WebSocket 比 reaper 活得更久。这补充了按端口回收——后者只覆盖 reaper 运行期间静默的端口。
+- **失败隔离**：回收用 try-catch 包裹 `target.notify()`/`close()`/`stop()`，`dispose()` 则包裹 `close()`/`stop()`，单个异常端口不会中断本轮回收，也不会让后续死 Tab 无人回收。抛出的那一步之后的步骤确实会被跳过——但只跳过**这一个**端口的。
+- **`dispose()` 没有 Worker 侧调用者**：它会清除回收定时器并关闭/停止**所有**仍被追踪的会话，单元测试也覆盖了它，但发布出去的 SharedWorker 从不调用它——`MessagePort` 没有 close 事件，因此根本不存在"SharedWorker 正在关闭"这种可以挂靠的信号。每个端口都通过自己的 `STOP` 处理或回收器离开追踪，而最后一个被追踪的端口消失后，回收器的定时器随即清除。
 
 这是从崩溃（未发送 `STOP`）的 Tab 中恢复会话的机制；而它发出的那条通知，正是没有崩溃、只是被饿死的 Tab 能够察觉并重连的原因。降低 `heartbeatIntervalMs` 可更快回收死会话，代价是端口上更频繁的 PING 消息——另外请注意：如果它的值低于页面最长任务耗时的约三分之一，活着的 Tab 也会被开始回收，而每一次回收都要靠重建会话来恢复。
 

package/docs/zh/roadmap.md

@@ -1,6 +1,24 @@
 # 路线图
 
-0.21.9 已于 2026 年 9 月 23 日发布。项目会先持续完成可靠性发布，再进入 1.0.0 稳定性冻结。
+0.21.10 已于 2026 年 9 月 23 日发布。项目会先持续完成可靠性发布，再进入 1.0.0 稳定性冻结。
+
+## 0.21.10 已完成范围
+
+- `heartbeatIntervalMs: Infinity`——文档中关闭 SharedWorker PING 心跳的方式——此前被回收器当成了一个
+  畸形数字：它与 `NaN`、`0`、负数走同一道 `Number.isFinite` 检查，于是回退到默认 10 秒，也就给
+  了这个"注定再也不会发消息"的端口安上一个 30 秒的会话超时。这个选项的本意是"不需要回收器"，结果却保证
+  连接 30 秒后必被回收。`Infinity` 现在让该端口豁免于回收，而那三个连 transport 构造函数都会拒绝（因此
+  根本不可能来自本库）的值仍走回退路径。用一个测试钉住：三个变异体分别死在三条不同断言上；另有一条断言钉住
+  `INIT` 确实带着这个值——这个缺陷的两半各有绿灯测试覆盖，正是它活到今天的原因。
+- 发布出去的回收器文档不再承诺代码没有做的事（中英双语）：不存在"SharedWorker 关闭时"运行的
+  `PortReaper.dispose()` 钩子（没有任何地方调用它——`MessagePort` 没有 close 事件，因此压根没有可供挂靠的
+  信号）；而关闭心跳的代价也和它关掉了什么一起写明了（这样配置的 Tab 若崩溃，其会话与 WebSocket 会原地保留）。
+- 一个"测试全绿却把门禁弄红"的缺陷：IndexedDB 回放的一条断言在某个 await 之后才挂上 rejection handler，
+  而那个 await 可能被真实的 40 毫秒定时器超过，于是在繁忙的 runner 上 `pnpm test:coverage` 会以
+  `Unhandled Rejection` 退出 1，而所有测试都显示通过。现在 handler 与 promise 一起创建——把往返强行拉长到
+  200 毫秒后两个方向都实测过。
+- 没有改变线路格式、存储布局或集群协议。行为变化仅限于 shared 模式下配置 `heartbeatIntervalMs: Infinity`
+  的情形，而那种配置此前根本无法按文档所说工作。
 
 ## 0.21.9 已完成范围
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cross-tab-worker-databus",
-  "version": "0.21.9",
+  "version": "0.21.10",
   "description": "Framework-agnostic cross-tab data bus with Dedicated/Shared Worker clustering and Centrifuge support.",
   "type": "module",
   "license": "MIT",