cross-tab-worker-databus 0.1.2 → 0.2.1

package/dist/core/environment.d.ts

@@ -28,21 +28,33 @@ export interface ClusterChannel {
  * Tests inject a fake environment to control timing, storage, and lifecycle.
  */
 export interface ClusterEnvironment {
-    /** localStorage (or null if unavailable). */
+    /** localStorage (or null if unavailable). Wrapped by BatchingStorageWriter. */
     storage: StorageLike | null;
     /** sessionStorage (or null if unavailable). Used for stable tab IDs. */
     sessionStorage: StorageLike | null;
+    /** Monotonic clock; injected so tests can control time. */
     now: () => number;
+    /** Generates a random ID (UUID when crypto is available, else Math.random). */
     randomId: () => string;
+    /** Creates a BroadcastChannel by name, or null if unsupported. */
     createChannel: (name: string) => ClusterChannel | null;
+    /** Sets an interval; returns a handle for clearInterval. */
     setInterval: (callback: () => void, intervalMs: number) => unknown;
+    /** Clears a handle from setInterval. */
     clearInterval: (handle: unknown) => void;
+    /** Current tab visibility ('visible' or 'hidden'). */
     getVisibilityState: () => TabVisibilityState;
+    /** Register a listener for visibilitychange events. */
     addVisibilityChangeListener: (listener: () => void) => void;
+    /** Remove a previously-added visibilitychange listener. */
     removeVisibilityChangeListener: (listener: () => void) => void;
+    /** Register a listener for pagehide (BFCache entry). */
     addPageHideListener: (listener: () => void) => void;
+    /** Remove a previously-added pagehide listener. */
     removePageHideListener: (listener: () => void) => void;
+    /** Register a listener for pageshow (BFCache exit / restore). */
     addPageShowListener: (listener: () => void) => void;
+    /** Remove a previously-added pageshow listener. */
     removePageShowListener: (listener: () => void) => void;
 }
 /**
@@ -54,7 +66,9 @@ export declare function createBrowserEnvironment(): ClusterEnvironment;
 /**
  * Probe a storage instance with a write-read-delete round-trip.
  * Returns a type guard so the caller can narrow the type after a successful check.
- * Catches quota errors, disabled-storage, or opaque exceptions.
+ * Catches quota errors, disabled-storage (Safari private mode), or opaque
+ * exceptions — any of which means the storage is not usable for coordination
+ * and the Runtime must degrade to local mode.
  */
 export declare function canUseStorage(storage: StorageLike | null, probeKey: string): storage is StorageLike;
 /**

package/dist/core/environment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/core/environment.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAExE,qFAAqF;AACrF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,KAAK,IAAI,IAAI,CAAC;IACd,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAClC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED,sGAAsG;AACtG,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,oBAAoB,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;IACvG,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,oBAAoB,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;IAC1G,WAAW,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACjD,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,6CAA6C;IAC7C,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,wEAAwE;IACxE,cAAc,EAAE,WAAW,GAAG,IAAI,CAAC;IACnC,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,MAAM,CAAC;IACvB,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,cAAc,GAAG,IAAI,CAAC;IACvD,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC;IACnE,aAAa,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;IAC7C,2BAA2B,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IAC5D,8BAA8B,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IAC/D,mBAAmB,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IACpD,sBAAsB,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IACvD,mBAAmB,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IACpD,sBAAsB,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;CACxD;AAuBD;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,kBAAkB,CAoC7D;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,IAAI,WAAW,CASnG;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,kBAAkB,EAC/B,GAAG,SAAoC,GACtC,MAAM,CAqBR"}
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../src/core/environment.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAExE,qFAAqF;AACrF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,KAAK,IAAI,IAAI,CAAC;IACd,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAClC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED,sGAAsG;AACtG,MAAM,WAAW,cAAc;IAC7B,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,oBAAoB,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;IACvG,mBAAmB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,oBAAoB,CAAC,KAAK,IAAI,GAAG,IAAI,CAAC;IAC1G,WAAW,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACjD,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,wEAAwE;IACxE,cAAc,EAAE,WAAW,GAAG,IAAI,CAAC;IACnC,2DAA2D;IAC3D,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,MAAM,CAAC;IACvB,kEAAkE;IAClE,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,cAAc,GAAG,IAAI,CAAC;IACvD,4DAA4D;IAC5D,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC;IACnE,wCAAwC;IACxC,aAAa,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC,sDAAsD;IACtD,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;IAC7C,uDAAuD;IACvD,2BAA2B,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IAC5D,2DAA2D;IAC3D,8BAA8B,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IAC/D,wDAAwD;IACxD,mBAAmB,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IACpD,mDAAmD;IACnD,sBAAsB,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IACvD,iEAAiE;IACjE,mBAAmB,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;IACpD,mDAAmD;IACnD,sBAAsB,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;CACxD;AA2BD;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,kBAAkB,CAoC7D;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,IAAI,WAAW,CASnG;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,kBAAkB,EAC/B,GAAG,SAAoC,GACtC,MAAM,CAqBR"}

package/dist/core/hash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/core/hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAyBrD"}
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/core/hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CA+BrD"}

package/dist/core/routing.d.ts

@@ -6,13 +6,16 @@
  * them straightforward to test and reason about.
  */
 import type { WorkerRecord, WorkerRoute } from './types';
-/** Default cap on the number of Workers that can own topics concurrently. */
+/** Default cap on the number of Workers that can own topics concurrently.
+ * Limits fan-out breadth: only N workers are eligible to be new-route
+ * owners, so a cluster of 20 tabs still concentrates ownership on a few. */
 export declare const DEFAULT_MAX_ACTIVE_WORKERS = 3;
 /**
  * Pick the Worker with the fewest owned topics, optionally preferring a
  * specific sticky owner when it is still in the candidate set.
  * Uses a single reduce pass instead of a full sort — O(n) — and breaks
- * load ties by workerId for deterministic routing across tabs.
+ * load ties by workerId for deterministic routing across tabs (the
+ * comparison is code-unit based, not locale-based, for cross-host stability).
  */
 export declare function selectLeastLoadedWorker(workers: readonly WorkerRecord[], preferredWorkerId?: string): WorkerRecord | undefined;
 /**

package/dist/core/routing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/core/routing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEzD,6EAA6E;AAC7E,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,iBAAiB,CAAC,EAAE,MAAM,GACzB,YAAY,GAAG,SAAS,CAS1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,gBAAgB,SAA6B,GAC5C,YAAY,EAAE,CAWhB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,eAAe,EAAE,MAAM,GACtB,YAAY,GAAG,IAAI,CAYrB;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,EAAE,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,OAAO,CAEnG"}
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/core/routing.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEzD;;4EAE4E;AAC5E,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAE5C;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,iBAAiB,CAAC,EAAE,MAAM,GACzB,YAAY,GAAG,SAAS,CAY1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,gBAAgB,SAA6B,GAC5C,YAAY,EAAE,CAYhB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,eAAe,EAAE,MAAM,GACtB,YAAY,GAAG,IAAI,CAYrB;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,EAAE,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,OAAO,CAEnG"}

package/dist/core/storage-batch.d.ts

@@ -10,6 +10,15 @@ import type { StorageLike } from './environment';
  * Coalesces synchronous storage writes and applies them in one pass, with
  * exponential backoff when the underlying storage rejects a write.
  */
+/**
+ * Coalesces synchronous storage writes and applies them in one pass, with
+ * exponential backoff when the underlying storage rejects a write.
+ *
+ * Wraps a {@link StorageLike} so callers (WorkerClusterRuntime) see a normal
+ * storage interface; reads transparently see pending writes before they flush.
+ * The coalescing window is one microtask, so a burst of heartbeat + route +
+ * subscriber writes in the same task becomes a single localStorage flush.
+ */
 export declare class BatchingStorageWriter implements StorageLike {
     private readonly storage;
     /** Coalesced write set. A `null` value represents a pending delete. */
@@ -20,6 +29,9 @@ export declare class BatchingStorageWriter implements StorageLike {
     private retryHandle;
     private retryDelayMs;
     constructor(storage: StorageLike);
+    /** Number of writes queued in memory but not yet flushed to storage.
+     * Used by tests to assert the coalescing window and by flush() to detect
+     * the all-drained state. */
     get pendingSize(): number;
     get length(): number;
     clear(): void;

package/dist/core/storage-batch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage-batch.d.ts","sourceRoot":"","sources":["../../src/core/storage-batch.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AASjD;;;GAGG;AACH,qBAAa,qBAAsB,YAAW,WAAW;IAS3C,OAAO,CAAC,QAAQ,CAAC,OAAO;IARpC,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IACxD,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,WAAW,CAA8C;IACjE,OAAO,CAAC,YAAY,CAA0B;gBAEjB,OAAO,EAAE,WAAW;IAEjD,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,KAAK,IAAI,IAAI;IAab,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAKnC,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIjC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAK7B,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAKzC,KAAK,IAAI,IAAI;IAsCb,yEAAyE;IACzE,OAAO,CAAC,IAAI;IAeZ,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,WAAW;CAMpB"}
+{"version":3,"file":"storage-batch.d.ts","sourceRoot":"","sources":["../../src/core/storage-batch.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAYjD;;;GAGG;AACH;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,YAAW,WAAW;IAS3C,OAAO,CAAC,QAAQ,CAAC,OAAO;IARpC,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IACxD,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,WAAW,CAA8C;IACjE,OAAO,CAAC,YAAY,CAA0B;gBAEjB,OAAO,EAAE,WAAW;IAEjD;;gCAE4B;IAC5B,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,KAAK,IAAI,IAAI;IAab,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAKnC,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIjC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAK7B,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAKzC,KAAK,IAAI,IAAI;IA6Cb,yEAAyE;IACzE,OAAO,CAAC,IAAI;IAiBZ,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,WAAW;CAMpB"}

package/dist/core/trace.d.ts

@@ -8,6 +8,10 @@
  */
 import type { WorkerStatus } from './types';
 /** Trace reporting mode: record only events, only metrics, or both. */
+/** Selects which trace categories the reporter emits.
+ * - `events` — lifecycle/status/subscription/coordination/error events only.
+ * - `metrics` — periodic `message_metrics` snapshots only.
+ * - `all` — both event streams and metrics snapshots. */
 export type DataBusTraceMode = 'events' | 'metrics' | 'all';
 /** Emitted when the DataBus starts, stops, suspends, or resumes. */
 export interface DataBusLifecycleTraceEvent {
@@ -65,10 +69,16 @@ export interface DataBusMetricsTraceEvent {
 export type DataBusTraceEvent = DataBusLifecycleTraceEvent | DataBusStatusTraceEvent | DataBusSubscriptionTraceEvent | DataBusCoordinationTraceEvent | DataBusErrorTraceEvent | DataBusMetricsTraceEvent;
 /** Distributive-conditional type: given a trace event union, derive the same shape minus `timestamp`. */
 type DataBusTraceEventInput = DataBusTraceEvent extends infer TEvent ? TEvent extends DataBusTraceEvent ? Omit<TEvent, 'timestamp'> : never : never;
+/** Configuration for {@link DataBusTraceReporter}. `sink` receives every
+ * emitted event (filtered by `mode`); all other fields are optional. */
 export interface DataBusTraceOptions {
+    /** When `false`, the reporter is inert (no events emitted). Default `true`. */
     enabled?: boolean;
+    /** Which event categories to emit. Default `all`. */
     mode?: DataBusTraceMode;
+    /** Aggregation window for `message_metrics` events. Default 5 s. */
     metricsIntervalMs?: number;
+    /** Callback invoked for each emitted trace event. */
     sink: (event: DataBusTraceEvent) => void;
 }
 /**
@@ -94,7 +104,8 @@ export declare class DataBusTraceReporter {
     private readonly latencyBuckets;
     private latencySumMs;
     constructor(options?: DataBusTraceOptions, now?: () => number);
-    /** Start the periodic metrics flush interval. No-op when mode is 'events'. */
+    /** Start the periodic metrics flush interval. No-op when mode is 'events'
+     * (no metrics to emit), when disabled, or when already running. */
     start(): void;
     /** Pause the metrics interval and reset accumulated counters. */
     pause(): void;
@@ -116,6 +127,10 @@ export declare class DataBusTraceReporter {
      * as dispatched but do not produce a latency sample.
      */
     recordDispatched(topic: string): void;
+    /** True when metrics recording is active: enabled and mode includes metrics.
+     * Extracted so the four record / flush methods share one guard expression
+     * instead of repeating `!this.enabled || this.mode === 'events'` at each. */
+    private get metricsActive();
     /** Emit the accumulated metrics snapshot if the interval is active. */
     flush(): void;
     private flushNow;

package/dist/core/trace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/core/trace.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/core/trace.ts"],"names":[],"mappings":"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"}

package/dist/core/types.d.ts

@@ -5,31 +5,40 @@
  * transport interfaces, trace events, and all supporting types used across
  * the cluster coordination, DataBus public API, and diagnostics layers.
  */
-/** Convenience alias for values that may be synchronously returned or Promise. */
+/** Convenience alias for values that may be synchronously returned or as a
+ * Promise. Used by the DataBusTransport contract so implementations can be
+ * either sync or async without changing the call signature. */
 export type MaybePromise<T> = T | Promise<T>;
-/** Whether this Worker can act as a Topic owner. */
+/** Whether this Worker can act as a Topic owner. `active` workers are eligible
+ * for new topic assignments; `standby` workers hold existing assignments but
+ * are not selected for new ones (e.g. a hidden tab that already owns topics). */
 export type WorkerRole = 'active' | 'standby';
-/** Connection-level status of the transport. */
+/** Connection-level status of the transport. `error` triggers auto-recovery
+ * (subject to a cooldown); `disconnected` is a clean or suspend state. */
 export type WorkerStatus = 'connecting' | 'connected' | 'disconnected' | 'error';
-/** Control-plane actions routed between Workers via BroadcastChannel. */
+/** Control-plane actions routed between Workers via BroadcastChannel.
+ * These are the three operations a subscriber asks the owning worker to perform. */
 export type WorkerControlAction = 'SUBSCRIBE' | 'UNSUBSCRIBE' | 'PUBLISH';
-/** Whether the tab is currently visible to the user. */
+/** Whether the tab is currently visible to the user. Only influences placement
+ * of NEW topic routes; existing routes are sticky and never migrated on hide. */
 export type TabVisibilityState = 'visible' | 'hidden';
 /**
  * A Worker's self-published registration record, written to localStorage
  * so sibling tabs can discover and route to it.
  */
 export interface WorkerRecord {
+    /** Stable identity of this runtime instance. Random-suffixed; survives refresh. */
     workerId: string;
+    /** Identity of the browser tab hosting this worker. Survives refresh. */
     tabId: string;
-    /** Number of topics this Worker owns. Not a CPU load. */
+    /** Number of topics this Worker owns. NOT a CPU load metric. */
     load: number;
     role: WorkerRole;
     status: WorkerStatus;
     visibilityState: TabVisibilityState;
-    /** Last heartbeat write timestamp (ms). */
+    /** Last heartbeat write timestamp (ms). Workers past `workerTtlMs` are pruned. */
     heartbeatAt: number;
-    /** First registration timestamp (ms). Used for deterministic ordering. */
+    /** First registration timestamp (ms). Used for deterministic ordering in owner selection. */
     registeredAt: number;
 }
 /**
@@ -38,45 +47,71 @@ export interface WorkerRecord {
  * the SUBSCRIBE control message.
  */
 export interface WorkerRoute {
+    /** Opaque 128-bit hash of the topic name (never the plaintext). */
     topicKey: string;
+    /** The workerId that owns this topic's transport subscription. */
     workerId: string;
+    /** The tabId of the owning worker. */
     tabId: string;
+    /** Timestamp (ms) of the last route write. Used for orphan-TTL cleanup. */
     updatedAt: number;
-    /** Monotonic route generation; handoff acknowledgements must match it. */
+    /** Monotonic route generation; handoff acknowledgements must match it to
+     * prevent a stale ACK from authorizing a superseded owner. */
     generation: number;
-    /** Previous owner must release its transport subscription before takeover. */
+    /** Previous owner that must release its transport subscription before the
+     * new owner takes over (graceful handoff only). */
     handoffFromWorkerId?: string;
-    /** Set by the owner when it has processed the SUBSCRIBE. Absent → subscriber will retry. */
+    /** Set by the owner when it has processed the SUBSCRIBE. Absent → the
+     * subscriber will retry the control message to recover from channel loss. */
     confirmedAt?: number;
 }
-/** Per-tab-per-topic marker stored in localStorage so the cluster knows which tabs still need a topic. */
+/** Per-tab-per-topic marker stored in localStorage so the cluster knows which
+ * tabs still need a topic. Each tab writes its own record independently,
+ * avoiding read-modify-write contention on a shared array. */
 export interface TopicSubscriberRecord {
+    /** The tab that holds this subscription. */
     tabId: string;
+    /** Timestamp (ms) of the last subscriber write. */
     updatedAt: number;
 }
 /**
- * Messages exchanged over the BroadcastChannel. Three types:
- * - CONTROL: direct peer-to-peer actions (SUBSCRIBE / UNSUBSCRIBE / PUBLISH)
+ * Messages exchanged over the BroadcastChannel. Four types:
+ * - CONTROL: point-to-point action (SUBSCRIBE / UNSUBSCRIBE / PUBLISH)
  * - EVENT: fan-out publications from the owning Worker to all tabs
- * - REGISTRY: heartbeat signal that triggers reconciliation on other tabs
+ * - REGISTRY: nudge every tab to reconcile immediately
+ * - ROUTE_RELEASED: ACK a graceful handoff (only matching generation acts)
  */
-export type WorkerClusterMessage<TEvent = unknown> = {
+export type WorkerClusterMessage<TEvent = unknown> = 
+/** A subscriber asks the target worker to perform an action on a topic.
+ * Carries the plaintext topic (for transport calls) and the opaque key
+ * (for storage/route bookkeeping). */
+{
     type: 'CONTROL';
     sourceWorkerId: string;
     targetWorkerId: string;
     action: WorkerControlAction;
     topic: string;
     topicKey: string;
+    /** Present only for PUBLISH actions; the publication payload. */
     data?: unknown;
-} | {
+}
+/** The owning worker fans out a publication to every tab. `eventType`
+ * distinguishes databus publications from future event types. */
+ | {
     type: 'EVENT';
     sourceWorkerId: string;
     eventType: string;
     payload: TEvent;
-} | {
+}
+/** Nudge peers to reconcile immediately after a registry/route/subscriber
+ * write, instead of waiting for the next heartbeat (3 s default). */
+ | {
     type: 'REGISTRY';
     sourceWorkerId: string;
-} | {
+}
+/** The old owner acknowledges it released the transport subscription.
+ * Only the new owner whose route `generation` matches may act on this. */
+ | {
     type: 'ROUTE_RELEASED';
     sourceWorkerId: string;
     targetWorkerId: string;
@@ -84,29 +119,49 @@ export type WorkerClusterMessage<TEvent = unknown> = {
     topicKey: string;
     generation: number;
 };
+/** A publication delivered to a topic handler: the topic name and the
+ * structured-clone-safe payload. */
 export interface DataBusMessage<TData = unknown> {
     topic: string;
     data: TData;
 }
-/** Callbacks the transport calls to notify the DataBus of events. */
+/** Callbacks the transport calls to notify the DataBus of events.
+ * The DataBus wires these once during `start()`; the transport must hold
+ * the reference and call them for the lifetime of the connection. */
 export interface DataBusTransportHandlers<TData = unknown> {
+    /** A publication arrived from the server for a topic this worker owns. */
     onMessage: (message: DataBusMessage<TData>) => void;
+    /** The connection status changed. `error` triggers auto-recovery. */
     onStatus: (status: WorkerStatus) => void;
+    /** A non-fatal transport error occurred. Does not imply disconnection. */
     onError: (error: unknown) => void;
 }
 /**
  * Transport abstraction that the DataBus delegates to for real I/O.
  * Implementations may wrap a WebSocket library, a Worker, or a mock.
- * subscribe / unsubscribe MUST be idempotent.
+ *
+ * Contract requirements:
+ * - `subscribe` / `unsubscribe` MUST be idempotent (called on reconnect).
+ * - `start` is called once per lifecycle; `stop` is idempotent.
+ * - `publish` may be called before `start` settles (queued by the DataBus).
  */
 export interface DataBusTransport<TConfig = unknown, TData = unknown> {
+    /** Open the connection with `config`. Report status changes via `handlers.onStatus`.
+     * May return a Promise that resolves on connect or rejects on failure. */
     start(config: TConfig, handlers: DataBusTransportHandlers<TData>): MaybePromise<void>;
+    /** Subscribe to a topic. Idempotent: re-subscribing an active topic is a no-op. */
     subscribe(topic: string): MaybePromise<void>;
+    /** Unsubscribe from a topic. Idempotent: unsubscribing a non-subscribed topic is a no-op. */
     unsubscribe(topic: string): MaybePromise<void>;
+    /** Publish `data` to `topic` via the server. */
     publish(topic: string, data: unknown): MaybePromise<void>;
+    /** Close the connection and release all resources. Safe to call multiple times. */
     stop(): MaybePromise<void>;
 }
+/** Callback invoked for each publication delivered to a subscribed topic. */
 export type DataBusMessageHandler<TData = unknown> = (message: DataBusMessage<TData>) => void;
+/** Callback invoked on every transport status change. */
 export type DataBusStatusHandler = (status: WorkerStatus) => void;
+/** Callback invoked when the transport or an operation reports an error. */
 export type DataBusErrorHandler = (error: unknown) => void;
 //# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,kFAAkF;AAClF,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAE7C,oDAAoD;AACpD,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC;AAC9C,gDAAgD;AAChD,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,WAAW,GAAG,cAAc,GAAG,OAAO,CAAC;AACjF,yEAAyE;AACzE,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,aAAa,GAAG,SAAS,CAAC;AAC1E,wDAAwD;AACxD,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEtD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,YAAY,CAAC;IACrB,eAAe,EAAE,kBAAkB,CAAC;IACpC,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,4FAA4F;IAC5F,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,0GAA0G;AAC1G,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,CAAC,MAAM,GAAG,OAAO,IAC7C;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,GACD;IACE,IAAI,EAAE,OAAO,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB,GACD;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CACxB,GACD;IACE,IAAI,EAAE,gBAAgB,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEN,MAAM,WAAW,cAAc,CAAC,KAAK,GAAG,OAAO;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,KAAK,CAAC;CACb;AAED,qEAAqE;AACrE,MAAM,WAAW,wBAAwB,CAAC,KAAK,GAAG,OAAO;IACvD,SAAS,EAAE,CAAC,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;IACpD,QAAQ,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IACzC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB,CAAC,OAAO,GAAG,OAAO,EAAE,KAAK,GAAG,OAAO;IAClE,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,wBAAwB,CAAC,KAAK,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACtF,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC7C,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC/C,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC1D,IAAI,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED,MAAM,MAAM,qBAAqB,CAAC,KAAK,GAAG,OAAO,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;AAC9F,MAAM,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;AAClE,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -10,7 +10,7 @@ import {
   selectLeastLoadedWorker,
   selectRebalanceTarget,
   selectWorkerBackend
-} from "./chunk-53INHVYO.js";
+} from "./chunk-LBXREMZA.js";
 export {
   CrossTabDataBus,
   DEFAULT_MAX_ACTIVE_WORKERS,

package/dist/worker-mode.d.ts

@@ -5,13 +5,21 @@
  * that resolves the preference against browser capability to pick the actual
  * backend (dedicated, shared, or local fallback).
  */
-/** Preferred Worker mode: 'dedicated' → try Dedicated Worker first, 'shared'/'auto' → try SharedWorker first. */
+/** Preferred Worker mode.
+ * - `dedicated` → try Dedicated Worker first (one WebSocket per tab).
+ * - `shared` → try SharedWorker first (one process, per-port connections).
+ * - `auto` → same as `shared` (alias for forward compatibility). */
 export type WorkerMode = 'dedicated' | 'shared' | 'auto';
-/** Resolved backend that was actually created. */
+/** Resolved backend that was actually created. `local` means the session
+ * runs on the main thread (fallback when no Worker API is available). */
 export type WorkerBackend = 'dedicated' | 'shared' | 'local';
-/** Override Worker availability for testing or environments where feature detection is unreliable. */
+/** Override Worker availability for testing or environments where feature
+ * detection is unreliable (e.g. sandboxed iframes). When a field is omitted,
+ * the global `typeof Worker` / `typeof SharedWorker` check is used. */
 export interface WorkerAvailability {
+    /** When provided, overrides `typeof Worker !== 'undefined'`. */
     worker?: boolean;
+    /** When provided, overrides `typeof SharedWorker !== 'undefined'`. */
     sharedWorker?: boolean;
 }
 /**
@@ -20,6 +28,7 @@ export interface WorkerAvailability {
  *
  * - `dedicated` prefers Dedicated Worker, then SharedWorker, then local mode.
  * - `shared` and `auto` prefer SharedWorker, then Dedicated Worker, then local.
+ * Returns `'local'` when neither Worker API is available (main-thread fallback).
  */
 export declare function selectWorkerBackend(mode: WorkerMode, availability?: WorkerAvailability): WorkerBackend;
 //# sourceMappingURL=worker-mode.d.ts.map

package/dist/worker-mode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker-mode.d.ts","sourceRoot":"","sources":["../src/worker-mode.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,iHAAiH;AACjH,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEzD,kDAAkD;AAClD,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE7D,sGAAsG;AACtG,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,UAAU,EAChB,YAAY,GAAE,kBAAuB,GACpC,aAAa,CAOf"}
+{"version":3,"file":"worker-mode.d.ts","sourceRoot":"","sources":["../src/worker-mode.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;oEAGoE;AACpE,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEzD;yEACyE;AACzE,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE7D;;uEAEuE;AACvE,MAAM,WAAW,kBAAkB;IACjC,gEAAgE;IAChE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sEAAsE;IACtE,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,UAAU,EAChB,YAAY,GAAE,kBAAuB,GACpC,aAAa,CAOf"}

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

@@ -32,23 +32,38 @@ export declare class PortReaper {
     private readonly setTimer;
     private readonly clearTimer;
     /** Track a newly connected port and its session. The default timeout applies
-     * until the port sends an INIT with its own heartbeat config. */
+     * until the port sends an INIT with its own heartbeat config, at which point
+     * setTimeout() overrides it. register() always calls schedule() so the
+     * reaper interval starts as soon as the first port connects. */
     register(port: MessagePort, target: ReapTarget): void;
-    /** Record activity on a port (any incoming message). No-op for untracked ports. */
+    /** Record activity on a port (any incoming message). No-op for untracked
+     * ports — a late PING from a port that was already removed/STOP'd must not
+     * resurrect it in the reaper's tracking maps. */
     touch(port: MessagePort): void;
     /** Override a port's session timeout from its INIT heartbeat config.
      * A non-finite or non-positive value falls back to the default so a bad
-     * payload cannot degenerate the reaper into a busy loop or silence it. */
+     * payload cannot degenerate the reaper into a busy loop or silence it.
+     * No-op for untracked ports (e.g. setTimeout arrives after remove/STOP). */
     setTimeout(port: MessagePort, heartbeatIntervalMs: number): void;
     /** Remove a port (STOP message). The caller is responsible for closing the
-     * port and stopping the session. */
+     * port and stopping the session. No-op for untracked ports so a duplicate
+     * STOP or a STOP-after-reap cannot corrupt the reaper's bookkeeping. */
     remove(port: MessagePort): void;
     /** Clear all state and stop the reaper. Closes and stops every tracked
      * session so the SharedWorker does not leak WebSockets on shutdown. */
     dispose(): void;
-    /** Recompute the reaper cadence, or stop it entirely when no ports remain. */
+    /** Recompute the reaper cadence, or stop it entirely when no ports remain.
+     * Idempotent: if the interval is already running at the correct cadence,
+     * no new timer is created. This guards against register/remove/setTimeout
+     * each spawning redundant timers when the cadence hasn't changed. */
     private schedule;
-    /** Close sessions whose port has been silent longer than its timeout. */
+    /** Smallest heartbeat interval among active ports, derived from each port's
+     * configured session timeout. Exposed as a method so the cadence logic can
+     * be unit-tested in isolation from the timer plumbing. */
+    private computeMinHeartbeat;
+    /** Close sessions whose port has been silent longer than its timeout.
+     * Iterates a snapshot so closing a target (which mutates `targets`) during
+     * the loop cannot skip a subsequent entry or visit one twice. */
     private reap;
 }
 export {};

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

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

package/docs/README.md

@@ -6,6 +6,7 @@
 |---|---|
 | [Getting Started](./getting-started.md) | Installation, creating instances, subscribing, publishing, and destroying |
 | [Configuration](./configuration.md) | Core configuration, Centrifuge configuration, defaults, and constraints |
+| [Transports](./transports.md) | The `DataBusTransport` contract, worker protocol, and third-party backend guide |
 | [API Reference](./api.md) | Public API, types, methods, return values, and behavior |
 | [Architecture](./architecture.md) | Worker cluster, routing, storage, migration, and degradation design |
 | [Capabilities Matrix](./capabilities.md) | Implemented, not implemented, and planned capabilities matrix |

package/docs/architecture.md

@@ -10,23 +10,33 @@ graph TB
     subgraph TabA["Tab A"]
       AppA["Business Module"] --> BusA["CrossTabDataBus"]
       BusA --> RuntimeA["WorkerClusterRuntime"]
-      BusA --> WorkerA["Dedicated / Shared Worker A"]
+      BusA --> TransportA["CentrifugeWorkerTransport"]
+      TransportA --> WorkerA["Dedicated / Shared Worker A"]
     end
     subgraph TabB["Tab B"]
       AppB["Business Module"] --> BusB["CrossTabDataBus"]
       BusB --> RuntimeB["WorkerClusterRuntime"]
-      BusB --> WorkerB["Dedicated / Shared Worker B"]
+      BusB --> TransportB["CentrifugeWorkerTransport"]
+      TransportB --> 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
+  RuntimeA --> BatchA["BatchingStorageWriter"]
+  RuntimeB --> BatchB["BatchingStorageWriter"]
+  BatchA <--> Registry["localStorage Worker Registration"]
+  BatchB <--> Registry
+  BatchA <--> Routes["localStorage Topic Routes"]
+  BatchB <--> Routes
+  WorkerA --> SessionA["CentrifugeSession"]
+  WorkerB --> SessionB["CentrifugeSession"]
+  SessionA --> Server["Centrifuge / realtime server"]
+  SessionB --> Server
+  subgraph SW["SharedWorker process (when backend = shared)"]
+    Reaper["PortReaper"] -.-> SessionA
+    Reaper -.-> SessionB
+  end
 ```
 
 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.

package/docs/getting-started.md

@@ -12,8 +12,11 @@ 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.worker`: the Dedicated Worker build artifact, loaded by default by the built-in factory; typically no need to reference it directly
 - `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
 
+The `cross-tab-worker-databus/centrifuge` entry point relies on the optional peer dependency `centrifuge` (^5.5.3). Install it alongside this package when using the built-in Centrifuge transport: `pnpm add centrifuge`.
+
 ## 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.