cross-tab-worker-databus 0.20.70 → 0.20.85

package/dist/utils/constants.d.ts

@@ -0,0 +1,170 @@
+/**
+ * 公共字符串常量 —— 生命周期状态、角色、控制动作、协议消息类型、枚举与
+ * 命名空间前缀。
+ *
+ * 所有运行时使用的字符串字面量集中在此一份值，类型定义（src/core/types.ts
+ * 等）通过 `(typeof X)[keyof typeof X]` 从这些常量派生，比较/switch 处引用
+ * 同一对象成员。这样既能消除散落在各文件里的重复字符串（避免大小写不统一
+ * 或笔误），又保证类型与值永不错位。
+ *
+ * ## 使用约定
+ *
+ * - **新增或修改字符串字面量时，先到这里查找/增补，不要在业务文件里直接写
+ *   魔法字符串。** 扫描残留字面量：`rg "'(['a-z]+)'" src/`。
+ * - **只用于类型位置的常量**（如 `PERSISTENCE_OPERATION`）在调用方用
+ *   `import type`；**在运行时比较/构造中使用的**（如 `WORKER_STATUS.ERROR`、
+ *   `TRACE_EVENT_TYPE.LIFECYCLE`）必须用值导入，否则会报 "cannot be used as
+ *   a value because it was imported using 'import type'"。
+ * - **值派生类型**：`export type WorkerStatus = (typeof WORKER_STATUS)[keyof
+ *   typeof WORKER_STATUS]`。这样新增枚举分支时类型自动收窄，编译器会指出
+ *   每个遗漏的 switch 分支。
+ * - 分组的顺序（状态 / 角色 / 后端 / 消息类型 / 枚举 / 前缀）保持稳定，方便
+ *   维护者一眼定位。
+ */
+export declare const WORKER_STATUS: {
+    readonly CONNECTING: "connecting";
+    readonly CONNECTED: "connected";
+    readonly DISCONNECTED: "disconnected";
+    readonly ERROR: "error";
+};
+export declare const WORKER_ROLE: {
+    readonly ACTIVE: "active";
+    readonly STANDBY: "standby";
+};
+export declare const TAB_VISIBILITY: {
+    readonly VISIBLE: "visible";
+    readonly HIDDEN: "hidden";
+};
+export declare const WORKER_MODE: {
+    readonly DEDICATED: "dedicated";
+    readonly SHARED: "shared";
+    readonly AUTO: "auto";
+};
+export declare const WORKER_BACKEND: {
+    readonly DEDICATED: "dedicated";
+    readonly SHARED: "shared";
+    readonly LOCAL: "local";
+};
+export declare const CHANNEL_FALLBACK: {
+    readonly NONE: "none";
+    readonly STORAGE_EVENT: "storage-event";
+};
+export declare const EVENT_TYPE: {
+    readonly MESSAGE: "message";
+    readonly MESSAGEERROR: "messageerror";
+    readonly ERROR: "error";
+};
+export declare const CONTROL_ACTION: {
+    readonly SUBSCRIBE: "SUBSCRIBE";
+    readonly UNSUBSCRIBE: "UNSUBSCRIBE";
+    readonly PUBLISH: "PUBLISH";
+};
+export declare const CLUSTER_MESSAGE_TYPE: {
+    readonly CONTROL: "CONTROL";
+    readonly EVENT: "EVENT";
+    readonly REGISTRY: "REGISTRY";
+    readonly ROUTE_RELEASED: "ROUTE_RELEASED";
+};
+export declare const DEFAULT_STORAGE_PREFIX = "cross-tab-worker-databus";
+export declare const STORAGE_CHANNEL_PREFIX = "cross-tab-worker-databus:channel:";
+export declare const TAB_ID_STORAGE_KEY = "cross-tab-worker-databus:tab-id";
+export declare const PUBLICATION_EVENT = "DATABUS_PUBLICATION";
+export declare const PUBLICATION_ENVELOPE_OP = "publication";
+export declare const TRACE_EVENT_TYPE: {
+    readonly LIFECYCLE: "lifecycle";
+    readonly STATUS: "status";
+    readonly SUBSCRIPTION: "subscription";
+    readonly COORDINATION: "coordination";
+    readonly ERROR: "error";
+    readonly RELIABILITY: "reliability";
+    readonly MESSAGE_METRICS: "message_metrics";
+};
+export declare const TRACE_LIFECYCLE_ACTION: {
+    readonly START: "start";
+    readonly STOP: "stop";
+    readonly SUSPEND: "suspend";
+    readonly RESUME: "resume";
+};
+export declare const INVOKE_LABEL: {
+    readonly DISPATCH: "dispatch";
+    readonly STATUS: "status";
+    readonly ERROR_HANDLER: "error handler";
+};
+export declare const TRACE_MODE: {
+    readonly EVENTS: "events";
+    readonly METRICS: "metrics";
+    readonly ALL: "all";
+};
+export declare const TRACE_ERROR_SOURCE: {
+    readonly TRANSPORT: "transport";
+    readonly OPERATION: "operation";
+};
+export declare const RELIABILITY_OPERATION: {
+    readonly TRANSPORT_RECOVERY: "transport_recovery";
+    readonly ROUTE_ACK: "route_ack";
+    readonly ROUTE_MIGRATION: "route_migration";
+    readonly ROUTE_MIGRATION_RECOVERY: "route_migration_recovery";
+    readonly PERSISTENCE_CLEANUP: "persistence_cleanup";
+    readonly PERSISTENCE_RETRY: "persistence_retry";
+    readonly DEDUP_SUPPRESSED: "dedup_suppressed";
+};
+export declare const RECOVERY_OUTCOME: {
+    readonly SCHEDULED: "scheduled";
+    readonly SUCCEEDED: "succeeded";
+    readonly FAILED: "failed";
+    readonly EXHAUSTED: "exhausted";
+};
+export declare const SUBSCRIPTION_ACTION: {
+    readonly SUBSCRIBE: "subscribe";
+    readonly UNSUBSCRIBE: "unsubscribe";
+};
+export declare const PRUNE_STRATEGY: {
+    readonly COUNT: "count";
+    readonly AGE: "age";
+    readonly BOTH: "both";
+};
+export declare const PERSISTENCE_OPERATION: {
+    readonly LOAD: "load";
+    readonly APPEND: "append";
+    readonly CLEAR: "clear";
+    readonly CLEAR_TOPIC: "clearTopic";
+    readonly CLEAR_BEFORE: "clearBefore";
+};
+export declare const FAILURE_SOURCE: {
+    readonly TRANSPORT: "transport";
+    readonly PERSISTENCE: "persistence";
+    readonly DISPATCH: "dispatch";
+};
+export declare const HEALTH_STATE: {
+    readonly STOPPED: "stopped";
+    readonly STARTING: "starting";
+    readonly HEALTHY: "healthy";
+    readonly RECOVERING: "recovering";
+    readonly SUSPENDED: "suspended";
+    readonly DEGRADED: "degraded";
+};
+export declare const WS_OP: {
+    readonly SUBSCRIBE: "subscribe";
+    readonly UNSUBSCRIBE: "unsubscribe";
+    readonly PUBLISH: "publish";
+    readonly PUBLISH_BATCH: "publishBatch";
+};
+export declare const CENTRIFUGE_INPUT_TYPE: {
+    readonly INIT: "INIT";
+    readonly SUBSCRIBE: "SUBSCRIBE";
+    readonly UNSUBSCRIBE: "UNSUBSCRIBE";
+    readonly PUBLISH: "PUBLISH";
+    readonly PUBLISH_BIN: "PUBLISH_BIN";
+    readonly PING: "PING";
+    readonly STOP: "STOP";
+    readonly TOKEN_RESPONSE: "TOKEN_RESPONSE";
+    readonly TOKEN_ERROR: "TOKEN_ERROR";
+};
+export declare const CENTRIFUGE_OUTPUT_TYPE: {
+    readonly STATUS: "STATUS";
+    readonly MESSAGE: "MESSAGE";
+    readonly MESSAGE_BIN: "MESSAGE_BIN";
+    readonly ERROR: "ERROR";
+    readonly TOKEN_REQUEST: "TOKEN_REQUEST";
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/utils/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/utils/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAEX,eAAO,MAAM,WAAW;;;CAGd,CAAC;AAEX,eAAO,MAAM,cAAc;;;CAGjB,CAAC;AAGX,eAAO,MAAM,WAAW;;;;CAId,CAAC;AAEX,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AAGX,eAAO,MAAM,gBAAgB;;;CAGnB,CAAC;AAKX,eAAO,MAAM,UAAU;;;;CAIb,CAAC;AAGX,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AAGX,eAAO,MAAM,oBAAoB;;;;;CAKvB,CAAC;AAGX,eAAO,MAAM,sBAAsB,6BAA6B,CAAC;AACjE,eAAO,MAAM,sBAAsB,sCAAuC,CAAC;AAC3E,eAAO,MAAM,kBAAkB,oCAAqC,CAAC;AACrE,eAAO,MAAM,iBAAiB,wBAAwB,CAAC;AAGvD,eAAO,MAAM,uBAAuB,gBAAgB,CAAC;AAGrD,eAAO,MAAM,gBAAgB;;;;;;;;CAQnB,CAAC;AAGX,eAAO,MAAM,sBAAsB;;;;;CAKzB,CAAC;AAGX,eAAO,MAAM,YAAY;;;;CAIf,CAAC;AAGX,eAAO,MAAM,UAAU;;;;CAIb,CAAC;AAGX,eAAO,MAAM,kBAAkB;;;CAGrB,CAAC;AAGX,eAAO,MAAM,qBAAqB;;;;;;;;CAWxB,CAAC;AAGX,eAAO,MAAM,gBAAgB;;;;;CAKnB,CAAC;AAGX,eAAO,MAAM,mBAAmB;;;CAGtB,CAAC;AAGX,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AAGX,eAAO,MAAM,qBAAqB;;;;;;CAMxB,CAAC;AAGX,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AAGX,eAAO,MAAM,YAAY;;;;;;;CAOf,CAAC;AAGX,eAAO,MAAM,KAAK;;;;;CAKR,CAAC;AAGX,eAAO,MAAM,qBAAqB;;;;;;;;;;CAUxB,CAAC;AAGX,eAAO,MAAM,sBAAsB;;;;;;CAMzB,CAAC"}

package/dist/utils/error-utils.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 错误序列化工具 —— 在 Worker 边界往返传输 Error。
+ *
+ * Error 实例无法通过 postMessage 结构化克隆，所以 CentrifugeSession 侧用
+ * serializeError 把它压成 plain object，主线程侧用 deserializeWorkerError
+ * 还原成真 Error（带 name/stack）。此前两个函数分别内联在 centrifuge-session.ts
+ * 与 centrifuge.ts，此处统一定义并从两处引用。
+ */
+/** Error object serialized for cross-thread transfer. */
+export interface SerializedWorkerError {
+    /** The Error's `name` (e.g. 'TypeError', 'CentrifugeError'). */
+    name: string;
+    /** The Error's `message`. */
+    message: string;
+    /** The Error's `stack` if available (for debugging). */
+    stack?: string;
+    /** Arbitrary context attached by the Worker (e.g. the failing operation). */
+    context?: unknown;
+}
+/** Convert an arbitrary error into a structured-cloneable form for postMessage.
+ * A non-Error value is attached as `context`, but only when it is itself
+ * structured-cloneable: a function, symbol, or an object/map holding one would
+ * otherwise make the serialised error unserializable, so `postMessage` would
+ * throw `DataCloneError` while reporting the original failure. */
+export declare function serializeError(error: unknown): SerializedWorkerError;
+/** Reconstruct an Error instance from its serialised form. */
+export declare function deserializeWorkerError(error: SerializedWorkerError): Error;
+//# sourceMappingURL=error-utils.d.ts.map

package/dist/utils/error-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-utils.d.ts","sourceRoot":"","sources":["../../src/utils/error-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,yDAAyD;AACzD,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;kEAIkE;AAClE,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAcpE;AAeD,8DAA8D;AAC9D,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,qBAAqB,GAAG,KAAK,CAM1E"}

package/dist/utils/metadata.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 发布元数据工具 —— 构造 { messageId?, timestamp? }，仅在字段已定义时写入，
+ * 避免往 wire 帧/控制消息里塞空枚举字段。
+ *
+ * 此前 cluster.ts、data-bus.ts、centrifuge.ts、centrifuge-session.ts 各自内联
+ * 实现了一遍 `...(x === undefined ? {} : { x })` 展开，行为容易漂移；统一到此
+ * 一处后所有调用方共享同一语义。
+ */
+import type { DataBusPublicationMetadata } from '../core/types';
+/**
+ * Copy defined publication metadata without adding empty enumerable fields.
+ * Returns `undefined` when neither field is set, so callers can preserve a
+ * legacy "no metadata" argument shape (e.g. `onControl(..., undefined)`).
+ */
+export declare function publicationMetadata(messageId?: string, timestamp?: number): DataBusPublicationMetadata | undefined;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/utils/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/utils/metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAEhE;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,CAAC,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,GACjB,0BAA0B,GAAG,SAAS,CAMxC"}

package/dist/utils/storage-utils.d.ts

@@ -0,0 +1,24 @@
+/**
+ * localStorage 读写工具 —— 容错的 JSON 读、静默写、按前缀枚举。
+ *
+ * 从 WorkerClusterRuntime 拆出：cluster.ts 顶部原有的 readJson/writeJson/
+ * listKeys/readAllByPrefix 四处搬到此文件，协调层与快照逻辑共用同一套
+ * 容错语义（损坏 JSON 视为不存在、写失败不抛出）。
+ */
+import type { StorageLike } from '../core/environment';
+/** Parse a JSON value from storage, returning null on malformed or missing data.
+ * Never throws — a corrupt record is treated as absent so the reconcile cycle
+ * can recreate it. */
+export declare function readJson<T>(storage: StorageLike, key: string): T | null;
+/** Write a JSON value to storage, swallowing storage errors (coordination is
+ * best-effort; a failed write does not break the local transport). The actual
+ * write may be coalesced by BatchingStorageWriter — this just calls setItem. */
+export declare function writeJson(storage: StorageLike, key: string, value: unknown): void;
+/** List all storage keys that start with `prefix`. */
+export declare function listKeys(storage: StorageLike, prefix: string): string[];
+/** Read and parse every JSON record whose key starts with `prefix`. */
+export declare function readAllByPrefix<T>(storage: StorageLike, prefix: string): Array<{
+    key: string;
+    value: T;
+}>;
+//# sourceMappingURL=storage-utils.d.ts.map

package/dist/utils/storage-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-utils.d.ts","sourceRoot":"","sources":["../../src/utils/storage-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;sBAEsB;AACtB,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAOvE;AAED;;gFAEgF;AAChF,wBAAgB,SAAS,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAMjF;AAED,sDAAsD;AACtD,wBAAgB,QAAQ,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAQvE;AAED,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC,CAIzG"}

package/dist/utils/validation.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 参数校验工具 —— CrossTabDataBus 构造选项与持久化配置的入口校验。
+ *
+ * 所有 `throw new TypeError(...)` 校验集中在此，DataBus 构造器与
+ * IndexedDbReplayPersistence 共用同一组断言，错误消息与原有语义保持一致。
+ *
+ * 语义约定：可选字段只在**显式提供**时校验（undefined 由调用方落到默认值，
+ * 默认值始终合法）；必填字段总是校验。
+ */
+import type { DataBusDedupOptions, DataBusPersistenceRetryOptions, DataBusReplayOptions } from '../core/data-bus';
+import type { LoadWeightingOptions } from '../core/types';
+/** Assert `value` is a positive safe integer. Throws a TypeError otherwise. */
+export declare function assertPositiveSafeInteger(value: unknown, name: string): void;
+/** Assert `value` is a positive finite number. Throws a TypeError otherwise. */
+export declare function assertPositiveFiniteNumber(value: unknown, name: string): void;
+/** Assert `value` is a non-negative finite number. Throws a TypeError otherwise. */
+export declare function assertNonNegativeFiniteNumber(value: unknown, name: string): void;
+/** Assert `value` is a valid replay prune strategy ('count' | 'age' | 'both'). */
+export declare function assertPruneStrategy(value: unknown): asserts value is 'count' | 'age' | 'both';
+/** Validate the replay options block. Optional fields are validated only when
+ * provided; omitted fields fall through to their defaults. */
+export declare function assertReplayOptions(replay: DataBusReplayOptions | undefined): void;
+/** Validate the replay persistence retry policy. */
+export declare function assertPersistenceRetryOptions(retry: DataBusPersistenceRetryOptions): void;
+/** Validate the dedup options block. Optional fields are validated only when
+ * provided; omitted fields fall through to their defaults. */
+export declare function assertDedupOptions(dedup: DataBusDedupOptions | undefined): void;
+/** Validate the transport recovery pacing options. Optional fields are validated
+ * only when provided; omitted fields fall through to their defaults. */
+export declare function assertRecoveryOptions(recovery: {
+    cooldownMs?: number;
+    maxAttempts?: number;
+} | undefined): void;
+/** Validate the adaptive owner-weighting weights.
+ *
+ * Each weight is a non-negative finite number of "topic-equivalents" added per
+ * unit of the sampled signal; `0` (the default) disables that signal. A
+ * negative weight would invert the documented policy — biasing NEW routes
+ * toward the *busiest* Worker instead of the quietest — and a non-finite one
+ * would poison the score, so both are rejected here rather than silently
+ * steering traffic. */
+export declare function assertLoadWeightingOptions(loadWeighting: LoadWeightingOptions | undefined): void;
+/** Validate the cluster coordination options shared by `WorkerClusterRuntime`
+ * and `CrossTabDataBus`.
+ *
+ * These were previously unvalidated, so a `heartbeatIntervalMs` of `0` or `NaN`
+ * silently turned the heartbeat `setInterval` into a 0ms busy loop (the same
+ * failure the Centrifuge PING guard exists to prevent), a non-positive
+ * `workerTtlMs` pruned every peer on the first reconcile, and a non-positive
+ * `maxActiveWorkers`/`routeOwnerCacheMax` disabled ownership or caching
+ * outright. `Infinity` is rejected for the heartbeat here: unlike the Centrifuge
+ * PING it cannot mean "disable", because a Worker that never refreshes its
+ * heartbeat is pruned by its own TTL. */
+export declare function assertClusterOptions(options: {
+    maxActiveWorkers?: number;
+    heartbeatIntervalMs?: number;
+    workerTtlMs?: number;
+    routeOwnerCacheMax?: number;
+    loadWeighting?: LoadWeightingOptions;
+}): void;
+/** Validate the SharedWorker PING heartbeat interval. A value of `0`, a negative
+ * number, or `NaN` would otherwise make `setInterval` degenerate into a 0ms busy
+ * loop, driving the reaper and the main-thread PING out of control. `Infinity`
+ * is allowed and disables heartbeats entirely (for environments where the
+ * SharedWorker reaper is not needed, e.g. a single-tab deployment).
+ * @throws {TypeError} when `value` is not a positive finite number or Infinity. */
+export declare function assertHeartbeatInterval(value: number): void;
+/** Validate that `value` is structured-cloneable. Throws early so config errors
+ * surface on the main thread rather than silently failing inside the Worker
+ * (where a DataCloneError would be reported as a generic Worker error with no
+ * actionable message). Skips validation when `structuredClone` is unavailable
+ * (older browsers without the API) — the Worker will still throw on its own.
+ * @throws {TypeError} when `value` contains non-cloneable members (functions,
+ *   Symbols, DOM nodes, etc.). */
+export declare function assertStructuredCloneable(value: unknown): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/utils/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EACV,mBAAmB,EACnB,8BAA8B,EAC9B,oBAAoB,EACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAG1D,+EAA+E;AAC/E,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAI5E;AAED,gFAAgF;AAChF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAI7E;AAED,oFAAoF;AACpF,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAIhF;AAED,kFAAkF;AAClF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,GAAG,KAAK,GAAG,MAAM,CAK7F;AAED;8DAC8D;AAC9D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB,GAAG,SAAS,GAAG,IAAI,CASlF;AAED,oDAAoD;AACpD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,8BAA8B,GAAG,IAAI,CAOzF;AAED;8DAC8D;AAC9D,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,mBAAmB,GAAG,SAAS,GAAG,IAAI,CAiB/E;AAED;wEACwE;AACxE,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,SAAS,GAAG,IAAI,CAanB;AAED;;;;;;;uBAOuB;AACvB,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,oBAAoB,GAAG,SAAS,GAAG,IAAI,CAUhG;AAED;;;;;;;;;;yCAUyC;AACzC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAC5C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,aAAa,CAAC,EAAE,oBAAoB,CAAC;CACtC,GAAG,IAAI,CAcP;AAED;;;;;mFAKmF;AACnF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAM3D;AAED;;;;;;kCAMkC;AAClC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAU9D"}

package/dist/vue.d.ts

@@ -2,9 +2,21 @@
  * Vue is an optional peer dependency; this module is a separate entry point.
  */
 import { type Ref } from 'vue';
-import type { CrossTabDataBus } from './core/data-bus';
+import type { CrossTabDataBus, DataBusHealthSummary } from './core/data-bus';
 import type { DataBusMessage, WorkerStatus } from './core/types';
 export declare function useCrossTabDataBus<TConfig, TData>(create: () => CrossTabDataBus<TConfig, TData>, deps?: ReadonlyArray<Ref<unknown> | (() => unknown)>): Ref<CrossTabDataBus<TConfig, TData> | null>;
 export declare function useCrossTabSubscription<TConfig, TData>(bus: Ref<CrossTabDataBus<TConfig, TData> | null>, topic: Ref<string> | string, handler: (message: DataBusMessage<TData>) => void): void;
 export declare function useCrossTabStatus<TConfig, TData>(bus: Ref<CrossTabDataBus<TConfig, TData> | null>): Ref<WorkerStatus>;
+/** Options for {@link useCrossTabHealth}. */
+export interface UseCrossTabHealthOptions {
+    /** Polling cadence in ms for the health snapshot. Default 1000; `0` disables
+     * polling and relies on status/error events only. */
+    intervalMs?: number;
+}
+/**
+ * Mirror the bus health summary into a Vue ref. `getHealthSummary()` is a
+ * snapshot, so the composable polls it on an interval (default 1000 ms) and
+ * refreshes on status changes and errors. Returns `null` until the bus exists.
+ */
+export declare function useCrossTabHealth<TConfig, TData>(bus: Ref<CrossTabDataBus<TConfig, TData> | null>, options?: UseCrossTabHealthOptions): Ref<DataBusHealthSummary | null>;
 //# sourceMappingURL=vue.d.ts.map

package/dist/vue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vue.d.ts","sourceRoot":"","sources":["../src/vue.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAsD,KAAK,GAAG,EAAE,MAAM,KAAK,CAAC;AACnF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,KAAK,EAC/C,MAAM,EAAE,MAAM,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,EAC7C,IAAI,GAAE,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,CAAM,GACvD,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,CAmB7C;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,KAAK,EACpD,GAAG,EAAE,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAC7E,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC,KAAK,IAAI,GAChD,IAAI,CAoBN;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,KAAK,EAC9C,GAAG,EAAE,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,GAC/C,GAAG,CAAC,YAAY,CAAC,CAUnB"}
+{"version":3,"file":"vue.d.ts","sourceRoot":"","sources":["../src/vue.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAsD,KAAK,GAAG,EAAE,MAAM,KAAK,CAAC;AACnF,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC7E,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGjE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,KAAK,EAC/C,MAAM,EAAE,MAAM,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,EAC7C,IAAI,GAAE,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,OAAO,CAAC,CAAM,GACvD,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,CA2B7C;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,KAAK,EACpD,GAAG,EAAE,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,EAC7E,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,CAAC,KAAK,CAAC,KAAK,IAAI,GAChD,IAAI,CAoBN;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,KAAK,EAC9C,GAAG,EAAE,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,GAC/C,GAAG,CAAC,YAAY,CAAC,CAUnB;AAED,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC;yDACqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,KAAK,EAC9C,GAAG,EAAE,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC,EAChD,OAAO,CAAC,EAAE,wBAAwB,GACjC,GAAG,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAyBlC"}

package/dist/vue.js

@@ -1,3 +1,7 @@
+import {
+  WORKER_STATUS
+} from "./chunk-TZ7ZP7YD.js";
+
 // src/vue.ts
 import { onBeforeUnmount, onMounted, ref, shallowRef, watch } from "vue";
 function useCrossTabDataBus(create, deps = []) {
@@ -23,6 +27,7 @@ function useCrossTabDataBus(create, deps = []) {
   };
   onMounted(start);
   onBeforeUnmount(() => {
+    lifecycleGeneration += 1;
     void stop();
   });
   if (deps.length > 0) watch(deps, start);
@@ -57,12 +62,12 @@ function useCrossTabSubscription(bus, topic, handler) {
   onBeforeUnmount(stop);
 }
 function useCrossTabStatus(bus) {
-  const status = ref("connecting");
+  const status = ref(WORKER_STATUS.CONNECTING);
   let cleanup;
   watch(bus, (next) => {
     cleanup?.();
     cleanup = void 0;
-    status.value = next?.getStatus() ?? "connecting";
+    status.value = next?.getStatus() ?? WORKER_STATUS.CONNECTING;
     if (next) cleanup = next.onStatus((value) => {
       status.value = value;
     });
@@ -70,8 +75,37 @@ function useCrossTabStatus(bus) {
   onBeforeUnmount(() => cleanup?.());
   return status;
 }
+function useCrossTabHealth(bus, options) {
+  const health = ref(null);
+  let timer = null;
+  let cleanups = [];
+  const teardown = () => {
+    if (timer) clearInterval(timer);
+    timer = null;
+    for (const cleanup of cleanups) cleanup();
+    cleanups = [];
+  };
+  watch(bus, (next) => {
+    teardown();
+    if (!next) {
+      health.value = null;
+      return;
+    }
+    const refresh = () => {
+      health.value = next.getHealthSummary();
+    };
+    refresh();
+    cleanups.push(next.onStatus(refresh));
+    cleanups.push(next.onError(refresh));
+    const intervalMs = options?.intervalMs ?? 1e3;
+    if (intervalMs > 0) timer = setInterval(refresh, intervalMs);
+  }, { immediate: true });
+  onBeforeUnmount(teardown);
+  return health;
+}
 export {
   useCrossTabDataBus,
+  useCrossTabHealth,
   useCrossTabStatus,
   useCrossTabSubscription
 };

package/dist/vue.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/vue.ts"],
-  "sourcesContent": ["/** Vue 3 composables adapter for cross-tab-worker-databus.\n * Vue is an optional peer dependency; this module is a separate entry point.\n */\nimport { onBeforeUnmount, onMounted, ref, shallowRef, watch, type Ref } from 'vue';\nimport type { CrossTabDataBus } from './core/data-bus';\nimport type { DataBusMessage, WorkerStatus } from './core/types';\n\nexport function useCrossTabDataBus<TConfig, TData>(\n  create: () => CrossTabDataBus<TConfig, TData>,\n  deps: ReadonlyArray<Ref<unknown> | (() => unknown)> = []\n): Ref<CrossTabDataBus<TConfig, TData> | null> {\n  const bus = shallowRef<CrossTabDataBus<TConfig, TData> | null>(null);\n  let instance: CrossTabDataBus<TConfig, TData> | null = null;\n  let lifecycleGeneration = 0;\n  const stop = async () => { const current = instance; instance = null; bus.value = null; if (current) await current.stop(); };\n  const start = () => {\n    const generation = ++lifecycleGeneration;\n    void stop().then(() => {\n      if (generation !== lifecycleGeneration) return;\n      const next = create();\n      instance = next;\n      bus.value = next;\n      void next.ready().catch(() => {});\n    });\n  };\n  onMounted(start);\n  onBeforeUnmount(() => { void stop(); });\n  if (deps.length > 0) watch(deps, start);\n  return bus as Ref<CrossTabDataBus<TConfig, TData> | null>;\n}\n\nexport function useCrossTabSubscription<TConfig, TData>(\n  bus: Ref<CrossTabDataBus<TConfig, TData> | null>, topic: Ref<string> | string,\n  handler: (message: DataBusMessage<TData>) => void\n): void {\n  let currentBus: CrossTabDataBus<TConfig, TData> | null = null;\n  let currentTopic: string | null = null;\n  let cleanup: (() => void) | undefined;\n  let latestHandler = handler;\n  const stop = () => { cleanup?.(); cleanup = undefined; currentBus = null; currentTopic = null; };\n  const sync = () => {\n    const nextBus = bus.value;\n    const nextTopic = typeof topic === 'string' ? topic : topic.value;\n    if (nextBus === currentBus && currentTopic === nextTopic && cleanup) return;\n    stop();\n    if (!nextBus) return;\n    currentBus = nextBus;\n    currentTopic = nextTopic;\n    cleanup = nextBus.subscribe(nextTopic, message => latestHandler(message));\n  };\n  watch(bus, sync, { immediate: true });\n  if (typeof topic !== 'string') watch(topic, sync);\n  watch(() => handler, value => { latestHandler = value; });\n  onBeforeUnmount(stop);\n}\n\nexport function useCrossTabStatus<TConfig, TData>(\n  bus: Ref<CrossTabDataBus<TConfig, TData> | null>\n): Ref<WorkerStatus> {\n  const status = ref<WorkerStatus>('connecting');\n  let cleanup: (() => void) | undefined;\n  watch(bus, next => {\n    cleanup?.(); cleanup = undefined;\n    status.value = next?.getStatus() ?? 'connecting';\n    if (next) cleanup = next.onStatus(value => { status.value = value; });\n  }, { immediate: true });\n  onBeforeUnmount(() => cleanup?.());\n  return status;\n}\n"],
-  "mappings": ";AAGA,SAAS,iBAAiB,WAAW,KAAK,YAAY,aAAuB;AAItE,SAAS,mBACd,QACA,OAAsD,CAAC,GACV;AAC7C,QAAM,MAAM,WAAmD,IAAI;AACnE,MAAI,WAAmD;AACvD,MAAI,sBAAsB;AAC1B,QAAM,OAAO,YAAY;AAAE,UAAM,UAAU;AAAU,eAAW;AAAM,QAAI,QAAQ;AAAM,QAAI,QAAS,OAAM,QAAQ,KAAK;AAAA,EAAG;AAC3H,QAAM,QAAQ,MAAM;AAClB,UAAM,aAAa,EAAE;AACrB,SAAK,KAAK,EAAE,KAAK,MAAM;AACrB,UAAI,eAAe,oBAAqB;AACxC,YAAM,OAAO,OAAO;AACpB,iBAAW;AACX,UAAI,QAAQ;AACZ,WAAK,KAAK,MAAM,EAAE,MAAM,MAAM;AAAA,MAAC,CAAC;AAAA,IAClC,CAAC;AAAA,EACH;AACA,YAAU,KAAK;AACf,kBAAgB,MAAM;AAAE,SAAK,KAAK;AAAA,EAAG,CAAC;AACtC,MAAI,KAAK,SAAS,EAAG,OAAM,MAAM,KAAK;AACtC,SAAO;AACT;AAEO,SAAS,wBACd,KAAkD,OAClD,SACM;AACN,MAAI,aAAqD;AACzD,MAAI,eAA8B;AAClC,MAAI;AACJ,MAAI,gBAAgB;AACpB,QAAM,OAAO,MAAM;AAAE,cAAU;AAAG,cAAU;AAAW,iBAAa;AAAM,mBAAe;AAAA,EAAM;AAC/F,QAAM,OAAO,MAAM;AACjB,UAAM,UAAU,IAAI;AACpB,UAAM,YAAY,OAAO,UAAU,WAAW,QAAQ,MAAM;AAC5D,QAAI,YAAY,cAAc,iBAAiB,aAAa,QAAS;AACrE,SAAK;AACL,QAAI,CAAC,QAAS;AACd,iBAAa;AACb,mBAAe;AACf,cAAU,QAAQ,UAAU,WAAW,aAAW,cAAc,OAAO,CAAC;AAAA,EAC1E;AACA,QAAM,KAAK,MAAM,EAAE,WAAW,KAAK,CAAC;AACpC,MAAI,OAAO,UAAU,SAAU,OAAM,OAAO,IAAI;AAChD,QAAM,MAAM,SAAS,WAAS;AAAE,oBAAgB;AAAA,EAAO,CAAC;AACxD,kBAAgB,IAAI;AACtB;AAEO,SAAS,kBACd,KACmB;AACnB,QAAM,SAAS,IAAkB,YAAY;AAC7C,MAAI;AACJ,QAAM,KAAK,UAAQ;AACjB,cAAU;AAAG,cAAU;AACvB,WAAO,QAAQ,MAAM,UAAU,KAAK;AACpC,QAAI,KAAM,WAAU,KAAK,SAAS,WAAS;AAAE,aAAO,QAAQ;AAAA,IAAO,CAAC;AAAA,EACtE,GAAG,EAAE,WAAW,KAAK,CAAC;AACtB,kBAAgB,MAAM,UAAU,CAAC;AACjC,SAAO;AACT;",
+  "sourcesContent": ["/** Vue 3 composables adapter for cross-tab-worker-databus.\n * Vue is an optional peer dependency; this module is a separate entry point.\n */\nimport { onBeforeUnmount, onMounted, ref, shallowRef, watch, type Ref } from 'vue';\nimport type { CrossTabDataBus, DataBusHealthSummary } from './core/data-bus';\nimport type { DataBusMessage, WorkerStatus } from './core/types';\nimport { WORKER_STATUS } from './utils/constants';\n\nexport function useCrossTabDataBus<TConfig, TData>(\n  create: () => CrossTabDataBus<TConfig, TData>,\n  deps: ReadonlyArray<Ref<unknown> | (() => unknown)> = []\n): Ref<CrossTabDataBus<TConfig, TData> | null> {\n  const bus = shallowRef<CrossTabDataBus<TConfig, TData> | null>(null);\n  let instance: CrossTabDataBus<TConfig, TData> | null = null;\n  let lifecycleGeneration = 0;\n  const stop = async () => { const current = instance; instance = null; bus.value = null; if (current) await current.stop(); };\n  const start = () => {\n    const generation = ++lifecycleGeneration;\n    void stop().then(() => {\n      if (generation !== lifecycleGeneration) return;\n      const next = create();\n      instance = next;\n      bus.value = next;\n      void next.ready().catch(() => {});\n    });\n  };\n  onMounted(start);\n  onBeforeUnmount(() => {\n    // Bump the generation so a start() still awaiting its stop() sees itself\n    // superseded. Without this the pending continuation would run create()\n    // after the component is gone, leaving a live bus with no owner to stop\n    // it (the React adapter has no such window: its create() is synchronous\n    // inside useEffect).\n    lifecycleGeneration += 1;\n    void stop();\n  });\n  if (deps.length > 0) watch(deps, start);\n  return bus as Ref<CrossTabDataBus<TConfig, TData> | null>;\n}\n\nexport function useCrossTabSubscription<TConfig, TData>(\n  bus: Ref<CrossTabDataBus<TConfig, TData> | null>, topic: Ref<string> | string,\n  handler: (message: DataBusMessage<TData>) => void\n): void {\n  let currentBus: CrossTabDataBus<TConfig, TData> | null = null;\n  let currentTopic: string | null = null;\n  let cleanup: (() => void) | undefined;\n  let latestHandler = handler;\n  const stop = () => { cleanup?.(); cleanup = undefined; currentBus = null; currentTopic = null; };\n  const sync = () => {\n    const nextBus = bus.value;\n    const nextTopic = typeof topic === 'string' ? topic : topic.value;\n    if (nextBus === currentBus && currentTopic === nextTopic && cleanup) return;\n    stop();\n    if (!nextBus) return;\n    currentBus = nextBus;\n    currentTopic = nextTopic;\n    cleanup = nextBus.subscribe(nextTopic, message => latestHandler(message));\n  };\n  watch(bus, sync, { immediate: true });\n  if (typeof topic !== 'string') watch(topic, sync);\n  watch(() => handler, value => { latestHandler = value; });\n  onBeforeUnmount(stop);\n}\n\nexport function useCrossTabStatus<TConfig, TData>(\n  bus: Ref<CrossTabDataBus<TConfig, TData> | null>\n): Ref<WorkerStatus> {\n  const status = ref<WorkerStatus>(WORKER_STATUS.CONNECTING);\n  let cleanup: (() => void) | undefined;\n  watch(bus, next => {\n    cleanup?.(); cleanup = undefined;\n    status.value = next?.getStatus() ?? WORKER_STATUS.CONNECTING;\n    if (next) cleanup = next.onStatus(value => { status.value = value; });\n  }, { immediate: true });\n  onBeforeUnmount(() => cleanup?.());\n  return status;\n}\n\n/** Options for {@link useCrossTabHealth}. */\nexport interface UseCrossTabHealthOptions {\n  /** Polling cadence in ms for the health snapshot. Default 1000; `0` disables\n   * polling and relies on status/error events only. */\n  intervalMs?: number;\n}\n\n/**\n * Mirror the bus health summary into a Vue ref. `getHealthSummary()` is a\n * snapshot, so the composable polls it on an interval (default 1000 ms) and\n * refreshes on status changes and errors. Returns `null` until the bus exists.\n */\nexport function useCrossTabHealth<TConfig, TData>(\n  bus: Ref<CrossTabDataBus<TConfig, TData> | null>,\n  options?: UseCrossTabHealthOptions\n): Ref<DataBusHealthSummary | null> {\n  const health = ref<DataBusHealthSummary | null>(null);\n  let timer: ReturnType<typeof setInterval> | null = null;\n  let cleanups: Array<() => void> = [];\n  const teardown = () => {\n    if (timer) clearInterval(timer);\n    timer = null;\n    for (const cleanup of cleanups) cleanup();\n    cleanups = [];\n  };\n  watch(bus, next => {\n    teardown();\n    if (!next) {\n      health.value = null;\n      return;\n    }\n    const refresh = () => { health.value = next.getHealthSummary(); };\n    refresh();\n    cleanups.push(next.onStatus(refresh));\n    cleanups.push(next.onError(refresh));\n    const intervalMs = options?.intervalMs ?? 1_000;\n    if (intervalMs > 0) timer = setInterval(refresh, intervalMs);\n  }, { immediate: true });\n  onBeforeUnmount(teardown);\n  return health as Ref<DataBusHealthSummary | null>;\n}\n"],
+  "mappings": ";;;;;AAGA,SAAS,iBAAiB,WAAW,KAAK,YAAY,aAAuB;AAKtE,SAAS,mBACd,QACA,OAAsD,CAAC,GACV;AAC7C,QAAM,MAAM,WAAmD,IAAI;AACnE,MAAI,WAAmD;AACvD,MAAI,sBAAsB;AAC1B,QAAM,OAAO,YAAY;AAAE,UAAM,UAAU;AAAU,eAAW;AAAM,QAAI,QAAQ;AAAM,QAAI,QAAS,OAAM,QAAQ,KAAK;AAAA,EAAG;AAC3H,QAAM,QAAQ,MAAM;AAClB,UAAM,aAAa,EAAE;AACrB,SAAK,KAAK,EAAE,KAAK,MAAM;AACrB,UAAI,eAAe,oBAAqB;AACxC,YAAM,OAAO,OAAO;AACpB,iBAAW;AACX,UAAI,QAAQ;AACZ,WAAK,KAAK,MAAM,EAAE,MAAM,MAAM;AAAA,MAAC,CAAC;AAAA,IAClC,CAAC;AAAA,EACH;AACA,YAAU,KAAK;AACf,kBAAgB,MAAM;AAMpB,2BAAuB;AACvB,SAAK,KAAK;AAAA,EACZ,CAAC;AACD,MAAI,KAAK,SAAS,EAAG,OAAM,MAAM,KAAK;AACtC,SAAO;AACT;AAEO,SAAS,wBACd,KAAkD,OAClD,SACM;AACN,MAAI,aAAqD;AACzD,MAAI,eAA8B;AAClC,MAAI;AACJ,MAAI,gBAAgB;AACpB,QAAM,OAAO,MAAM;AAAE,cAAU;AAAG,cAAU;AAAW,iBAAa;AAAM,mBAAe;AAAA,EAAM;AAC/F,QAAM,OAAO,MAAM;AACjB,UAAM,UAAU,IAAI;AACpB,UAAM,YAAY,OAAO,UAAU,WAAW,QAAQ,MAAM;AAC5D,QAAI,YAAY,cAAc,iBAAiB,aAAa,QAAS;AACrE,SAAK;AACL,QAAI,CAAC,QAAS;AACd,iBAAa;AACb,mBAAe;AACf,cAAU,QAAQ,UAAU,WAAW,aAAW,cAAc,OAAO,CAAC;AAAA,EAC1E;AACA,QAAM,KAAK,MAAM,EAAE,WAAW,KAAK,CAAC;AACpC,MAAI,OAAO,UAAU,SAAU,OAAM,OAAO,IAAI;AAChD,QAAM,MAAM,SAAS,WAAS;AAAE,oBAAgB;AAAA,EAAO,CAAC;AACxD,kBAAgB,IAAI;AACtB;AAEO,SAAS,kBACd,KACmB;AACnB,QAAM,SAAS,IAAkB,cAAc,UAAU;AACzD,MAAI;AACJ,QAAM,KAAK,UAAQ;AACjB,cAAU;AAAG,cAAU;AACvB,WAAO,QAAQ,MAAM,UAAU,KAAK,cAAc;AAClD,QAAI,KAAM,WAAU,KAAK,SAAS,WAAS;AAAE,aAAO,QAAQ;AAAA,IAAO,CAAC;AAAA,EACtE,GAAG,EAAE,WAAW,KAAK,CAAC;AACtB,kBAAgB,MAAM,UAAU,CAAC;AACjC,SAAO;AACT;AAcO,SAAS,kBACd,KACA,SACkC;AAClC,QAAM,SAAS,IAAiC,IAAI;AACpD,MAAI,QAA+C;AACnD,MAAI,WAA8B,CAAC;AACnC,QAAM,WAAW,MAAM;AACrB,QAAI,MAAO,eAAc,KAAK;AAC9B,YAAQ;AACR,eAAW,WAAW,SAAU,SAAQ;AACxC,eAAW,CAAC;AAAA,EACd;AACA,QAAM,KAAK,UAAQ;AACjB,aAAS;AACT,QAAI,CAAC,MAAM;AACT,aAAO,QAAQ;AACf;AAAA,IACF;AACA,UAAM,UAAU,MAAM;AAAE,aAAO,QAAQ,KAAK,iBAAiB;AAAA,IAAG;AAChE,YAAQ;AACR,aAAS,KAAK,KAAK,SAAS,OAAO,CAAC;AACpC,aAAS,KAAK,KAAK,QAAQ,OAAO,CAAC;AACnC,UAAM,aAAa,SAAS,cAAc;AAC1C,QAAI,aAAa,EAAG,SAAQ,YAAY,SAAS,UAAU;AAAA,EAC7D,GAAG,EAAE,WAAW,KAAK,CAAC;AACtB,kBAAgB,QAAQ;AACxB,SAAO;AACT;",
   "names": []
 }

package/dist/websocket.d.ts

@@ -8,12 +8,13 @@
  *
  * Wire protocol (JSON text frames):
  * - client → server: `{"op":"subscribe"|"unsubscribe"|"publish","topic":...,"data":...}`
+ * - client → server (batched): `{"op":"publishBatch","topic":...,"items":[{data,...}]}`
  * - server → client: `{"topic":...,"data":...}` for publications; anything
  *   without a string `topic` field is ignored (forward-compatible).
  */
 import { CrossTabDataBus } from './core/data-bus';
 import type { CrossTabDataBusOptions } from './core/data-bus';
-import type { DataBusTransport, DataBusTransportHandlers, DataBusPublishOptions, MaybePromise, WorkerStatus } from './core/types';
+import type { DataBusTransport, DataBusTransportHandlers, DataBusPublishOptions, DataBusPublicationItem, MaybePromise, WorkerStatus } from './core/types';
 /** Minimal WebSocket surface used by the transport. Matches the browser
  * `WebSocket` subset the transport touches; injectable for tests and runtimes. */
 export interface WebSocketLike {
@@ -68,6 +69,10 @@ export declare class WebSocketTransport<TData = unknown> implements DataBusTrans
     unsubscribe(topic: string): MaybePromise<void>;
     /** Publish `data` to `topic` as a JSON frame. Requires an open socket. */
     publish(topic: string, data: unknown, options?: DataBusPublishOptions): MaybePromise<void>;
+    /** Publish many items for one topic as a single wire frame. One-item
+     * batches delegate to `publish` so the legacy single-publication frame
+     * shape (including binary framing) is preserved. */
+    publishBatch(topic: string, items: ReadonlyArray<DataBusPublicationItem>): MaybePromise<void>;
     /** Close the socket and drop all state. Safe to call multiple times. */
     stop(): MaybePromise<void>;
     /** Send one JSON frame. Frames are dropped with an `onError` report when

package/dist/websocket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../src/websocket.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../src/websocket.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAE9D,OAAO,KAAK,EACV,gBAAgB,EAChB,wBAAwB,EACxB,qBAAqB,EACrB,sBAAsB,EAEtB,YAAY,EACZ,YAAY,EACb,MAAM,cAAc,CAAC;AAEtB;kFACkF;AAClF,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;IACvC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,MAAM,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;IAC5B,OAAO,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;IAC7B,OAAO,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC;IAC7B,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CACxD;AAED,+DAA+D;AAC/D,MAAM,WAAW,sBAAsB;IACrC,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;IACZ,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC9B;6CACyC;IACzC,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,aAAa,CAAC;CAClF;AAED,0FAA0F;AAC1F,MAAM,WAAW,6BAA6B,CAAC,KAAK,GAAG,OAAO,CAC5D,SAAQ,IAAI,CACV,sBAAsB,CAAC,sBAAsB,EAAE,KAAK,CAAC,EACrD,WAAW,GAAG,YAAY,GAAG,eAAe,GAAG,WAAW,CAC3D;IACD,0CAA0C;IAC1C,UAAU,EAAE,sBAAsB,CAAC;IACnC,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID;;;;qEAIqE;AACrE,qBAAa,kBAAkB,CAAC,KAAK,GAAG,OAAO,CAC7C,YAAW,gBAAgB,CAAC,sBAAsB,EAAE,KAAK,CAAC;IAQ9C,OAAO,CAAC,QAAQ,CAAC,UAAU;IANvC,QAAQ,CAAC,eAAe,eAAe;IACvC,QAAQ,CAAC,kBAAkB,sBAAsB;IACjD,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,QAAQ,CAAgD;IAChE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;gBAEzB,UAAU,EAAE,sBAAsB;IAE/D;0EACsE;IACtE,KAAK,CAAC,MAAM,EAAE,sBAAsB,EAAE,QAAQ,EAAE,wBAAwB,CAAC,KAAK,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC;IAoCpG;iDAC6C;IAC7C,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC;IAK5C,6DAA6D;IAC7D,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC;IAK9C,0EAA0E;IAC1E,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,YAAY,CAAC,IAAI,CAAC;IAc1F;;wDAEoD;IACpD,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,CAAC,sBAAsB,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC;IA0B7F,wEAAwE;IACxE,IAAI,IAAI,YAAY,CAAC,IAAI,CAAC;IAQ1B;;iEAE6D;IAC7D,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,eAAe;IA8BvB;;+CAE2C;YAC7B,aAAa;CAkC5B;AAUD;;iEAEiE;AACjE,wBAAgB,sBAAsB,CAAC,KAAK,GAAG,OAAO,EACpD,OAAO,EAAE,6BAA6B,CAAC,KAAK,CAAC,GAC5C,eAAe,CAAC,sBAAsB,EAAE,KAAK,CAAC,CAShD;AAED,wEAAwE;AACxE,YAAY,EAAE,YAAY,EAAE,CAAC"}

package/dist/worker-mode.d.ts

@@ -4,15 +4,19 @@
  * Defines the WorkerMode preference flags and the selectWorkerBackend function
  * that resolves the preference against browser capability to pick the actual
  * backend (dedicated, shared, or local fallback).
+ *
+ * The literal values are derived from `utils/constants.ts` so the preference and
+ * resolved-backend strings referenced across the transport stay in one place.
  */
+import { WORKER_BACKEND, WORKER_MODE } from './utils/constants';
 /** 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';
+export type WorkerMode = (typeof WORKER_MODE)[keyof typeof WORKER_MODE];
 /** 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';
+export type WorkerBackend = (typeof WORKER_BACKEND)[keyof typeof WORKER_BACKEND];
 /** 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. */

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;;;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"}
+{"version":3,"file":"worker-mode.d.ts","sourceRoot":"","sources":["../src/worker-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhE;;;oEAGoE;AACpE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAExE;yEACyE;AACzE,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAEjF;;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/docs/README.md

@@ -11,6 +11,7 @@
 | [Architecture](./architecture.md) | Worker cluster, routing, storage, migration, and degradation design |
 | [Capabilities Matrix](./capabilities.md) | Implemented, not implemented, and planned capabilities matrix |
 | [Roadmap](./roadmap.md) | Release-oriented priorities and verification checklist |
+| [Benchmark trend](./benchmarks.md) | Auto-generated browser benchmark history from `bench-results/` |
 | [Release checklist](./release-checklist.md) | Local gates, tagging, publishing, and post-release verification |
 | [../examples/demo](../examples/demo) | Runnable multi-tab browser demo |
 | [../CHANGELOG.md](../CHANGELOG.md) | Version changelog |