cross-tab-worker-databus 0.21.12 → 0.21.13

package/dist/cjs/hooks.cjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/hooks.ts", "../../src/utils/constants.ts"],
-  "sourcesContent": ["/**\n * React hooks adapter for cross-tab-worker-databus.\n *\n * A thin, transport-agnostic bridge between the imperative CrossTabDataBus\n * API and React component lifecycles. React is an optional peer dependency \u2014\n * this module is a separate entry point so consumers who don't use React\n * never load it.\n *\n * - `useCrossTabDataBus` owns the bus lifecycle: created on mount, stopped on\n *   unmount. It is StrictMode-safe: the double-invoked effect exercises the\n *   same stop/recreate path as BFCache suspend/resume.\n * - `useCrossTabSubscription` attaches a message handler with automatic\n *   cleanup; the handler is read through a ref, so you can pass inline\n *   closures without resubscribing on every render.\n * - `useCrossTabStatus` mirrors `bus.onStatus()` into React state.\n * - `useCrossTabHealth` polls `bus.getHealthSummary()` into React state,\n *   with event-driven refreshes on status changes and errors.\n */\nimport { useEffect, useRef, useState } from 'react';\nimport type { DependencyList } from 'react';\nimport type { CrossTabDataBus, DataBusHealthSummary } from './core/data-bus';\nimport type { DataBusMessage, WorkerStatus } from './core/types';\nimport { WORKER_STATUS } from './utils/constants';\n\n/**\n * Create a CrossTabDataBus for the component's lifetime.\n *\n * @param create Factory invoked once per effect run. Return a fresh bus \u2014\n *   do not share a bus instance between effects, or StrictMode's\n *   mount \u2192 stop \u2192 mount cycle will stop the shared instance out from\n *   under the second mount.\n * @param deps Re-create the bus when these change (default: create once).\n * @returns The active bus, or `null` before the first effect has run (SSR\n *   and the initial render).\n */\nexport function useCrossTabDataBus<TConfig, TData>(\n  create: () => CrossTabDataBus<TConfig, TData>,\n  deps: DependencyList = []\n): CrossTabDataBus<TConfig, TData> | null {\n  const [bus, setBus] = useState<CrossTabDataBus<TConfig, TData> | null>(null);\n  useEffect(() => {\n    // No \"is this effect still current?\" check is needed: React runs an\n    // effect's cleanup before its next invocation, and nothing between the\n    // lines below yields, so `create()` cannot be interleaved with a newer\n    // mount and this cleanup always stops the instance its own run created.\n    const instance = create();\n    setBus(instance);\n    void instance.ready().catch(() => {});\n    return () => {\n      setBus(null);\n      void instance.stop();\n    };\n    // The factory is intentionally not a dependency: callers pass an inline\n    // closure and key recreation through `deps` instead.\n  }, deps);\n  return bus;\n}\n\n/**\n * Subscribe to `topic` for the component's lifetime. The handler is read\n * through a ref on each delivery, so inline closures are safe without\n * unsubscribing/resubscribing on re-renders.\n *\n * When `bus` is null (not yet created) the subscription is queued until the\n * bus appears \u2014 the bus itself queues it until the transport is ready.\n */\nexport function useCrossTabSubscription<TConfig, TData>(\n  bus: CrossTabDataBus<TConfig, TData> | null,\n  topic: string,\n  handler: (message: DataBusMessage<TData>) => void\n): void {\n  const handlerRef = useRef(handler);\n  handlerRef.current = handler;\n  useEffect(() => {\n    if (!bus) return;\n    return bus.subscribe(topic, message => handlerRef.current(message));\n  }, [bus, topic]);\n}\n\n/**\n * Mirror the bus connection status into React state. Reports the live value\n * via `onStatus` and reads the current value synchronously whenever `bus`\n * changes identity.\n */\nexport function useCrossTabStatus<TConfig, TData>(\n  bus: CrossTabDataBus<TConfig, TData> | null\n): WorkerStatus {\n  const [status, setStatus] = useState<WorkerStatus>(WORKER_STATUS.CONNECTING);\n  useEffect(() => {\n    if (!bus) {\n      setStatus(WORKER_STATUS.CONNECTING);\n      return;\n    }\n    setStatus(bus.getStatus());\n    return bus.onStatus(setStatus);\n  }, [bus]);\n  return status;\n}\n\n/**\n * Mirror the bus health summary into React state.\n *\n * `getHealthSummary()` is a snapshot, not an event stream, so the hook polls\n * it on an interval (default 1000 ms) and refreshes immediately on status\n * changes and errors. Pass `intervalMs: 0` to rely on event-driven refreshes\n * only; changing the interval replaces the timer without recreating the bus.\n * Returns `null` while the bus has not been created yet.\n */\nexport function useCrossTabHealth<TConfig, TData>(\n  bus: CrossTabDataBus<TConfig, TData> | null,\n  options?: { intervalMs?: number }\n): DataBusHealthSummary | null {\n  const [health, setHealth] = useState<DataBusHealthSummary | null>(null);\n  const intervalMs = options?.intervalMs ?? 1_000;\n  useEffect(() => {\n    if (!bus) {\n      setHealth(null);\n      return;\n    }\n    const refresh = () => setHealth(bus.getHealthSummary());\n    refresh();\n    const unsubscribeStatus = bus.onStatus(refresh);\n    const unsubscribeError = bus.onError(refresh);\n    const timer = intervalMs > 0 ? setInterval(refresh, intervalMs) : null;\n    return () => {\n      unsubscribeStatus();\n      unsubscribeError();\n      if (timer) clearInterval(timer);\n    };\n    // Depend on the normalized cadence rather than the options object so inline\n    // option literals do not restart the effect on every render, while a real\n    // intervalMs change still replaces the polling timer.\n  }, [bus, intervalMs]);\n  return health;\n}\n", "/**\n * \u516C\u5171\u5B57\u7B26\u4E32\u5E38\u91CF \u2014\u2014 \u751F\u547D\u5468\u671F\u72B6\u6001\u3001\u89D2\u8272\u3001\u63A7\u5236\u52A8\u4F5C\u3001\u534F\u8BAE\u6D88\u606F\u7C7B\u578B\u3001\u679A\u4E3E\u4E0E\n * \u547D\u540D\u7A7A\u95F4\u524D\u7F00\u3002\n *\n * \u6240\u6709\u8FD0\u884C\u65F6\u4F7F\u7528\u7684\u5B57\u7B26\u4E32\u5B57\u9762\u91CF\u96C6\u4E2D\u5728\u6B64\u4E00\u4EFD\u503C\uFF0C\u7C7B\u578B\u5B9A\u4E49\uFF08src/core/types.ts\n * \u7B49\uFF09\u901A\u8FC7 `(typeof X)[keyof typeof X]` \u4ECE\u8FD9\u4E9B\u5E38\u91CF\u6D3E\u751F\uFF0C\u6BD4\u8F83/switch \u5904\u5F15\u7528\n * \u540C\u4E00\u5BF9\u8C61\u6210\u5458\u3002\u8FD9\u6837\u65E2\u80FD\u6D88\u9664\u6563\u843D\u5728\u5404\u6587\u4EF6\u91CC\u7684\u91CD\u590D\u5B57\u7B26\u4E32\uFF08\u907F\u514D\u5927\u5C0F\u5199\u4E0D\u7EDF\u4E00\n * \u6216\u7B14\u8BEF\uFF09\uFF0C\u53C8\u4FDD\u8BC1\u7C7B\u578B\u4E0E\u503C\u6C38\u4E0D\u9519\u4F4D\u3002\n *\n * ## \u4F7F\u7528\u7EA6\u5B9A\n *\n * - **\u65B0\u589E\u6216\u4FEE\u6539\u5B57\u7B26\u4E32\u5B57\u9762\u91CF\u65F6\uFF0C\u5148\u5230\u8FD9\u91CC\u67E5\u627E/\u589E\u8865\uFF0C\u4E0D\u8981\u5728\u4E1A\u52A1\u6587\u4EF6\u91CC\u76F4\u63A5\u5199\n *   \u9B54\u6CD5\u5B57\u7B26\u4E32\u3002** \u626B\u63CF\u6B8B\u7559\u5B57\u9762\u91CF\uFF1A`rg \"'(['a-z]+)'\" src/`\u3002\n * - **\u53EA\u7528\u4E8E\u7C7B\u578B\u4F4D\u7F6E\u7684\u5E38\u91CF**\uFF08\u5982 `PERSISTENCE_OPERATION`\uFF09\u5728\u8C03\u7528\u65B9\u7528\n *   `import type`\uFF1B**\u5728\u8FD0\u884C\u65F6\u6BD4\u8F83/\u6784\u9020\u4E2D\u4F7F\u7528\u7684**\uFF08\u5982 `WORKER_STATUS.ERROR`\u3001\n *   `TRACE_EVENT_TYPE.LIFECYCLE`\uFF09\u5FC5\u987B\u7528\u503C\u5BFC\u5165\uFF0C\u5426\u5219\u4F1A\u62A5 \"cannot be used as\n *   a value because it was imported using 'import type'\"\u3002\n * - **\u503C\u6D3E\u751F\u7C7B\u578B**\uFF1A`export type WorkerStatus = (typeof WORKER_STATUS)[keyof\n *   typeof WORKER_STATUS]`\u3002\u8FD9\u6837\u65B0\u589E\u679A\u4E3E\u5206\u652F\u65F6\u7C7B\u578B\u81EA\u52A8\u6536\u7A84\uFF0C\u7F16\u8BD1\u5668\u4F1A\u6307\u51FA\n *   \u6BCF\u4E2A\u9057\u6F0F\u7684 switch \u5206\u652F\u3002\n * - \u5206\u7EC4\u7684\u987A\u5E8F\uFF08\u72B6\u6001 / \u89D2\u8272 / \u540E\u7AEF / \u6D88\u606F\u7C7B\u578B / \u679A\u4E3E / \u524D\u7F00\uFF09\u4FDD\u6301\u7A33\u5B9A\uFF0C\u65B9\u4FBF\n *   \u7EF4\u62A4\u8005\u4E00\u773C\u5B9A\u4F4D\u3002\n */\n\n// ---- \u751F\u547D\u5468\u671F\u72B6\u6001 / \u89D2\u8272 / \u53EF\u89C1\u6027 ----\nexport const WORKER_STATUS = {\n  CONNECTING: 'connecting',\n  CONNECTED: 'connected',\n  DISCONNECTED: 'disconnected',\n  ERROR: 'error',\n} as const;\n\nexport const WORKER_ROLE = {\n  ACTIVE: 'active',\n  STANDBY: 'standby',\n} as const;\n\nexport const TAB_VISIBILITY = {\n  VISIBLE: 'visible',\n  HIDDEN: 'hidden',\n} as const;\n\n// ---- Worker \u540E\u7AEF\u6A21\u5F0F\u4E0E\u89E3\u6790\u7ED3\u679C\uFF08WorkerMode / WorkerBackend\uFF09----\nexport const WORKER_MODE = {\n  DEDICATED: 'dedicated',\n  SHARED: 'shared',\n  AUTO: 'auto',\n} as const;\n\nexport const WORKER_BACKEND = {\n  DEDICATED: 'dedicated',\n  SHARED: 'shared',\n  LOCAL: 'local',\n} as const;\n\n// ---- \u5B58\u50A8\u4E8B\u4EF6\u901A\u9053\u56DE\u9000 ----\nexport const CHANNEL_FALLBACK = {\n  NONE: 'none',\n  STORAGE_EVENT: 'storage-event',\n} as const;\n\n// ---- Worker / MessagePort / BroadcastChannel \u7684 EventTarget \u4E8B\u4EF6\u540D\u5224\u522B ----\n// MessageEvent.type\uFF08'message' / 'messageerror'\uFF09\u4E0E Worker \u4E0A\u7684 'error' \u4E8B\u4EF6\u540D\uFF0C\n// \u7528\u4E8E\u73AF\u5883\u9002\u914D\u5668\u63A5\u53E3\u7B7E\u540D\u4E0E\u6D4B\u8BD5\u66FF\u8EAB\u7684 addEventListener \u771F\u5047\u5206\u652F\u3002\nexport const EVENT_TYPE = {\n  MESSAGE: 'message',\n  MESSAGEERROR: 'messageerror',\n  ERROR: 'error',\n} as const;\n\n// ---- \u63A7\u5236\u5E73\u9762\u52A8\u4F5C\uFF08WorkerControlAction\uFF09----\nexport const CONTROL_ACTION = {\n  SUBSCRIBE: 'SUBSCRIBE',\n  UNSUBSCRIBE: 'UNSUBSCRIBE',\n  PUBLISH: 'PUBLISH',\n} as const;\n\n// ---- BroadcastChannel \u96C6\u7FA4\u6D88\u606F\u7C7B\u578B ----\nexport const CLUSTER_MESSAGE_TYPE = {\n  CONTROL: 'CONTROL',\n  EVENT: 'EVENT',\n  REGISTRY: 'REGISTRY',\n  ROUTE_RELEASED: 'ROUTE_RELEASED',\n} as const;\n\n// ---- \u547D\u540D\u7A7A\u95F4\u524D\u7F00\u4E0E\u4E8B\u4EF6\u540D ----\nexport const DEFAULT_STORAGE_PREFIX = 'cross-tab-worker-databus';\nexport const STORAGE_CHANNEL_PREFIX = `${DEFAULT_STORAGE_PREFIX}:channel:`;\nexport const TAB_ID_STORAGE_KEY = `${DEFAULT_STORAGE_PREFIX}:tab-id`;\nexport const PUBLICATION_EVENT = 'DATABUS_PUBLICATION';\n\n// ---- \u89C4\u8303 JSON \u4FE1\u5C01\u64CD\u4F5C\u7801 ----\nexport const PUBLICATION_ENVELOPE_OP = 'publication';\n\n// ---- trace \u4E8B\u4EF6\u7C7B\u578B ----\nexport const TRACE_EVENT_TYPE = {\n  LIFECYCLE: 'lifecycle',\n  STATUS: 'status',\n  SUBSCRIPTION: 'subscription',\n  COORDINATION: 'coordination',\n  ERROR: 'error',\n  RELIABILITY: 'reliability',\n  MESSAGE_METRICS: 'message_metrics',\n} as const;\n\n// ---- trace \u751F\u547D\u5468\u671F\u52A8\u4F5C ----\nexport const TRACE_LIFECYCLE_ACTION = {\n  START: 'start',\n  STOP: 'stop',\n  SUSPEND: 'suspend',\n  RESUME: 'resume',\n} as const;\n\n// ---- \u5185\u90E8 handler \u8C03\u7528\u6807\u7B7E\uFF08\u9694\u79BB\u5F02\u5E38\u65F6\u7684\u5206\u7C7B\u6765\u6E90\uFF09----\nexport const INVOKE_LABEL = {\n  DISPATCH: 'dispatch',\n  STATUS: 'status',\n  ERROR_HANDLER: 'error handler',\n} as const;\n\n// ---- trace \u6A21\u5F0F\uFF08DataBusTraceMode\uFF09----\nexport const TRACE_MODE = {\n  EVENTS: 'events',\n  METRICS: 'metrics',\n  ALL: 'all',\n} as const;\n\n// ---- trace \u9519\u8BEF\u6765\u6E90 ----\nexport const TRACE_ERROR_SOURCE = {\n  TRANSPORT: 'transport',\n  OPERATION: 'operation',\n} as const;\n\n// ---- reliability \u8BCA\u65AD\u64CD\u4F5C ----\nexport const RELIABILITY_OPERATION = {\n  TRANSPORT_RECOVERY: 'transport_recovery',\n  ROUTE_ACK: 'route_ack',\n  ROUTE_MIGRATION: 'route_migration',\n  // A re-election that recovered a stranded unconfirmed handoff (previous\n  // owner gone, ACK never arrived). Distinct from ROUTE_MIGRATION so trace\n  // consumers can tell recoveries apart from routine graceful handoffs.\n  ROUTE_MIGRATION_RECOVERY: 'route_migration_recovery',\n  PERSISTENCE_CLEANUP: 'persistence_cleanup',\n  PERSISTENCE_RETRY: 'persistence_retry',\n  DEDUP_SUPPRESSED: 'dedup_suppressed',\n} as const;\n\n// ---- \u81EA\u52A8\u6062\u590D\u5C1D\u8BD5\u7ED3\u679C ----\nexport const RECOVERY_OUTCOME = {\n  SCHEDULED: 'scheduled',\n  SUCCEEDED: 'succeeded',\n  FAILED: 'failed',\n  EXHAUSTED: 'exhausted',\n} as const;\n\n// ---- \u8BA2\u9605\u52A8\u4F5C ----\nexport const SUBSCRIPTION_ACTION = {\n  SUBSCRIBE: 'subscribe',\n  UNSUBSCRIBE: 'unsubscribe',\n} as const;\n\n// ---- \u56DE\u653E\u4FEE\u526A\u7B56\u7565 ----\nexport const PRUNE_STRATEGY = {\n  COUNT: 'count',\n  AGE: 'age',\n  BOTH: 'both',\n} as const;\n\n// ---- \u6301\u4E45\u5316\u64CD\u4F5C ----\nexport const PERSISTENCE_OPERATION = {\n  LOAD: 'load',\n  APPEND: 'append',\n  CLEAR: 'clear',\n  CLEAR_TOPIC: 'clearTopic',\n  CLEAR_BEFORE: 'clearBefore',\n} as const;\n\n// ---- \u6545\u969C\u6765\u6E90\uFF08DataBusFailureSource\uFF09----\nexport const FAILURE_SOURCE = {\n  TRANSPORT: 'transport',\n  PERSISTENCE: 'persistence',\n  DISPATCH: 'dispatch',\n} as const;\n\n// ---- \u5065\u5EB7\u5224\u5B9A\u72B6\u6001\uFF08DataBusHealthSummary['state']\uFF09----\nexport const HEALTH_STATE = {\n  STOPPED: 'stopped',\n  STARTING: 'starting',\n  HEALTHY: 'healthy',\n  RECOVERING: 'recovering',\n  SUSPENDED: 'suspended',\n  DEGRADED: 'degraded',\n} as const;\n\n// ---- WebSocket wire \u534F\u8BAE\u64CD\u4F5C\u7801 ----\nexport const WS_OP = {\n  SUBSCRIBE: 'subscribe',\n  UNSUBSCRIBE: 'unsubscribe',\n  PUBLISH: 'publish',\n  PUBLISH_BATCH: 'publishBatch',\n} as const;\n\n// ---- Centrifuge Worker \u8F93\u5165\u6D88\u606F\u7C7B\u578B ----\nexport const CENTRIFUGE_INPUT_TYPE = {\n  INIT: 'INIT',\n  SUBSCRIBE: 'SUBSCRIBE',\n  UNSUBSCRIBE: 'UNSUBSCRIBE',\n  PUBLISH: 'PUBLISH',\n  PUBLISH_BIN: 'PUBLISH_BIN',\n  PING: 'PING',\n  STOP: 'STOP',\n  TOKEN_RESPONSE: 'TOKEN_RESPONSE',\n  TOKEN_ERROR: 'TOKEN_ERROR',\n} as const;\n\n// ---- Centrifuge Worker \u8F93\u51FA\u6D88\u606F\u7C7B\u578B ----\nexport const CENTRIFUGE_OUTPUT_TYPE = {\n  STATUS: 'STATUS',\n  MESSAGE: 'MESSAGE',\n  MESSAGE_BIN: 'MESSAGE_BIN',\n  ERROR: 'ERROR',\n  TOKEN_REQUEST: 'TOKEN_REQUEST',\n  SESSION_REAPED: 'SESSION_REAPED',\n} as const;\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAkBA,mBAA4C;;;ACOrC,IAAM,gBAAgB;AAAA,EAC3B,YAAY;AAAA,EACZ,WAAW;AAAA,EACX,cAAc;AAAA,EACd,OAAO;AACT;AAwDO,IAAM,yBAAyB;AAC/B,IAAM,yBAAyB,GAAG,sBAAsB;AACxD,IAAM,qBAAqB,GAAG,sBAAsB;;;ADrDpD,SAAS,mBACd,QACA,OAAuB,CAAC,GACgB;AACxC,QAAM,CAAC,KAAK,MAAM,QAAI,uBAAiD,IAAI;AAC3E,8BAAU,MAAM;AAKd,UAAM,WAAW,OAAO;AACxB,WAAO,QAAQ;AACf,SAAK,SAAS,MAAM,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AACpC,WAAO,MAAM;AACX,aAAO,IAAI;AACX,WAAK,SAAS,KAAK;AAAA,IACrB;AAAA,EAGF,GAAG,IAAI;AACP,SAAO;AACT;AAUO,SAAS,wBACd,KACA,OACA,SACM;AACN,QAAM,iBAAa,qBAAO,OAAO;AACjC,aAAW,UAAU;AACrB,8BAAU,MAAM;AACd,QAAI,CAAC,IAAK;AACV,WAAO,IAAI,UAAU,OAAO,aAAW,WAAW,QAAQ,OAAO,CAAC;AAAA,EACpE,GAAG,CAAC,KAAK,KAAK,CAAC;AACjB;AAOO,SAAS,kBACd,KACc;AACd,QAAM,CAAC,QAAQ,SAAS,QAAI,uBAAuB,cAAc,UAAU;AAC3E,8BAAU,MAAM;AACd,QAAI,CAAC,KAAK;AACR,gBAAU,cAAc,UAAU;AAClC;AAAA,IACF;AACA,cAAU,IAAI,UAAU,CAAC;AACzB,WAAO,IAAI,SAAS,SAAS;AAAA,EAC/B,GAAG,CAAC,GAAG,CAAC;AACR,SAAO;AACT;AAWO,SAAS,kBACd,KACA,SAC6B;AAC7B,QAAM,CAAC,QAAQ,SAAS,QAAI,uBAAsC,IAAI;AACtE,QAAM,aAAa,SAAS,cAAc;AAC1C,8BAAU,MAAM;AACd,QAAI,CAAC,KAAK;AACR,gBAAU,IAAI;AACd;AAAA,IACF;AACA,UAAM,UAAU,MAAM,UAAU,IAAI,iBAAiB,CAAC;AACtD,YAAQ;AACR,UAAM,oBAAoB,IAAI,SAAS,OAAO;AAC9C,UAAM,mBAAmB,IAAI,QAAQ,OAAO;AAC5C,UAAM,QAAQ,aAAa,IAAI,YAAY,SAAS,UAAU,IAAI;AAClE,WAAO,MAAM;AACX,wBAAkB;AAClB,uBAAiB;AACjB,UAAI,MAAO,eAAc,KAAK;AAAA,IAChC;AAAA,EAIF,GAAG,CAAC,KAAK,UAAU,CAAC;AACpB,SAAO;AACT;",
+  "sourcesContent": ["/**\n * React hooks adapter for cross-tab-worker-databus.\n *\n * A thin, transport-agnostic bridge between the imperative CrossTabDataBus\n * API and React component lifecycles. React is an optional peer dependency \u2014\n * this module is a separate entry point so consumers who don't use React\n * never load it.\n *\n * - `useCrossTabDataBus` owns the bus lifecycle: created on mount, stopped on\n *   unmount. It is StrictMode-safe: the cleanup calls `instance.stop()`, so the\n *   double-invoked effect runs a full create \u2192 stop \u2192 create across *separate*\n *   instances. That is not the BFCache path and does not stand in for it \u2014\n *   page-hide takes `onSuspend`, which keeps this same bus, its `topicHandlers`\n *   and its replay buffers, and is reversed by resume. So suspend/resume\n *   coverage has to come from a real hide/show, not from this hook.\n * - `useCrossTabSubscription` attaches a message handler with automatic\n *   cleanup; the handler is read through a ref, so you can pass inline\n *   closures without resubscribing on every render.\n * - `useCrossTabStatus` mirrors `bus.onStatus()` into React state.\n * - `useCrossTabHealth` polls `bus.getHealthSummary()` into React state,\n *   with event-driven refreshes on status changes and errors.\n */\nimport { useEffect, useRef, useState } from 'react';\nimport type { DependencyList } from 'react';\nimport type { CrossTabDataBus, DataBusHealthSummary } from './core/data-bus';\nimport type { DataBusMessage, WorkerStatus } from './core/types';\nimport { WORKER_STATUS } from './utils/constants';\n\n/**\n * Create a CrossTabDataBus for the component's lifetime.\n *\n * @param create Factory invoked once per effect run. Return a fresh bus \u2014\n *   do not share a bus instance between effects, or StrictMode's\n *   mount \u2192 stop \u2192 mount cycle will stop the shared instance out from\n *   under the second mount.\n * @param deps Re-create the bus when these change (default: create once).\n * @returns The active bus, or `null` before the first effect has run (SSR\n *   and the initial render).\n */\nexport function useCrossTabDataBus<TConfig, TData>(\n  create: () => CrossTabDataBus<TConfig, TData>,\n  deps: DependencyList = []\n): CrossTabDataBus<TConfig, TData> | null {\n  const [bus, setBus] = useState<CrossTabDataBus<TConfig, TData> | null>(null);\n  useEffect(() => {\n    // No \"is this effect still current?\" check is needed: React runs an\n    // effect's cleanup before its next invocation, and nothing between the\n    // lines below yields, so `create()` cannot be interleaved with a newer\n    // mount and this cleanup always stops the instance its own run created.\n    const instance = create();\n    setBus(instance);\n    void instance.ready().catch(() => {});\n    return () => {\n      setBus(null);\n      void instance.stop();\n    };\n    // The factory is intentionally not a dependency: callers pass an inline\n    // closure and key recreation through `deps` instead.\n  }, deps);\n  return bus;\n}\n\n/**\n * Subscribe to `topic` for the component's lifetime. The handler is read\n * through a ref on each delivery, so inline closures are safe without\n * unsubscribing/resubscribing on re-renders.\n *\n * When `bus` is null (not yet created) the subscription is queued until the\n * bus appears \u2014 the bus itself queues it until the transport is ready.\n */\nexport function useCrossTabSubscription<TConfig, TData>(\n  bus: CrossTabDataBus<TConfig, TData> | null,\n  topic: string,\n  handler: (message: DataBusMessage<TData>) => void\n): void {\n  const handlerRef = useRef(handler);\n  handlerRef.current = handler;\n  useEffect(() => {\n    if (!bus) return;\n    return bus.subscribe(topic, message => handlerRef.current(message));\n  }, [bus, topic]);\n}\n\n/**\n * Mirror the bus connection status into React state. Reports the live value\n * via `onStatus` and reads the current value synchronously whenever `bus`\n * changes identity.\n */\nexport function useCrossTabStatus<TConfig, TData>(\n  bus: CrossTabDataBus<TConfig, TData> | null\n): WorkerStatus {\n  const [status, setStatus] = useState<WorkerStatus>(WORKER_STATUS.CONNECTING);\n  useEffect(() => {\n    if (!bus) {\n      setStatus(WORKER_STATUS.CONNECTING);\n      return;\n    }\n    setStatus(bus.getStatus());\n    return bus.onStatus(setStatus);\n  }, [bus]);\n  return status;\n}\n\n/**\n * Mirror the bus health summary into React state.\n *\n * `getHealthSummary()` is a snapshot, not an event stream, so the hook polls\n * it on an interval (default 1000 ms) and refreshes immediately on status\n * changes and errors. Pass `intervalMs: 0` to rely on event-driven refreshes\n * only; changing the interval replaces the timer without recreating the bus.\n * Returns `null` while the bus has not been created yet.\n */\nexport function useCrossTabHealth<TConfig, TData>(\n  bus: CrossTabDataBus<TConfig, TData> | null,\n  options?: { intervalMs?: number }\n): DataBusHealthSummary | null {\n  const [health, setHealth] = useState<DataBusHealthSummary | null>(null);\n  const intervalMs = options?.intervalMs ?? 1_000;\n  useEffect(() => {\n    if (!bus) {\n      setHealth(null);\n      return;\n    }\n    const refresh = () => setHealth(bus.getHealthSummary());\n    refresh();\n    const unsubscribeStatus = bus.onStatus(refresh);\n    const unsubscribeError = bus.onError(refresh);\n    const timer = intervalMs > 0 ? setInterval(refresh, intervalMs) : null;\n    return () => {\n      unsubscribeStatus();\n      unsubscribeError();\n      if (timer) clearInterval(timer);\n    };\n    // Depend on the normalized cadence rather than the options object so inline\n    // option literals do not restart the effect on every render, while a real\n    // intervalMs change still replaces the polling timer.\n  }, [bus, intervalMs]);\n  return health;\n}\n", "/**\n * \u516C\u5171\u5B57\u7B26\u4E32\u5E38\u91CF \u2014\u2014 \u751F\u547D\u5468\u671F\u72B6\u6001\u3001\u89D2\u8272\u3001\u63A7\u5236\u52A8\u4F5C\u3001\u534F\u8BAE\u6D88\u606F\u7C7B\u578B\u3001\u679A\u4E3E\u4E0E\n * \u547D\u540D\u7A7A\u95F4\u524D\u7F00\u3002\n *\n * \u6240\u6709\u8FD0\u884C\u65F6\u4F7F\u7528\u7684\u5B57\u7B26\u4E32\u5B57\u9762\u91CF\u96C6\u4E2D\u5728\u6B64\u4E00\u4EFD\u503C\uFF0C\u7C7B\u578B\u5B9A\u4E49\uFF08src/core/types.ts\n * \u7B49\uFF09\u901A\u8FC7 `(typeof X)[keyof typeof X]` \u4ECE\u8FD9\u4E9B\u5E38\u91CF\u6D3E\u751F\uFF0C\u6BD4\u8F83/switch \u5904\u5F15\u7528\n * \u540C\u4E00\u5BF9\u8C61\u6210\u5458\u3002\u8FD9\u6837\u65E2\u80FD\u6D88\u9664\u6563\u843D\u5728\u5404\u6587\u4EF6\u91CC\u7684\u91CD\u590D\u5B57\u7B26\u4E32\uFF08\u907F\u514D\u5927\u5C0F\u5199\u4E0D\u7EDF\u4E00\n * \u6216\u7B14\u8BEF\uFF09\uFF0C\u53C8\u4FDD\u8BC1\u7C7B\u578B\u4E0E\u503C\u6C38\u4E0D\u9519\u4F4D\u3002\n *\n * ## \u4F7F\u7528\u7EA6\u5B9A\n *\n * - **\u65B0\u589E\u6216\u4FEE\u6539\u5B57\u7B26\u4E32\u5B57\u9762\u91CF\u65F6\uFF0C\u5148\u5230\u8FD9\u91CC\u67E5\u627E/\u589E\u8865\uFF0C\u4E0D\u8981\u5728\u4E1A\u52A1\u6587\u4EF6\u91CC\u76F4\u63A5\u5199\n *   \u9B54\u6CD5\u5B57\u7B26\u4E32\u3002** \u626B\u63CF\u6B8B\u7559\u5B57\u9762\u91CF\uFF1A`rg \"'(['a-z]+)'\" src/`\u3002\n * - **\u53EA\u7528\u4E8E\u7C7B\u578B\u4F4D\u7F6E\u7684\u5E38\u91CF**\uFF08\u5373\u53EA\u51FA\u73B0\u5728 `typeof X[keyof typeof X]` \u8FD9\u7C7B\u6D3E\u751F\u91CC\u3001\n *   \u4ECE\u4E0D\u53C2\u4E0E\u8FD0\u884C\u65F6\u6BD4\u8F83\u7684\uFF09\u5728\u8C03\u7528\u65B9\u7528 `import type`\uFF1B**\u5728\u8FD0\u884C\u65F6\u6BD4\u8F83/\u6784\u9020\u4E2D\u4F7F\u7528\u7684**\n *   \uFF08\u5982 `WORKER_STATUS.ERROR`\u3001`TRACE_EVENT_TYPE.LIFECYCLE`\u3001\n *   `PERSISTENCE_OPERATION.APPEND`\uFF09\u5FC5\u987B\u7528\u503C\u5BFC\u5165\uFF0C\u5426\u5219\u4F1A\u62A5 \"cannot be used as\n *   a value because it was imported using 'import type'\"\u3002`PERSISTENCE_OPERATION`\n *   \u5C5E\u4E8E\u540E\u8005\u800C\u4E0D\u662F\u7C7B\u578B\u4FA7\u7684\u4F8B\u5B50\uFF1A`replay-manager.ts` \u4EE5\u503C\u5BFC\u5165\u5B83\uFF0C\u5E76\u628A\u5B83\u7684\u6210\u5458\u4F5C\u4E3A\n *   `withPersistenceRetry` \u7684\u7B2C\u4E00\u4E2A\u5B9E\u53C2\u4F20\u8FDB\u53BB\u3002\n * - **\u503C\u6D3E\u751F\u7C7B\u578B**\uFF1A`export type WorkerStatus = (typeof WORKER_STATUS)[keyof\n *   typeof WORKER_STATUS]`\u3002\u8FD9\u6837\u65B0\u589E\u679A\u4E3E\u5206\u652F\u65F6\u7C7B\u578B\u81EA\u52A8\u6536\u7A84\uFF0C\u7F16\u8BD1\u5668\u4F1A\u6307\u51FA\n *   \u6BCF\u4E2A\u9057\u6F0F\u7684 switch \u5206\u652F\u3002\n * - \u5206\u7EC4\u7684\u987A\u5E8F\uFF08\u72B6\u6001 / \u89D2\u8272 / \u540E\u7AEF / \u6D88\u606F\u7C7B\u578B / \u679A\u4E3E / \u524D\u7F00\uFF09\u4FDD\u6301\u7A33\u5B9A\uFF0C\u65B9\u4FBF\n *   \u7EF4\u62A4\u8005\u4E00\u773C\u5B9A\u4F4D\u3002\n */\n\n// ---- \u751F\u547D\u5468\u671F\u72B6\u6001 / \u89D2\u8272 / \u53EF\u89C1\u6027 ----\nexport const WORKER_STATUS = {\n  CONNECTING: 'connecting',\n  CONNECTED: 'connected',\n  DISCONNECTED: 'disconnected',\n  ERROR: 'error',\n} as const;\n\nexport const WORKER_ROLE = {\n  ACTIVE: 'active',\n  STANDBY: 'standby',\n} as const;\n\nexport const TAB_VISIBILITY = {\n  VISIBLE: 'visible',\n  HIDDEN: 'hidden',\n} as const;\n\n// ---- Worker \u540E\u7AEF\u6A21\u5F0F\u4E0E\u89E3\u6790\u7ED3\u679C\uFF08WorkerMode / WorkerBackend\uFF09----\nexport const WORKER_MODE = {\n  DEDICATED: 'dedicated',\n  SHARED: 'shared',\n  AUTO: 'auto',\n} as const;\n\nexport const WORKER_BACKEND = {\n  DEDICATED: 'dedicated',\n  SHARED: 'shared',\n  LOCAL: 'local',\n} as const;\n\n// ---- \u5B58\u50A8\u4E8B\u4EF6\u901A\u9053\u56DE\u9000 ----\nexport const CHANNEL_FALLBACK = {\n  NONE: 'none',\n  STORAGE_EVENT: 'storage-event',\n} as const;\n\n// ---- Worker / MessagePort / BroadcastChannel \u7684 EventTarget \u4E8B\u4EF6\u540D\u5224\u522B ----\n// MessageEvent.type\uFF08'message' / 'messageerror'\uFF09\u4E0E Worker \u4E0A\u7684 'error' \u4E8B\u4EF6\u540D\uFF0C\n// \u7528\u4E8E\u73AF\u5883\u9002\u914D\u5668\u63A5\u53E3\u7B7E\u540D\u4E0E\u6D4B\u8BD5\u66FF\u8EAB\u7684 addEventListener \u771F\u5047\u5206\u652F\u3002\nexport const EVENT_TYPE = {\n  MESSAGE: 'message',\n  MESSAGEERROR: 'messageerror',\n  ERROR: 'error',\n} as const;\n\n// ---- \u63A7\u5236\u5E73\u9762\u52A8\u4F5C\uFF08WorkerControlAction\uFF09----\nexport const CONTROL_ACTION = {\n  SUBSCRIBE: 'SUBSCRIBE',\n  UNSUBSCRIBE: 'UNSUBSCRIBE',\n  PUBLISH: 'PUBLISH',\n} as const;\n\n// ---- BroadcastChannel \u96C6\u7FA4\u6D88\u606F\u7C7B\u578B ----\nexport const CLUSTER_MESSAGE_TYPE = {\n  CONTROL: 'CONTROL',\n  EVENT: 'EVENT',\n  REGISTRY: 'REGISTRY',\n  ROUTE_RELEASED: 'ROUTE_RELEASED',\n} as const;\n\n// ---- \u547D\u540D\u7A7A\u95F4\u524D\u7F00\u4E0E\u4E8B\u4EF6\u540D ----\nexport const DEFAULT_STORAGE_PREFIX = 'cross-tab-worker-databus';\nexport const STORAGE_CHANNEL_PREFIX = `${DEFAULT_STORAGE_PREFIX}:channel:`;\nexport const TAB_ID_STORAGE_KEY = `${DEFAULT_STORAGE_PREFIX}:tab-id`;\nexport const PUBLICATION_EVENT = 'DATABUS_PUBLICATION';\n\n// ---- \u89C4\u8303 JSON \u4FE1\u5C01\u64CD\u4F5C\u7801 ----\nexport const PUBLICATION_ENVELOPE_OP = 'publication';\n\n// ---- trace \u4E8B\u4EF6\u7C7B\u578B ----\nexport const TRACE_EVENT_TYPE = {\n  LIFECYCLE: 'lifecycle',\n  STATUS: 'status',\n  SUBSCRIPTION: 'subscription',\n  COORDINATION: 'coordination',\n  ERROR: 'error',\n  RELIABILITY: 'reliability',\n  MESSAGE_METRICS: 'message_metrics',\n} as const;\n\n// ---- trace \u751F\u547D\u5468\u671F\u52A8\u4F5C ----\nexport const TRACE_LIFECYCLE_ACTION = {\n  START: 'start',\n  STOP: 'stop',\n  SUSPEND: 'suspend',\n  RESUME: 'resume',\n} as const;\n\n// ---- \u5185\u90E8 handler \u8C03\u7528\u6807\u7B7E\uFF08\u9694\u79BB\u5F02\u5E38\u65F6\u7684\u5206\u7C7B\u6765\u6E90\uFF09----\nexport const INVOKE_LABEL = {\n  DISPATCH: 'dispatch',\n  STATUS: 'status',\n  ERROR_HANDLER: 'error handler',\n} as const;\n\n// ---- trace \u6A21\u5F0F\uFF08DataBusTraceMode\uFF09----\nexport const TRACE_MODE = {\n  EVENTS: 'events',\n  METRICS: 'metrics',\n  ALL: 'all',\n} as const;\n\n// ---- trace \u9519\u8BEF\u6765\u6E90 ----\nexport const TRACE_ERROR_SOURCE = {\n  TRANSPORT: 'transport',\n  OPERATION: 'operation',\n} as const;\n\n// ---- reliability \u8BCA\u65AD\u64CD\u4F5C ----\nexport const RELIABILITY_OPERATION = {\n  TRANSPORT_RECOVERY: 'transport_recovery',\n  ROUTE_ACK: 'route_ack',\n  ROUTE_MIGRATION: 'route_migration',\n  // A re-election that recovered a stranded unconfirmed handoff (previous\n  // owner gone, ACK never arrived). Distinct from ROUTE_MIGRATION so trace\n  // consumers can tell recoveries apart from routine graceful handoffs.\n  ROUTE_MIGRATION_RECOVERY: 'route_migration_recovery',\n  PERSISTENCE_CLEANUP: 'persistence_cleanup',\n  PERSISTENCE_RETRY: 'persistence_retry',\n  DEDUP_SUPPRESSED: 'dedup_suppressed',\n} as const;\n\n// ---- \u81EA\u52A8\u6062\u590D\u5C1D\u8BD5\u7ED3\u679C ----\nexport const RECOVERY_OUTCOME = {\n  SCHEDULED: 'scheduled',\n  SUCCEEDED: 'succeeded',\n  FAILED: 'failed',\n  EXHAUSTED: 'exhausted',\n} as const;\n\n// ---- \u8BA2\u9605\u52A8\u4F5C ----\nexport const SUBSCRIPTION_ACTION = {\n  SUBSCRIBE: 'subscribe',\n  UNSUBSCRIBE: 'unsubscribe',\n} as const;\n\n// ---- \u56DE\u653E\u4FEE\u526A\u7B56\u7565 ----\nexport const PRUNE_STRATEGY = {\n  COUNT: 'count',\n  AGE: 'age',\n  BOTH: 'both',\n} as const;\n\n// ---- \u6301\u4E45\u5316\u64CD\u4F5C ----\nexport const PERSISTENCE_OPERATION = {\n  LOAD: 'load',\n  APPEND: 'append',\n  CLEAR: 'clear',\n  CLEAR_TOPIC: 'clearTopic',\n  CLEAR_BEFORE: 'clearBefore',\n} as const;\n\n// ---- \u6545\u969C\u6765\u6E90\uFF08DataBusFailureSource\uFF09----\nexport const FAILURE_SOURCE = {\n  TRANSPORT: 'transport',\n  PERSISTENCE: 'persistence',\n  DISPATCH: 'dispatch',\n} as const;\n\n// ---- \u5065\u5EB7\u5224\u5B9A\u72B6\u6001\uFF08DataBusHealthSummary['state']\uFF09----\nexport const HEALTH_STATE = {\n  STOPPED: 'stopped',\n  STARTING: 'starting',\n  HEALTHY: 'healthy',\n  RECOVERING: 'recovering',\n  SUSPENDED: 'suspended',\n  DEGRADED: 'degraded',\n} as const;\n\n// ---- WebSocket wire \u534F\u8BAE\u64CD\u4F5C\u7801 ----\nexport const WS_OP = {\n  SUBSCRIBE: 'subscribe',\n  UNSUBSCRIBE: 'unsubscribe',\n  PUBLISH: 'publish',\n  PUBLISH_BATCH: 'publishBatch',\n} as const;\n\n// ---- Centrifuge Worker \u8F93\u5165\u6D88\u606F\u7C7B\u578B ----\nexport const CENTRIFUGE_INPUT_TYPE = {\n  INIT: 'INIT',\n  SUBSCRIBE: 'SUBSCRIBE',\n  UNSUBSCRIBE: 'UNSUBSCRIBE',\n  PUBLISH: 'PUBLISH',\n  PUBLISH_BIN: 'PUBLISH_BIN',\n  PING: 'PING',\n  STOP: 'STOP',\n  TOKEN_RESPONSE: 'TOKEN_RESPONSE',\n  TOKEN_ERROR: 'TOKEN_ERROR',\n} as const;\n\n// ---- Centrifuge Worker \u8F93\u51FA\u6D88\u606F\u7C7B\u578B ----\nexport const CENTRIFUGE_OUTPUT_TYPE = {\n  STATUS: 'STATUS',\n  MESSAGE: 'MESSAGE',\n  MESSAGE_BIN: 'MESSAGE_BIN',\n  ERROR: 'ERROR',\n  TOKEN_REQUEST: 'TOKEN_REQUEST',\n  SESSION_REAPED: 'SESSION_REAPED',\n} as const;\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAsBA,mBAA4C;;;ACMrC,IAAM,gBAAgB;AAAA,EAC3B,YAAY;AAAA,EACZ,WAAW;AAAA,EACX,cAAc;AAAA,EACd,OAAO;AACT;AAwDO,IAAM,yBAAyB;AAC/B,IAAM,yBAAyB,GAAG,sBAAsB;AACxD,IAAM,qBAAqB,GAAG,sBAAsB;;;ADpDpD,SAAS,mBACd,QACA,OAAuB,CAAC,GACgB;AACxC,QAAM,CAAC,KAAK,MAAM,QAAI,uBAAiD,IAAI;AAC3E,8BAAU,MAAM;AAKd,UAAM,WAAW,OAAO;AACxB,WAAO,QAAQ;AACf,SAAK,SAAS,MAAM,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AACpC,WAAO,MAAM;AACX,aAAO,IAAI;AACX,WAAK,SAAS,KAAK;AAAA,IACrB;AAAA,EAGF,GAAG,IAAI;AACP,SAAO;AACT;AAUO,SAAS,wBACd,KACA,OACA,SACM;AACN,QAAM,iBAAa,qBAAO,OAAO;AACjC,aAAW,UAAU;AACrB,8BAAU,MAAM;AACd,QAAI,CAAC,IAAK;AACV,WAAO,IAAI,UAAU,OAAO,aAAW,WAAW,QAAQ,OAAO,CAAC;AAAA,EACpE,GAAG,CAAC,KAAK,KAAK,CAAC;AACjB;AAOO,SAAS,kBACd,KACc;AACd,QAAM,CAAC,QAAQ,SAAS,QAAI,uBAAuB,cAAc,UAAU;AAC3E,8BAAU,MAAM;AACd,QAAI,CAAC,KAAK;AACR,gBAAU,cAAc,UAAU;AAClC;AAAA,IACF;AACA,cAAU,IAAI,UAAU,CAAC;AACzB,WAAO,IAAI,SAAS,SAAS;AAAA,EAC/B,GAAG,CAAC,GAAG,CAAC;AACR,SAAO;AACT;AAWO,SAAS,kBACd,KACA,SAC6B;AAC7B,QAAM,CAAC,QAAQ,SAAS,QAAI,uBAAsC,IAAI;AACtE,QAAM,aAAa,SAAS,cAAc;AAC1C,8BAAU,MAAM;AACd,QAAI,CAAC,KAAK;AACR,gBAAU,IAAI;AACd;AAAA,IACF;AACA,UAAM,UAAU,MAAM,UAAU,IAAI,iBAAiB,CAAC;AACtD,YAAQ;AACR,UAAM,oBAAoB,IAAI,SAAS,OAAO;AAC9C,UAAM,mBAAmB,IAAI,QAAQ,OAAO;AAC5C,UAAM,QAAQ,aAAa,IAAI,YAAY,SAAS,UAAU,IAAI;AAClE,WAAO,MAAM;AACX,wBAAkB;AAClB,uBAAiB;AACjB,UAAI,MAAO,eAAc,KAAK;AAAA,IAChC;AAAA,EAIF,GAAG,CAAC,KAAK,UAAU,CAAC;AACpB,SAAO;AACT;",
   "names": []
 }

package/dist/cjs/index.cjs

@@ -459,8 +459,8 @@ var BatchingStorageWriter = class {
   retryHandle = null;
   retryDelayMs = INITIAL_RETRY_DELAY_MS;
   /** 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. */
+   * Test-only as a reader: `flush()` tests `pending.size` directly rather than
+   * going through this getter, so it is not part of the drain decision. */
   get pendingSize() {
     return this.pending.size;
   }
@@ -749,8 +749,9 @@ var WorkerClusterRuntime = class {
   // Topics this tab has subscribed to (local interest, plaintext).
   subscribedTopics = /* @__PURE__ */ new Set();
   // Topics assigned to this Worker as owner (topicKey → topic). Authoritative:
-  // membership drives isAssigned() and load. Grows only via CONTROL/SUBSCRIBE
-  // (or local self-subscribe), never via the reverse cache.
+  // membership drives isAssigned() and load. Grown by exactly three writers —
+  // CONTROL/SUBSCRIBE, ROUTE_RELEASED (completing a handoff this worker accepted),
+  // and local self-subscribe — and never by the reverse cache.
   assignedTopics = /* @__PURE__ */ new Map();
   routeOwnerCache = /* @__PURE__ */ new Map();
   routeOwnerCacheMax;
@@ -1144,9 +1145,12 @@ var WorkerClusterRuntime = class {
       windowMs,
       messageCount: this.throughputWindow.messageCount,
       byteCount: this.throughputWindow.byteCount,
-      // How much later the heartbeat landed than its nominal interval. This
-      // window is anchored at the previous writeRecord (one heartbeat tick),
-      // so a starved event loop stretches windowMs past the interval and the
+      // How much later the last record write landed relative to a nominal
+      // heartbeat interval. The window is anchored at the previous writeRecord,
+      // which the heartbeat tick causes but activation, a status change, a
+      // visibility change and a load update also cause — so a worker writing on
+      // any of those shorter paths yields a small window and a clamped zero.
+      // A starved event loop stretches the window past the interval, and the
       // positive excess is the scheduling-overrun signal.
       overrunMs: Math.max(0, windowMs - this.heartbeatIntervalMs),
       sampledAt: now
@@ -1311,11 +1315,13 @@ var WorkerClusterRuntime = class {
     else this.handlers.onControl(message.action, message.topic, message.data);
     if (message.action !== CONTROL_ACTION.PUBLISH) this.updateLoad();
   }
-  /**
-   * When this worker is the previous owner in a graceful handoff and the new
-   * owner asks us to unsubscribe, release the old transport subscription and
-   * ACK the handoff with ROUTE_RELEASED. Returns true when the message was a
-   * handoff release (the generic CONTROL dispatch must not run as well).
+  /** Drop this worker's ownership of the topic, then — only when this worker is
+   * the previous owner in a graceful handoff and the new owner is asking us to
+   * unsubscribe — release the old transport subscription and ACK the handoff with
+   * ROUTE_RELEASED. The ownership delete runs for *every* CONTROL/UNSUBSCRIBE,
+   * before the handoff test; the handoff legs below do not gate it. Returns true
+   * when the message was a handoff release (the generic CONTROL dispatch must not
+   * run as well).
    */
   releaseHandoffOnUnsubscribe(message) {
     this.assignedTopics.delete(message.topicKey);
@@ -1537,7 +1543,10 @@ var WorkerClusterRuntime = class {
     }
     return Array.from(subscribers);
   }
-  /** Read the current route for `topicKey`, returning null when no storage layer exists. */
+  /** Read the current route for `topicKey`. With a storage layer this returns
+   * the durable route, or null when none is recorded. Without one (degraded
+   * mode) it returns the synthesized local route from `buildLocalRoute`, which
+   * is itself null unless this worker actually holds the topic. */
   readRoute(topicKey) {
     if (!this.storage) return this.buildLocalRoute(topicKey);
     return readJson(this.storage, this.routeStorageKey(topicKey));
@@ -1618,8 +1627,9 @@ var WorkerClusterRuntime = class {
    * @param notify — when true, broadcast a REGISTRY nudge so peers reconcile
    *   immediately instead of waiting for the next heartbeat. False on the
    *   periodic heartbeat tick (peers will notice on their own heartbeat) to
-   *   avoid a REGISTRY storm every 3 s; true on status/role changes that
-   *   peers should observe promptly. */
+   *   avoid a REGISTRY storm every 3 s. Which sites pass what: activation,
+   *   status, visibility and load changes pass true; the heartbeat tick and a
+   *   role change pass false. */
   writeRecord(notify) {
     const now = this.environment.now();
     const sample = this.loadWeighting !== void 0 ? this.sampleThroughput(now) : void 0;
@@ -1655,10 +1665,15 @@ var WorkerClusterRuntime = class {
    * Despite the name, this is NOT a cache lookup — it unconditionally writes
    * the `topicKey → topic` pair. Hashing is cheap enough that a caller needing
    * the key should always call this rather than check `knownTopics` first;
-   * the cache's FIFO eviction below keeps it bounded. Only `isAssigned`
-   * deliberately bypasses this (it must not pollute the cache on a read-only
-   * query), so if you add a new call site, prefer `rememberTopic` unless you
-   * have the same "read-only query" reason.
+   * the cache's FIFO eviction below keeps it bounded. Two sites deliberately
+   * bypass it, and for the same kind of reason — neither may write a plaintext
+   * into the reverse cache before it is authorized: `isAssigned` re-derives the
+   * key as a read-only query, and the `ROUTE_RELEASED` handler hashes the
+   * frame's own `topic` only to compare it against `topicKey`, on a channel
+   * where that field is attacker-controlled until the comparison passes. (The
+   * `CONTROL` handler performs the same re-derivation but then *does* call this
+   * method, so it is not a bypass.) If you add a new call site, prefer
+   * `rememberTopic` unless you have one of those reasons.
    */
   rememberTopic(topic) {
     const topicKey = createOpaqueKey(topic);
@@ -1732,8 +1747,10 @@ var DataBusTraceReporter = class {
     this.asyncSink = options?.asyncSink ?? false;
     this.now = now;
   }
-  /** Start the periodic metrics flush interval. No-op when mode is 'events'
-   * (no metrics to emit), when disabled, or when already running. */
+  /** Start the periodic metrics flush interval. Only the `!enabled` return is a
+   * true no-op: in 'events' mode, or with an interval already armed, it returns
+   * without arming anything but has already cleared `stopped` one statement
+   * earlier — which is what re-opens the event stream after a `stop()`. */
   start() {
     if (!this.enabled) return;
     this.stopped = false;
@@ -1840,9 +1857,11 @@ var DataBusTraceReporter = class {
   recordDedupSuppressed() {
     if (this.metricsActive) this.dedupSuppressed += 1;
   }
-  /** 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. */
+  /** True when metrics recording is active: enabled, not stopped, and the mode
+   * includes metrics. Extracted so the seven readers — `getMetrics`, the five
+   * `record*` methods and `flush` — share one guard instead of repeating it.
+   * The `!stopped` term is part of the contract, not a bonus: `event()` does not
+   * go through this getter and gates on `stopped` itself. */
   get metricsActive() {
     return this.enabled && !this.stopped && this.mode !== TRACE_MODE.EVENTS;
   }
@@ -2106,7 +2125,8 @@ var ReplayManager = class {
       }
     }
   }
-  /** Clear replay history for one exact topic, including durable storage. */
+  /** Clear replay history for one exact topic, and for its durable history when
+   * the injected adapter provides the optional `clearTopic`. */
   async clearTopic(topic) {
     if (!this.buffers) return;
     const clearing = this.persistence?.clearTopic ? this.withPersistenceRetry(PERSISTENCE_OPERATION.CLEAR_TOPIC, () => this.persistence.clearTopic(topic)) : null;
@@ -2485,7 +2505,7 @@ var DedupManager = class {
 };
 
 // src/core/version.ts
-var SDK_VERSION = true ? "0.21.12" : "";
+var SDK_VERSION = true ? "0.21.13" : "";
 
 // src/core/data-bus.ts
 var DEFAULT_REPLAY_MAX_PER_TOPIC = 100;
@@ -3016,7 +3036,10 @@ var CrossTabDataBus = class {
   async clearReplay() {
     await this.replayManager.clearAll();
   }
-  /** Clear replay history for one exact topic, including durable storage. */
+  /** Clear replay history for one exact topic and, when the persistence adapter
+   * implements `clearTopic`, its durable history too — an adapter without that
+   * optional method leaves the persisted rows in place, exactly as `clearReplay`
+   * does. */
   async clearReplayTopic(topic) {
     await this.replayManager.clearTopic(topic);
   }
@@ -3411,9 +3434,14 @@ var CrossTabDataBus = class {
     });
   }
   /** Emit the coordination trace snapshot from the current cluster state.
-   * Called after a transport opens (start and recovery), when the role and
-   * route picture has settled — the synchronous pre-open snapshot would see no
-   * routes because their writes are still coalesced in the batch writer. */
+   * Called once per successful `start()`: `reopenTransport()`'s settle arms do not
+   * emit, so a recovery produces no second snapshot. It runs after the opening
+   * resolves — and not because a pre-open read would see no routes, which is the
+   * wrong mechanism and was the shipped claim until it was measured: a snapshot
+   * taken with the opening still unresolved already listed the route, its
+   * confirmation and both tabs' worker records, because
+   * `BatchingStorageWriter` serves pending writes on read (`storage-batch.ts:79-82`
+   * for `getItem`, `:143-155` for the `keys()` union that `readAllByPrefix` uses). */
   emitCoordinationTrace() {
     const snapshot = this.cluster.getSnapshot();
     this.trace.event({
@@ -3607,7 +3635,13 @@ var CrossTabDataBus = class {
   }
   /**
    * Ensure the DataBus is started, throwing if no initialConfig was provided.
-   * Called automatically by subscribe/publish/ready when autoStart is true.
+   * subscribe/publish/ready call this *unconditionally*: the gate is the
+   * `hasInitialConfig` check below, not the `autoStart` option. `autoStart`
+   * participates in exactly one place, the constructor's
+   * `if (autoStart ?? this.hasInitialConfig)`, where it overrides the default rather
+   * than enabling a later path — so `autoStart: true` with no `initialConfig` throws
+   * from the constructor. `docs/configuration.md`'s "`true` when `initialConfig` is
+   * provided" row describes that single site.
    */
   ensureStarted() {
     if (this.started) return;
@@ -4038,7 +4072,8 @@ var WebSocketTransport = class {
     this.subscribedTopics.add(topic);
     this.sendFrame({ op: WS_OP.SUBSCRIBE, topic });
   }
-  /** Idempotent: unsubscribing an unknown topic is a no-op. */
+  /** Idempotent for local tracking: an unknown topic has nothing to delete, but
+   * the UNSUBSCRIBE frame is still sent, exactly as SUBSCRIBE is re-sent above. */
   unsubscribe(topic) {
     this.subscribedTopics.delete(topic);
     this.sendFrame({ op: WS_OP.UNSUBSCRIBE, topic });
@@ -4128,8 +4163,14 @@ var WebSocketTransport = class {
     }
   }
   /** Send one JSON frame. Frames are dropped with an `onError` report when
-   * the socket is not open — subscribe frames are re-sent on open, so the
-   * only real loss is a publish during a disconnect window. */
+   * the socket is not open. A dropped SUBSCRIBE is recovered — `onopen`
+   * re-asserts every topic in `subscribedTopics` — but the other two are not:
+   * a dropped PUBLISH is the documented at-most-once loss, and a dropped
+   * UNSUBSCRIBE is the quieter one, because `unsubscribe()` has already deleted
+   * the topic from that set, so no later re-assert resends it and the server
+   * keeps streaming a channel the app left. Through the DataBus neither of the
+   * two is reachable while closed — `runTransport()` queues both operations
+   * behind recovery — so this reads as a direct-transport-contract note. */
   sendFrame(payload) {
     if (this.socket?.readyState !== WS_OPEN) {
       this.handlers?.onError(new Error(`WebSocket is not open; dropped "${payload.op}" frame.`));
@@ -4165,8 +4206,11 @@ var WebSocketTransport = class {
     this.socket.send(frame.buffer);
   }
   /** Parse a server frame. Only objects carrying a string `topic` are
-   * publications; malformed JSON and unknown shapes are ignored so a chatty
-   * server cannot crash the message path. */
+   * publications, and unknown shapes are dropped silently so a chatty server
+   * cannot crash the message path. Malformed JSON is *not* dropped silently: it
+   * goes to `handlers.onError` as "WebSocket server sent a non-JSON frame.",
+   * which also records it in the bus's last-failure diagnostics. Neither case
+   * throws out of the socket listener. */
   async handleMessage(raw) {
     if (typeof Blob !== "undefined" && raw instanceof Blob) {
       const socket = this.socket;