cross-tab-worker-databus 0.1.2 → 0.2.0

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":"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"}
+{"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/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.