cross-tab-worker-databus 0.1.0

package/docs/configuration.md

@@ -0,0 +1,211 @@
+> [中文](./zh/configuration.md) | English
+
+# Configuration
+
+## Core DataBus Configuration
+
+`CrossTabDataBus<TConfig, TData>` accepts `CrossTabDataBusOptions<TConfig, TData>`.
+
+| Config | Type | Default | Description |
+|---|---|---|---|
+| `clusterKey` | `string` | Required | Isolates different connection contexts; not written to storage in plaintext |
+| `transport` | `DataBusTransport<TConfig, TData>` | Required | Actual connection and subscription implementation |
+| `initialConfig` | `TConfig` | None | Passed to transport on auto-start |
+| `autoStart` | `boolean` | `true` when `initialConfig` is provided | Whether to auto-start after instance creation |
+| `storagePrefix` | `string` | `cross-tab-worker-databus` | Namespace for storage keys and BroadcastChannel |
+| `maxActiveWorkers` | `number` | `3` | Maximum number of Workers that can be Topic owners |
+| `heartbeatIntervalMs` | `number` | `3000` | Worker heartbeat interval |
+| `workerTtlMs` | `number` | `10000` | Worker expiry threshold |
+| `environment` | `ClusterEnvironment` | Browser native environment | Used for testing, embedded environments, or capability replacement |
+| `tabId` | `string` | Auto-generated | Advanced debugging and test injection; not recommended for production use |
+| `workerId` | `string` | Auto-generated | Advanced debugging and test injection; not recommended for production use |
+| `trace` | `DataBusTraceOptions` | Disabled | Optional diagnostic events, message throughput, and distribution latency aggregates; does not affect data transfer |
+
+## Diagnostics & Throughput Metrics
+
+Trace is disabled by default. When enabled, lifecycle, connection status, coordination mode, and subscription count changes are output immediately; high-frequency messages are aggregated by count rather than printed individually.
+
+```ts
+const bus = new CrossTabDataBus({
+  clusterKey: 'realtime-feed',
+  initialConfig: {},
+  transport,
+  trace: {
+    enabled: true,
+    mode: 'all',
+    metricsIntervalMs: 5000,
+    sink: event => console.info('[DataBus]', event)
+  }
+});
+```
+
+| Config | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | `boolean` | `false` | Master switch |
+| `mode` | `'events' \| 'metrics' \| 'all'` | `'all'` | Low-frequency events only, aggregated metrics only, or both |
+| `metricsIntervalMs` | `number` | `5000` | Aggregation window; must be a finite value greater than 0 |
+| `sink` | `(event) => void` | Required | Determined by the integrator: console, monitoring SDK, or other output |
+
+`message_metrics` contains window duration, received count, dispatched count, active Topic count, and receive-to-dispatch latency sample count, average, P50, P95, and maximum. Latency is aggregated in 50ms buckets and never contains an individual message payload. Subscription events include their Topic so an integrator can correlate ownership changes. They are emitted only when the owner transport subscription set changes; idempotent `CONTROL` retries do not produce duplicate subscription events. Treat trace sinks as diagnostic surfaces: redact sensitive Topic conventions before writing to a console or external telemetry. Trace events do not include URLs, credentials, payloads, or error bodies. Errors thrown in the sink are isolated and will not interrupt message distribution, but will output to `console.warn` to help integrators discover diagnostic configuration issues.
+
+On `pagehide`, the aggregation timer stops and discards the incomplete window; on `pageshow`, it resumes with a new window. A permanent `stop()` clears the timer. Only diagnostics output is throttled; actual message reception and distribution are never rate-limited.
+
+### Timing Parameter Constraints
+
+- `workerTtlMs` should be at least twice `heartbeatIntervalMs`.
+- A TTL that is too short may cause false migrations during background scheduling jitter.
+- A TTL that is too long delays recovery of abnormal tabs.
+- The default `3000/10000` is suitable for general desktop browser real-time scenarios.
+
+### TTL Message-Loss Window
+
+When a worker dies abnormally (e.g., tab crash):
+
+- Other workers detect the death only after `workerTtlMs` (default 10 000 ms) — the stale record is pruned during the next reconciliation cycle.
+- The periodic heartbeat writes to localStorage without a BroadcastChannel notification, so a full heartbeat interval may pass before the stale record is discovered.
+- **Worst-case window**: up to `heartbeatIntervalMs + workerTtlMs` (~13 s by default). During this window, topics owned by the dead worker receive no service — publications to those topics are lost.
+- **Mitigation**: reduce `heartbeatIntervalMs` and `workerTtlMs` proportionally (e.g. 1 s / 4 s). This increases storage write frequency and raises the risk of false migrations during scheduling jitter.
+
+The default 3 s / 10 s values are suitable for general desktop browser real-time scenarios. Tune based on your tolerance for missed publications vs. false migration rate.
+
+### Active Worker Count
+
+`maxActiveWorkers` limits the number of Workers that can become Topic owners, not the number of connections established by transport. In Dedicated Worker mode, each Tab can still create its own Worker; in SharedWorker mode, same-origin Tabs reuse the same Worker.
+
+The active set is used only when a Topic needs a new owner. An existing live owner keeps its established routes even if visibility changes later mark that Worker as standby or place it outside the current candidate set.
+
+- `1`: Minimum connections and subscriptions, but the single owner bears a concentrated load.
+- `2-3`: Balances resource reuse and fault recovery.
+- Larger values: Suitable for scenarios with many Topics and where a single connection faces server-side limits.
+
+## Centrifuge Configuration
+
+Main configuration for `createCentrifugeDataBus<TData>(options)`:
+
+| Config | Type | Default | Description |
+|---|---|---|---|
+| `connection.url` | `string` | Required | Centrifuge connection URL |
+| `connection.options` | `CentrifugeWorkerConfig` | `{}` | Client configuration sent to the Worker |
+| `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 |
+| `workerFactory` | `() => Worker` | Built-in Worker | For testing or custom Worker loading |
+| `sharedWorkerFactory` | `() => SharedWorker` | Built-in SharedWorker | For testing or custom SharedWorker loading |
+| Other Core config | Corresponding type | Core defaults | `storagePrefix`, heartbeat, TTL, etc. |
+
+```ts
+const bus = createCentrifugeDataBus({
+  connection: {
+    url: getConnectionUrl(),
+    options: {
+      token: getConnectionCredential(),
+      timeout: 5000,
+      maxServerPingDelay: 10000
+    }
+  },
+  maxActiveWorkers: 3,
+  heartbeatIntervalMs: 3000,
+  workerTtlMs: 10000
+});
+```
+
+## Worker Mode & Degradation
+
+`workerMode` controls how the Centrifuge transport operates:
+
+- `dedicated` (default): Each Tab creates its own Dedicated Worker; best compatibility.
+- `shared`: Same-origin Tabs reuse the same SharedWorker; within the Worker, each connection port maintains its own independent `CentrifugeSession`. Stopping or refreshing one Tab does not affect other Tabs' connections.
+- `auto`: Selects SharedWorker at runtime, degrades to Dedicated Worker if unsupported, and finally degrades to main-thread local mode.
+
+The full chain for `auto` is **SharedWorker -> Dedicated Worker -> main-thread local mode**; the chain for explicit `shared` is identical to `auto` (**SharedWorker -> Dedicated Worker -> main-thread local mode**); the chain for explicit `dedicated` is **Dedicated Worker -> SharedWorker -> main-thread local mode**.
+
+`shared` does not refuse to degrade: if the browser lacks `SharedWorker` support, it falls back through the same chain as `auto`. The only difference between `shared` and `auto` is the preference order's first choice — `shared` always prefers the SharedWorker, while `auto` performs the same selection but is the mode used when the caller has no strong preference.
+
+When neither `sharedWorkerFactory` nor `workerFactory` is provided, the transport detects global `SharedWorker` / `Worker` capability at startup. When a custom factory is provided, the corresponding backend is considered available, avoiding false negatives from global capability detection in Node, SSR, or embedded environments. All modes perform the same structured clone validation; config and `publish` data must be structured-clonable.
+
+## SharedWorker Session Reaper
+
+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.
+- **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.
+- **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.
+
+This is the mechanism that recovers sessions for tabs that crash without sending `STOP`. Lower `heartbeatIntervalMs` to reap dead sessions faster, at the cost of more frequent PING messages on the port.
+
+`heartbeatIntervalMs` must be a positive number or `Infinity`; a value of `0`, a negative number, or `NaN` causes the transport constructor to throw a `TypeError` immediately (such a value would otherwise degenerate `setInterval` into a 0ms busy loop).
+
+> **Two heartbeats, don't confuse them.** The Core `heartbeatIntervalMs` (default `3000` ms) is the cluster heartbeat — the WorkerClusterRuntime writes its liveness record to localStorage on this cadence. The Centrifuge `heartbeatIntervalMs` (default `10000` ms) is the SharedWorker PING heartbeat documented here. They are independent and both appear in the config surface; the Centrifuge one is only meaningful in `shared` mode.
+
+## Binary Message Transfer
+
+`transferable: true` enables the ArrayBuffer optimization path without changing the external API:
+
+```ts
+const bus = createCentrifugeDataBus({
+  connection: { url: 'wss://example.test/connection/websocket' },
+  transferable: true
+});
+
+bus.publish('resource.command', binaryBuffer);
+```
+
+When enabled, `publish(topic, ArrayBuffer)` uses `PUBLISH_BIN` for Worker transport and adds the buffer to the transfer list, avoiding structured clone copying. ArrayBuffer publications returned by the Worker are transferred back to the main thread via `MESSAGE_BIN`. The business layer still only sees `DataBusMessage<TData>`; object, string, and number payloads continue along the existing object message path. When disabled, ArrayBuffers are copied via structured clone like ordinary objects.
+
+## Worker Structured Clone Constraints
+
+In Worker mode, config is sent via `Worker` / `SharedWorker` `postMessage`; local mode also performs the same validation. Values must be structured-clonable. The following config items must not be passed directly:
+
+- `getToken`
+- `getData`
+- Custom `websocket`
+- Custom `fetch`
+- `eventsource`
+- `sockjs`
+- `networkEventTarget`
+- `ReadableStream` and other runtime objects
+
+When non-clonable data is passed, `CentrifugeWorkerTransport` will throw a clear `TypeError`.
+
+## Storage Data Boundaries
+
+Storage only holds:
+
+- Worker ID, Tab ID, status, visibility, load, and heartbeat
+- Opaque Topic key, owner Worker, and last update time
+- Topic subscriber's Tab ID
+
+Storage does NOT hold:
+
+- Connection URL plaintext
+- Topic names
+- Connection credentials
+- Publication data
+- Publish data
+
+Note: BroadcastChannel coordination messages carry topic names, event types, and publication payloads in plaintext (in-memory only). Only localStorage metadata is hashed via `createOpaqueKey()`.
+
+## Security & Trust Model
+
+The coordination plane has **no authentication**. Only use this library on pages where every same-origin script is trusted:
+
+- `BroadcastChannel` messages are delivered to **every same-origin tab**, unencrypted, and any script in that origin can send or receive them. `localStorage` coordination records can likewise be read and written by any same-origin script.
+- A malicious or buggy same-origin script can forge Worker records, hijack topic ownership, read Topic names and publication payloads from the BroadcastChannel, inject publications, or impersonate subscribers. Topics and payloads traverse the BroadcastChannel **in plaintext** (in memory only) — do not place credentials, tokens, or PII in Topic names or in coordinated message payloads beyond what your server would send anyway.
+- `clusterKey` provides **isolation, not security**: it only prevents *accidental* cross-talk between logical clusters. It does not stop a script that can read `localStorage` or listen on the BroadcastChannel, because the opaque keys and channel name are derived from the same origin and can be recomputed. It also does not protect against scripts that read your page's own runtime state.
+- `clusterKey` is hashed via `createOpaqueKey` (a non-cryptographic 128-bit hash) to derive the storage prefix and BroadcastChannel name. In practice `clusterKey` is always a connection URL or a developer-controlled namespace, so a hash collision between two different clusterKeys (~2⁻⁶⁴ birthday bound) is not a practical concern.
+- Mitigations: keep the page free of untrusted third-party scripts; load coordination on an isolated origin; treat the origin's `localStorage` and BroadcastChannel namespaces as public. CSP cannot restrict BroadcastChannel or localStorage access from same-origin scripts.
+
+The transport plane (e.g. the Centrifuge WebSocket) has its own security model — tokens, TLS, and server-side permissions — and is unaffected by the above. The cluster only routes which tab owns the transport subscription; it never proxies the payload through `localStorage` (payloads travel via BroadcastChannel in memory or via the server directly).
+
+## Cluster Isolation Recommendations
+
+The following contexts must use different `clusterKey`:
+
+- Different server connections
+- Different authentication identities
+- Different data permission scopes
+- Different protocol versions
+
+When using the Centrifuge factory, the default connection URL usually provides sufficient isolation. When identity or permissions change under the same URL, an explicit `clusterKey` should be provided that includes the context version but not the credential plaintext.

package/docs/getting-started.md

@@ -0,0 +1,161 @@
+> [中文](./zh/getting-started.md) | English
+
+# Getting Started
+
+## 1. Installation
+
+```bash
+pnpm add cross-tab-worker-databus
+```
+
+The package provides the following entry points:
+
+- `cross-tab-worker-databus`: the core DataBus and transport interfaces
+- `cross-tab-worker-databus/centrifuge`: the built-in Centrifuge Worker transport
+- `cross-tab-worker-databus/centrifuge.shared.worker`: the SharedWorker build artifact, loaded by default by the built-in factory; typically no need to reference it directly
+
+## 2. Creating an Instance
+
+It is recommended to create an instance in the application's infrastructure layer and have other modules import it directly. This way, business modules within the same Tab share the Worker, connection, and Topic references.
+
+```ts
+import { createCentrifugeDataBus } from 'cross-tab-worker-databus/centrifuge';
+
+export interface ResourceEvent {
+  id: string;
+  version: number;
+  content: unknown;
+}
+
+export const dataBus = createCentrifugeDataBus<ResourceEvent>({
+  connection: {
+    url: getConnectionUrl(),
+    options: getConnectionOptions()
+  }
+});
+```
+
+`clusterKey` is derived from the connection URL by default. It is only used for cluster isolation and is converted to an opaque key before entering localStorage and as the BroadcastChannel channel name. Note that topic names and event types sent over the BroadcastChannel coordination channel are transmitted in plaintext; only localStorage metadata is obfuscated via hashing.
+
+By default, a Dedicated Worker is used, one Worker per Tab. To have same-origin Tabs reuse a single connection, set `workerMode: 'shared'` or `'auto'`:
+
+```ts
+export const dataBus = createCentrifugeDataBus<ResourceEvent>({
+  connection: {
+    url: getConnectionUrl(),
+    options: getConnectionOptions()
+  },
+  workerMode: 'auto'
+});
+```
+
+`auto` prefers SharedWorker when available, otherwise falls back to Dedicated Worker, and finally to the main-thread local mode.
+
+## 3. Subscribing
+
+You can subscribe immediately after the instance is created, without waiting for the connection to complete.
+
+```ts
+const unsubscribe = dataBus.subscribe('resource.changed', message => {
+  applyResourceEvent(message.data);
+});
+```
+
+When the connection is not yet ready, the SDK saves the subscription intent and executes it after the transport is ready. Multiple handlers for the same Topic use local reference counting, producing only a single cluster subscription.
+
+## 4. Waiting for Connection
+
+Most business logic does not need to call `ready()`. Only wait when subsequent steps must confirm that the Worker has been created and transport's `start` has completed:
+
+```ts
+await dataBus.ready();
+```
+
+`ready()` does not guarantee that the server has finished authentication; the connection state is determined by the `onStatus` callback.
+
+If the instance was created without `initialConfig` and you call `ready()` before an explicit `start(config)`, the returned Promise rejects instead of throwing; attach `.catch` and retry with `start(config)` when appropriate.
+
+## 5. Publishing
+
+```ts
+dataBus.publish('resource.command', {
+  action: 'refresh',
+  targetId: 'resource-id'
+});
+```
+
+Only use `publish` when the server protocol allows the client to publish. The SDK does not automatically replay publish operations that were not executed due to page suspension, to avoid side effects from stale commands.
+
+## 6. Status and Errors
+
+```ts
+const removeStatusListener = dataBus.onStatus(status => {
+  updateConnectionIndicator(status);
+});
+
+const removeErrorListener = dataBus.onError(error => {
+  reportDataBusError(error);
+});
+```
+
+Status values:
+
+- `connecting`
+- `connected`
+- `disconnected`
+- `error`
+
+## 7. Cleanup
+
+Release a single module subscription:
+
+```ts
+unsubscribe();
+```
+
+Fully destroy an instance:
+
+```ts
+removeStatusListener();
+removeErrorListener();
+await dataBus.stop();
+```
+
+Normal Tab hiding, entering BFCache, and restoring do not require business logic to call `stop()` or re-subscribe; the SDK handles this automatically.
+
+## 8. Running the Multi-Tab Demo
+
+The repository's `examples/demo` provides a browser demo page where you can see the full flow of messages across Tabs, clusters, Worker sessions, and the server:
+
+```bash
+pnpm install
+pnpm build
+pnpm examples
+```
+
+Open `http://localhost:4173/examples/demo/` and open it in multiple browser Tabs at the same time to observe cross-Tab data flow. The page supports:
+
+- Connecting to the public Centrifugo demo address `wss://faye.centrifugal.dev/connection/websocket` by default
+- Modifying the WSS address, `workerMode`, Topic, and `transferable` configuration in the page
+- Switching to "Local Broadcast" mode, which does not depend on an external server and demonstrates multi-Tab collaboration using only BroadcastChannel
+- Data flow animations, event stream, distribution latency metrics, and cluster Worker routing status
+- SDK capability, transport configuration, active/standby Worker, and visible/hidden Tab state
+
+When consuming the repository directly through a Git dependency, use a pinned commit. The repository ships `dist` so consumers do not need to build the SDK during installation.
+
+## 9. Explicit Start
+
+When a custom transport's configuration needs to be fetched asynchronously, you can omit `initialConfig` and explicitly start once preparation is complete:
+
+```ts
+import { CrossTabDataBus } from 'cross-tab-worker-databus';
+
+const bus = new CrossTabDataBus({
+  clusterKey: 'shared-resource-stream',
+  transport
+});
+
+const config = await loadTransportConfig();
+await bus.start(config);
+bus.subscribe('resource.changed', handleResourceEvent);
+```

