@demlik/tea 0.2.0 → 0.4.0

package/dist/{durable-effects-9LxFpmh3.d.ts → durable-effects-CFRngTNA.d.ts}

@@ -1,4 +1,4 @@
-import { C as Cmd } from './core-BmlJOvxM.js';
+import { C as Cmd } from './core-42kapW0n.js';
 
 /**
  * @demlik/tea/do — the durable pending-effects ledger (substrate primitive #1).
@@ -47,8 +47,8 @@ import { C as Cmd } from './core-BmlJOvxM.js';
  *   - Re-firing every historical effect during replay. Only `survivingEffects`
  *     (post-fold) re-emits.
  *   - Assuming the receiver gets each effect exactly once. At-least-once: dedup
- *     by `id` at the receiver (`hasOwed` / `isConfirmed` here are the sender's
- *     view; the receiver owns its own dedup).
+ *     by `id` at the receiver (`isOwed` here is the sender's view; the receiver
+ *     owns its own dedup).
  */
 
 /** Monotonic, gap-free delivery id — the single correlation + dedup key. */

package/dist/extension/index.d.ts

@@ -1,5 +1,5 @@
-import { Runtime, Store } from '../index.js';
-import '../core-BmlJOvxM.js';
+import { R as Runtime, S as Store } from '../runtime-types-CukV8kMX.js';
+import '../core-42kapW0n.js';
 
 /**
  * Runtime bridge — expose a `@demlik/tea` runtime running in one chrome context
@@ -32,8 +32,22 @@ import '../core-BmlJOvxM.js';
  * delivery guarantees should layer their own retry, not bake it here.
  */
 
-interface BridgeRuntimeOpts<S, V = S> {
+interface BridgeRuntimeOpts<S, M, V = S> {
     channel: string;
+    /**
+     * REQUIRED parse for inbound `msg` payloads on `:dispatch` envelopes.
+     * Chrome runtime messages are an `unknown` boundary (Inv 8) — the same
+     * JSON/chrome serialization seam the symmetric client side parses via
+     * `BridgeClientOpts.parseMsg`. An untrusted surface can drive the host
+     * reducer with an arbitrary `M`, so the host parses too — never casts. A
+     * `msg` that parses to `null` is dropped: the dispatch never reaches the
+     * reducer and the surface's `dispatch()` rejects with `{ ok: false }`.
+     *
+     * Hosts that trust the dispatch channel and treat the msg as opaque opt
+     * out EXPLICITLY by passing the {@link passThroughMsg} helper — the unsound
+     * cast is then a visible call-site decision, not a silent default.
+     */
+    parseMsg: (raw: unknown) => M | null;
     /**
      * Optional projection from the runtime's live state `S` to a JSON-safe
      * view `V` that goes over the wire (broadcast + hydrate). Required when
@@ -86,13 +100,16 @@ interface BridgeRuntimeOpts<S, V = S> {
  *   is mid-boot (store load not yet resolved), `getState()` throws — we
  *   swallow and reply with `state: null`; surfaces should treat null as
  *   "not ready yet" and wait for the first broadcast.
- * - **Dispatch:** `{ type: ":dispatch", msg }` routes to `runtime.dispatch`.
- *   Returns `true` from the listener so chrome keeps the message channel
- *   open until dispatch's promise settles (we ack with `{ ok: true }`).
+ * - **Dispatch:** `{ type: ":dispatch", msg }` is parsed through `parseMsg`
+ *   (Inv 8 — inbound msgs are an `unknown` boundary) and, if non-null, routes
+ *   to `runtime.dispatch`. Returns `true` from the listener so chrome keeps the
+ *   message channel open until dispatch's promise settles (we ack with
+ *   `{ ok: true }`). A msg that fails the parse is dropped — the reducer never
+ *   sees it and we reply `{ ok: false }`.
  */
 declare function bridgeRuntime<S, M extends {
     type: string;
-}, V = S>(runtime: Runtime<S, M>, { channel, serialize, historySize }: BridgeRuntimeOpts<S, V>): () => void;
+}, V = S>(runtime: Runtime<S, M>, { channel, parseMsg, serialize, historySize }: BridgeRuntimeOpts<S, M, V>): () => void;
 /**
  * The explicit opt-out of inbound msg parsing: an identity pass-through that
  * casts the raw `unknown` to `M`. Surfaces that gate only on state and treat
@@ -188,6 +205,7 @@ declare function bridgeTabClient<S, M extends {
 }>({ tabId, channel, parseState, parseMsg, }: BridgeTabClientOpts<S, M>): BridgeClient<S, M>;
 
 /**
+ * @packageDocumentation
  * @demlik/tea/extension — Chrome service-worker host adapter for @demlik/tea.
  *
  * Substrate-level companion to @demlik/tea/do (Durable Objects) and

package/dist/extension/index.js

@@ -1,6 +1,7 @@
-export { bridgeClient, bridgeRuntime, bridgeTabClient, passThroughMsg } from '../chunk-EGWTT5XJ.js';
-import '../chunk-6VDCTR7N.js';
-import '../chunk-DYRKDCJI.js';
+export { bridgeClient, bridgeRuntime, bridgeTabClient, passThroughMsg } from '../chunk-ET6QQNSQ.js';
+import '../chunk-G5E74IJB.js';
+import '../chunk-D4NJBQAH.js';
+import '../chunk-PBDYW2TU.js';
 
 // src/extension/index.ts
 var MALFORMED = "chromeStorageStore: stored value is not a string";

package/dist/extension/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/extension/index.ts"],"names":[],"mappings":";;;;;AAkCA,IAAM,SAAA,GAAY,kDAAA;AAqBX,SAAS,mBACd,GAAA,EACA,KAAA,EACA,IAAA,GAAmC,MAAA,CAAO,QAAQ,KAAA,EACxC;AACV,EAAA,OAAO;AAAA,IACL,MAAM,IAAA,GAAyB;AAC7B,MAAA,MAAM,MAAA,GAAS,MAAM,IAAA,CAAK,GAAA,CAAI,GAAG,CAAA;AACjC,MAAA,MAAM,GAAA,GAAO,OAAmC,GAAG,CAAA;AACnD,MAAA,IAAI,GAAA,KAAQ,MAAA,IAAa,GAAA,KAAQ,IAAA,EAAM,OAAO,IAAA;AAC9C,MAAA,IAAI,OAAO,GAAA,KAAQ,QAAA;AACjB,QAAA,MAAM,IAAI,KAAA,CAAM,CAAA,EAAG,SAAS,CAAA,SAAA,EAAY,GAAG,CAAA,CAAA,CAAG,CAAA;AAKhD,MAAA,OAAO,IAAA,CAAK,MAAM,GAAG,CAAA;AAAA,IACvB,CAAA;AAAA,IACA,MAAM,KAAK,KAAA,EAAyB;AAClC,MAAA,MAAM,IAAA,CAAK,GAAA,CAAI,EAAE,CAAC,GAAG,GAAG,IAAA,CAAK,SAAA,CAAU,KAAK,CAAA,EAAG,CAAA;AAAA,IACjD,CAAA;AAAA,IACA,QAAQ,GAAA,EAAwB;AAC9B,MAAA,OAAO,MAAM,GAAG,CAAA;AAAA,IAClB;AAAA,GACF;AACF","file":"index.js","sourcesContent":["/**\n * @demlik/tea/extension — Chrome service-worker host adapter for @demlik/tea.\n *\n * Substrate-level companion to @demlik/tea/do (Durable Objects) and\n * @demlik/tea/react (React). Lets a chrome service worker run a @demlik/tea\n * machine with persistence backed by chrome.storage.\n *\n * Single export: chromeStorageStore<S>(key, area?). Apps register chrome.*\n * listeners themselves and call runtime.dispatch from inside the handler —\n * those wiring patterns are app-specific (different extensions register\n * different listener sets, with different Msg adapters), so we don't\n * abstract them here until the shape stabilizes across consumers.\n */\n\nimport type { Store } from \"../index\";\n\nexport type {\n  BridgeClient,\n  BridgeClientOpts,\n  BridgeRuntimeOpts,\n  BridgeTabClientOpts,\n} from \"./bridge\";\n// Re-export the wire-envelope types — surfaces that test against the\n// bridge can pin the shapes without round-tripping through the runtime.\n// Re-export the runtime bridge primitives. The React adapter lives at\n// `@demlik/tea/extension/react` so the main entry stays react-free for the\n// background service-worker side.\nexport {\n  bridgeClient,\n  bridgeRuntime,\n  bridgeTabClient,\n  passThroughMsg,\n} from \"./bridge\";\n\nconst MALFORMED = \"chromeStorageStore: stored value is not a string\";\n\n/**\n * `Store<S>` backed by `chrome.storage.local` (or any compatible\n * `StorageArea`). JSON.stringify on save, JSON.parse on load. Returns `null`\n * (typed as `unknown` per `Store<S>.load` contract) when the key is absent.\n *\n * Throws on the structural layer if the stored value is malformed (non-string\n * at the key, or unparseable JSON) — matches @demlik/tea/do's \"throw at boot via\n * store.load\" contract so tea's `run()` surfaces it predictably. The\n * `parse` callback handles the semantic layer (shape mismatch → return\n * `null`); it must NOT throw, per the `Store<S>.migrate` contract.\n *\n * `parse` is REQUIRED because chrome.storage is a real serialization boundary\n * — JSON to disk, then back — and the structural type of what comes back is\n * `unknown`. The caller (extension code that knows `S`) is the only party\n * with enough information to write the parse. There is no honest default.\n *\n * `area` defaults to `chrome.storage.local` for production. Tests pass a\n * `fakeChrome().storage.local` in.\n */\nexport function chromeStorageStore<S>(\n  key: string,\n  parse: (raw: unknown) => S | null,\n  area: chrome.storage.StorageArea = chrome.storage.local,\n): Store<S> {\n  return {\n    async load(): Promise<unknown> {\n      const result = await area.get(key);\n      const raw = (result as Record<string, unknown>)[key];\n      if (raw === undefined || raw === null) return null;\n      if (typeof raw !== \"string\")\n        throw new Error(`${MALFORMED} at key \"${key}\"`);\n      // JSON.parse throws on malformed — propagate per @demlik/tea/do parity.\n      // The decoded value is intentionally returned as `unknown`; the\n      // substrate's `migrate` callback (forwarded from `parse`) is the\n      // boundary parse that turns it into `S | null`.\n      return JSON.parse(raw);\n    },\n    async save(state: S): Promise<void> {\n      await area.set({ [key]: JSON.stringify(state) });\n    },\n    migrate(raw: unknown): S | null {\n      return parse(raw);\n    },\n  };\n}\n"]}
+{"version":3,"sources":["../../src/extension/index.ts"],"names":[],"mappings":";;;;;;AAmCA,IAAM,SAAA,GAAY,kDAAA;AAqBX,SAAS,mBACd,GAAA,EACA,KAAA,EACA,IAAA,GAAmC,MAAA,CAAO,QAAQ,KAAA,EACxC;AACV,EAAA,OAAO;AAAA,IACL,MAAM,IAAA,GAAyB;AAC7B,MAAA,MAAM,MAAA,GAAS,MAAM,IAAA,CAAK,GAAA,CAAI,GAAG,CAAA;AACjC,MAAA,MAAM,GAAA,GAAO,OAAmC,GAAG,CAAA;AACnD,MAAA,IAAI,GAAA,KAAQ,MAAA,IAAa,GAAA,KAAQ,IAAA,EAAM,OAAO,IAAA;AAC9C,MAAA,IAAI,OAAO,GAAA,KAAQ,QAAA;AACjB,QAAA,MAAM,IAAI,KAAA,CAAM,CAAA,EAAG,SAAS,CAAA,SAAA,EAAY,GAAG,CAAA,CAAA,CAAG,CAAA;AAKhD,MAAA,OAAO,IAAA,CAAK,MAAM,GAAG,CAAA;AAAA,IACvB,CAAA;AAAA,IACA,MAAM,KAAK,KAAA,EAAyB;AAClC,MAAA,MAAM,IAAA,CAAK,GAAA,CAAI,EAAE,CAAC,GAAG,GAAG,IAAA,CAAK,SAAA,CAAU,KAAK,CAAA,EAAG,CAAA;AAAA,IACjD,CAAA;AAAA,IACA,QAAQ,GAAA,EAAwB;AAC9B,MAAA,OAAO,MAAM,GAAG,CAAA;AAAA,IAClB;AAAA,GACF;AACF","file":"index.js","sourcesContent":["/**\n * @packageDocumentation\n * @demlik/tea/extension — Chrome service-worker host adapter for @demlik/tea.\n *\n * Substrate-level companion to @demlik/tea/do (Durable Objects) and\n * @demlik/tea/react (React). Lets a chrome service worker run a @demlik/tea\n * machine with persistence backed by chrome.storage.\n *\n * Single export: chromeStorageStore<S>(key, area?). Apps register chrome.*\n * listeners themselves and call runtime.dispatch from inside the handler —\n * those wiring patterns are app-specific (different extensions register\n * different listener sets, with different Msg adapters), so we don't\n * abstract them here until the shape stabilizes across consumers.\n */\n\nimport type { Store } from \"../index\";\n\nexport type {\n  BridgeClient,\n  BridgeClientOpts,\n  BridgeRuntimeOpts,\n  BridgeTabClientOpts,\n} from \"./bridge\";\n// Re-export the wire-envelope types — surfaces that test against the\n// bridge can pin the shapes without round-tripping through the runtime.\n// Re-export the runtime bridge primitives. The React adapter lives at\n// `@demlik/tea/extension/react` so the main entry stays react-free for the\n// background service-worker side.\nexport {\n  bridgeClient,\n  bridgeRuntime,\n  bridgeTabClient,\n  passThroughMsg,\n} from \"./bridge\";\n\nconst MALFORMED = \"chromeStorageStore: stored value is not a string\";\n\n/**\n * `Store<S>` backed by `chrome.storage.local` (or any compatible\n * `StorageArea`). JSON.stringify on save, JSON.parse on load. Returns `null`\n * (typed as `unknown` per `Store<S>.load` contract) when the key is absent.\n *\n * Throws on the structural layer if the stored value is malformed (non-string\n * at the key, or unparseable JSON) — matches @demlik/tea/do's \"throw at boot via\n * store.load\" contract so tea's `run()` surfaces it predictably. The\n * `parse` callback handles the semantic layer (shape mismatch → return\n * `null`); it must NOT throw, per the `Store<S>.migrate` contract.\n *\n * `parse` is REQUIRED because chrome.storage is a real serialization boundary\n * — JSON to disk, then back — and the structural type of what comes back is\n * `unknown`. The caller (extension code that knows `S`) is the only party\n * with enough information to write the parse. There is no honest default.\n *\n * `area` defaults to `chrome.storage.local` for production. Tests pass a\n * `fakeChrome().storage.local` in.\n */\nexport function chromeStorageStore<S>(\n  key: string,\n  parse: (raw: unknown) => S | null,\n  area: chrome.storage.StorageArea = chrome.storage.local,\n): Store<S> {\n  return {\n    async load(): Promise<unknown> {\n      const result = await area.get(key);\n      const raw = (result as Record<string, unknown>)[key];\n      if (raw === undefined || raw === null) return null;\n      if (typeof raw !== \"string\")\n        throw new Error(`${MALFORMED} at key \"${key}\"`);\n      // JSON.parse throws on malformed — propagate per @demlik/tea/do parity.\n      // The decoded value is intentionally returned as `unknown`; the\n      // substrate's `migrate` callback (forwarded from `parse`) is the\n      // boundary parse that turns it into `S | null`.\n      return JSON.parse(raw);\n    },\n    async save(state: S): Promise<void> {\n      await area.set({ [key]: JSON.stringify(state) });\n    },\n    migrate(raw: unknown): S | null {\n      return parse(raw);\n    },\n  };\n}\n"]}

