cross-tab-worker-databus 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,50 @@
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-08-27
+
+### Changed
+
+- `centrifuge` 从 `dependencies` 改为 optional `peerDependencies`：仅在使用内置 Centrifuge 后端时需要安装，核心包零运行时依赖。
+- `CentrifugeSession.handle()` 由连续 `if` 改为 `switch` + `default`，未知消息类型静默忽略，为未来协议扩展留出兼容余地。
+- `routing.ts` 的 workerId 平局处理由 `localeCompare` 改为数值比较，消除宿主 locale 对路由确定性的影响。
+- `port-reaper.ts` 提取 `computeMinHeartbeat()` 方法，reap 迭代改用 `Array.from` 快照，reaper 节奏计算与计时器逻辑解耦。
+- `centrifuge-protocol.ts` 新增 `DEFAULT_SESSION_TIMEOUT_MS` 派生常量，消除 `port-reaper` 中重复的字面量计算。
+- `CentrifugeWorkerTransport` 提取 `buildInitInput()` 与 `postToPortLike()` helper，消除 `start()`/`post()` 中的重复构造逻辑。
+- `cluster.ts` 提取 `readAllByPrefix()` helper，统一 `readWorkers`/`cleanupOrphanedRoutes`/`cleanupOrphanedSubscribers`/`getSnapshot` 的 listKeys+readJson 循环；删除无调用点的 `listKeysSafe`。
+- `cluster.ts` 提取 `buildLocalRoute()`，将 `readRoute` 的无 storage 降级分支独立命名并补文档；`readSubscriberTabIds` 同类分支拆为多行可读形式。
+- `cluster.ts` 提取 `sendRouteReleased()` helper，消除三处 `ROUTE_RELEASED` 消息构造的重复；`handoffAssignedTopics` 的 generation 计算复用单次求值；`reconcileAssignedTopics` 去除同一 topicKey 的二次 `readRoute` 调用。
+- `cluster.ts` `releaseSubscription` 返回 topicKey，`unsubscribe` 复用而非重新哈希；`handleMessage`/`handleControlMessage`/`sendControl` 连续 `if` 改 `switch`；`getSnapshot` 的序列化改用 `Array.from`。
+- `data-bus.ts` `onControl` 连续 `if` 改 `switch`；提取 `invokeHandlers()` 统一 dispatch/status/error 三处 handler 遍历的 try-catch 隔离；提取 `formatWorkerTrace`/`formatRouteTrace` 格式化函数。
+- `trace.ts` 提取 `metricsActive` getter，统一四个 record/flush 方法的守卫表达式。
+- `cluster.ts` 提取 `routeOwnerIsLive()` 与 `isActiveAmong()`，消除 subscribe/publish 和 isActiveWorker/refreshRole 中的重复 route+workers.some / selectActiveWorkers+some 模式。
+- `cluster.ts` 提取 `isStaleRouteRelease()`，命名 handleRouteReleasedMessage 的守卫条件。
+- `cluster.ts` `activate()` 合并两个分支的 rememberTopic 调用为单循环；`handoffAssignedTopics` 去掉同一 topicKey 的二次 readRoute。
+- `cluster.ts` `readSubscriberTabIds` 改用 `readAllByPrefix` + `Array.from`；`getSnapshot` 序列化改用 `Array.from` + mapping callback。
+- `data-bus.ts` 提取 `formatWorkerTrace`/`formatRouteTrace` 格式化函数；`invokeHandlers` 的 label 参数改为联合类型字面量而非自由字符串。
+- 多处 JSDoc/注释补全：writeRecord notify 参数、activate channel 判空、reconcileWorkers cleanup 顺序、rememberTopic eviction break、suspendTransport pendingStop 守卫、reopenTransport startPromise 检查、trace flushNow 条件、storage-batch flush break / scheduleFlush 降级 / scheduleRetry、port-reaper 各方法守卫、centrifuge assertHeartbeatInterval/assertStructuredCloneable/deserializeWorkerError、environment canUseStorage。
+
+### Documentation (JSDoc 全覆盖)
+
+- `hash.ts` 提取 seed/prime/avalanche 常量与 `avalancheMix()` 函数，补非 ASCII 字符处理注释。
+- `types.ts` 全部类型（WorkerRecord/WorkerRoute/WorkerClusterMessage/DataBusTransport/DataBusMessage/handler 别名）字段级 JSDoc 补全。
+- `centrifuge-protocol.ts` 全部协议变体（WorkerUnsafeOption/CentrifugeWorkerConfig/CentrifugeWorkerInput 各变体/CentrifugeWorkerOutput 各变体/SerializedWorkerError）JSDoc 补全。
+- `worker-mode.ts` WorkerMode/WorkerBackend/WorkerAvailability/selectWorkerBackend JSDoc 补全。
+- `routing.ts` DEFAULT_MAX_ACTIVE_WORKERS/selectLeastLoadedWorker JSDoc 增强。
+- `storage-batch.ts` INITIAL/MAX_RETRY 常量 + BatchingStorageWriter 类 + pendingSize getter JSDoc 补全。
+- `trace.ts` normalizeInterval/roundMs JSDoc 补全。
+- `environment.ts` ClusterEnvironment 各字段 + canUseStorage JSDoc 补全。
+- `cluster.ts` readJson/writeJson/WorkerClusterOptions 各字段 JSDoc 补全。
+- `data-bus.ts` PUBLICATION_EVENT/getStatus/getClusterSnapshot/CrossTabDataBusOptions JSDoc 补全。
+- `centrifuge.ts` handleOutput/onWorkerFailed JSDoc 补全。
+
+### Documentation
+
+- 架构运行时图（中英）补全 `BatchingStorageWriter`、`PortReaper`、`CentrifugeSession`、`CentrifugeWorkerTransport` 节点，与代码结构对齐。
+- `AGENTS.md` 目录注释明确列出每个测试文件职责。
+- `README`（中英）补充 `centrifuge` 为可选 peer 依赖的安装说明。
+- `trace.ts`、`environment.ts` 补充 JSDoc：trace 模式与选项字段含义、SSR 场景的 storage/ BroadcastChannel 检测说明。
+
 ## [0.1.2] - 2026-08-24
 
 ### Fixed