package/docs/zh/README.md

@@ -0,0 +1,23 @@
+> 中文 | [English](../README.md)
+
+# 文档索引（中文版）
+
+本目录为中文版本地化文档。英文原版位于 [docs/](../README.md)。
+
+| 文档 | 内容 |
+|---|---|
+| [快速接入](./getting-started.md) | 安装、创建实例、订阅、发布和销毁 |
+| [配置说明](./configuration.md) | 核心配置、Centrifuge 配置、默认值和约束 |
+| [API 参考](./api.md) | 公共入口、类型、方法、返回值和行为 |
+| [架构说明](./architecture.md) | Worker 集群、路由、存储、迁移和降级设计 |
+| [能力矩阵](./capabilities.md) | 已实现、未实现和计划待实现的能力矩阵 |
+| [../..//examples/demo](../../examples/demo) | 可运行的多标签浏览器演示 |
+| [../../CHANGELOG.md](../../CHANGELOG.md) | 版本变更记录 |
+
+## 阅读顺序
+
+1. 首次接入阅读 [快速接入](./getting-started.md)。
+2. 生产配置阅读 [配置说明](./configuration.md)。
+3. 开发封装或自定义 transport 时阅读 [API 参考](./api.md)。
+4. 排查跨 Tab 行为时阅读 [架构说明](./architecture.md)。
+5. 评估当前边界和后续计划时阅读 [能力矩阵](./capabilities.md)。

package/docs/zh/api.md

@@ -0,0 +1,261 @@
+> 中文 | [English](../api.md)
+
+# API 参考
+
+## 包入口
+
+```ts
+import {
+  CrossTabDataBus,
+  type DataBusTraceEvent,
+  WorkerClusterRuntime,
+  createBrowserEnvironment,
+  createOpaqueKey,
+  selectWorkerBackend,
+  type WorkerMode
+} from 'cross-tab-worker-databus';
+
+import {
+  CentrifugeWorkerTransport,
+  createCentrifugeDataBus
+} from 'cross-tab-worker-databus/centrifuge';
+```
+
+业务接入优先使用 `CrossTabDataBus` 或 `createCentrifugeDataBus`。`WorkerClusterRuntime` 属于高级协调 API。
+
+## `CrossTabDataBus<TConfig, TData>`
+
+### constructor
+
+```ts
+new CrossTabDataBus<TConfig, TData>(options)
+```
+
+创建 DataBus。传入 `initialConfig` 时默认自动启动。
+
+### `start(config)`
+
+```ts
+start(config: TConfig): Promise<void>
+```
+
+启动集群协调和 transport。首次调用真正启动 transport；启动过程中并发调用共享同一个启动 Promise，不重复创建 transport。启动成功或失败后，内部 gate 会重置：之后再次调用是已启动的空操作（立即 resolve），不会重复启动；`stop()` 之后可重新调用再次启动。
+
+### `ready()`
+
+```ts
+ready(): Promise<void>
+```
+
+等待当前 transport 的 `start` 完成。自动启动失败时 Promise 会 reject；再次调用可以触发基于 `initialConfig` 的重试。
+
+未传入 `initialConfig` 且未显式调用 `start(config)` 时，`ready()` 返回 rejected Promise 而不是同步抛出，调用方可以统一通过 `.catch` 处理并决定是否显式启动。
+
+`ready()` 不等价于服务端已连接，协议连接状态通过 `onStatus` 获取。
+
+### `subscribe(topic, handler)`
+
+```ts
+subscribe(
+  topic: string,
+  handler: DataBusMessageHandler<TData>
+): () => void
+```
+
+登记本地订阅并返回释放函数。
+
+- 同一 Topic 的多个 handler 使用引用计数。
+- 当前 Tab 第一个 handler 会登记集群订阅。
+- 最后一个 handler 释放后，当前 Tab 才退出该 Topic。
+- transport 尚未 ready 时订阅自动排队。
+
+### `unsubscribe(topic, handler?)`
+
+```ts
+unsubscribe(topic: string, handler?: DataBusMessageHandler<TData>): void
+```
+
+传入 handler 时只释放对应回调；省略 handler 时释放当前实例中该 Topic 的全部 handler。
+
+优先使用 `subscribe` 返回的释放函数，避免误删其他模块的回调。
+
+### `publish(topic, data)`
+
+```ts
+publish(topic: string, data: unknown): void
+```
+
+将发布操作路由到当前 Topic owner；没有有效路由时使用当前 Worker。
+
+发布数据必须满足底层 transport 的序列化约束。SDK 不会在页面暂停期间持久化或延迟重放发布命令。
+
+当 owner 是远端 Tab、且发布控制消息无法投递时（例如 BroadcastChannel 无法克隆 payload），`publish()` 会通过 `onError` 上报失败，而不是静默丢弃。
+
+### `onStatus(handler)`
+
+```ts
+onStatus(handler: DataBusStatusHandler): () => void
+```
+
+监听 transport 状态。注册后立即收到当前状态。
+
+### `onError(handler)`
+
+```ts
+onError(handler: DataBusErrorHandler): () => void
+```
+
+监听启动、订阅、退订、发布和 Worker 错误。
+
+### `getStatus()`
+
+```ts
+getStatus(): WorkerStatus
+```
+
+返回当前状态：`connecting`、`connected`、`disconnected` 或 `error`。
+
+### `getClusterSnapshot()`
+
+返回诊断快照：
+
+```ts
+interface WorkerClusterSnapshot {
+  coordinated: boolean;
+  suspended: boolean;
+  currentWorker: WorkerRecord;
+  workers: WorkerRecord[];
+  /** 路由记录，从 knownTopics 缓存注入明文 topic。 */
+  routes: Array<WorkerRoute & { topic: string | null }>;
+  subscribedTopics: string[];
+  assignedTopics: string[];
+  /** 不透明 key → 明文 topic 的映射，用于调试。 */
+  knownTopics: Array<{ topicKey: string; topic: string }>;
+}
+```
+
+快照用于诊断和测试，不应作为业务状态源。
+
+使用 `console.table(snapshot.routes)` 查看所有路由及其明文 topic，或 `snapshot.knownTopics` 关联不透明 key 与 topic。
+
+### `trace`
+
+通过构造配置启用可选诊断：
+
+```ts
+trace: {
+  enabled: true,
+  mode: 'all',
+  metricsIntervalMs: 5000,
+  sink: (event: DataBusTraceEvent) => report(event)
+}
+```
+
+低频事件类型包括 `lifecycle`、`status`、`subscription`、`coordination` 和 `error`；高频数据按窗口输出 `message_metrics`，包含接收/分发计数、活跃 Topic 数量和分发延迟聚合（`dispatchSamples`、`dispatchAvgMs`、`dispatchP50Ms`、`dispatchP95Ms`、`dispatchMaxMs`）。所有公开事件都使用固定结构，不包含原始 Topic、消息 payload、连接地址或错误正文。sink 抛错会被隔离，不会中断消息分发，但会向 `console.warn` 输出错误，便于定位诊断配置问题。sink 应尽量避免抛出异常——预期中的错误条件应通过事件数据表达，而不是通过异常上报。
+
+### `stop()`
+
+```ts
+stop(): Promise<void>
+```
+
+永久销毁当前实例：清理 handler、集群注册、路由、Worker 和 transport。普通页面隐藏和恢复不需要调用。
+
+## `DataBusTransport<TConfig, TData>`
+
+```ts
+interface DataBusTransport<TConfig, TData> {
+  start(config, handlers): void | Promise<void>;
+  subscribe(topic): void | Promise<void>;
+  unsubscribe(topic): void | Promise<void>;
+  publish(topic, data): void | Promise<void>;
+  stop(): void | Promise<void>;
+}
+```
+
+实现要求：
+
+- `subscribe` 和 `unsubscribe` 必须幂等。
+- `stop` 后必须允许再次 `start`，用于 BFCache 恢复。
+- 收到数据时调用 `handlers.onMessage({ topic, data })`。
+- 状态变化时调用 `handlers.onStatus(status)`。
+- 异步错误通过 reject 或 `handlers.onError(error)` 上报。
+
+## `createCentrifugeDataBus<TData>(options)`
+
+```ts
+createCentrifugeDataBus<TData>(options): CrossTabDataBus<CentrifugeDataBusConfig, TData>
+```
+
+创建自动启动的 Centrifuge DataBus。默认：
+
+- `clusterKey = connection.url`
+- `workerMode = 'dedicated'`，每个 Tab 使用独立 Dedicated Worker
+- 使用包内 `centrifuge.worker.js`
+- Worker 名称为 `cross-tab-worker-databus`
+
+SharedWorker 模式使用包内 `centrifuge.shared.worker.js`。`workerMode: 'auto'` 时按 SharedWorker → Dedicated Worker → 本地模式降级。完整配置见 [configuration.md](./configuration.md)。
+
+## `CentrifugeWorkerTransport<TData>`
+
+低层 Centrifuge transport。只有需要自定义 DataBus 组装时才直接创建：
+
+```ts
+const transport = new CentrifugeWorkerTransport({
+  workerMode: 'auto',
+  workerFactory: () => new Worker(customWorkerUrl, { type: 'module' }),
+  sharedWorkerFactory: () => new SharedWorker(customSharedWorkerUrl, { type: 'module' })
+});
+```
+
+可用选项：
+
+- `workerMode`：`'dedicated'`（默认）、`'shared'` 或 `'auto'`；`auto` 的降级链路为 SharedWorker → Dedicated Worker → 本地模式
+- `transferable`：`boolean`，默认 `false`；开启后 ArrayBuffer payload 使用 Transferable 传输，对象消息 API 不变
+- `heartbeatIntervalMs`：`number`，默认 `10000`；SharedWorker PING 心跳间隔（毫秒）。传 `Infinity` 完全禁用心跳。详见 [配置](./configuration.md#sharedworker-会话回收)
+- `workerFactory`：自定义 Dedicated Worker 加载方式
+- `sharedWorkerFactory`：自定义 SharedWorker 加载方式
+
+## `WorkerClusterRuntime`
+
+高级 API，负责 Worker 注册、心跳、可见性、路由、BroadcastChannel 协议和迁移。业务模块不应直接操作它。
+
+主要方法：
+
+- `start()` / `stop()`
+- `setStatus(status)`
+- `subscribe(topic)` / `unsubscribe(topic)`
+- `publish(topic, data)`
+- `broadcastEvent(eventType, payload)`
+- `isAssigned(topic)`
+- `isActiveWorker()`
+- `hasLocalSubscriber(topic)`
+- `getSnapshot()`
+
+## 工具函数
+
+### `createOpaqueKey(value)`
+
+生成稳定的 128-bit 十六进制不透明 key。用于避免把连接或 Topic 原文写入协调元数据；它不是密码学摘要，不应用于密码存储或安全签名。
+
+### `createBrowserEnvironment()`
+
+创建默认浏览器环境适配器，包含 storage、BroadcastChannel、定时器和页面生命周期事件。
+
+### `selectWorkerBackend(mode, availability?)`
+
+按 `WorkerMode` 和能力检测选择实际后端，返回 `'shared' | 'dedicated' | 'local'`：
+
+- `shared` / `auto`：SharedWorker → Dedicated Worker → 本地模式
+- `dedicated`（默认）：Dedicated Worker → SharedWorker → 本地模式
+
+`availability` 可显式传入 `worker` / `sharedWorker` 能力标记，用于 SSR、测试或嵌入环境，避免访问不存在的全局对象。
+
+### 路由选择函数
+
+- `selectActiveWorkers`
+- `selectLeastLoadedWorker`
+- `selectRebalanceTarget`
+- `hasActiveOwner`
+
+这些纯函数主要用于测试、诊断和自定义协调策略。