package/dist/extension/react.js

@@ -1,6 +1,7 @@
-import { bridgeClient, passThroughMsg } from '../chunk-EGWTT5XJ.js';
-import '../chunk-6VDCTR7N.js';
-import '../chunk-DYRKDCJI.js';
+import { bridgeClient, passThroughMsg } from '../chunk-ET6QQNSQ.js';
+import '../chunk-G5E74IJB.js';
+import '../chunk-D4NJBQAH.js';
+import '../chunk-PBDYW2TU.js';
 import { useRef, useSyncExternalStore, useEffect, useCallback, createContext, useMemo, useContext } from 'react';
 import { jsx } from 'react/jsx-runtime';
 

package/dist/extension/react.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/extension/react.tsx"],"names":[],"mappings":";;;;;;AAoFO,SAAS,oBAAA,CAAoD;AAAA,EAClE,OAAA;AAAA,EACA;AACF,CAAA,EAAkE;AAIhE,EAAA,MAAM,SAAA,GAAY,OAAqD,IAAI,CAAA;AAC3E,EAAA,IAAI,SAAA,CAAU,YAAY,IAAA,EAAM;AAI9B,IAAA,SAAA,CAAU,UAAU,YAAA,CAAmB;AAAA,MACrC,OAAA;AAAA,MACA,UAAA;AAAA,MACA,QAAA,EAAU;AAAA,KACX,CAAA;AAAA,EACH;AACA,EAAA,MAAM,SAAS,SAAA,CAAU,OAAA;AAEzB,EAAA,MAAM,KAAA,GAAQ,oBAAA;AAAA,IACZ,MAAA,CAAO,SAAA;AAAA,IACP,MAAA,CAAO,WAAA;AAAA,IACP,MAAA,CAAO;AAAA,GACT;AAQA,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,MAAA,CAAO,OAAA,EAAQ,CAAE,KAAA,CAAM,MAAM;AAAA,IAE7B,CAAC,CAAA;AAAA,EACH,CAAA,EAAG,CAAC,MAAM,CAAC,CAAA;AAEX,EAAA,MAAM,QAAA,GAAW,WAAA;AAAA,IACf,OAAO,GAAA,KAA0B;AAC/B,MAAA,MAAM,MAAA,CAAO,SAAS,GAAG,CAAA;AAAA,IAC3B,CAAA;AAAA,IACA,CAAC,MAAM;AAAA,GACT;AAEA,EAAA,OAAO,EAAE,OAAO,QAAA,EAAS;AAC3B;AA6DA,IAAM,cAAA,GACJ,+HAAA;AAEK,SAAS,8BAAA,GAGoB;AAIlC,EAAA,MAAM,GAAA,GAAM,cAAuD,IAAI,CAAA;AAEvE,EAAA,SAAS,QAAA,CAAS;AAAA,IAChB,IAAA;AAAA,IACA;AAAA,GACF,EAGc;AACZ,IAAA,MAAM,MAAA,GAAS,qBAA2B,IAAI,CAAA;AAO9C,IAAA,MAAM,KAAA,GAAQ,OAAA;AAAA,MACZ,OAAO,EAAE,KAAA,EAAO,OAAO,KAAA,EAAO,QAAA,EAAU,OAAO,QAAA,EAAS,CAAA;AAAA,MACxD,CAAC,MAAA,CAAO,KAAA,EAAO,MAAA,CAAO,QAAQ;AAAA,KAChC;AACA,IAAA,uBAAO,GAAA,CAAC,GAAA,CAAI,QAAA,EAAJ,EAAa,OAAe,QAAA,EAAS,CAAA;AAAA,EAC/C;AAEA,EAAA,SAAS,UAAA,GAA+C;AACtD,IAAA,MAAM,GAAA,GAAM,WAAW,GAAG,CAAA;AAC1B,IAAA,IAAI,GAAA,KAAQ,IAAA,EAAM,MAAM,IAAI,MAAM,cAAc,CAAA;AAChD,IAAA,OAAO,GAAA;AAAA,EACT;AAEA,EAAA,SAAS,WAAA,GAAyC;AAChD,IAAA,OAAO,YAAW,CAAE,QAAA;AAAA,EACtB;AAOA,EAAA,SAAS,aAAgB,QAAA,EAAmD;AAC1E,IAAA,MAAM,EAAE,KAAA,EAAM,GAAI,UAAA,EAAW;AAC7B,IAAA,IAAI,QAAA,KAAa,QAAW,OAAO,KAAA;AACnC,IAAA,OAAO,SAAS,KAAK,CAAA;AAAA,EACvB;AAEA,EAAA,OAAO;AAAA,IACL,QAAA;AAAA,IACA,WAAA;AAAA,IACA,QAAA,EAAU,YAAA;AAAA,IACV;AAAA,GACF;AACF","file":"react.js","sourcesContent":["/**\n * React adapters for the background TEA runtime.\n *\n * Two layers, both built on the same `bridgeClient`:\n *\n *   1. `useBackgroundRuntime(opts)` — direct hook. One bridge client per\n *      call. Surfaces that only have a single consumer mount it inline.\n *\n *   2. `createBackgroundRuntimeContext<S, M>()` → `{ Provider, useDispatch,\n *      useState, useRuntime }` — factory-style React context. Mounts the\n *      bridge client ONCE inside the Provider; child hooks read `state` /\n *      `dispatch` from context. Surfaces that drill `dispatch` through\n *      multiple component layers, or mount `useBackgroundRuntime` more\n *      than once for the same channel, should use this instead.\n *\n * Why a factory (not a single global context):\n *   - Type safety: each app types it against its own `S` / `M`.\n *   - Tests can mount fresh contexts per test (no module-level state to\n *     reset).\n *   - Multiple-runtimes case: an app COULD theoretically have two\n *     background-shaped runtimes (e.g. one per channel); the factory\n *     pattern doesn't preclude it.\n *\n * Hook lifecycle (`useBackgroundRuntime`) — preserved from the prior\n * single-export module:\n *   1. `useSyncExternalStore` subscribes to broadcasts via\n *      `bridgeClient.subscribe`, reading the latest state via\n *      `bridgeClient.getSnapshot`. Reference stability is owned by the\n *      bridge — `getSnapshot` returns the SAME `S` until a new broadcast\n *      overwrites it, so React doesn't loop.\n *   2. A one-shot `hydrate()` call seeds `latestState` before the first\n *      broadcast arrives. The hydrate side-effect runs in an effect so the\n *      first render shows `null` and the subsequent render flips to the\n *      hydrated snapshot (or stays null if the host is still booting).\n *   3. `dispatch(msg)` sends `:dispatch` envelopes.\n *\n * On unmount: `useSyncExternalStore` removes the listener; the host's\n * bridge stays installed.\n *\n * Canon §3.1: React adapters use `useSyncExternalStore`, not\n * `useState + useEffect`. `useMachine` and `useRuntime` already follow this\n * — `useBackgroundRuntime` (and by extension the Provider) does too. One\n * Way to Do Each Thing.\n *\n * NOTE: This is a separate entry from the main `index.ts` so apps that\n * never need React don't drag react into their type graph. The React\n * adapter peer-depends on react (you must have it installed in the app).\n */\n\n\"use client\";\n\nimport {\n  createContext,\n  type ReactNode,\n  useCallback,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useSyncExternalStore,\n} from \"react\";\nimport { bridgeClient, passThroughMsg } from \"./bridge\";\n\nexport interface UseBackgroundRuntimeOpts<S> {\n  channel: string;\n  /**\n   * REQUIRED parse for inbound `state` payloads. Forwarded to\n   * `bridgeClient` — see `BridgeClientOpts.parseState`. Surfaces own this\n   * because the chrome.runtime boundary is `unknown` (Inv 8). Returning\n   * `null` drops the payload silently.\n   */\n  parseState: (raw: unknown) => S | null;\n}\n\nexport interface UseBackgroundRuntimeResult<S, M> {\n  /** Latest snapshot from the host. `null` until the first hydrate response\n   * or the first broadcast arrives. Surfaces SHOULD render a placeholder\n   * for the null window. */\n  state: S | null;\n  /** Send a msg to the host runtime. Resolves once the host's dispatch\n   * settles. */\n  dispatch(msg: M): Promise<void>;\n}\n\nexport function useBackgroundRuntime<S, M extends { type: string }>({\n  channel,\n  parseState,\n}: UseBackgroundRuntimeOpts<S>): UseBackgroundRuntimeResult<S, M> {\n  // Pin the client across renders. Identity must be stable because\n  // `useSyncExternalStore` deduplicates subscribe by reference; rebuilding\n  // the client every render would re-register listeners every render too.\n  const clientRef = useRef<ReturnType<typeof bridgeClient<S, M>> | null>(null);\n  if (clientRef.current === null) {\n    // This hook surfaces only `state`; the broadcast msg is unused, so it\n    // explicitly opts out of msg parsing via `passThroughMsg`. Same behavior\n    // as the former optional-`parseMsg` default, now a visible decision.\n    clientRef.current = bridgeClient<S, M>({\n      channel,\n      parseState,\n      parseMsg: passThroughMsg,\n    });\n  }\n  const client = clientRef.current;\n\n  const state = useSyncExternalStore<S | null>(\n    client.subscribe,\n    client.getSnapshot,\n    client.getSnapshot,\n  );\n\n  // One-shot hydrate on mount. The hydrate response primes `getSnapshot`\n  // before the first broadcast lands so newly-opened surfaces show the\n  // right view immediately. We don't read its return value — the hook\n  // re-renders when `useSyncExternalStore` notices the snapshot change.\n  // Hydrate failures (host not present yet) are swallowed; surfaces wait\n  // for the next broadcast.\n  useEffect(() => {\n    client.hydrate().catch(() => {\n      // No host yet. Surfaces fall back to broadcasts.\n    });\n  }, [client]);\n\n  const dispatch = useCallback(\n    async (msg: M): Promise<void> => {\n      await client.dispatch(msg);\n    },\n    [client],\n  );\n\n  return { state, dispatch };\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Provider + consumer hooks — factory-style React context.\n//\n// `createBackgroundRuntimeContext<S, M>()` returns a `{ Provider, useDispatch,\n// useState, useRuntime }` tuple bound to the caller's `S` / `M`. The\n// Provider mounts `useBackgroundRuntime(opts)` ONCE internally and shares\n// the `{ state, dispatch }` pair via context. Child consumers (anywhere in\n// the tree) read the slice they need — no prop drilling, single bridge\n// client per channel per Provider mount.\n//\n// The factory is generic; the returned hooks throw a clear error if used\n// outside the Provider so the failure mode is \"loud and obvious\" rather\n// than \"silently returns null state forever\".\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface BackgroundRuntimeContext<S, M> {\n  /**\n   * Wrap a subtree to share a single background-runtime bridge client.\n   * `opts` is forwarded verbatim to `useBackgroundRuntime` — same channel,\n   * same parse contract.\n   */\n  Provider: (props: {\n    opts: UseBackgroundRuntimeOpts<S>;\n    children: ReactNode;\n  }) => ReactNode;\n  /**\n   * Returns the dispatch function bound to this Provider's bridge client.\n   * Reference is stable across renders (per `useBackgroundRuntime`'s\n   * `useCallback`), so passing it to memoized children won't churn them.\n   */\n  useDispatch: () => (msg: M) => Promise<void>;\n  /**\n   * Returns a slice of the latest state. `selector` defaults to identity\n   * (returns the whole `S | null` snapshot). Selectors run on every state\n   * change — surfaces with expensive transforms should memoize the\n   * selector at call site.\n   *\n   * Returns `null` until the first hydrate / broadcast lands when the\n   * selector is identity; for non-identity selectors the return type is\n   * `T` and the caller's selector decides how to handle the pre-hydrate\n   * `null` snapshot.\n   */\n  useState: {\n    (): S | null;\n    <T>(selector: (state: S | null) => T): T;\n  };\n  /**\n   * Escape hatch — returns the full `{ state, dispatch }` pair as-is.\n   * Useful for consumers that want both the snapshot and the dispatch\n   * fn in a single hook call (e.g. effects that read state THEN\n   * dispatch in response).\n   *\n   * Not a `@demlik/tea` `Runtime<S, M>` — the bridge surface is a thinner\n   * client. This hook returns the same shape as `useBackgroundRuntime`,\n   * just sourced from context instead of mounting a fresh client.\n   */\n  useRuntime: () => UseBackgroundRuntimeResult<S, M>;\n}\n\nconst PROVIDER_ERROR =\n  \"createBackgroundRuntimeContext: hook used outside its Provider. Wrap the consumer in <BackgroundRuntime.Provider opts={...}>.\";\n\nexport function createBackgroundRuntimeContext<\n  S,\n  M extends { type: string },\n>(): BackgroundRuntimeContext<S, M> {\n  // `null` is the \"not inside a Provider\" sentinel — the hooks below\n  // throw on read. Distinct from `state: null` (pre-hydrate), which IS a\n  // valid context value.\n  const Ctx = createContext<UseBackgroundRuntimeResult<S, M> | null>(null);\n\n  function Provider({\n    opts,\n    children,\n  }: {\n    opts: UseBackgroundRuntimeOpts<S>;\n    children: ReactNode;\n  }): ReactNode {\n    const result = useBackgroundRuntime<S, M>(opts);\n    // Stabilize the context value reference so consumers that subscribe via\n    // `useContext` don't re-render unless `state` or `dispatch` actually\n    // changes. `state` is reference-stable (bridge's `getSnapshot` returns\n    // the same `S` until a new broadcast). `dispatch` is stable per\n    // `useBackgroundRuntime`'s `useCallback`. So `useMemo` keyed on both\n    // gives a stable value object across renders.\n    const value = useMemo<UseBackgroundRuntimeResult<S, M>>(\n      () => ({ state: result.state, dispatch: result.dispatch }),\n      [result.state, result.dispatch],\n    );\n    return <Ctx.Provider value={value}>{children}</Ctx.Provider>;\n  }\n\n  function useRuntime(): UseBackgroundRuntimeResult<S, M> {\n    const ctx = useContext(Ctx);\n    if (ctx === null) throw new Error(PROVIDER_ERROR);\n    return ctx;\n  }\n\n  function useDispatch(): (msg: M) => Promise<void> {\n    return useRuntime().dispatch;\n  }\n\n  // Two-overload `useState` so callers see `S | null` without passing a\n  // selector and `T` when they do. The runtime body collapses them — if\n  // `selector` is omitted we pass identity through.\n  function useStateHook(): S | null;\n  function useStateHook<T>(selector: (state: S | null) => T): T;\n  function useStateHook<T>(selector?: (state: S | null) => T): T | (S | null) {\n    const { state } = useRuntime();\n    if (selector === undefined) return state;\n    return selector(state);\n  }\n\n  return {\n    Provider,\n    useDispatch,\n    useState: useStateHook,\n    useRuntime,\n  };\n}\n"]}
+{"version":3,"sources":["../../src/extension/react.tsx"],"names":[],"mappings":";;;;;;;AAoFO,SAAS,oBAAA,CAAoD;AAAA,EAClE,OAAA;AAAA,EACA;AACF,CAAA,EAAkE;AAIhE,EAAA,MAAM,SAAA,GAAY,OAAqD,IAAI,CAAA;AAC3E,EAAA,IAAI,SAAA,CAAU,YAAY,IAAA,EAAM;AAI9B,IAAA,SAAA,CAAU,UAAU,YAAA,CAAmB;AAAA,MACrC,OAAA;AAAA,MACA,UAAA;AAAA,MACA,QAAA,EAAU;AAAA,KACX,CAAA;AAAA,EACH;AACA,EAAA,MAAM,SAAS,SAAA,CAAU,OAAA;AAEzB,EAAA,MAAM,KAAA,GAAQ,oBAAA;AAAA,IACZ,MAAA,CAAO,SAAA;AAAA,IACP,MAAA,CAAO,WAAA;AAAA,IACP,MAAA,CAAO;AAAA,GACT;AAQA,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,MAAA,CAAO,OAAA,EAAQ,CAAE,KAAA,CAAM,MAAM;AAAA,IAE7B,CAAC,CAAA;AAAA,EACH,CAAA,EAAG,CAAC,MAAM,CAAC,CAAA;AAEX,EAAA,MAAM,QAAA,GAAW,WAAA;AAAA,IACf,OAAO,GAAA,KAA0B;AAC/B,MAAA,MAAM,MAAA,CAAO,SAAS,GAAG,CAAA;AAAA,IAC3B,CAAA;AAAA,IACA,CAAC,MAAM;AAAA,GACT;AAEA,EAAA,OAAO,EAAE,OAAO,QAAA,EAAS;AAC3B;AA6DA,IAAM,cAAA,GACJ,+HAAA;AAEK,SAAS,8BAAA,GAGoB;AAIlC,EAAA,MAAM,GAAA,GAAM,cAAuD,IAAI,CAAA;AAEvE,EAAA,SAAS,QAAA,CAAS;AAAA,IAChB,IAAA;AAAA,IACA;AAAA,GACF,EAGc;AACZ,IAAA,MAAM,MAAA,GAAS,qBAA2B,IAAI,CAAA;AAO9C,IAAA,MAAM,KAAA,GAAQ,OAAA;AAAA,MACZ,OAAO,EAAE,KAAA,EAAO,OAAO,KAAA,EAAO,QAAA,EAAU,OAAO,QAAA,EAAS,CAAA;AAAA,MACxD,CAAC,MAAA,CAAO,KAAA,EAAO,MAAA,CAAO,QAAQ;AAAA,KAChC;AACA,IAAA,uBAAO,GAAA,CAAC,GAAA,CAAI,QAAA,EAAJ,EAAa,OAAe,QAAA,EAAS,CAAA;AAAA,EAC/C;AAEA,EAAA,SAAS,UAAA,GAA+C;AACtD,IAAA,MAAM,GAAA,GAAM,WAAW,GAAG,CAAA;AAC1B,IAAA,IAAI,GAAA,KAAQ,IAAA,EAAM,MAAM,IAAI,MAAM,cAAc,CAAA;AAChD,IAAA,OAAO,GAAA;AAAA,EACT;AAEA,EAAA,SAAS,WAAA,GAAyC;AAChD,IAAA,OAAO,YAAW,CAAE,QAAA;AAAA,EACtB;AAOA,EAAA,SAAS,aAAgB,QAAA,EAAmD;AAC1E,IAAA,MAAM,EAAE,KAAA,EAAM,GAAI,UAAA,EAAW;AAC7B,IAAA,IAAI,QAAA,KAAa,QAAW,OAAO,KAAA;AACnC,IAAA,OAAO,SAAS,KAAK,CAAA;AAAA,EACvB;AAEA,EAAA,OAAO;AAAA,IACL,QAAA;AAAA,IACA,WAAA;AAAA,IACA,QAAA,EAAU,YAAA;AAAA,IACV;AAAA,GACF;AACF","file":"react.js","sourcesContent":["/**\n * React adapters for the background TEA runtime.\n *\n * Two layers, both built on the same `bridgeClient`:\n *\n *   1. `useBackgroundRuntime(opts)` — direct hook. One bridge client per\n *      call. Surfaces that only have a single consumer mount it inline.\n *\n *   2. `createBackgroundRuntimeContext<S, M>()` → `{ Provider, useDispatch,\n *      useState, useRuntime }` — factory-style React context. Mounts the\n *      bridge client ONCE inside the Provider; child hooks read `state` /\n *      `dispatch` from context. Surfaces that drill `dispatch` through\n *      multiple component layers, or mount `useBackgroundRuntime` more\n *      than once for the same channel, should use this instead.\n *\n * Why a factory (not a single global context):\n *   - Type safety: each app types it against its own `S` / `M`.\n *   - Tests can mount fresh contexts per test (no module-level state to\n *     reset).\n *   - Multiple-runtimes case: an app COULD theoretically have two\n *     background-shaped runtimes (e.g. one per channel); the factory\n *     pattern doesn't preclude it.\n *\n * Hook lifecycle (`useBackgroundRuntime`) — preserved from the prior\n * single-export module:\n *   1. `useSyncExternalStore` subscribes to broadcasts via\n *      `bridgeClient.subscribe`, reading the latest state via\n *      `bridgeClient.getSnapshot`. Reference stability is owned by the\n *      bridge — `getSnapshot` returns the SAME `S` until a new broadcast\n *      overwrites it, so React doesn't loop.\n *   2. A one-shot `hydrate()` call seeds `latestState` before the first\n *      broadcast arrives. The hydrate side-effect runs in an effect so the\n *      first render shows `null` and the subsequent render flips to the\n *      hydrated snapshot (or stays null if the host is still booting).\n *   3. `dispatch(msg)` sends `:dispatch` envelopes.\n *\n * On unmount: `useSyncExternalStore` removes the listener; the host's\n * bridge stays installed.\n *\n * Canon §3.1: React adapters use `useSyncExternalStore`, not\n * `useState + useEffect`. `useMachine` and `useRuntime` already follow this\n * — `useBackgroundRuntime` (and by extension the Provider) does too. One\n * Way to Do Each Thing.\n *\n * NOTE: This is a separate entry from the main `index.ts` so apps that\n * never need React don't drag react into their type graph. The React\n * adapter peer-depends on react (you must have it installed in the app).\n */\n\n\"use client\";\n\nimport {\n  createContext,\n  type ReactNode,\n  useCallback,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useSyncExternalStore,\n} from \"react\";\nimport { bridgeClient, passThroughMsg } from \"./bridge\";\n\nexport interface UseBackgroundRuntimeOpts<S> {\n  channel: string;\n  /**\n   * REQUIRED parse for inbound `state` payloads. Forwarded to\n   * `bridgeClient` — see `BridgeClientOpts.parseState`. Surfaces own this\n   * because the chrome.runtime boundary is `unknown` (Inv 8). Returning\n   * `null` drops the payload silently.\n   */\n  parseState: (raw: unknown) => S | null;\n}\n\nexport interface UseBackgroundRuntimeResult<S, M> {\n  /** Latest snapshot from the host. `null` until the first hydrate response\n   * or the first broadcast arrives. Surfaces SHOULD render a placeholder\n   * for the null window. */\n  state: S | null;\n  /** Send a msg to the host runtime. Resolves once the host's dispatch\n   * settles. */\n  dispatch(msg: M): Promise<void>;\n}\n\nexport function useBackgroundRuntime<S, M extends { type: string }>({\n  channel,\n  parseState,\n}: UseBackgroundRuntimeOpts<S>): UseBackgroundRuntimeResult<S, M> {\n  // Pin the client across renders. Identity must be stable because\n  // `useSyncExternalStore` deduplicates subscribe by reference; rebuilding\n  // the client every render would re-register listeners every render too.\n  const clientRef = useRef<ReturnType<typeof bridgeClient<S, M>> | null>(null);\n  if (clientRef.current === null) {\n    // This hook surfaces only `state`; the broadcast msg is unused, so it\n    // explicitly opts out of msg parsing via `passThroughMsg`. Same behavior\n    // as the former optional-`parseMsg` default, now a visible decision.\n    clientRef.current = bridgeClient<S, M>({\n      channel,\n      parseState,\n      parseMsg: passThroughMsg,\n    });\n  }\n  const client = clientRef.current;\n\n  const state = useSyncExternalStore<S | null>(\n    client.subscribe,\n    client.getSnapshot,\n    client.getSnapshot,\n  );\n\n  // One-shot hydrate on mount. The hydrate response primes `getSnapshot`\n  // before the first broadcast lands so newly-opened surfaces show the\n  // right view immediately. We don't read its return value — the hook\n  // re-renders when `useSyncExternalStore` notices the snapshot change.\n  // Hydrate failures (host not present yet) are swallowed; surfaces wait\n  // for the next broadcast.\n  useEffect(() => {\n    client.hydrate().catch(() => {\n      // No host yet. Surfaces fall back to broadcasts.\n    });\n  }, [client]);\n\n  const dispatch = useCallback(\n    async (msg: M): Promise<void> => {\n      await client.dispatch(msg);\n    },\n    [client],\n  );\n\n  return { state, dispatch };\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Provider + consumer hooks — factory-style React context.\n//\n// `createBackgroundRuntimeContext<S, M>()` returns a `{ Provider, useDispatch,\n// useState, useRuntime }` tuple bound to the caller's `S` / `M`. The\n// Provider mounts `useBackgroundRuntime(opts)` ONCE internally and shares\n// the `{ state, dispatch }` pair via context. Child consumers (anywhere in\n// the tree) read the slice they need — no prop drilling, single bridge\n// client per channel per Provider mount.\n//\n// The factory is generic; the returned hooks throw a clear error if used\n// outside the Provider so the failure mode is \"loud and obvious\" rather\n// than \"silently returns null state forever\".\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface BackgroundRuntimeContext<S, M> {\n  /**\n   * Wrap a subtree to share a single background-runtime bridge client.\n   * `opts` is forwarded verbatim to `useBackgroundRuntime` — same channel,\n   * same parse contract.\n   */\n  Provider: (props: {\n    opts: UseBackgroundRuntimeOpts<S>;\n    children: ReactNode;\n  }) => ReactNode;\n  /**\n   * Returns the dispatch function bound to this Provider's bridge client.\n   * Reference is stable across renders (per `useBackgroundRuntime`'s\n   * `useCallback`), so passing it to memoized children won't churn them.\n   */\n  useDispatch: () => (msg: M) => Promise<void>;\n  /**\n   * Returns a slice of the latest state. `selector` defaults to identity\n   * (returns the whole `S | null` snapshot). Selectors run on every state\n   * change — surfaces with expensive transforms should memoize the\n   * selector at call site.\n   *\n   * Returns `null` until the first hydrate / broadcast lands when the\n   * selector is identity; for non-identity selectors the return type is\n   * `T` and the caller's selector decides how to handle the pre-hydrate\n   * `null` snapshot.\n   */\n  useState: {\n    (): S | null;\n    <T>(selector: (state: S | null) => T): T;\n  };\n  /**\n   * Escape hatch — returns the full `{ state, dispatch }` pair as-is.\n   * Useful for consumers that want both the snapshot and the dispatch\n   * fn in a single hook call (e.g. effects that read state THEN\n   * dispatch in response).\n   *\n   * Not a `@demlik/tea` `Runtime<S, M>` — the bridge surface is a thinner\n   * client. This hook returns the same shape as `useBackgroundRuntime`,\n   * just sourced from context instead of mounting a fresh client.\n   */\n  useRuntime: () => UseBackgroundRuntimeResult<S, M>;\n}\n\nconst PROVIDER_ERROR =\n  \"createBackgroundRuntimeContext: hook used outside its Provider. Wrap the consumer in <BackgroundRuntime.Provider opts={...}>.\";\n\nexport function createBackgroundRuntimeContext<\n  S,\n  M extends { type: string },\n>(): BackgroundRuntimeContext<S, M> {\n  // `null` is the \"not inside a Provider\" sentinel — the hooks below\n  // throw on read. Distinct from `state: null` (pre-hydrate), which IS a\n  // valid context value.\n  const Ctx = createContext<UseBackgroundRuntimeResult<S, M> | null>(null);\n\n  function Provider({\n    opts,\n    children,\n  }: {\n    opts: UseBackgroundRuntimeOpts<S>;\n    children: ReactNode;\n  }): ReactNode {\n    const result = useBackgroundRuntime<S, M>(opts);\n    // Stabilize the context value reference so consumers that subscribe via\n    // `useContext` don't re-render unless `state` or `dispatch` actually\n    // changes. `state` is reference-stable (bridge's `getSnapshot` returns\n    // the same `S` until a new broadcast). `dispatch` is stable per\n    // `useBackgroundRuntime`'s `useCallback`. So `useMemo` keyed on both\n    // gives a stable value object across renders.\n    const value = useMemo<UseBackgroundRuntimeResult<S, M>>(\n      () => ({ state: result.state, dispatch: result.dispatch }),\n      [result.state, result.dispatch],\n    );\n    return <Ctx.Provider value={value}>{children}</Ctx.Provider>;\n  }\n\n  function useRuntime(): UseBackgroundRuntimeResult<S, M> {\n    const ctx = useContext(Ctx);\n    if (ctx === null) throw new Error(PROVIDER_ERROR);\n    return ctx;\n  }\n\n  function useDispatch(): (msg: M) => Promise<void> {\n    return useRuntime().dispatch;\n  }\n\n  // Two-overload `useState` so callers see `S | null` without passing a\n  // selector and `T` when they do. The runtime body collapses them — if\n  // `selector` is omitted we pass identity through.\n  function useStateHook(): S | null;\n  function useStateHook<T>(selector: (state: S | null) => T): T;\n  function useStateHook<T>(selector?: (state: S | null) => T): T | (S | null) {\n    const { state } = useRuntime();\n    if (selector === undefined) return state;\n    return selector(state);\n  }\n\n  return {\n    Provider,\n    useDispatch,\n    useState: useStateHook,\n    useRuntime,\n  };\n}\n"]}