package/README.md

@@ -31,6 +31,17 @@ See the [Capabilities Matrix](./docs/capabilities.md) for the full list of imple
 pnpm add cross-tab-worker-databus
 ```
 
+The core package has zero runtime dependencies. The Centrifuge transport
+(`cross-tab-worker-databus/centrifuge`) declares `centrifuge` as an optional
+peer dependency — install it only when you use the built-in Centrifuge backend:
+
+```bash
+pnpm add cross-tab-worker-databus centrifuge
+```
+
+Tabs that only use the local BroadcastChannel data bus (no WebSocket server)
+do not need to install `centrifuge` at all.
+
 ## Getting Started
 
 ```ts

package/README.zh.md

@@ -31,6 +31,15 @@
 pnpm add cross-tab-worker-databus
 ```
 
+核心包零运行时依赖。Centrifuge transport（`cross-tab-worker-databus/centrifuge`）
+将 `centrifuge` 声明为可选 peer 依赖——仅在使用内置 Centrifuge 后端时安装：
+
+```bash
+pnpm add cross-tab-worker-databus centrifuge
+```
+
+仅使用本地 BroadcastChannel 数据总线（不连 WebSocket 服务）的 Tab 无需安装 `centrifuge`。
+
 ## 快速接入
 
 ```ts

package/dist/centrifuge-protocol.d.ts

@@ -19,58 +19,94 @@ export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 10000;
  * heartbeat interval. A live port PINGs every heartbeat interval, so a timeout of
  * several intervals tolerates throttled tabs without reaping healthy sessions. */
 export declare const DEFAULT_SESSION_TIMEOUT_MULTIPLIER = 3;
+/** Default per-port session timeout in ms, derived from the heartbeat interval
+ * and the multiplier. Used as the fallback when a port sends no INIT config. */
+export declare const DEFAULT_SESSION_TIMEOUT_MS: number;
 type WorkerUnsafeOption = 'eventsource' | 'fetch' | 'getData' | 'getToken' | 'networkEventTarget' | 'readableStream' | 'sockjs' | 'websocket';
