@demlik/tea 0.1.0 → 0.1.2

package/dist/{chunk-PYOCUBQJ.js → chunk-LP7VQBRG.js}

@@ -1,4 +1,4 @@
-import { historyTracker } from './chunk-CMG2KMWX.js';
+import { historyTracker } from './chunk-MMH7CW5K.js';
 
 // src/extension/bridge.ts
 function bridgeRuntime(runtime, { channel, serialize, historySize }) {
@@ -6,7 +6,7 @@ function bridgeRuntime(runtime, { channel, serialize, historySize }) {
   const hydrateType = `${channel}:hydrate`;
   const project = serialize ?? ((state) => state);
   const tracker = historySize !== void 0 && historySize > 0 ? historyTracker(runtime, historySize) : null;
-  const unobserve = runtime.observe((msg, state) => {
+  const sendBroadcast = (msg, state) => {
     const envelope = {
       type: channel,
       msg,
@@ -14,6 +14,12 @@ function bridgeRuntime(runtime, { channel, serialize, historySize }) {
     };
     chrome.runtime.sendMessage(envelope).catch(() => {
     });
+  };
+  const unobserve = runtime.observe((msg, state) => {
+    sendBroadcast(msg, state);
+  });
+  const unboot = runtime.onBoot((state) => {
+    sendBroadcast(null, state);
   });
   const onMessage = (message, _sender, sendResponse) => {
     if (!message || typeof message !== "object") return void 0;
@@ -35,7 +41,10 @@ function bridgeRuntime(runtime, { channel, serialize, historySize }) {
       runtime.dispatch(msg).then(() => {
         sendResponse({ ok: true });
       }).catch((err) => {
-        sendResponse({ ok: false, error: err instanceof Error ? err.message : String(err) });
+        sendResponse({
+          ok: false,
+          error: err instanceof Error ? err.message : String(err)
+        });
       });
       return true;
     }
@@ -44,10 +53,14 @@ function bridgeRuntime(runtime, { channel, serialize, historySize }) {
   chrome.runtime.onMessage.addListener(onMessage);
   return () => {
     unobserve();
+    unboot();
     chrome.runtime.onMessage.removeListener(onMessage);
     tracker?.stop();
   };
 }
+function passThroughMsg(raw) {
+  return raw;
+}
 function bridgeClient({
   channel,
   parseState,
@@ -87,11 +100,9 @@ function bridgeClient({
         let msg;
         if (obj.msg === null || obj.msg === void 0) {
           msg = null;
-        } else if (parseMsg !== void 0) {
+        } else {
           msg = parseMsg(obj.msg);
           if (msg === null) return;
-        } else {
-          msg = obj.msg;
         }
         latestState = state;
         listener(msg, state);
@@ -118,11 +129,9 @@ function replayBacklog(raw, parseState, parseMsg, listeners, commitState) {
     let msg;
     if (entry.msg === null || entry.msg === void 0) {
       msg = null;
-    } else if (parseMsg !== void 0) {
+    } else {
       msg = parseMsg(entry.msg);
       if (msg === null) continue;
-    } else {
-      msg = entry.msg;
     }
     commitState(state);
     for (const l of listeners) l(msg, state);
@@ -169,11 +178,9 @@ function bridgeTabClient({
         let msg;
         if (obj.msg === null || obj.msg === void 0) {
           msg = null;
-        } else if (parseMsg !== void 0) {
+        } else {
           msg = parseMsg(obj.msg);
           if (msg === null) return;
-        } else {
-          msg = obj.msg;
         }
         latestState = state;
         listener(msg, state);
@@ -191,6 +198,6 @@ function bridgeTabClient({
   return client;
 }
 
-export { bridgeClient, bridgeRuntime, bridgeTabClient };
-//# sourceMappingURL=chunk-PYOCUBQJ.js.map
-//# sourceMappingURL=chunk-PYOCUBQJ.js.map
+export { bridgeClient, bridgeRuntime, bridgeTabClient, passThroughMsg };
+//# sourceMappingURL=chunk-LP7VQBRG.js.map
+//# sourceMappingURL=chunk-LP7VQBRG.js.map

package/dist/chunk-LP7VQBRG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/extension/bridge.ts"],"names":[],"mappings":"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","file":"chunk-LP7VQBRG.js","sourcesContent":["/**\n * Runtime bridge — expose a `@demlik/tea` runtime running in one chrome context\n * (typically the background service worker) to consumers in other contexts\n * (sidepanel, popup, devtools panel) over `chrome.runtime.sendMessage` /\n * `chrome.runtime.onMessage`.\n *\n * Two halves, one channel name string.\n *\n *   ┌──── background (host) ────┐               ┌──── react surface ────┐\n *   │ bridgeRuntime(rt, {ch})   │  chrome.*     │ useBackgroundRuntime  │\n *   │  ├ observe → broadcast     │ ──────────▶  │  ├ hydrate (initial)  │\n *   │  └ onMessage(\":dispatch\") │ ◀──────────  │  └ dispatch (msgs)    │\n *   │  └ onMessage(\":hydrate\")  │               │                       │\n *   └────────────────────────────┘               └───────────────────────┘\n *\n * Wire-shape (single `channel` string, three messages):\n *\n *   { type: channel,                msg, state }   // background → surfaces (broadcast)\n *   { type: `${channel}:hydrate`  }                 // surface → background (request)\n *   { type: `${channel}:dispatch`, msg }            // surface → background (input)\n *\n * The `:hydrate` reply is the current `runtime.getState()` snapshot —\n * lets a newly-opened surface render the right view BEFORE the next\n * transition broadcast arrives.\n *\n * The bridge is intentionally agnostic to `chrome.runtime.sendMessage`\n * failure modes (no receiver, sender gone, etc.) — every cross-context send\n * is fire-and-forget with `.catch(() => {})`. Surfaces that need\n * delivery guarantees should layer their own retry, not bake it here.\n */\n\nimport { type HistoryTracker, historyTracker, type Runtime } from \"../index\";\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Wire types — internal. Consumers don't import these directly; they pick\n// the channel string and the bridge handles serialization.\n// ─────────────────────────────────────────────────────────────────────────────\n\ninterface BroadcastEnvelope<S, M> {\n  type: string; // === `channel`\n  msg: M | null;\n  state: S;\n}\n\ninterface DispatchEnvelope<M> {\n  type: string; // === `${channel}:dispatch`\n  msg: M;\n}\n\ninterface HydrateRequest {\n  type: string; // === `${channel}:hydrate`\n}\n\n/**\n * Wire shape of one entry in the hydrate `backlog`. Mirrors a single\n * broadcast envelope, but without the `type` discriminator (the parent\n * `HydrateResponse` already identified the channel).\n */\ninterface BacklogEntry<V, M> {\n  msg: M | null;\n  state: V;\n}\n\ninterface HydrateResponse<S, M> {\n  state: S;\n  /**\n   * The runtime's history (most recent transitions, oldest first) projected\n   * through `serialize` if provided. Present when the host runtime was\n   * started with `historySize > 0`; an empty array otherwise. The surface\n   * replays each entry through registered listeners before firing the\n   * current-state marker, so a late subscriber sees the recent msg log AND\n   * the current state on connect — not just the current state.\n   */\n  backlog: BacklogEntry<S, M>[];\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Background side — bridgeRuntime(runtime, { channel, serialize? })\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface BridgeRuntimeOpts<S, V = S> {\n  channel: string;\n  /**\n   * Optional projection from the runtime's live state `S` to a JSON-safe\n   * view `V` that goes over the wire (broadcast + hydrate). Required when\n   * `S` carries non-serializable values (DOM refs, Map, Date, …).\n   *\n   * Identity passthrough by default — existing callers with POJO state pass\n   * `serialize` unset and `V = S`.\n   *\n   * Wire shape with `serialize`:\n   *   { type: channel, msg, state: serialize(currentState) }   // broadcast\n   *   { type: hydrate } → { state: serialize(currentState) }    // hydrate\n   *\n   * Dispatch is NOT affected — it carries `M` end-to-end. Surfaces parse the\n   * `V` they receive (they should pick a type parameter matching the\n   * projection).\n   */\n  serialize?: (state: S) => V;\n  /**\n   * If > 0, the bridge composes a `historyTracker(runtime, size)` over the\n   * runtime and returns the captured `(msg, state)` backlog in every\n   * `:hydrate` reply. Late subscribers receive recent traffic on connect —\n   * the inspector then sees prior tool calls / phase transitions instead\n   * of just the current state snapshot.\n   *\n   * Defaults to 0 (no tracker, empty backlog). Composition stays opt-in:\n   * the substrate is untouched, the dispatch loop is untouched, and the\n   * bridge attaches the tracker only when this opt is set. Cleanup is\n   * the bridge's responsibility — the disposer returned by `bridgeRuntime`\n   * stops the tracker along with the observer.\n   *\n   * Memory cost: ~size × (msg + state) bytes, in-memory only, dies with\n   * the bridge. Privacy: backlog entries flow to every `:hydrate` reply —\n   * any surface that can hydrate sees them. Do not enable on bridges\n   * carrying user secrets.\n   */\n  historySize?: number;\n}\n\n/**\n * Install the bridge for a runtime. Returns a cleanup function that removes\n * the observer and the chrome listener.\n *\n * - **Broadcast:** every (msg, state) transition emits\n *   `{ type: channel, msg, state }` via `chrome.runtime.sendMessage`. The\n *   send is fire-and-forget — when no surface is listening, chrome.runtime\n *   rejects with \"Could not establish connection. Receiving end does not\n *   exist.\" which we swallow. If `serialize` is provided, `state` carries\n *   `serialize(state)` instead of the raw state.\n * - **Hydrate:** `{ type: \":hydrate\" }` is answered via `sendResponse` with\n *   the current (optionally projected) `runtime.getState()`. If the runtime\n *   is mid-boot (store load not yet resolved), `getState()` throws — we\n *   swallow and reply with `state: null`; surfaces should treat null as\n *   \"not ready yet\" and wait for the first broadcast.\n * - **Dispatch:** `{ type: \":dispatch\", msg }` routes to `runtime.dispatch`.\n *   Returns `true` from the listener so chrome keeps the message channel\n *   open until dispatch's promise settles (we ack with `{ ok: true }`).\n */\nexport function bridgeRuntime<S, M extends { type: string }, V = S>(\n  runtime: Runtime<S, M>,\n  { channel, serialize, historySize }: BridgeRuntimeOpts<S, V>,\n): () => void {\n  const dispatchType = `${channel}:dispatch`;\n  const hydrateType = `${channel}:hydrate`;\n  // Default to identity passthrough when no projection is provided. The\n  // type parameter defaults `V = S` so callers with no projection see no\n  // change in the wire-shape — the broadcast still carries `S`.\n  const project: (state: S) => V =\n    serialize ?? ((state: S): V => state as unknown as V);\n  // Compose a history tracker only when the caller opted in. Substrate\n  // (`@demlik/tea`'s `run()`) knows nothing about history — the tracker is a\n  // pure composition over `runtime.observe(...)`, owned by the bridge.\n  // `null` when unset means \"no backlog in :hydrate replies\"; the wire\n  // shape stays uniform (backlog is always an array, possibly empty).\n  const tracker: HistoryTracker<S, M> | null =\n    historySize !== undefined && historySize > 0\n      ? historyTracker(runtime, historySize)\n      : null;\n\n  // The broadcast wire still carries `msg: M | null` — surfaces depend on the\n  // boot frame (`msg: null`) to hydrate from the bridge. Applied transitions now\n  // arrive via `observe` with a total `msg`; the boot frame arrives via `onBoot`\n  // (#47). One helper builds the envelope for both.\n  const sendBroadcast = (msg: M | null, state: S): void => {\n    const envelope: BroadcastEnvelope<V, M | null> = {\n      type: channel,\n      msg,\n      state: project(state),\n    };\n    chrome.runtime.sendMessage(envelope).catch(() => {\n      // No surface listening — drop silently. Costs are negligible at\n      // typical audit-event rates; surfaces poll on hydrate on open.\n    });\n  };\n  const unobserve = runtime.observe((msg, state) => {\n    sendBroadcast(msg, state);\n  });\n  const unboot = runtime.onBoot((state) => {\n    sendBroadcast(null, state);\n  });\n\n  const onMessage = (\n    message: unknown,\n    _sender: chrome.runtime.MessageSender,\n    sendResponse: (response: unknown) => void,\n  ): boolean | undefined => {\n    if (!message || typeof message !== \"object\") return undefined;\n    const obj = message as Record<string, unknown>;\n\n    if (obj.type === hydrateType) {\n      let state: V | null;\n      try {\n        state = project(runtime.getState());\n      } catch {\n        // Runtime still booting (store.load pending). Surfaces fall back to\n        // waiting for the first broadcast.\n        state = null;\n      }\n      // Read the tracker's snapshot and project each entry's state through\n      // `serialize`. When `historySize` was unset (tracker === null) we\n      // send `[]` — uniform wire shape means surfaces never branch on\n      // \"did the bridge enable history\" — they always iterate.\n      const backlog: BacklogEntry<V, M>[] = tracker\n        ? tracker\n            .snapshot()\n            .map((entry) => ({ msg: entry.msg, state: project(entry.state) }))\n        : [];\n      const response: HydrateResponse<V | null, M> = { state, backlog };\n      sendResponse(response);\n      return false;\n    }\n\n    if (obj.type === dispatchType) {\n      const msg = obj.msg as M;\n      runtime\n        .dispatch(msg)\n        .then(() => {\n          sendResponse({ ok: true });\n        })\n        .catch((err: unknown) => {\n          sendResponse({\n            ok: false,\n            error: err instanceof Error ? err.message : String(err),\n          });\n        });\n      return true; // keep channel open for async sendResponse\n    }\n\n    return undefined;\n  };\n\n  chrome.runtime.onMessage.addListener(onMessage);\n\n  return () => {\n    unobserve();\n    unboot();\n    chrome.runtime.onMessage.removeListener(onMessage);\n    // Detach the history observer too — leaving it attached after the\n    // bridge tears down would silently retain memory and keep observing\n    // a runtime whose backlog can no longer reach any consumer.\n    tracker?.stop();\n  };\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Surface side — the bridge half that lives in a React surface. Exported as\n// a pure helper so the React adapter (or a test) wires the listeners and the\n// hydrate round-trip with the same wire format the host emits.\n//\n// Note: this file deliberately has NO React import. The React hook lives in\n// `react.ts` and consumes these helpers. Keeps the bridge testable in plain\n// vitest without happy-dom + React renderers.\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * The explicit opt-out of inbound msg parsing: an identity pass-through that\n * casts the raw `unknown` to `M`. Surfaces that gate only on state and treat\n * the broadcast msg as advisory pass this as `parseMsg` to acknowledge — at\n * the call site, in the types — that they are NOT parsing the msg boundary.\n *\n * This is the same behavior the old optional-`parseMsg` default had, but the\n * unsound cast now lives at one named, greppable, opt-in seam instead of being\n * the silent default for everyone. (Inv 8: the boundary parses; this helper is\n * the documented exception, chosen explicitly.)\n */\nexport function passThroughMsg<M>(raw: unknown): M | null {\n  return raw as M;\n}\n\nexport interface BridgeClient<S, M> {\n  /** Send the hydrate request; resolves with the initial snapshot (or null\n   * if the host is still booting OR the response failed to parse). Also\n   * primes `getSnapshot()` so React's `useSyncExternalStore` sees the\n   * hydrated value on the next render. */\n  hydrate(): Promise<S | null>;\n  /** Send a dispatch envelope; resolves once the host's dispatch settles. */\n  dispatch(msg: M): Promise<void>;\n  /** Subscribe to broadcasts. Returns a cleanup function. Broadcasts whose\n   * payload fails `parseState` or `parseMsg` are dropped silently — the\n   * listener is not called. Each successful broadcast updates\n   * `getSnapshot()`. */\n  subscribe(listener: (msg: M | null, state: S) => void): () => void;\n  /** Synchronous accessor for the latest known state, or `null` until the\n   * first successful hydrate or broadcast lands. Required reference stability\n   * for `useSyncExternalStore`: returns the SAME object reference when the\n   * underlying state hasn't changed since the prior call. */\n  getSnapshot(): S | null;\n}\n\nexport interface BridgeClientOpts<S, M> {\n  channel: string;\n  /**\n   * REQUIRED parse for inbound `state` payloads (from `:hydrate` reply AND\n   * every broadcast). Chrome runtime messages are an `unknown` boundary\n   * (Inv 8) — the surface is the only party that knows the domain type `S`,\n   * so it owns the boundary parse. Returning `null` drops the payload\n   * silently (subscriber not called; hydrate resolves to `null`). The\n   * parser MUST NOT throw — model rejection as `null`.\n   */\n  parseState: (raw: unknown) => S | null;\n  /**\n   * REQUIRED parse for inbound `msg` payloads on broadcasts. Chrome runtime\n   * messages are an `unknown` boundary (Inv 8) just like the `state` payload,\n   * so the msg crosses the same JSON serialization seam and must be parsed —\n   * never cast. Returning `null` drops the broadcast silently.\n   *\n   * Surfaces that treat the msg union as advisory and only gate on state opt\n   * out EXPLICITLY by passing the {@link passThroughMsg} helper — the opt-out\n   * is now a visible call-site decision, not a hidden default that lets an\n   * unparsed `unknown` reach listeners typed as `M`.\n   */\n  parseMsg: (raw: unknown) => M | null;\n}\n\nexport function bridgeClient<S, M extends { type: string }>({\n  channel,\n  parseState,\n  parseMsg,\n}: BridgeClientOpts<S, M>): BridgeClient<S, M> {\n  const dispatchType = `${channel}:dispatch`;\n  const hydrateType = `${channel}:hydrate`;\n  // Closure-held latest snapshot. `useSyncExternalStore` reads this via\n  // `getSnapshot`; the reference is stable across calls until a hydrate\n  // reply or broadcast overwrites it. Identity matters: returning a new\n  // object for the same logical state would loop React. `null` is the\n  // pre-hydrate sentinel.\n  let latestState: S | null = null;\n  // Each active subscribe() registers a listener. Hydrate replies notify\n  // every subscriber with `msg: null` (no host transition occurred — the\n  // change source is the hydrate round-trip) so `useSyncExternalStore`\n  // sees the snapshot update on first mount.\n  const listeners = new Set<(msg: M | null, state: S) => void>();\n\n  const client: BridgeClient<S, M> = {\n    async hydrate(): Promise<S | null> {\n      const req: HydrateRequest = { type: hydrateType };\n      const res = (await chrome.runtime.sendMessage(req)) as\n        | { state: unknown; backlog?: unknown }\n        | undefined;\n      // Replay the backlog FIRST — listeners observing for a msg log see\n      // historical (msg, state) pairs in oldest-first order before the\n      // current-state marker. Backlog entries that fail boundary parse are\n      // dropped silently (same posture as live broadcasts). When the host\n      // didn't enable history, `backlog` is `[]` and this loop is a no-op.\n      replayBacklog(res?.backlog, parseState, parseMsg, listeners, (next) => {\n        latestState = next;\n      });\n      const raw = res?.state;\n      if (raw === undefined || raw === null) return null;\n      const parsed = parseState(raw);\n      if (parsed === null) return null;\n      latestState = parsed;\n      // Fire the current-state marker (msg = null) — distinct from any\n      // backlog entry. Surfaces that show \"X just connected\" key off this.\n      for (const l of listeners) l(null, parsed);\n      return parsed;\n    },\n\n    async dispatch(msg: M): Promise<void> {\n      const env: DispatchEnvelope<M> = { type: dispatchType, msg };\n      await chrome.runtime.sendMessage(env);\n    },\n\n    subscribe(listener: (msg: M | null, state: S) => void): () => void {\n      listeners.add(listener);\n      const onMessage = (message: unknown): void => {\n        if (!message || typeof message !== \"object\") return;\n        const obj = message as Record<string, unknown>;\n        if (obj.type !== channel) return;\n        // Boundary parse (Inv 8): chrome runtime messages are `unknown`.\n        // A failed state parse drops the broadcast — null state would\n        // be indistinguishable from \"host still booting\" and is not a\n        // useful signal to surfaces. The msg is parsed through the\n        // (required) `parseMsg`; a null result drops the broadcast too.\n        const state = parseState(obj.state);\n        if (state === null) return;\n        let msg: M | null;\n        if (obj.msg === null || obj.msg === undefined) {\n          msg = null;\n        } else {\n          msg = parseMsg(obj.msg);\n          if (msg === null) return;\n        }\n        latestState = state;\n        listener(msg, state);\n      };\n      chrome.runtime.onMessage.addListener(onMessage);\n      return () => {\n        chrome.runtime.onMessage.removeListener(onMessage);\n        listeners.delete(listener);\n      };\n    },\n\n    getSnapshot(): S | null {\n      return latestState;\n    },\n  };\n\n  return client;\n}\n\n/**\n * Shared backlog-replay helper used by both `bridgeClient` and\n * `bridgeTabClient`. Iterates raw entries from the wire, runs each through\n * the same boundary-parse rules a live broadcast would (parseState +\n * parseMsg, both returning `null` to drop), and fires the listeners with the\n * parsed `(msg, state)` pair. Updates the closure-held `latestState` via\n * `commitState` so post-replay `getSnapshot()` returns the most recent backlog\n * state if the current-state marker is absent or unparseable.\n *\n * Extracted so the two clients can't drift in how they parse backlog\n * payloads — both must stay symmetric with their live `subscribe` parse.\n */\nfunction replayBacklog<S, M extends { type: string }>(\n  raw: unknown,\n  parseState: (raw: unknown) => S | null,\n  parseMsg: (raw: unknown) => M | null,\n  listeners: Set<(msg: M | null, state: S) => void>,\n  commitState: (next: S) => void,\n): void {\n  if (!Array.isArray(raw)) return;\n  for (const entryRaw of raw) {\n    if (!entryRaw || typeof entryRaw !== \"object\") continue;\n    const entry = entryRaw as Record<string, unknown>;\n    const state = parseState(entry.state);\n    if (state === null) continue;\n    let msg: M | null;\n    if (entry.msg === null || entry.msg === undefined) {\n      msg = null;\n    } else {\n      msg = parseMsg(entry.msg);\n      if (msg === null) continue;\n    }\n    commitState(state);\n    for (const l of listeners) l(msg, state);\n  }\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// SW-side client of a content-script-hosted runtime.\n//\n// `bridgeClient` above sends via `chrome.runtime.sendMessage`, which lands on\n// the SW's `chrome.runtime.onMessage`. That's the surface-to-SW direction.\n//\n// For the SW-to-content direction we need:\n//   - SENDS via `chrome.tabs.sendMessage(tabId, …)` — `chrome.runtime.sendMessage`\n//     does NOT reach content scripts running in a tab.\n//   - BROADCAST subscribers must filter on `sender.tab?.id === tabId`, since\n//     every tab's content script broadcasts through the same SW\n//     `chrome.runtime.onMessage`. Without the filter, a SW client subscribed\n//     to \"tab 17\" would also see broadcasts from tabs 22, 31, ….\n//\n// Shape mirrors `BridgeClient<S, M>` so consumers can pick the constructor by\n// context and use the rest of the surface identically.\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface BridgeTabClientOpts<S, M> {\n  tabId: number;\n  channel: string;\n  /**\n   * REQUIRED parse for inbound `state` payloads. See `BridgeClientOpts.parseState`\n   * — same contract, same rationale. Chrome runtime messages from a tab are\n   * an `unknown` boundary; the SW client owns the parse.\n   */\n  parseState: (raw: unknown) => S | null;\n  /**\n   * REQUIRED parse for inbound `msg` payloads. See `BridgeClientOpts.parseMsg`\n   * — same contract, same rationale. Opt out of msg parsing with\n   * {@link passThroughMsg}.\n   */\n  parseMsg: (raw: unknown) => M | null;\n}\n\n/**\n * SW-side client of a `bridgeRuntime` hosted in a content script.\n *\n * Identical contract to `bridgeClient` (same `BridgeClient<S, M>` shape).\n * Differences are confined to transport:\n *\n * - `hydrate()` / `dispatch(msg)` send via `chrome.tabs.sendMessage(tabId, …)`.\n *   If the tab is gone, `chrome.tabs.sendMessage` rejects (same shape as\n *   `chrome.runtime.sendMessage` with no receiver) — the promise propagates\n *   the rejection. Callers decide whether to retry, drop, or surface; the\n *   bridge has no opinion. Fire-and-forget posture matches `bridgeRuntime`.\n * - `subscribe(listener)` registers a `chrome.runtime.onMessage` listener\n *   filtered by both `envelope.type === channel` AND `sender.tab?.id === tabId`,\n *   so broadcasts from other tabs are ignored (no cross-contamination across\n *   per-tab content-script runtimes).\n */\nexport function bridgeTabClient<S, M extends { type: string }>({\n  tabId,\n  channel,\n  parseState,\n  parseMsg,\n}: BridgeTabClientOpts<S, M>): BridgeClient<S, M> {\n  const dispatchType = `${channel}:dispatch`;\n  const hydrateType = `${channel}:hydrate`;\n  let latestState: S | null = null;\n  const listeners = new Set<(msg: M | null, state: S) => void>();\n\n  const client: BridgeClient<S, M> = {\n    async hydrate(): Promise<S | null> {\n      const req: HydrateRequest = { type: hydrateType };\n      const res = (await chrome.tabs.sendMessage(tabId, req)) as\n        | { state: unknown; backlog?: unknown }\n        | undefined;\n      // Mirror bridgeClient.hydrate's backlog replay: same parse rules,\n      // same oldest-first ordering, same current-state-marker semantics.\n      // The two helpers diverge only in transport (tabs vs runtime), not\n      // in protocol shape.\n      replayBacklog(res?.backlog, parseState, parseMsg, listeners, (next) => {\n        latestState = next;\n      });\n      const raw = res?.state;\n      if (raw === undefined || raw === null) return null;\n      const parsed = parseState(raw);\n      if (parsed === null) return null;\n      latestState = parsed;\n      for (const l of listeners) l(null, parsed);\n      return parsed;\n    },\n\n    async dispatch(msg: M): Promise<void> {\n      const env: DispatchEnvelope<M> = { type: dispatchType, msg };\n      await chrome.tabs.sendMessage(tabId, env);\n    },\n\n    subscribe(listener: (msg: M | null, state: S) => void): () => void {\n      listeners.add(listener);\n      const onMessage = (\n        message: unknown,\n        sender: chrome.runtime.MessageSender,\n      ): void => {\n        if (sender.tab?.id !== tabId) return;\n        if (!message || typeof message !== \"object\") return;\n        const obj = message as Record<string, unknown>;\n        if (obj.type !== channel) return;\n        // Boundary parse (Inv 8) — mirror bridgeClient.\n        const state = parseState(obj.state);\n        if (state === null) return;\n        let msg: M | null;\n        if (obj.msg === null || obj.msg === undefined) {\n          msg = null;\n        } else {\n          msg = parseMsg(obj.msg);\n          if (msg === null) return;\n        }\n        latestState = state;\n        listener(msg, state);\n      };\n      chrome.runtime.onMessage.addListener(onMessage);\n      return () => {\n        chrome.runtime.onMessage.removeListener(onMessage);\n        listeners.delete(listener);\n      };\n    },\n\n    getSnapshot(): S | null {\n      return latestState;\n    },\n  };\n\n  return client;\n}\n"]}