package/dist/extension/subs/index.d.ts

@@ -1,5 +1,5 @@
-import { S as Sub } from '../../core-BmlJOvxM.js';
-import { S as SubscribeHandler } from '../../types-BoUWgwSm.js';
+import { S as Sub } from '../../core-42kapW0n.js';
+import { S as SubscribeHandler } from '../../types-KbL3W1mj.js';
 
 type AlarmSubData = {
     alarmName: string;

package/dist/extension/subs/index.js

@@ -1,10 +1,11 @@
+import { dispatchIfPresent } from '../../chunk-ZJ5AOYBH.js';
+
 // src/extension/subs/from-chrome-alarm.ts
 function fromChromeAlarm(msgFn) {
   return (sub, _ctx, dispatch) => {
     const listener = (alarm) => {
       if (alarm.name !== sub.alarmName) return;
-      const msg = msgFn(alarm, sub);
-      if (msg !== null) dispatch(msg);
+      dispatchIfPresent(dispatch, msgFn(alarm, sub));
     };
     chrome.alarms.onAlarm.addListener(listener);
     return () => chrome.alarms.onAlarm.removeListener(listener);
@@ -16,8 +17,7 @@ function fromChromeMessage(opts) {
   return (sub, _ctx, dispatch) => {
     const listener = (message, sender, _sendResponse) => {
       if (opts.filter !== void 0 && !opts.filter(message)) return;
-      const msg = opts.msgFn(message, sender, sub);
-      if (msg !== null) dispatch(msg);
+      dispatchIfPresent(dispatch, opts.msgFn(message, sender, sub));
     };
     chrome.runtime.onMessage.addListener(listener);
     return () => {
@@ -42,8 +42,7 @@ function fromChromeStorageChange(opts) {
         }
         if (!overlap) return;
       }
-      const msg = opts.msgFn(changes, sub);
-      if (msg !== null) dispatch(msg);
+      dispatchIfPresent(dispatch, opts.msgFn(changes, sub));
     };
     chrome.storage.onChanged.addListener(listener);
     return () => {
@@ -57,8 +56,7 @@ function fromChromeTabsEvent(opts) {
   return (sub, _ctx, dispatch) => {
     const installed = [];
     const listener = () => {
-      const msg = opts.msgFn(sub);
-      if (msg !== null) dispatch(msg);
+      dispatchIfPresent(dispatch, opts.msgFn(sub));
     };
     for (const event of opts.events) {
       const emitter = chrome.tabs[event];
@@ -66,8 +64,7 @@ function fromChromeTabsEvent(opts) {
       installed.push(event);
     }
     if (opts.fireOnMount === true) {
-      const msg = opts.msgFn(sub);
-      if (msg !== null) dispatch(msg);
+      dispatchIfPresent(dispatch, opts.msgFn(sub));
     }
     return () => {
       for (const event of installed) {

package/dist/extension/subs/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/extension/subs/from-chrome-alarm.ts","../../../src/extension/subs/from-chrome-message.ts","../../../src/extension/subs/from-chrome-storage-change.ts","../../../src/extension/subs/from-chrome-tabs-event.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["// ---------------------------------------------------------------------------\n// fromChromeAlarm — pure observer for `chrome.alarms.onAlarm`.\n//\n// chrome.alarms is a PERSISTENT resource (the alarm registry survives MV3\n// service-worker restarts — that's the whole reason it exists). Modeling\n// alarm CREATION inside `Sub.subscribe` conflates two concerns:\n//\n//   - Persistent-resource lifecycle (create/clear) — caller's responsibility,\n//     expressed as Cmds (typically `ensure_alarm` on boot, `clear_alarm`\n//     when retiring). Cmds run through `interpret`, where async is the\n//     contract.\n//   - Event observation — the Sub's responsibility. `SubscribeHandler` is\n//     SYNC: `(sub, ctx, dispatch) => () => void`. Mixing in a check-then-\n//     create await chain forces a `void (async () => …)()` wrapper that\n//     hides errors and breaks test ordering.\n//\n// World B: the Sub is pure listener. It carries `alarmName` only,\n// addListener + filter on mount, removeListener on cleanup. The Cmd\n// vocabulary in the consumer machine (`ensure_alarm`, `clear_alarm`) owns\n// the create/clear lifecycle.\n//\n// Cites invariant 3 (effects describe via Cmd, not perform inside Sub) and\n// invariant 4 (external events enter as Subs — observation only).\n// ---------------------------------------------------------------------------\n\nimport type { Sub } from \"../../index\";\nimport type { SubscribeHandler } from \"../../subs/index\";\n\ntype AlarmSubData = { alarmName: string };\n\nexport function fromChromeAlarm<S extends Sub & AlarmSubData, M>(\n  msgFn: (alarm: chrome.alarms.Alarm, sub: S) => M | null,\n): SubscribeHandler<S, M, unknown> {\n  return (sub, _ctx, dispatch) => {\n    const listener = (alarm: chrome.alarms.Alarm): void => {\n      // Filter by name — onAlarm fires for EVERY alarm registered in the\n      // extension, not just ours. Without this filter, two Subs with\n      // different alarmName values would cross-dispatch.\n      if (alarm.name !== sub.alarmName) return;\n      const msg = msgFn(alarm, sub);\n      if (msg !== null) dispatch(msg);\n    };\n    chrome.alarms.onAlarm.addListener(listener);\n    return () => chrome.alarms.onAlarm.removeListener(listener);\n  };\n}\n","// ---------------------------------------------------------------------------\n// fromChromeMessage — universal `chrome.runtime.onMessage`-shaped Sub\n// factory.\n//\n// `chrome.runtime.onMessage` is the extension's intra-process message bus:\n// the service worker receives broadcasts from popup, options, content\n// scripts, and the WebApp's `chrome.runtime.sendMessage` calls. Every\n// listener wakes for every message; consumers filter by shape (the message\n// is `unknown` to chrome — only the participants share a schema).\n//\n// Shape choices:\n//\n//   - `filter?: (message: unknown) => boolean` — optional pre-filter that\n//     runs BEFORE `msgFn`. The factory drops the dispatch when `filter`\n//     returns false. Use this for cheap discriminant checks (e.g.\n//     `message.type === \"ping\"`) that short-circuit before the more\n//     expensive Msg construction.\n//\n//   - `msgFn(message, sender, sub)` — both the message AND the sender\n//     are forwarded. `sender` carries `tab.id` for content-script sends\n//     and `id` for cross-extension sends; consumers that route by sender\n//     (e.g. \"only accept from this tab\") need it. Returns `M | null`;\n//     null drops the dispatch.\n//\n// What this factory deliberately does NOT do:\n//\n//   - It does not call `sendResponse` or return `true` from the listener\n//     — that's the request/response shape, not the broadcast shape. A\n//     factory that supports both would have to commit to a Promise<M>\n//     return path, which couples to async-Cmd plumbing that's not in\n//     scope for a Sub. Use a one-shot Cmd handler for request/response.\n//\n// Strengthens invariant 9 (named, small surface) and invariant 2 (the\n// reducer never sees chrome.runtime.onMessage).\n// ---------------------------------------------------------------------------\n\nimport type { Sub } from \"../../index\";\nimport type { SubscribeHandler } from \"../../subs/index\";\n\nexport interface ChromeMessageOpts<S extends Sub, M> {\n  /**\n   * Pre-filter — when provided, the factory only dispatches when this\n   * returns `true`. Cheap discriminant checks belong here.\n   */\n  filter?: (message: unknown) => boolean;\n  msgFn: (\n    message: unknown,\n    sender: chrome.runtime.MessageSender,\n    sub: S,\n  ) => M | null;\n}\n\nexport function fromChromeMessage<S extends Sub, M>(\n  opts: ChromeMessageOpts<S, M>,\n): SubscribeHandler<S, M, unknown> {\n  return (sub, _ctx, dispatch) => {\n    const listener = (\n      message: unknown,\n      sender: chrome.runtime.MessageSender,\n      _sendResponse: (response: unknown) => void,\n    ): void => {\n      if (opts.filter !== undefined && !opts.filter(message)) return;\n      const msg = opts.msgFn(message, sender, sub);\n      if (msg !== null) dispatch(msg);\n      // We intentionally do not return `true` here — that's the\n      // request/response posture, not the broadcast posture. See the\n      // module comment for the rationale.\n    };\n    chrome.runtime.onMessage.addListener(listener);\n    return () => {\n      chrome.runtime.onMessage.removeListener(listener);\n    };\n  };\n}\n","// ---------------------------------------------------------------------------\n// fromChromeStorageChange — universal `chrome.storage.onChanged`-shaped Sub\n// factory.\n//\n// `chrome.storage.onChanged` is the top-level event that fires for every\n// area (`local`, `sync`, `session`, `managed`) — the listener receives\n// `(changes, areaName)`. Consumers typically care about ONE area and often\n// only a subset of keys; without a filter, every listener wakes for every\n// change anywhere in the extension's storage. The factory absorbs the\n// addListener/removeListener pair PLUS the standard area/key filter.\n//\n// Shape choices:\n//\n//   - `area: chrome.storage.AreaName` — required. Chrome's typing covers\n//     \"local\" | \"sync\" | \"session\" | \"managed\". The factory drops every\n//     fire where `areaName !== opts.area`.\n//\n//   - `keys?: readonly string[]` — optional intersection filter. When\n//     provided, the factory drops fires where none of the changed keys\n//     overlaps with the requested set. Omitting means \"any key in the\n//     area\". The filter is `O(keys × changes)` per fire — acceptable for\n//     small key lists (typical: 1-5 keys per Sub).\n//\n//   - `msgFn` may return `null` — drops the dispatch even after the\n//     area/keys filters pass. Gives the caller a final hook for\n//     state-aware filtering (e.g. \"only when the new value is\n//     truthy\").\n//\n// Strengthens invariant 9 (named, small surface) and invariant 2 (the\n// reducer never sees chrome.storage; the factory owns the wiring).\n// ---------------------------------------------------------------------------\n\nimport type { Sub } from \"../../index\";\nimport type { SubscribeHandler } from \"../../subs/index\";\n\nexport interface ChromeStorageChangeOpts<S extends Sub, M> {\n  area: chrome.storage.AreaName;\n  /**\n   * If provided, only dispatch when at least one of the changed keys\n   * overlaps with this set. Omitting means \"any key in the area\".\n   */\n  keys?: readonly string[];\n  msgFn: (\n    changes: Record<string, chrome.storage.StorageChange>,\n    sub: S,\n  ) => M | null;\n}\n\nexport function fromChromeStorageChange<S extends Sub, M>(\n  opts: ChromeStorageChangeOpts<S, M>,\n): SubscribeHandler<S, M, unknown> {\n  return (sub, _ctx, dispatch) => {\n    const listener = (\n      changes: Record<string, chrome.storage.StorageChange>,\n      areaName: chrome.storage.AreaName,\n    ): void => {\n      if (areaName !== opts.area) return;\n      if (opts.keys !== undefined) {\n        // Intersect — at least one changed key must be in opts.keys.\n        // Using a small list scan over Object.keys(changes) avoids\n        // allocating a Set per fire for the typical 1-5 key case.\n        const changedKeys = Object.keys(changes);\n        let overlap = false;\n        for (const k of opts.keys) {\n          if (changedKeys.includes(k)) {\n            overlap = true;\n            break;\n          }\n        }\n        if (!overlap) return;\n      }\n      const msg = opts.msgFn(changes, sub);\n      if (msg !== null) dispatch(msg);\n    };\n    chrome.storage.onChanged.addListener(listener);\n    return () => {\n      chrome.storage.onChanged.removeListener(listener);\n    };\n  };\n}\n","// ---------------------------------------------------------------------------\n// fromChromeTabsEvent — universal `chrome.tabs.on*`-shaped Sub factory.\n//\n// chrome.tabs exposes a small set of lifecycle events (`onActivated`,\n// `onUpdated`, `onRemoved`) with different listener signatures but the\n// same wiring shape: register listener, dispatch on fire, remove on\n// cleanup. Most consumers subscribe to a SET of these events and treat\n// every fire the same way (e.g. \"tabs changed, please re-query\"). The\n// recurring ~20-line `addListener` × N + `removeListener` × N + optional\n// mount-time refresh is what this factory absorbs.\n//\n// Three shape choices worth flagging:\n//\n//   - `events: readonly TabsEventName[]` — a SET (semantically), passed\n//     as a tuple so the caller can be terse. The factory registers a\n//     single listener per event name. The listener fires `msgFn(sub)`;\n//     event-specific payloads (`activeInfo`, `tabId`, `changeInfo`,\n//     `removeInfo`) are NOT forwarded — consumers that care about which\n//     event fired model that as separate Subs with different ids.\n//\n//   - `fireOnMount?: boolean` — synthetic immediate dispatch at subscribe\n//     time. Most \"watch tabs\" subscriptions need the first emission to\n//     populate state without waiting for the first chrome event; this is\n//     the named, opt-in form of the otherwise-recurring `void refresh()`\n//     line at the top of every chrome-tabs subscribe cell. Default\n//     `false` matches the surprise principle (no synthetic dispatch\n//     unless the caller asks for one).\n//\n//   - `msgFn` may return `null` — drops the dispatch. The event fired,\n//     the factory called `msgFn`, the caller decided \"this event is not\n//     interesting given current state.\" No dispatch is made; listeners\n//     stay armed for the next fire.\n//\n// Cleanup removes listeners from every event the factory installed —\n// not from the full `events` list, since a future edit could expand the\n// list mid-Sub. Captured the resolved set at subscribe time.\n//\n// Strengthens invariant 9 (named, small surface) and invariant 2 (the\n// reducer never sees chrome.tabs; the factory owns the wiring).\n// ---------------------------------------------------------------------------\n\nimport type { Sub } from \"../../index\";\nimport type { SubscribeHandler } from \"../../subs/index\";\n\nexport type TabsEventName = \"onActivated\" | \"onUpdated\" | \"onRemoved\";\n\nexport interface ChromeTabsEventOpts<S extends Sub, M> {\n  events: readonly TabsEventName[];\n  /**\n   * If `true`, the factory dispatches a synthetic `msgFn(sub)` once at\n   * subscribe time — useful for \"populate tab list on mount\" patterns\n   * where the first emission must not wait for chrome to fire an event.\n   * Default `false`.\n   */\n  fireOnMount?: boolean;\n  msgFn: (sub: S) => M | null;\n}\n\n// The chrome.tabs.on* events have different listener signatures\n// (`activeInfo`, `(tabId, changeInfo, tab)`, `(tabId, removeInfo)`). We\n// type the listener as accepting unknown args because the factory does\n// not forward the event payload — every event collapses to `msgFn(sub)`.\ntype AnyTabsListener = (...args: unknown[]) => void;\n\nexport function fromChromeTabsEvent<S extends Sub, M>(\n  opts: ChromeTabsEventOpts<S, M>,\n): SubscribeHandler<S, M, unknown> {\n  return (sub, _ctx, dispatch) => {\n    const installed: TabsEventName[] = [];\n    const listener: AnyTabsListener = () => {\n      const msg = opts.msgFn(sub);\n      if (msg !== null) dispatch(msg);\n    };\n\n    for (const event of opts.events) {\n      // Each chrome.tabs.onX is a typed EventEmitter — addListener takes\n      // a callback whose signature matches the event. Cast at the chrome\n      // boundary since the factory collapses every payload shape into a\n      // single `msgFn(sub)` call.\n      const emitter = chrome.tabs[\n        event\n      ] as chrome.events.Event<AnyTabsListener>;\n      emitter.addListener(listener);\n      installed.push(event);\n    }\n\n    if (opts.fireOnMount === true) {\n      const msg = opts.msgFn(sub);\n      if (msg !== null) dispatch(msg);\n    }\n\n    return () => {\n      for (const event of installed) {\n        const emitter = chrome.tabs[\n          event\n        ] as chrome.events.Event<AnyTabsListener>;\n        emitter.removeListener(listener);\n      }\n    };\n  };\n}\n"]}
+{"version":3,"sources":["../../../src/extension/subs/from-chrome-alarm.ts","../../../src/extension/subs/from-chrome-message.ts","../../../src/extension/subs/from-chrome-storage-change.ts","../../../src/extension/subs/from-chrome-tabs-event.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["// ---------------------------------------------------------------------------\n// fromChromeAlarm — pure observer for `chrome.alarms.onAlarm`.\n//\n// chrome.alarms is a PERSISTENT resource (the alarm registry survives MV3\n// service-worker restarts — that's the whole reason it exists). Modeling\n// alarm CREATION inside `Sub.subscribe` conflates two concerns:\n//\n//   - Persistent-resource lifecycle (create/clear) — caller's responsibility,\n//     expressed as Cmds (typically `ensure_alarm` on boot, `clear_alarm`\n//     when retiring). Cmds run through `interpret`, where async is the\n//     contract.\n//   - Event observation — the Sub's responsibility. `SubscribeHandler` is\n//     SYNC: `(sub, ctx, dispatch) => () => void`. Mixing in a check-then-\n//     create await chain forces a `void (async () => …)()` wrapper that\n//     hides errors and breaks test ordering.\n//\n// World B: the Sub is pure listener. It carries `alarmName` only,\n// addListener + filter on mount, removeListener on cleanup. The Cmd\n// vocabulary in the consumer machine (`ensure_alarm`, `clear_alarm`) owns\n// the create/clear lifecycle.\n//\n// Cites invariant 3 (effects describe via Cmd, not perform inside Sub) and\n// invariant 4 (external events enter as Subs — observation only).\n// ---------------------------------------------------------------------------\n\nimport type { Sub } from \"../../index\";\nimport type { SubscribeHandler } from \"../../subs/index\";\nimport { dispatchIfPresent } from \"../../subs/types\";\n\ntype AlarmSubData = { alarmName: string };\n\nexport function fromChromeAlarm<S extends Sub & AlarmSubData, M>(\n  msgFn: (alarm: chrome.alarms.Alarm, sub: S) => M | null,\n): SubscribeHandler<S, M, unknown> {\n  return (sub, _ctx, dispatch) => {\n    const listener = (alarm: chrome.alarms.Alarm): void => {\n      // Filter by name — onAlarm fires for EVERY alarm registered in the\n      // extension, not just ours. Without this filter, two Subs with\n      // different alarmName values would cross-dispatch.\n      if (alarm.name !== sub.alarmName) return;\n      dispatchIfPresent(dispatch, msgFn(alarm, sub));\n    };\n    chrome.alarms.onAlarm.addListener(listener);\n    return () => chrome.alarms.onAlarm.removeListener(listener);\n  };\n}\n","// ---------------------------------------------------------------------------\n// fromChromeMessage — universal `chrome.runtime.onMessage`-shaped Sub\n// factory.\n//\n// `chrome.runtime.onMessage` is the extension's intra-process message bus:\n// the service worker receives broadcasts from popup, options, content\n// scripts, and the WebApp's `chrome.runtime.sendMessage` calls. Every\n// listener wakes for every message; consumers filter by shape (the message\n// is `unknown` to chrome — only the participants share a schema).\n//\n// Shape choices:\n//\n//   - `filter?: (message: unknown) => boolean` — optional pre-filter that\n//     runs BEFORE `msgFn`. The factory drops the dispatch when `filter`\n//     returns false. Use this for cheap discriminant checks (e.g.\n//     `message.type === \"ping\"`) that short-circuit before the more\n//     expensive Msg construction.\n//\n//   - `msgFn(message, sender, sub)` — both the message AND the sender\n//     are forwarded. `sender` carries `tab.id` for content-script sends\n//     and `id` for cross-extension sends; consumers that route by sender\n//     (e.g. \"only accept from this tab\") need it. Returns `M | null`;\n//     null drops the dispatch.\n//\n// What this factory deliberately does NOT do:\n//\n//   - It does not call `sendResponse` or return `true` from the listener\n//     — that's the request/response shape, not the broadcast shape. A\n//     factory that supports both would have to commit to a Promise<M>\n//     return path, which couples to async-Cmd plumbing that's not in\n//     scope for a Sub. Use a one-shot Cmd handler for request/response.\n//\n// Strengthens invariant 9 (named, small surface) and invariant 2 (the\n// reducer never sees chrome.runtime.onMessage).\n// ---------------------------------------------------------------------------\n\nimport type { Sub } from \"../../index\";\nimport type { SubscribeHandler } from \"../../subs/index\";\nimport { dispatchIfPresent } from \"../../subs/types\";\n\nexport interface ChromeMessageOpts<S extends Sub, M> {\n  /**\n   * Pre-filter — when provided, the factory only dispatches when this\n   * returns `true`. Cheap discriminant checks belong here.\n   */\n  filter?: (message: unknown) => boolean;\n  msgFn: (\n    message: unknown,\n    sender: chrome.runtime.MessageSender,\n    sub: S,\n  ) => M | null;\n}\n\nexport function fromChromeMessage<S extends Sub, M>(\n  opts: ChromeMessageOpts<S, M>,\n): SubscribeHandler<S, M, unknown> {\n  return (sub, _ctx, dispatch) => {\n    const listener = (\n      message: unknown,\n      sender: chrome.runtime.MessageSender,\n      _sendResponse: (response: unknown) => void,\n    ): void => {\n      if (opts.filter !== undefined && !opts.filter(message)) return;\n      dispatchIfPresent(dispatch, opts.msgFn(message, sender, sub));\n      // We intentionally do not return `true` here — that's the\n      // request/response posture, not the broadcast posture. See the\n      // module comment for the rationale.\n    };\n    chrome.runtime.onMessage.addListener(listener);\n    return () => {\n      chrome.runtime.onMessage.removeListener(listener);\n    };\n  };\n}\n","// ---------------------------------------------------------------------------\n// fromChromeStorageChange — universal `chrome.storage.onChanged`-shaped Sub\n// factory.\n//\n// `chrome.storage.onChanged` is the top-level event that fires for every\n// area (`local`, `sync`, `session`, `managed`) — the listener receives\n// `(changes, areaName)`. Consumers typically care about ONE area and often\n// only a subset of keys; without a filter, every listener wakes for every\n// change anywhere in the extension's storage. The factory absorbs the\n// addListener/removeListener pair PLUS the standard area/key filter.\n//\n// Shape choices:\n//\n//   - `area: chrome.storage.AreaName` — required. Chrome's typing covers\n//     \"local\" | \"sync\" | \"session\" | \"managed\". The factory drops every\n//     fire where `areaName !== opts.area`.\n//\n//   - `keys?: readonly string[]` — optional intersection filter. When\n//     provided, the factory drops fires where none of the changed keys\n//     overlaps with the requested set. Omitting means \"any key in the\n//     area\". The filter is `O(keys × changes)` per fire — acceptable for\n//     small key lists (typical: 1-5 keys per Sub).\n//\n//   - `msgFn` may return `null` — drops the dispatch even after the\n//     area/keys filters pass. Gives the caller a final hook for\n//     state-aware filtering (e.g. \"only when the new value is\n//     truthy\").\n//\n// Strengthens invariant 9 (named, small surface) and invariant 2 (the\n// reducer never sees chrome.storage; the factory owns the wiring).\n// ---------------------------------------------------------------------------\n\nimport type { Sub } from \"../../index\";\nimport type { SubscribeHandler } from \"../../subs/index\";\nimport { dispatchIfPresent } from \"../../subs/types\";\n\nexport interface ChromeStorageChangeOpts<S extends Sub, M> {\n  area: chrome.storage.AreaName;\n  /**\n   * If provided, only dispatch when at least one of the changed keys\n   * overlaps with this set. Omitting means \"any key in the area\".\n   */\n  keys?: readonly string[];\n  msgFn: (\n    changes: Record<string, chrome.storage.StorageChange>,\n    sub: S,\n  ) => M | null;\n}\n\nexport function fromChromeStorageChange<S extends Sub, M>(\n  opts: ChromeStorageChangeOpts<S, M>,\n): SubscribeHandler<S, M, unknown> {\n  return (sub, _ctx, dispatch) => {\n    const listener = (\n      changes: Record<string, chrome.storage.StorageChange>,\n      areaName: chrome.storage.AreaName,\n    ): void => {\n      if (areaName !== opts.area) return;\n      if (opts.keys !== undefined) {\n        // Intersect — at least one changed key must be in opts.keys.\n        // Using a small list scan over Object.keys(changes) avoids\n        // allocating a Set per fire for the typical 1-5 key case.\n        const changedKeys = Object.keys(changes);\n        let overlap = false;\n        for (const k of opts.keys) {\n          if (changedKeys.includes(k)) {\n            overlap = true;\n            break;\n          }\n        }\n        if (!overlap) return;\n      }\n      dispatchIfPresent(dispatch, opts.msgFn(changes, sub));\n    };\n    chrome.storage.onChanged.addListener(listener);\n    return () => {\n      chrome.storage.onChanged.removeListener(listener);\n    };\n  };\n}\n","// ---------------------------------------------------------------------------\n// fromChromeTabsEvent — universal `chrome.tabs.on*`-shaped Sub factory.\n//\n// chrome.tabs exposes a small set of lifecycle events (`onActivated`,\n// `onUpdated`, `onRemoved`) with different listener signatures but the\n// same wiring shape: register listener, dispatch on fire, remove on\n// cleanup. Most consumers subscribe to a SET of these events and treat\n// every fire the same way (e.g. \"tabs changed, please re-query\"). The\n// recurring ~20-line `addListener` × N + `removeListener` × N + optional\n// mount-time refresh is what this factory absorbs.\n//\n// Three shape choices worth flagging:\n//\n//   - `events: readonly TabsEventName[]` — a SET (semantically), passed\n//     as a tuple so the caller can be terse. The factory registers a\n//     single listener per event name. The listener fires `msgFn(sub)`;\n//     event-specific payloads (`activeInfo`, `tabId`, `changeInfo`,\n//     `removeInfo`) are NOT forwarded — consumers that care about which\n//     event fired model that as separate Subs with different ids.\n//\n//   - `fireOnMount?: boolean` — synthetic immediate dispatch at subscribe\n//     time. Most \"watch tabs\" subscriptions need the first emission to\n//     populate state without waiting for the first chrome event; this is\n//     the named, opt-in form of the otherwise-recurring `void refresh()`\n//     line at the top of every chrome-tabs subscribe cell. Default\n//     `false` matches the surprise principle (no synthetic dispatch\n//     unless the caller asks for one).\n//\n//   - `msgFn` may return `null` — drops the dispatch. The event fired,\n//     the factory called `msgFn`, the caller decided \"this event is not\n//     interesting given current state.\" No dispatch is made; listeners\n//     stay armed for the next fire.\n//\n// Cleanup removes listeners from every event the factory installed —\n// not from the full `events` list, since a future edit could expand the\n// list mid-Sub. Captured the resolved set at subscribe time.\n//\n// Strengthens invariant 9 (named, small surface) and invariant 2 (the\n// reducer never sees chrome.tabs; the factory owns the wiring).\n// ---------------------------------------------------------------------------\n\nimport type { Sub } from \"../../index\";\nimport type { SubscribeHandler } from \"../../subs/index\";\nimport { dispatchIfPresent } from \"../../subs/types\";\n\nexport type TabsEventName = \"onActivated\" | \"onUpdated\" | \"onRemoved\";\n\nexport interface ChromeTabsEventOpts<S extends Sub, M> {\n  events: readonly TabsEventName[];\n  /**\n   * If `true`, the factory dispatches a synthetic `msgFn(sub)` once at\n   * subscribe time — useful for \"populate tab list on mount\" patterns\n   * where the first emission must not wait for chrome to fire an event.\n   * Default `false`.\n   */\n  fireOnMount?: boolean;\n  msgFn: (sub: S) => M | null;\n}\n\n// The chrome.tabs.on* events have different listener signatures\n// (`activeInfo`, `(tabId, changeInfo, tab)`, `(tabId, removeInfo)`). We\n// type the listener as accepting unknown args because the factory does\n// not forward the event payload — every event collapses to `msgFn(sub)`.\ntype AnyTabsListener = (...args: unknown[]) => void;\n\nexport function fromChromeTabsEvent<S extends Sub, M>(\n  opts: ChromeTabsEventOpts<S, M>,\n): SubscribeHandler<S, M, unknown> {\n  return (sub, _ctx, dispatch) => {\n    const installed: TabsEventName[] = [];\n    const listener: AnyTabsListener = () => {\n      dispatchIfPresent(dispatch, opts.msgFn(sub));\n    };\n\n    for (const event of opts.events) {\n      // Each chrome.tabs.onX is a typed EventEmitter — addListener takes\n      // a callback whose signature matches the event. Cast at the chrome\n      // boundary since the factory collapses every payload shape into a\n      // single `msgFn(sub)` call.\n      const emitter = chrome.tabs[\n        event\n      ] as chrome.events.Event<AnyTabsListener>;\n      emitter.addListener(listener);\n      installed.push(event);\n    }\n\n    if (opts.fireOnMount === true) {\n      dispatchIfPresent(dispatch, opts.msgFn(sub));\n    }\n\n    return () => {\n      for (const event of installed) {\n        const emitter = chrome.tabs[\n          event\n        ] as chrome.events.Event<AnyTabsListener>;\n        emitter.removeListener(listener);\n      }\n    };\n  };\n}\n"]}

package/dist/fan-out/index.d.ts

@@ -1,6 +1,6 @@
-import { C as Cmd, P as Port } from '../core-BmlJOvxM.js';
+import { C as Cmd, P as Port } from '../core-42kapW0n.js';
 import { QueueItem } from '../work-queue/index.js';
-import '../index.js';
+import '../runtime-types-CukV8kMX.js';
 
 /**
  * @demlik/tea/fan-out — scatter-gather over a bounded-concurrency work list.
@@ -18,19 +18,19 @@ import '../index.js';
  *     partitions over that one lifecycle, so the work-queue's status taxonomy
  *     is the substrate rather than a parallel invention. We reuse its
  *     `QueueItem<I>` / `QueueItemStatus` TYPES and delegate the ledger
- *     transitions to its BLESSED pure ops (`@demlik/tea/work-queue/ops`):
- *     `scatter` mints each pending record with `enqueueOp`, and `launchUpTo`
- *     flips `pending → running` with `claimNextOp` (one positional claim per
+ *     transitions to the `QueueAdapter` verbs (`../work-queue/adapter`):
+ *     `scatter` mints each pending record with `queue.enqueue`, and `launchUpTo`
+ *     flips `pending → running` with `queue.claim` (one positional claim per
  *     launch). The lone exception is `settleOne`'s `running → done|failed`
  *     flip — it must match "first id-match that is still `running`" to settle
- *     exactly one of a DUPLICATE id, a status predicate the ops surface can't
+ *     exactly one of a DUPLICATE id, a status predicate the adapter verbs can't
  *     express, so fan-out owns that one index (see `settleOne`). The async
  *     `createQueue(store)` adapter is NOT used here because its `load → mutate
  *     → save` reads the clock and lives at an I/O boundary, while a combinator's
- *     verbs must be pure (invariant 2) — fan-out reaches the underlying ops
- *     directly instead, the same route `monitored-run` / `idempotent-intake`
- *     take. The slice lives in the Model instead — durable + replayable, the
- *     two non-negotiables every knob preserves.
+ *     verbs must be pure (invariant 2) — fan-out binds the pure `QueueAdapter`
+ *     to its in-Model ledger instead, the same route `monitored-run` /
+ *     `idempotent-intake` / `saga` take. The slice lives in the Model instead —
+ *     durable + replayable, the two non-negotiables every knob preserves.
  *
  * Typical wiring (combinator form — splice the hooks into your machine):
  *

package/dist/fan-out/index.js

@@ -1,5 +1,5 @@
-export { createFanOut, initFanOut, isComplete } from '../chunk-UV6UWGEO.js';
-import '../chunk-HJO6VNQI.js';
-import '../chunk-TGG26XMK.js';
+export { createFanOut, initFanOut, isComplete } from '../chunk-D736QUGF.js';
+import '../chunk-MU6MCIAC.js';
+import '../chunk-FV3Z5MBE.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/idempotent-intake/index.d.ts

@@ -1,7 +1,7 @@
 import { IdempotencyStore } from '../idempotency/index.js';
-import { C as Cmd } from '../core-BmlJOvxM.js';
+import { C as Cmd } from '../core-42kapW0n.js';
 import { QueueItem } from '../work-queue/index.js';
-import '../index.js';
+import '../runtime-types-CukV8kMX.js';
 
 /**
  * @demlik/tea/idempotent-intake — receive-once intake for webhooks / queue

package/dist/idempotent-intake/index.js

@@ -1,7 +1,7 @@
-export { createIntake } from '../chunk-LEC4U6CX.js';
+export { createIntake } from '../chunk-ZVJZ72HY.js';
 import '../chunk-BYQUGDD3.js';
 import '../chunk-K575PT4S.js';
-import '../chunk-HJO6VNQI.js';
-import '../chunk-TGG26XMK.js';
+import '../chunk-MU6MCIAC.js';
+import '../chunk-FV3Z5MBE.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map