-/** Centrifuge options safe to pass into a Worker; unsafe options are explicitly excluded. */
+/** Centrifuge options safe to pass into a Worker; unsafe options are explicitly
+ * excluded and set to `never` so the compiler rejects them at the call site. */
 export type CentrifugeWorkerConfig = Omit<Partial<Options>, WorkerUnsafeOption> & {
     [Key in WorkerUnsafeOption]?: never;
 };
-/** Messages sent from the main thread to the Worker. */
-export type CentrifugeWorkerInput = {
+/** Messages sent from the main thread to the Worker. All variants are
+ * structured-cloneable; `PUBLISH_BIN` carries an ArrayBuffer (transferable). */
+export type CentrifugeWorkerInput = 
+/** Initial connection: URL + config. Sent once per backend creation.
+ * `transferable` enables ArrayBuffer zero-copy for subsequent PUBLISH_BIN.
+ * `heartbeatIntervalMs` overrides the SharedWorker PING cadence. */
+{
     type: 'INIT';
     url: string;
     config: CentrifugeWorkerConfig;
     transferable?: boolean;
     heartbeatIntervalMs?: number;
-} | {
+}
+/** Subscribe to a channel. Idempotent — re-subscribing is a no-op. */
+ | {
     type: 'SUBSCRIBE';
     topic: string;
-} | {
+}
+/** Unsubscribe from a channel. Idempotent. */
+ | {
     type: 'UNSUBSCRIBE';
     topic: string;
-} | {
+}
+/** Publish a structured-cloneable payload to a channel. */
+ | {
     type: 'PUBLISH';
     topic: string;
     data: unknown;
-} | {
+}
+/** Publish an ArrayBuffer via Transferable (zero-copy when `transferable` is on). */
+ | {
     type: 'PUBLISH_BIN';
     topic: string;
     data: ArrayBuffer;
-} | {
+}
+/** Heartbeat from the main thread; the SharedWorker reaps silent ports. */
+ | {
     type: 'PING';
-} | {
+}
+/** Disconnect the client and clear all subscriptions. */
+ | {
     type: 'STOP';
 };
-/** Messages sent from the Worker back to the main thread. */
-export type CentrifugeWorkerOutput<TData = unknown> = {
+/** Messages sent from the Worker back to the main thread. The main thread
+ * routes these to the DataBusTransportHandlers via handleOutput(). */
+export type CentrifugeWorkerOutput<TData = unknown> = 
+/** Connection status changed. Maps Centrifuge states to the DataBus vocabulary. */
+{
     type: 'STATUS';
     status: WorkerStatus;
-} | {
+}
+/** A JSON publication arrived. Routed to onMessage via handleOutput. */
+ | {
     type: 'MESSAGE';
     topic: string;
     data: TData;
-} | {
+}
+/** A binary publication arrived (Transferable). Routed to onMessage with the ArrayBuffer. */
+ | {
     type: 'MESSAGE_BIN';
     topic: string;
     data: ArrayBuffer;
-} | {
+}
+/** A non-fatal error occurred. Does not imply disconnection (the client retries internally). */
+ | {
     type: 'ERROR';
     error: SerializedWorkerError;
 };
-/** Error object serialized for cross-thread transfer (Error instances cannot be cloned via postMessage). */
+/** Error object serialized for cross-thread transfer. Error instances cannot
+ * be structured-cloned via postMessage, so the Worker converts them to this
+ * shape and the main thread rebuilds an Error via deserializeWorkerError(). */
 export interface SerializedWorkerError {
+    /** The Error's `name` (e.g. 'TypeError', 'CentrifugeError'). */
     name: string;
+    /** The Error's `message`. */
     message: string;
+    /** The Error's `stack` if available (for debugging). */
     stack?: string;
+    /** Arbitrary context attached by the Worker (e.g. the failing operation). */
     context?: unknown;
 }
 export {};

package/dist/centrifuge-protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"centrifuge-protocol.d.ts","sourceRoot":"","sources":["../src/centrifuge-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,QAAS,CAAC;AACpD;;kFAEkF;AAClF,eAAO,MAAM,kCAAkC,IAAI,CAAC;AAIpD,KAAK,kBAAkB,GACnB,aAAa,GACb,OAAO,GACP,SAAS,GACT,UAAU,GACV,oBAAoB,GACpB,gBAAgB,GAChB,QAAQ,GACR,WAAW,CAAC;AAEhB,6FAA6F;AAC7F,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC,GAAG;KAC/E,GAAG,IAAI,kBAAkB,CAAC,CAAC,EAAE,KAAK;CACpC,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,sBAAsB,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAAE,GACnH;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB,6DAA6D;AAC7D,MAAM,MAAM,sBAAsB,CAAC,KAAK,GAAG,OAAO,IAC9C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAEpD,4GAA4G;AAC5G,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB"}
+{"version":3,"file":"centrifuge-protocol.d.ts","sourceRoot":"","sources":["../src/centrifuge-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,QAAS,CAAC;AACpD;;kFAEkF;AAClF,eAAO,MAAM,kCAAkC,IAAI,CAAC;AACpD;gFACgF;AAChF,eAAO,MAAM,0BAA0B,QAC6B,CAAC;AAOrE,KAAK,kBAAkB,GACnB,aAAa,GACb,OAAO,GACP,SAAS,GACT,UAAU,GACV,oBAAoB,GACpB,gBAAgB,GAChB,QAAQ,GACR,WAAW,CAAC;AAEhB;gFACgF;AAChF,MAAM,MAAM,sBAAsB,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC,GAAG;KAC/E,GAAG,IAAI,kBAAkB,CAAC,CAAC,EAAE,KAAK;CACpC,CAAC;AAEF;gFACgF;AAChF,MAAM,MAAM,qBAAqB;AAC/B;;oEAEoE;AAClE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,sBAAsB,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;CAAE;AACrH,sEAAsE;GACpE;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AACtC,8CAA8C;GAC5C;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AACxC,2DAA2D;GACzD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE;AACnD,qFAAqF;GACnF;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE;AAC3D,2EAA2E;GACzE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;AAClB,yDAAyD;GACvD;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB;sEACsE;AACtE,MAAM,MAAM,sBAAsB,CAAC,KAAK,GAAG,OAAO;AAChD,mFAAmF;AACjF;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE;AAC1C,wEAAwE;GACtE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE;AACjD,6FAA6F;GAC3F;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE;AAC3D,gGAAgG;GAC9F;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAEpD;;+EAE+E;AAC/E,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB"}

package/dist/centrifuge-session.d.ts

@@ -13,11 +13,16 @@ export declare class CentrifugeSession<TData = unknown> {
     private readonly subscriptions;
     private transferable;
     constructor(sink: CentrifugeSessionSink<TData>);
-    /** Dispatch an incoming Worker message to the matching operation. */
+    /** Dispatch an incoming Worker message to the matching operation.
+     * Unknown message types are ignored rather than thrown, so a future protocol
+     * extension adding a new variant cannot crash an older session. */
     handle(message: CentrifugeWorkerInput): void;
     /** Create the Centrifuge client, wire up lifecycle listeners, and connect. */
     private initialize;
-    /** Subscribe to a Centrifuge channel. Reuses an existing subscription if one exists. */
+    /** Subscribe to a Centrifuge channel. Reuses an existing subscription if one exists.
+     * Listeners are only registered once per subscription object — a repeated
+     * SUBSCRIBE for an already-tracked topic skips the listener wiring entirely,
+     * avoiding the removeAllListeners + re-on churn on every duplicate message. */
     private subscribe;
     /** Unsubscribe from a Centrifuge channel and clean up the local reference.
      * Listeners are removed before unsubscribing so a late `unsubscribed` event
@@ -25,7 +30,10 @@ export declare class CentrifugeSession<TData = unknown> {
     private unsubscribe;
     /** Publish a message to the Centrifuge channel. */
     private publish;
-    /** Forward a publication to the transport, using Transferable for binary data when enabled. */
+    /** Forward a publication to the transport. Binary payloads take the
+     * zero-copy `MESSAGE_BIN` path when `transferable` is enabled; everything
+     * else is structured-cloned via `MESSAGE`. An empty topic means the
+     * publication carried no channel info and is silently dropped. */
     private postPublication;
     /** Disconnect the client and clear all subscriptions. */
     private stop;

package/dist/centrifuge-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"centrifuge-session.d.ts","sourceRoot":"","sources":["../src/centrifuge-session.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAEV,qBAAqB,EACrB,sBAAsB,EAEvB,MAAM,uBAAuB,CAAC;AAE/B,2EAA2E;AAC3E,MAAM,WAAW,qBAAqB,CAAC,KAAK,GAAG,OAAO;IACpD,IAAI,CAAC,OAAO,EAAE,sBAAsB,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;CAC9E;AAED;;;GAGG;AACH,qBAAa,iBAAiB,CAAC,KAAK,GAAG,OAAO;IAKhC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmC;IACjE,OAAO,CAAC,YAAY,CAAS;gBAEA,IAAI,EAAE,qBAAqB,CAAC,KAAK,CAAC;IAE/D,qEAAqE;IACrE,MAAM,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI;IAS5C,8EAA8E;IAC9E,OAAO,CAAC,UAAU;IAuBlB,wFAAwF;IACxF,OAAO,CAAC,SAAS;IAmBjB;;gFAE4E;IAC5E,OAAO,CAAC,WAAW;IAUnB,mDAAmD;IACnD,OAAO,CAAC,OAAO;IAKf,+FAA+F;IAC/F,OAAO,CAAC,eAAe;IASvB,yDAAyD;IACzD,OAAO,CAAC,IAAI;IAOZ,2DAA2D;IAC3D,OAAO,CAAC,IAAI;IAIZ;;;;0DAIsD;IACtD,OAAO,CAAC,SAAS;CAGlB"}
+{"version":3,"file":"centrifuge-session.d.ts","sourceRoot":"","sources":["../src/centrifuge-session.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAEV,qBAAqB,EACrB,sBAAsB,EAEvB,MAAM,uBAAuB,CAAC;AAE/B,2EAA2E;AAC3E,MAAM,WAAW,qBAAqB,CAAC,KAAK,GAAG,OAAO;IACpD,IAAI,CAAC,OAAO,EAAE,sBAAsB,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;CAC9E;AAED;;;GAGG;AACH,qBAAa,iBAAiB,CAAC,KAAK,GAAG,OAAO;IAKhC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAmC;IACjE,OAAO,CAAC,YAAY,CAAS;gBAEA,IAAI,EAAE,qBAAqB,CAAC,KAAK,CAAC;IAE/D;;uEAEmE;IACnE,MAAM,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI;IAyB5C,8EAA8E;IAC9E,OAAO,CAAC,UAAU;IAuBlB;;;mFAG+E;IAC/E,OAAO,CAAC,SAAS;IA2BjB;;gFAE4E;IAC5E,OAAO,CAAC,WAAW;IAUnB,mDAAmD;IACnD,OAAO,CAAC,OAAO;IAKf;;;sEAGkE;IAClE,OAAO,CAAC,eAAe;IASvB,yDAAyD;IACzD,OAAO,CAAC,IAAI;IAOZ,2DAA2D;IAC3D,OAAO,CAAC,IAAI;IAIZ;;;;0DAIsD;IACtD,OAAO,CAAC,SAAS;CAGlB"}

package/dist/centrifuge.d.ts

@@ -88,6 +88,10 @@ export declare class CentrifugeWorkerTransport<TData = unknown> implements DataB
      * terminate the Worker (or close the SharedWorker port).
      */
     stop(): void;
+    /** Build the INIT payload sent to the Worker / local session. Optional fields
+     * are only included when they deviate from the defaults, so the Worker's own
+     * default-resolution logic kicks in for the common case. */
+    private buildInitInput;
     /** Create and initialise a dedicated Worker, then send the INIT message. */
     private startDedicatedWorker;
     /** Create and initialise a SharedWorker, open the MessagePort, and send the INIT message. */
@@ -96,11 +100,15 @@ export declare class CentrifugeWorkerTransport<TData = unknown> implements DataB
     private readonly handleMessage;
     /** Handle a message from the in-process CentrifugeSession (local fallback). */
     private readonly handleSessionOutput;
-    /** Route a Worker output message to the appropriate handler callback. */
+    /** Route a Worker output message to the appropriate handler callback.
+     * Shared by the Worker message listener, the SharedWorker port listener,
+     * and the local-session sink — all three feed into this single dispatcher. */
     private handleOutput;
     /** Handle a Worker-level failure (crash, message decode error). Discards the
      * dead backend so a later start()/reopen can rebuild from scratch, and
-     * signals an error status so the DataBus can trigger recovery. */
+     * signals an error status so the DataBus can trigger recovery.
+     * Only invoked when the generation guard confirms the failing backend is
+     * still current — late errors from a superseded Worker are silently dropped. */
     private onWorkerFailed;
     /** Remove every listener attached to the current SharedWorker and its port. */
     private detachSharedWorkerListeners;

package/dist/centrifuge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"centrifuge.d.ts","sourceRoot":"","sources":["../src/centrifuge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAG/E,OAAO,KAAK,EAAiB,UAAU,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,KAAK,EACV,sBAAsB,EAIvB,MAAM,uBAAuB,CAAC;AAG/B,YAAY,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC3F,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE/D,uEAAuE;AACvE,MAAM,WAAW,uBAAuB;IACtC,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,+DAA+D;IAC/D,OAAO,CAAC,EAAE,sBAAsB,CAAC;CAClC;AAED,gFAAgF;AAChF,MAAM,WAAW,gCAAgC;IAC/C,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,MAAM,CAAC;IAC7B,mCAAmC;IACnC,mBAAmB,CAAC,EAAE,MAAM,YAAY,CAAC;IACzC,+DAA+D;IAC/D,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,iEAAiE;IACjE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;6CAGyC;IACzC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,2FAA2F;AAC3F,MAAM,WAAW,8BAA8B,CAAC,KAAK,GAAG,OAAO,CAC7D,SAAQ,IAAI,CACR,sBAAsB,CAAC,uBAAuB,EAAE,KAAK,CAAC,EACtD,WAAW,GAAG,YAAY,GAAG,eAAe,GAAG,WAAW,CAC3D,EACD,gCAAgC;IAClC,2CAA2C;IAC3C,UAAU,EAAE,uBAAuB,CAAC;IACpC,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,qBAAa,yBAAyB,CAAC,KAAK,GAAG,OAAO,CACpD,YAAW,gBAAgB,CAAC,uBAAuB,EAAE,KAAK,CAAC;IAE3D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IACvC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAmC;IACvE,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,IAAI,CAA4B;IACxC,OAAO,CAAC,eAAe,CAA+C;IACtE,OAAO,CAAC,YAAY,CAAyC;IAC7D,OAAO,CAAC,QAAQ,CAAgD;IAGhE,OAAO,CAAC,UAAU,CAAK;IAGvB,OAAO,CAAC,iBAAiB,CAAK;gBAElB,OAAO,GAAE,gCAAqC;IAS1D;;;OAGG;IACH,KAAK,CAAC,MAAM,EAAE,uBAAuB,EAAE,QAAQ,EAAE,wBAAwB,CAAC,KAAK,CAAC,GAAG,IAAI;IAgCvF,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAI9B,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIhC;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI;IAQ3C;;;OAGG;IACH,IAAI,IAAI,IAAI;IAkBZ,4EAA4E;IAC5E,OAAO,CAAC,oBAAoB;IAS5B,6FAA6F;IAC7F,OAAO,CAAC,iBAAiB;IAczB,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAE5B;IAEF,+EAA+E;IAC/E,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAElC;IAEF,yEAAyE;IACzE,OAAO,CAAC,YAAY;IAOpB;;sEAEkE;IAClE,OAAO,CAAC,cAAc;IAetB,+EAA+E;IAC/E,OAAO,CAAC,2BAA2B;IAMnC,sFAAsF;IACtF,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAGhC;IAEF,OAAO,CAAC,QAAQ,CAAC,eAAe,CAG9B;IAEF,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAGtC;IAEF,wEAAwE;IACxE,OAAO,CAAC,YAAY;IAQpB;;;OAGG;IACH,OAAO,CAAC,IAAI;CAiBb;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,GAAG,OAAO,EACrD,OAAO,EAAE,8BAA8B,CAAC,KAAK,CAAC,GAC7C,eAAe,CAAC,uBAAuB,EAAE,KAAK,CAAC,CAwBjD"}
+{"version":3,"file":"centrifuge.d.ts","sourceRoot":"","sources":["../src/centrifuge.ts"],"names":[],"mappings":"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"}

package/dist/centrifuge.js

@@ -1,7 +1,7 @@
 import {
   CrossTabDataBus,
   selectWorkerBackend
-} from "./chunk-53INHVYO.js";
+} from "./chunk-LBXREMZA.js";
 
 // src/centrifuge-session.ts
 import { Centrifuge } from "centrifuge";
@@ -12,14 +12,30 @@ var CentrifugeSession = class {
   client = null;
   subscriptions = /* @__PURE__ */ new Map();
   transferable = false;
-  /** Dispatch an incoming Worker message to the matching operation. */
+  /** Dispatch an incoming Worker message to the matching operation.
+   * Unknown message types are ignored rather than thrown, so a future protocol
+   * extension adding a new variant cannot crash an older session. */
   handle(message) {
-    if (message.type === "INIT") this.initialize(message.url, message.config, message.transferable === true);
-    if (message.type === "SUBSCRIBE") this.subscribe(message.topic);
-    if (message.type === "UNSUBSCRIBE") this.unsubscribe(message.topic);
-    if (message.type === "PUBLISH") this.publish(message.topic, message.data);
-    if (message.type === "PUBLISH_BIN") this.publish(message.topic, message.data);
-    if (message.type === "STOP") this.stop();
+    switch (message.type) {
+      case "INIT":
+        this.initialize(message.url, message.config, message.transferable === true);
+        return;
+      case "SUBSCRIBE":
+        this.subscribe(message.topic);
+        return;
+      case "UNSUBSCRIBE":
+        this.unsubscribe(message.topic);
+        return;
+      case "PUBLISH":
+      case "PUBLISH_BIN":
+        this.publish(message.topic, message.data);
+        return;
+      case "STOP":
+        this.stop();
+        return;
+      default:
+        return;
+    }
   }
   /** Create the Centrifuge client, wire up lifecycle listeners, and connect. */
   initialize(url, config, transferable) {
@@ -40,9 +56,17 @@ var CentrifugeSession = class {
     });
     client.connect();
   }
-  /** Subscribe to a Centrifuge channel. Reuses an existing subscription if one exists. */
+  /** Subscribe to a Centrifuge channel. Reuses an existing subscription if one exists.
+   * Listeners are only registered once per subscription object — a repeated
+   * SUBSCRIBE for an already-tracked topic skips the listener wiring entirely,
+   * avoiding the removeAllListeners + re-on churn on every duplicate message. */
   subscribe(topic) {
     if (!this.client) return this.postError(new Error("Centrifuge client is not initialized."));
+    const existing = this.subscriptions.get(topic);
+    if (existing) {
+      existing.subscribe();
+      return;
+    }
     let subscription = this.client.getSubscription(topic);
     if (!subscription) subscription = this.client.newSubscription(topic);
     subscription.removeAllListeners("publication");
@@ -73,7 +97,10 @@ var CentrifugeSession = class {
     if (!this.client) return this.postError(new Error("Centrifuge client is not initialized."));
     void this.client.publish(topic, data).catch((error) => this.postError(error));
   }
-  /** Forward a publication to the transport, using Transferable for binary data when enabled. */
+  /** Forward a publication to the transport. Binary payloads take the
+   * zero-copy `MESSAGE_BIN` path when `transferable` is enabled; everything
+   * else is structured-cloned via `MESSAGE`. An empty topic means the
+   * publication carried no channel info and is silently dropped. */
   postPublication(topic, data) {
     if (!topic) return;
     if (this.transferable && data instanceof ArrayBuffer) {
@@ -105,12 +132,14 @@ var CentrifugeSession = class {
 function getPayloadTopic(data) {
   if (!data || typeof data !== "object") return "";
   const payload = data;
-  const topic = payload.push?.channel ?? payload.channel;
+  const push = payload.push;
+  const nested = typeof push === "object" && push !== null ? push.channel : void 0;
+  const topic = nested ?? payload.channel;
   return typeof topic === "string" ? topic : "";
 }
+var LIVE_STATES = /* @__PURE__ */ new Set(["connecting", "connected"]);
 function normalizeStatus(status) {
-  if (status === "connecting" || status === "connected") return status;
-  return "disconnected";
+  return LIVE_STATES.has(status) ? status : "disconnected";
 }
 function serializeError(error) {
   if (error instanceof Error) {
@@ -129,6 +158,8 @@ function serializeError(error) {
 
 // src/centrifuge-protocol.ts
 var DEFAULT_HEARTBEAT_INTERVAL_MS = 1e4;
+var DEFAULT_SESSION_TIMEOUT_MULTIPLIER = 3;
+var DEFAULT_SESSION_TIMEOUT_MS = DEFAULT_HEARTBEAT_INTERVAL_MS * DEFAULT_SESSION_TIMEOUT_MULTIPLIER;
 
 // src/centrifuge.ts
 var CentrifugeWorkerTransport = class {
@@ -170,13 +201,7 @@ var CentrifugeWorkerTransport = class {
       worker: this.workerFactory !== void 0,
       sharedWorker: this.sharedWorkerFactory !== void 0
     });
-    const input = {
-      type: "INIT",
-      url: config.url,
-      config: config.options ?? {},
-      ...this.transferable ? { transferable: true } : {},
-      ...this.heartbeatIntervalMs !== DEFAULT_HEARTBEAT_INTERVAL_MS ? { heartbeatIntervalMs: this.heartbeatIntervalMs } : {}
-    };
+    const input = this.buildInitInput(config);
     if (backend === "shared") {
       this.startSharedWorker(input);
       this.backend = "shared";
@@ -229,6 +254,18 @@ var CentrifugeWorkerTransport = class {
     this.resetBackend();
     this.handlers = null;
   }
+  /** Build the INIT payload sent to the Worker / local session. Optional fields
+   * are only included when they deviate from the defaults, so the Worker's own
+   * default-resolution logic kicks in for the common case. */
+  buildInitInput(config) {
+    return {
+      type: "INIT",
+      url: config.url,
+      config: config.options ?? {},
+      ...this.transferable ? { transferable: true } : {},
+      ...this.heartbeatIntervalMs !== DEFAULT_HEARTBEAT_INTERVAL_MS ? { heartbeatIntervalMs: this.heartbeatIntervalMs } : {}
+    };
+  }
   /** Create and initialise a dedicated Worker, then send the INIT message. */
   startDedicatedWorker(input) {
     this.backendGeneration = ++this.generation;
@@ -260,7 +297,9 @@ var CentrifugeWorkerTransport = class {
   handleSessionOutput = (message) => {
     this.handleOutput(message);
   };
-  /** Route a Worker output message to the appropriate handler callback. */
+  /** Route a Worker output message to the appropriate handler callback.
+   * Shared by the Worker message listener, the SharedWorker port listener,
+   * and the local-session sink — all three feed into this single dispatcher. */
   handleOutput(message) {
     if (message.type === "STATUS") this.handlers?.onStatus(message.status);
     if (message.type === "MESSAGE") this.handlers?.onMessage({ topic: message.topic, data: message.data });
@@ -269,7 +308,9 @@ var CentrifugeWorkerTransport = class {
   }
   /** Handle a Worker-level failure (crash, message decode error). Discards the
    * dead backend so a later start()/reopen can rebuild from scratch, and
-   * signals an error status so the DataBus can trigger recovery. */
+   * signals an error status so the DataBus can trigger recovery.
+   * Only invoked when the generation guard confirms the failing backend is
+   * still current — late errors from a superseded Worker are silently dropped. */
   onWorkerFailed(message) {
     this.worker?.removeEventListener("message", this.handleMessage);
     this.worker?.removeEventListener("error", this.handleWorkerError);
@@ -325,13 +366,11 @@ var CentrifugeWorkerTransport = class {
    */
   post(message, transfer) {
     if (this.worker) {
-      if (transfer) this.worker.postMessage(message, transfer);
-      else this.worker.postMessage(message);
+      postToPortLike(this.worker, message, transfer);
       return;
     }
     if (this.port) {
-      if (transfer) this.port.postMessage(message, transfer);
-      else this.port.postMessage(message);
+      postToPortLike(this.port, message, transfer);
       return;
     }
     if (this.localSession) {
@@ -402,6 +441,10 @@ function assertStructuredCloneable(value) {
     );
   }
 }
+function postToPortLike(target, message, transfer) {
+  if (transfer) target.postMessage(message, transfer);
+  else target.postMessage(message);
+}
 function deserializeWorkerError(error) {
   const result = new Error(error.message);
   result.name = error.name;