cross-tab-worker-databus 0.1.0

package/docs/architecture.md

@@ -0,0 +1,514 @@
+> [中文](./zh/architecture.md) | English
+
+# Architecture
+
+## Runtime Model
+
+```mermaid
+graph TB
+  subgraph Browser["Browser (same-origin)"]
+    subgraph TabA["Tab A"]
+      AppA["Business Module"] --> BusA["CrossTabDataBus"]
+      BusA --> RuntimeA["WorkerClusterRuntime"]
+      BusA --> WorkerA["Dedicated / Shared Worker A"]
+    end
+    subgraph TabB["Tab B"]
+      AppB["Business Module"] --> BusB["CrossTabDataBus"]
+      BusB --> RuntimeB["WorkerClusterRuntime"]
+      BusB --> WorkerB["Dedicated / Shared Worker B"]
+    end
+  end
+
+  RuntimeA <--> Channel["BroadcastChannel Control Plane"]
+  RuntimeB <--> Channel
+  RuntimeA <--> Registry["localStorage Worker Registration"]
+  RuntimeB <--> Registry
+  RuntimeA <--> Routes["localStorage Topic Routes"]
+  RuntimeB <--> Routes
+  WorkerA --> Server["Centrifuge / realtime server"]
+  WorkerB --> Server
+```
+
+By default, when `workerMode: 'dedicated'`, each Tab has its own dedicated transport Worker. When configured as `shared` or `auto` and the browser supports SharedWorker, same-origin tabs share the same SharedWorker; each connection port within the SharedWorker creates its own independent `CentrifugeSession`, so one Tab refreshing or stopping does not affect other Tabs. The `auto` mode degrades in order of **SharedWorker → Dedicated Worker → Local mode**, while the `dedicated` mode degrades in order of **Dedicated Worker → SharedWorker → Local mode**. `BroadcastChannel` is only responsible for control messages and real-time publication forwarding; localStorage is only responsible for eventually-consistent coordination metadata.
+
+Because `MessagePort` has no `close` event, a tab that crashes before sending `STOP` would otherwise leak its session and WebSocket. The main thread therefore sends a `PING` every 10 seconds, and the SharedWorker reaps any port that stays silent for more than 30 seconds, releasing the session and its subscriptions.
+
+## Layers
+
+| Layer | Entry | Responsibility |
+|---|---|---|
+| DataBus | `CrossTabDataBus` | Local handler reference counting, message dispatch, state and transport lifecycle |
+| Cluster Coordination | `WorkerClusterRuntime` | Worker registration, roles, heartbeat, Topic owner, migration and broadcast protocol |
+| Transport | `DataBusTransport` | Executes subscribe, unsubscribe, publish on the real Worker/connection |
+| Centrifuge | `CentrifugeWorkerTransport` | Protocol adaptation between the main thread and the built-in Centrifuge Worker |
+
+## Glossary
+
+Terms are explained in plain language; the code and the rest of this document use the short names.
+
+| Term | Short name in code | Plain-language meaning |
+|---|---|---|
+| **Topic** | `topic` | A named channel (e.g. `price.feed`) that applications subscribe to or publish on. |
+| **Topic key** | `topicKey` | An opaque 128-bit hash of the Topic name. The Topic name itself is never persisted in coordination storage. |
+| **Tab** | `tabId` | One browser page instance. `tabId` survives refresh so a tab keeps its identity across the page lifecycle. |
+| **Worker** | `workerId` | One runtime instance inside a Tab. Each Worker publishes its own heartbeat and can own Topics. A Tab can briefly run two Workers during a restart/handoff. |
+| **Topic owner** | — | The Worker responsible for the real transport subscription of a Topic. "Owner" is a hat a Worker wears, not a permanent role: it receives the Topic's publications from the server and fans them out to other Tabs. |
+| **Assignment** | `assignedTopics` | The set of Topics a Worker currently owns. |
+| **Active / standby** | `role` | `active` Workers are eligible to become new Topic owners; `standby` Workers are not. A hidden tab is still `active` if it already owns Topics. |
+| **Subscriber** | `subscriber` | A Tab that holds a local subscription record for a Topic. |
+| **Route** | `route` | The persisted record mapping a `topicKey` to its owner Worker. |
+| **Sticky** | — | Existing routes keep their owner while that owner is alive; load and visibility only affect placement of brand-new routes. |
+| **Heartbeat** | `heartbeatAt` | A Worker's periodic liveness write to storage. Workers past `workerTtlMs` without refreshing are considered dead. |
+| **Handoff** | `handoffFromWorkerId` | The graceful passing of a Topic from an old owner to a new one (e.g. on `pagehide`), with a strict release-ACK protocol so no Topic is ever owned twice simultaneously. |
+| **Generation** | `generation` | A monotonic counter on each route. Handoff ACKs must reference a generation at least as new as the route's, so stale ACKs are ignored. |
+| **Local mode** | `coordinated: false` | Degraded operation when storage or BroadcastChannel is unavailable: no cross-Tab routing, the Tab only uses its own transport. |
+
+## Storage Structure
+
+All keys are isolated by `createOpaqueKey(clusterKey)`. Topics are also stored as 128-bit opaque keys.
+
+BroadcastChannel messages carry topic names, event types, and publication payloads in plaintext. Only the channel name (derived from `clusterKey`) is hashed. If topic names are sensitive, avoid including them as part of the plaintext payload, or use an end-to-end encryption layer on top of the data bus.
+
+```text
+cross-tab-worker-databus:{clusterHash}:worker:{workerId}
+cross-tab-worker-databus:{clusterHash}:route:{topicKey}
+cross-tab-worker-databus:{clusterHash}:subscriber:{topicKey}:{tabId}
+```
+
+Unlike the old single-JSON route table, subscribers use per-Tab independent keys. When Tab A and Tab B subscribe/unsubscribe concurrently, they do not perform a read-modify-write on the same `subscribers[]`, structurally reducing the probability of lost updates.
+
+### Worker Record
+
+```ts
+interface WorkerRecord {
+  workerId: string;
+  tabId: string;
+  load: number;
+  role: 'active' | 'standby';
+  status: 'connecting' | 'connected' | 'disconnected' | 'error';
+  visibilityState: 'visible' | 'hidden';
+  heartbeatAt: number;
+  registeredAt: number;
+}
+```
+
+Each Worker writes its own record independently. `load` is the number of Topics it is responsible for, not CPU percentage.
+
+### Topic Route
+
+```ts
+interface WorkerRoute {
+  topicKey: string;
+  workerId: string;
+  tabId: string;
+  updatedAt: number;
+  generation: number;
+  handoffFromWorkerId?: string;
+  confirmedAt?: number;
+}
+```
+
+`generation` increments on every re-assignment and must match across the handoff handshake; `handoffFromWorkerId` records the previous owner during a graceful handoff. The interface above matches the current protocol — see [Failover](#failover) for how these two fields drive takeover.
+
+Routes do not store the original topic string or payload. When the actual owner receives `CONTROL/SUBSCRIBE`, the original topic string is only passed through the BroadcastChannel in-memory message. `confirmedAt` is written after the owner processes the control message; before the route is confirmed, the subscriber Runtime holding the original topic string will resend `SUBSCRIBE` to recover from BroadcastChannel message loss that results in "a route without a real subscription".
+
+### How `topic`, `topicKey`, `tabId`, `workerId`, and BroadcastChannel relate
+
+These identifiers represent different layers:
+
+| Object | Meaning | Main use | Persisted in coordination storage |
+|---|---|---|---|
+| `topic` | Original application Topic string | Passed to transport `subscribe`, `unsubscribe`, and `publish` | No; kept in Runtime memory and control messages |
+| `topicKey` | Stable opaque key from `createOpaqueKey(topic)` | Joins route and subscriber records | Yes |
+| `tabId` | Stable identity of a browser Tab | Identifies which Tab subscribes to a `topicKey` | Yes, in subscriber keys |
+| `workerId` | Identity of the current Runtime/Worker instance | Identifies the Worker that owns the transport subscription | Yes, in worker/route records |
+| `BroadcastChannel` | Same-origin, in-memory real-time channel | Carries control actions, publication events, and reconciliation signals | No |
+
+```text
+topic
+  └─ createOpaqueKey(topic) → topicKey
+       ├─ route:{topicKey}
+       │    └─ workerId / tabId / generation / confirmedAt
+       └─ subscriber:{topicKey}:{tabId}
+
+BroadcastChannel CONTROL
+  └─ topic + topicKey + sourceWorkerId + targetWorkerId + action
+```
+
+`topicKey` links storage records to control messages, but it cannot be reversed to recover the original `topic`. Only a live Runtime retains the in-memory `topicKey → topic` mapping.
+
+### In-memory topic key cache (`knownTopics`)
+
+Each Runtime maintains a `Map<topicKey, topic>` called `knownTopics` that serves as the reverse-lookup cache from opaque key to plaintext topic. It is populated by `rememberTopic()`, which is called on every `subscribe`, `publish`, `unsubscribe`, and inbound `CONTROL` message.
+
+The cache exists for two reasons:
+
+1. **Storage-less fallback.** When localStorage is unavailable (degraded mode), `readRoute()` and `readSubscriberTabIds()` have no persisted records to query. They reconstruct the route from in-memory state — but that requires recovering the plaintext `topic` from a `topicKey`. Without `knownTopics`, a topic whose key was evicted would silently return `null` from `readRoute()` even though the worker still owns it.
+
+2. **Avoid re-hashing on every reconcile.** Each reconcile cycle iterates `subscribedTopics` and calls `rememberTopic` for each topic. The cache is updated unconditionally (hash is cheap, so there is no hit/miss penalty), but the reverse mapping is essential for the storage-less path.
+
+**Cap and eviction.** The cache is capped at `MAX_KNOWN_TOPICS = 500` entries. This limit prevents a misbehaving or malicious peer from exhausting memory by referencing arbitrary topics in control messages — every `CONTROL` message the handler processes calls `rememberTopic`, which would otherwise grow the map unboundedly.
+
+Eviction is FIFO (insertion order, Map iteration order). When the cache exceeds the cap, the oldest entry (first key in Map iteration) is removed:
+
+- An entry is **never evicted** if the current worker still owns it (`assignedTopics.has(oldest)` guard), because the storage-less `readRoute` path depends on it.
+- The entry being inserted is never evicted in the same step (`oldest !== topicKey` guard).
+- Reads do not promote recency, so this is not true LRU. Hashing is cheap enough that a missed reverse-lookup merely recomputes the key.
+
+**`isAssigned` bypasses the cache.** `isAssigned(topic)` calls `createOpaqueKey(topic)` directly rather than `rememberTopic()`. This is deliberate: `isAssigned` is a read-only query, not a state change, so it must not populate `knownTopics` (which could evict an entry the storage-less path needs). It also prefers the synchronous `assignedTopics` Map over reading the route from storage, avoiding a race with the `BatchingStorageWriter` flush window.
+
+**Opaque key collision.** `createOpaqueKey` is a non-cryptographic 128-bit hash. The birthday collision bound (~2⁶⁴ for 50% probability) is far beyond the number of topics a single cluster handles (thousands at most). Similarly, `clusterKey` is hashed via `createOpaqueKey` to derive the storage prefix and BroadcastChannel name. In practice, `clusterKey` is always a connection URL or a developer-controlled namespace — naturally unique, so cross-cluster collision is not a concern.
+
+**`clusterKey` isolation.** The `clusterKey` defines the cluster boundary. Two DataBus instances with different `clusterKey` values — even in the same origin — operate on completely isolated storage namespaces and BroadcastChannel names, even if they happen to use the same transport connection. This is how different logical clusters (e.g. market data vs. notifications) coexist without cross-talk.
+
+**`knownTopics` lifecycle.** The cache is populated, read, and cleaned at specific points:
+
+| Event | `knownTopics` mutation | Why |
+|---|---|---|
+| `subscribe(topic)` | `rememberTopic(topic)` → `set(topicKey, topic)` | Populate the reverse mapping; needed for storage-less `readRoute` |
+| `publish(topic, data)` | `rememberTopic(topic)` → `set(topicKey, topic)` | Populate; same reason |
+| `unsubscribe(topic)` | `delete(topicKey)` if not in `assignedTopics` | No longer needed; only keep it if we still own the topic |
+| `CONTROL` received (any action: SUBSCRIBE / UNSUBSCRIBE / PUBLISH) | `rememberTopic(message.topic)` → `set(topicKey, topic)` | Every inbound control message carries the plaintext topic and the handler caches it before acting |
+| `CONTROL/UNSUBSCRIBE` received | no direct deletion | `rememberTopic` still caches the topic; the entry is later removed by `reconcileAssignedTopics` once the route no longer points to this worker |
+| `reconcileAssignedTopics` | `delete(topicKey)` if not subscribed and not owned | Route no longer points to us — clean up unless we're still a subscriber |
+| `stop()` | `clear()` | Full teardown |
+| FIFO eviction (next `rememberTopic` call) | `delete(oldest)` if `!assignedTopics.has(oldest)` | Cache size exceeded `MAX_KNOWN_TOPICS`; never evict owned keys |
+
+**Storage-less fallback dependency.** When `this.storage` is `null` (degraded mode), `readRoute()` and `readSubscriberTabIds()` cannot query persisted records. They reconstruct routes from in-memory state alone:
+
+- `readRoute(topicKey)` → looks up `knownTopics.get(topicKey)` to recover the plaintext topic, then checks `subscribedTopics.has(topic)` or `assignedTopics.has(topicKey)` to determine if this worker is the owner.
+- `readSubscriberTabIds(topicKey, workers)` → `knownTopics.get(topicKey)` recovers the plaintext topic, then checks `subscribedTopics.has(topic)` — if we are a subscriber, we are the only subscriber (no storage means no cross-tab coordination).
+
+This is why `assignedTopics` guards the FIFO eviction: evicting a key we still own would silently break `readRoute()` in storage-less mode, causing `isAssigned()` to disagree with `readRoute()`.
+
+### One subscription and publication flow
+
+```mermaid
+sequenceDiagram
+  participant App as App (Tab A)
+  participant RuntimeA as Runtime A
+  participant Storage as localStorage
+  participant Channel as BroadcastChannel
+  participant RuntimeB as Owner Runtime B
+  participant Transport as Transport/server
+
+  App->>RuntimeA: subscribe(topic, handler)
+  RuntimeA->>RuntimeA: derive topicKey
+  RuntimeA->>Storage: write subscriber:{topicKey}:{tabId}
+  RuntimeA->>Storage: read or create route:{topicKey}
+  RuntimeA->>Channel: CONTROL/SUBSCRIBE(topic, topicKey, targetWorkerId)
+  Channel->>RuntimeB: deliver control message
+  RuntimeB->>Transport: subscribe(topic)
+  RuntimeB->>Storage: write route.confirmedAt
+  Transport-->>RuntimeB: publication(topic, payload)
+  RuntimeB->>Channel: EVENT/DATABUS_PUBLICATION
+  Channel->>RuntimeA: deliver event
+  RuntimeA->>App: invoke handler(payload)
+```
+
+A second Tab subscribing to the same Topic adds only its own subscriber record; it does not create another transport subscription while the existing owner is alive. Unsubscribe removes the current Tab's subscriber record. The owner unsubscribes the transport and removes the route only when no subscriber remains.
+
+### Console diagnostics
+
+If the application exposes the DataBus instance as `window.__bus`, the live Runtime can be inspected with:
+
+```js
+__bus.getClusterSnapshot().subscribedTopics
+__bus.getClusterSnapshot().assignedTopics
+__bus.getClusterSnapshot().knownTopics
+console.table(__bus.getClusterSnapshot().routes)
+```
+
+`routes` now includes the plaintext `topic` (injected from the in-memory `knownTopics` cache), so each entry shows both the opaque key and the original topic name. `knownTopics` exposes the full `topicKey → topic` mapping for debugging. BroadcastChannel has no history API; inspect live messages by enabling trace or temporarily logging the `postMessage` and receive paths.
+
+### Why Multiple localStorage Keys
+
+This decentralized structure is a trade-off for concurrency correctness, not for reducing event listeners:
+
+| Approach | Write Conflict | Cleanup Granularity | Main Issue |
+|---|---|---|---|
+| Single large JSON for Worker/route/subscriber | High | Only whole read/write | Multiple Tabs doing read-modify-write concurrently can easily overwrite each other, losing subscribers |
+| Independent key per entity | Low | Can clean up per Worker, per route, per Topic+Tab precisely | More keys, requires TTL-based garbage collection |
+
+The SDK does not rely on `storage` events to drive coordination; control notifications use BroadcastChannel. Although Worker heartbeats update their own independent key, this does not trigger repeated business callbacks or message dispatch within the SDK. The core benefit of separate keys is that different Tabs write different records, avoiding overwrite contention on a shared large object.
+
+Under normal conditions, the number of keys is approximately: `Number of Workers + Number of Topic routes + Number of Topic/Tab subscription relationships`. The Runtime cleans up timed-out Workers, orphaned subscribers without active Tabs, and orphaned routes that have exceeded the Worker TTL and no longer have subscribers. Other naming structures left over from older versions do not belong to the current SDK protocol and do not participate in current route resolution.
+
+### Storage Write Coalescing
+
+Coordination metadata writes first enter an in-memory pending table, where they are merged by key within the same task (heartbeats, route confirmations, and subscriber updates share one flush), then batch-flushed to localStorage via a microtask. When a flush encounters a quota or write failure, it retries with exponential backoff from `50ms → 1600ms`. The current Tab's transport is not interrupted by coordination write failures. `clear()` resets the backoff counter to avoid starting retries from a delayed initial value after frequent cleaning.
+
+Reads always see the not-yet-flushed pending values within the same task; cross-tab visibility is guaranteed by the microtask flush and the synchronous flush on `pagehide` / `stop()`. During `pagehide`, the owner writes and flushes the transferred route and its worker removal before broadcasting `REGISTRY`. If the unload-time `CONTROL / SUBSCRIBE` message is lost, receiving tabs therefore reconcile against the final persisted topology instead of waiting for their next heartbeat.
+
+## Key State Inventory
+
+Every keyed piece of state in the system — the full picture of what the previous sections described piece by piece. Each row has its own lifecycle; that is **why they are separate** and must not be merged:
+
+| State | Owner class | Key | Value | Lifecycle | Why it is separate |
+|---|---|---|---|---|---|
+| `topicHandlers` | `CrossTabDataBus` | Plaintext `topic` | `Set<handler>` | Added/removed by app `subscribe`/`unsubscribe`; entry deleted when its last handler leaves | Reference-counts application-level handlers; belongs to the business layer |
+| `transportSubscribedTopics` | `CrossTabDataBus` | Plaintext `topic` | marker | Cleared on disconnect; replayed from `assignedTopics` on reconnect | Tracks what the live transport connection actually holds; dies with the connection |
+| `subscribedTopics` | `WorkerClusterRuntime` | Plaintext `topic` | marker | Grows as the first local handler subscribes; shrinks when the last one leaves | The Tab's durable subscription intent, survives transport failures |
+| `assignedTopics` | `WorkerClusterRuntime` | `topicKey` | Plaintext `topic` | Set on receiving `CONTROL/SUBSCRIBE`; cleared on `CONTROL/UNSUBSCRIBE` or handoff | The authoritative "what I own" set; drives `isAssigned` and load |
+| `knownTopics` | `WorkerClusterRuntime` | `topicKey` | Plaintext `topic` | FIFO-capped at 500; never evicts owned keys | The reverse-lookup cache; also the only source of plaintext in storage-less mode |
+| Storage `worker:` | persisted | `clusterHash:…:worker:{workerId}` | JSON `WorkerRecord` | Heartbeat refresh; pruned after `workerTtlMs` | Cross-tab liveness discovery |
+| Storage `route:` | persisted | `clusterHash:…:route:{topicKey}` | JSON `WorkerRoute` | Created/stamped by subscriber; pruned when no subscribers + TTL expired | Cross-tab owner mapping |
+| Storage `subscriber:` | persisted | `clusterHash:…:subscriber:{topicKey}:{tabId}` | JSON `TopicSubscriberRecord` | Written per Tab subscription; pruned when the Tab dies | Cross-tab subscriber intent |
+
+**How the three in-memory topic forms relate** (`knownTopics` ↔ `assignedTopics` ↔ the four plaintext sets):
+
+```text
+app subscribe/unsubscribe loop
+        │  (handler reference counting)
+        ▼
+   topicHandlers ──────────────► subscribedTopics ──► storage subscriber + route
+        (plaintext topic)         (plaintext topic)      (topicKey)
+                                            │ CONTROL/SUBSCRIBE on the wire
+                                            ▼
+                                    assignedTopics ──► transport subscription
+                                      (topicKey)         (plaintext topic again)
+                                            │
+                                            └─► knownTopics: reverse cache used by
+                                                readRoute/readSubscriberTabIds (esp. storage-less)
+```
+
+The two `topicKey → topic` maps (`assignedTopics`, `knownTopics`) deliberately hold **the same pairs with different lifecycles**: `assignedTopics` is authoritative and never evicts, `knownTopics` is a bounded cache to keep plaintext reachable when no storage is present. After a plaintext topic leaves `assignedTopics` and `knownTopics` (via `reconcileAssignedTopics` or eviction), the Runtime can still read routes by `topicKey` — it just can no longer reverse them to plaintext.
+
+## BroadcastChannel Protocol
+
+All real-time coordination flows through one BroadcastChannel per cluster, whose name is derived from `clusterKey`. Messages on it exist only in memory: they never touch localStorage and never pass through the transport server. Four message types are exchanged:
+
+| Type | Direction | Purpose |
+|---|---|---|
+| `CONTROL` | point-to-point (A → B) | Ask the target Worker to `SUBSCRIBE`, `UNSUBSCRIBE`, or `PUBLISH` a topic. Carries `action`, `topic`, `topicKey`, `targetWorkerId`, and an optional `data` payload. |
+| `EVENT` | broadcast (owner → all Tabs) | Fan out a publication that the transport delivered to the owning Worker. Carries `eventType` and `payload`. |
+| `REGISTRY` | broadcast | Nudge every Tab to reconcile immediately after a registry or route write, instead of waiting for the next heartbeat. |
+| `ROUTE_RELEASED` | point-to-point (old owner → new owner) | Acknowledge a graceful handoff; only the new owner whose route `generation` matches may `SUBSCRIBE` (see Failover). |
+
+The owning Worker filters every publication it receives with `isAssigned(topic)`, and every Tab filters inbound `EVENT` messages through its local subscriber records — each message is therefore dispatched exactly once. BroadcastChannel never echoes a message back to its sender, which is also why the owner does not double-dispatch its own broadcast.
+
+## Owner Selection
+
+1. Workers with status `connecting` / `connected` are prioritized for the candidate set.
+2. If a visible Tab exists, visible Workers are preferred when choosing an owner for a new Topic; when all Tabs are hidden, hidden Workers remain eligible.
+3. Sorted by `registeredAt, workerId`, up to 3 active Workers are selected as new-route candidates.
+4. An existing route remains sticky as long as its owner Worker record is alive, regardless of load, visibility, or whether the owner remains in the new-route candidate set.
+5. A second Tab subscribing to an existing Topic only writes its subscriber record. It does not modify the route or call its own transport `subscribe`.
+6. Only a Topic without a route, or a route whose owner has departed or expired by heartbeat TTL, is assigned to the least-loaded candidate Worker.
+7. A new route is considered unconfirmed until the owner writes `confirmedAt`; the subscriber will automatically resend the control message.
+
+## Subscription Flow
+
+```mermaid
+sequenceDiagram
+  participant App as Business Module
+  participant Bus as CrossTabDataBus
+  participant Route as Topic Route
+  participant Channel as BroadcastChannel
+  participant Owner as Owner Worker
+
+  App->>Bus: subscribe(topic, handler)
+  Bus->>Bus: First handler in this Tab?
+  Bus->>Route: Write subscriber:{topicKey}:{tabId}
+  Route-->>Bus: Current owner
+  alt Owner does not exist or is invalid
+    Bus->>Route: Write lowest-load owner
+    Bus->>Channel: CONTROL / SUBSCRIBE
+    Channel->>Owner: transport.subscribe(topic)
+  end
+```
+
+Within the same DataBus instance, multiple handlers subscribing to the same topic are only registered once; the Tab's subscription is only canceled from the cluster after the last handler is released.
+
+### Subscription state layers
+
+The system maintains four independent subscription-tracking sets. Understanding their relationship is key to the architecture:
+
+| Set | Location | Tracks | Lifecycle |
+|---|---|---|---|
+| `topicHandlers` | `CrossTabDataBus` | Application-level handler references per topic | Added/removed by `subscribe(topic, handler)` / `unsubscribe(topic, handler)` |
+| `subscribedTopics` | `WorkerClusterRuntime` | Topics this tab has asked the cluster to coordinate | Added when `topicHandlers` goes 0→1; removed when it goes n→0 |
+| `assignedTopics` | `WorkerClusterRuntime` | Topics this worker is the owner of (transport subscription responsibility) | Set on receiving `CONTROL/SUBSCRIBE`; cleared on `CONTROL/UNSUBSCRIBE` or handoff |
+| `transportSubscribedTopics` | `CrossTabDataBus` | Topics the transport has been asked to subscribe to | Cleared on disconnect; replayed from `assignedTopics` on reconnect |
+
+**Subscription propagation chain:**
+
+```text
+Application: subscribe(topic, handler)
+  → topicHandlers 0→1
+    → cluster.subscribe(topic) → subscribedTopics.add(topic)
+      → write subscriber:{topicKey}:{tabId}
+      → readRoute(topicKey)
+        → if no route: selectLeastLoadedWorker, writeRoute, sendControl(SUBSCRIBE)
+          → owner receives CONTROL/SUBSCRIBE
+            → assignedTopics.set(topicKey, topic)
+            → transport.subscribe(topic) → transportSubscribedTopics.add(topic)
+```
+
+**Unsubscribe propagation chain:**
+
+```text
+Application: unsubscribe(topic, handler) (last handler)
+  → topicHandlers empty
+    → cluster.unsubscribe(topic) → subscribedTopics.delete(topic)
+      → releaseSubscription → delete subscriber record
+        → if no subscribers left: delete route, sendControl(UNSUBSCRIBE)
+          → owner receives CONTROL/UNSUBSCRIBE
+            → assignedTopics.delete(topicKey)
+            → transport.unsubscribe(topic) → transportSubscribedTopics.delete(topic)
+```
+
+**Disconnect / reconnect behavior:**
+
+- On transport disconnect: `transportSubscribedTopics` is **cleared** immediately. The other three sets (`topicHandlers`, `subscribedTopics`, `assignedTopics`) survive unchanged.
+- On transport reconnect: `CrossTabDataBus` iterates `assignedTopics` and re-calls `transport.subscribe(topic)` for each one, repopulating `transportSubscribedTopics`.
+- This is how business subscription intent survives transport failures: the application never needs to re-subscribe after a reconnect.
+
+## Message Flow
+
+A publication travels publisher → current Topic owner → transport/server → owner → all Tabs:
+
+1. Any Tab calls `publish(topic, data)`. The Runtime looks up `route:{topicKey}` and sends `CONTROL/PUBLISH` to the owner Worker; when no route exists the message is submitted to the current Tab's own transport.
+2. The owner runs `transport.publish(topic, data)`. Because only the owner holds a real transport subscription to the topic, the server delivers the resulting publication back to exactly one Worker.
+3. The owner accepts a publication only while `isAssigned(topic)` still holds. Stale messages from an expired owner are discarded — keeping the fan-out single-sourced.
+4. The owner broadcasts `EVENT/DATABUS_PUBLICATION` over the BroadcastChannel and, if its own Tab also has a local subscription, dispatches once directly. BroadcastChannel never echoes to the sender, so there is no duplicate dispatch.
+5. Every other Tab receives the `EVENT` but invokes its local handlers only when it holds a `subscriber:{topicKey}:{tabId}` record for that topic; Tabs without a local subscription drop the message.
+
+```mermaid
+sequenceDiagram
+  participant Pub as Publisher Tab A
+  participant CH as BroadcastChannel
+  participant Owner as Owner Tab B
+  participant Server as Transport / server
+  participant Other as Other Tabs C / D / E
+
+  Pub->>CH: CONTROL/PUBLISH(topic, data, targetWorkerId=owner)
+  CH->>Owner: deliver CONTROL/PUBLISH
+  Owner->>Server: transport.publish(topic, data)
+  Server-->>Owner: publication(topic, payload)
+  Owner->>Owner: isAssigned(topic) holds?
+  Owner->>CH: EVENT/DATABUS_PUBLICATION
+  Owner->>Owner: local dispatch (if subscribed)
+  CH->>Other: deliver EVENT
+  Other->>Other: hasLocalSubscriber(topic) → invoke handlers
+```
+
+BroadcastChannel does not echo to its sender, so the owner receives no `EVENT` back for its own broadcast — its local dispatch is the only local delivery.
+
+Publications are not written to localStorage. Message data only exists in the BroadcastChannel in-memory event and within the transport; batch writes only cover coordination metadata.
+
+### Dispatch flow: three gates
+
+Every publication from the transport goes through three checks before reaching the application handler:
+
+1. **`isAssigned(topic)`** — called on the owning Worker when a transport message arrives (`handleTransportMessage`). If the topic is no longer assigned to this worker (e.g. a stale message from a previous ownership window), the message is dropped immediately. This is the outer gate: it prevents a non-owner from broadcasting.
+
+2. **`broadcastEvent('DATABUS_PUBLICATION', message)`** — called only after `isAssigned` passes. The owning Worker fans the message out to all tabs via BroadcastChannel `EVENT`. Each tab receives the event but does not dispatch yet — it must pass the inner gate.
+
+3. **`hasLocalSubscriber(topic)`** — called on each tab receiving the `EVENT`. Only tabs that have a local subscriber record for this topic invoke the registered handler. Tabs without a local subscription drop the message silently.
+
+These three checks ensure **exactly-once dispatch per subscriber**:
+- The outer gate (`isAssigned`) prevents duplicate broadcasts from a stale owner.
+- The inner gate (`hasLocalSubscriber`) prevents a tab from dispatching a topic it never subscribed to.
+- BroadcastChannel never echoes to its sender, so the owner does not receive its own `EVENT` — its local dispatch is the only local delivery.
+
+```text
+Transport message → isAssigned(topic)? → Yes → broadcastEvent(EVENT)
+                                                 ↓
+                                     Each tab receives EVENT
+                                                 ↓
+                                     hasLocalSubscriber(topic)? → Yes → dispatch(handler)
+```
+
+## Coordination & Reconciliation
+
+Cluster convergence is driven on two timelines:
+
+- **Heartbeat + reconcile loop** (default `3000 ms`, `heartbeatIntervalMs`). On every tick each Worker refreshes its own record and runs a reconcile pass: prunes Workers past `workerTtlMs`, orphaned subscribers whose Tab is no longer active, and orphaned routes that have no subscribers and exceed the TTL; recomputes its own active/standby role; re-writes its subscriber records; and re-sends `CONTROL/SUBSCRIBE` for any route that still lacks `confirmedAt` — which also recovers control messages lost on the channel.
+- **`REGISTRY` nudge**. Writes to Worker records, routes, or subscribers broadcast a `REGISTRY` message so every peer reconciles immediately rather than waiting for the next heartbeat.
+
+Heartbeat writes are not announced, so a stale record is only noticed within one heartbeat interval. The worst case for failing to detect a dead owner is `heartbeatIntervalMs + workerTtlMs` (default about 13 s); see [TTL Message-Loss Window](./configuration.md#ttl-message-loss-window) for the trade-offs.
+
+## Failover
+
+On normal close or entry into BFCache, `pagehide` pauses the Runtime: it deletes Worker and subscriber records, yields the actual owner, and closes the underlying transport, but retains the business subscription intent in memory. After the page is restored via `pageshow`, DataBus rebuilds the Worker/connection, and the Runtime automatically re-registers, restores subscriber records, and reconciles Topics, without requiring the business to re-call `subscribe`.
+
+#### Tab identity and `window.open`
+
+Each Runtime stores its `tabId` in `sessionStorage` so refreshes retain identity; every Runtime gets a random-suffixed `workerId`. Browsers may clone the opener's `sessionStorage` when `window.open()` creates a page, causing two physical tabs to share a `tabId` and collide on subscriber or diagnostic keys.
+
+Applications should use `noopener` when opening a new tab. As a safety net, the SDK discards a copied sessionStorage id when an opener is detected and generates a fresh one. Inspection records are keyed by `tabId + workerId`, preventing Worker restart or handoff snapshots from overwriting one another.
+
+`visibilitychange` does not remove business subscriptions or migrate established routes. A hidden Tab keeps the Topics it already owns and can still receive data broadcast by other owners. Visibility only affects candidate selection when a new Topic needs its first owner.
+
+When an abnormal exit cannot execute the `pagehide` cleanup, other Runtimes scan Worker records and clean up by TTL.
+
+If a Tab still subscribed to a Topic finds that the owner Worker has departed or expired, it selects a new owner and increments the route `generation`. Normal `pagehide` handoff is strict: the new route records `handoffFromWorkerId`, the old owner unsubscribes from transport first, then sends `ROUTE_RELEASED(generation)`, and only the matching new owner ACK handler sends `SUBSCRIBE`. If the old Worker has already disappeared, the new owner takes over immediately. A refreshed Tab that rejoins afterward records itself as a subscriber and reuses the replacement owner instead of taking the route back.
+
+This process prevents overlap during graceful owner handoff while retaining availability during failure recovery; it does not guarantee exactly-once delivery.
+
+## Transport Reconnection
+
+DataBus separates "business subscription intent" from "transport current subscription state". When the transport reports `disconnected` / `error`, it only clears the underlying subscription flag, not the business handler; when it re-enters `connected`, DataBus automatically replays the Topics the current Worker is responsible for.
+
+The built-in Centrifuge transport also retains its own Subscriptions and performs protocol-level reconnection. Both layers of recovery require `subscribe` / `unsubscribe` to be idempotent.
+
+## Lifecycle State Machine
+
+`CrossTabDataBus` uses several boolean flags and promise gates to serialize lifecycle transitions. The interaction between them is the most complex part of the DataBus layer.
+
+### Flags
+
+| Flag | Type | Meaning |
+|---|---|---|
+| `started` | `boolean` | `start()` has been called and no `stop()` has completed since |
+| `stopping` | `boolean` | `stop()` is in progress; prevents new operations |
+| `suspended` | `boolean` | Tab is hidden; transport is intentionally stopped |
+| `transportReady` | `boolean` | Transport has reported `connected` and is accepting operations |
+| `startPromise` | `Promise \| null` | Gate for concurrent `start()` calls; cleared after settle |
+| `pendingStop` | `Promise \| null` | Gate for async `transport.stop()`; shared by suspend and failure paths |
+
+### State transitions
+
+```text
+                  ┌──────────────────────────────────────────────┐
+                  │                                              ▼
+              ┌───────┐   start(config)    ┌──────────┐   openTransport ok   ┌───────────┐
+              │ idle  │ ──────────────────→ │ starting │ ──────────────────→ │  running  │
+              └───────┘                     └──────────┘                     └───────────┘
+                  ▲                              │                               │
+                  │                              │ openTransport fails           │ pagehide
+                  │                              ▼                               │
+                  │                          ┌──────────┐                        ▼
+                  │                          │  failed  │                  ┌───────────┐
+                  │                          └──────────┘                  │ suspended │
+                  │                              │                         └───────────┘
+                  │                              │ start(config) again          │
+                  │                              ▼                              │ pageshow
+                  │                          ┌──────────┐                        │
+                  │                          │ starting │◄───────────────────────┘
+                  │                          └──────────┘
+                  │
+                  │   stop()                  ┌──────────┐
+                  └────────────────────────── │ stopped  │
+                                              └──────────┘
+```
+
+**Key behaviors:**
+
+- **Concurrent start**: If `start()` is called while `startPromise` is non-null, the second call returns the same promise. Only one transport open is in flight at a time.
+- **Suspend during start**: If `pagehide` fires while `openTransport` is in flight, `suspendTransport()` sets `suspended = true` and chains a `transport.stop()` after the in-flight start. The `openTransport` catch path detects `suspended` and abandons the open without treating it as a failure.
+- **Recovery cooldown**: When the transport reports `error` while `started` is true and `stopping` is false, `updateStatus` schedules an automatic `reopenTransport()` after `RECOVERY_COOLDOWN_MS` (1000 ms). A second error within the cooldown window is suppressed to prevent a tight retry loop.
+- **Stop during suspend**: `stop()` sets `stopping = true`, which prevents `suspendTransport()` from running. The cleanup awaits `startPromise` and `pendingStop` to ensure any in-flight open or stop completes before the final `transport.stop()`.
+
+## Degradation
+
+The Runtime degrades to local mode when any of the following conditions are met:
+
+- localStorage is not writable
+- BroadcastChannel does not exist or construction fails
+- SSR / Node environment without browser APIs
+
+Local mode still calls the current transport's subscribe and publish methods, but does not perform cross-Tab routing or forwarding.
+
+The Centrifuge transport also has a backend degradation scheme based on `workerMode`: `auto` tries SharedWorker → Dedicated Worker → main-thread local session in order; `dedicated` tries Dedicated Worker → SharedWorker → main-thread local session in order. The Runtime's cross-Tab degradation and the transport's backend degradation are independent of each other: even if the transport runs in a Worker, when localStorage or BroadcastChannel is unavailable, it still only runs within the current Tab.

package/docs/capabilities.md

@@ -0,0 +1,41 @@
+> [中文](./zh/capabilities.md) | English
+
+# Capabilities Matrix
+
+Status Legend: `✅ Implemented` means the current version has code and test coverage; `Not Implemented` means no guarantee is currently provided; `Planned` means it has entered the scope of future design, but no version has been committed yet.
+
+| Category | Capability | Status | Current Behavior / Boundary |
+|---|---|---|---|
+| Core API | Framework-agnostic subscribe, unsubscribe, publish, and status listening | ✅ Implemented | Provides a unified API via `CrossTabDataBus` |
+| Startup Experience | Auto-start after creation, queued subscriptions before connecting, `ready()` | ✅ Implemented | Apps don't need to wait for a connection before registering Topics |
+| In-Tab Reuse | Reference counting for multiple handlers on the same Topic | ✅ Implemented | The first handler registers; the last handler releases |
+| Cross-Tab Coordination | Worker transport with BroadcastChannel control plane | ✅ Implemented | Each Tab gets a Dedicated Worker by default; in SharedWorker mode same-origin Tabs reuse the Worker, and Topic owners are shared across Tabs |
+| Resource Limits | At most three active Workers | ✅ Implemented | Configurable via `maxActiveWorkers` |
+| Topic Routing | Sticky existing owners with load-balanced first assignment | ✅ Implemented | Existing routes stay unchanged while the owner is alive; only new or orphaned Topics select the least-loaded candidate |
+| Subscription Reliability | Per-Tab independent subscriber records | ✅ Implemented | Avoids multiple Tabs modifying the same subscriber array and overwriting each other |
+| Subscription Reliability | Owner acknowledgment and automatic resend of unconfirmed routes | ✅ Implemented | Automatically retransmits when control messages are lost, so a stored route is not mistaken for a real successful subscription |
+| Page Lifecycle | `pagehide` owner pre-transfer and transport shutdown | ✅ Implemented | Persists the replacement route and worker removal before notifying peers, so a dropped unload-time control message still converges immediately |
+| Page Lifecycle | `pageshow`, BFCache restoration, and business subscription rebuild | ✅ Implemented | Apps don't need to call `subscribe` again |
+| Visibility | Visible preference for new Topic placement | ✅ Implemented | Visibility changes do not migrate established routes; visible Workers are preferred only when a Topic needs a new owner |
+| Exception Recovery | Worker TTL, stale owner migration, and coordination cache cleanup | ✅ Implemented | Reclaims dead Workers, orphaned subscribers, and expired routes with no subscribers |
+| transport | Replays owner Topics after reconnect | ✅ Implemented | Business handlers and subscription intent are not cleared on disconnect |
+| Degradation | Runs locally when localStorage or BroadcastChannel is unavailable | ✅ Implemented | Preserves the current Tab's connection and subscription capabilities |
+| Centrifuge | Built-in Dedicated / Shared Worker transport | ✅ Implemented | Supports subscribe, unsubscribe, publish, connection status, and error reporting; `auto` degrades from SharedWorker → Dedicated Worker → main-thread WebSocket |
+| Security Boundary | localStorage uses opaque keys derived from connection and Topic; BroadcastChannel coordination messages carry plaintext topic names | ✅ Implemented | Does not persist URLs, raw Topic names, credentials, or publication payloads. BroadcastChannel coordination messages are in-memory only and carry plaintext topic names — they are not persisted. |
+| Diagnostics | Aggregates lifecycle events, throughput, and delivery latency | ✅ Implemented | Disabled by default; metrics are emitted every 5 seconds by default, with latency reporting sample count, average, P50, P95, and maximum |
+| Performance | Batched writes of coordination metadata with backoff retry | ✅ Implemented | Heartbeat, route, and subscriber writes are merged and flushed in a microtask; failures use exponential backoff; `pagehide` / `stop()` flush synchronously |
+| Performance | Optional ArrayBuffer Transferable transport | ✅ Implemented | With `transferable: true`, binary publish / receive bypasses structured clone copying; the object message API is unchanged |
+| Message Semantics | exactly-once delivery | Not Implemented | Graceful handoff avoids overlap, but crash recovery and transport/server behavior still do not provide an exactly-once guarantee |
+| Message Semantics | Pluggable publication deduplication | Planned | Plans to support caller-provided message IDs and a deduplication window |
+| Authentication | Async credential refresh bridge inside the Worker | Planned | Current Worker config must be structured-cloneable and cannot pass functions |
+| Load Policy | Adaptive weighting by message rate, byte count, or CPU | Planned | Load is currently computed only from the number of owner Topics |
+| Observability | Metrics for owner acknowledgment latency, migration duration, and retry counts | Planned | Current trace provides status, lifecycle, message throughput, and delivery latency |
+| Runtime Model | SharedWorker / Dedicated Worker transport | ✅ Implemented | `workerMode` supports `dedicated`, `shared`, and `auto`, defaulting to `dedicated` |
+| Runtime Model | Service Worker transport | Not Implemented | Service Worker hosting of real-time connections is not currently provided |
+| Durable Messages | Persisting publications or publish commands across page close | Not Implemented | The SDK does not persist business payloads, nor does it replay publish commands after restoration |
+
+## Acceptance Criteria
+
+- "Implemented" does not mean every browser environment provides cross-Tab capability; when localStorage or BroadcastChannel is missing, it falls back to local degradation by design.
+- Writing an owner route to storage does not mean the subscription has been established. Only when the owner writes `confirmedAt` after processing `SUBSCRIBE` does it represent that the control message has arrived; the server-side final subscription state is still the responsibility of the transport.
+- The SDK guarantees subscription-intent recovery and eventual migration, but does not guarantee exactly-once within the migration window.