@demlik/tea 0.13.0 → 0.15.0

package/dist/deadline/index.d.ts

@@ -1,199 +0,0 @@
-import { S as Sub, b as SubId } from '../core-Co0LWkIA.js';
-import { S as SubscribeHandler } from '../types-XS_miRnB.js';
-import 'zod';
-
-/**
- * @demlik/tea/deadline — a one-shot Sub that fires when an ABSOLUTE wall-clock
- * deadline is reached.
- *
- * Generalizes the recurring "auto-fail a machine at T+N" / "15-minute stale
- * guard" pattern: a Sub whose `subscriptions(state)` returns it only while the
- * deadline should be armed, and which dispatches a single `DeadlineExceeded`
- * Msg when the wall clock crosses `atMs`.
- *
- * Difference from `fromTimeout` (relative — "fire after N ms"): a deadline is
- * an ABSOLUTE target. The delay is computed at subscribe time as
- * `max(0, atMs - Date.now())`. The consequence that matters: subscribing LATE —
- * e.g. after a `Store` rehydrate that resumes a machine whose deadline was set
- * before the page reloaded — still fires at the correct absolute moment,
- * because the remaining delay is recomputed from the current clock, not stored
- * in the Sub. A deadline already in the past at subscribe time yields delay `0`,
- * so `setTimeout(fn, 0)` fires on the NEXT tick (never synchronously inside the
- * reconcile pass — the substrate must finish wiring all subs before any Msg
- * lands).
- *
- * Composition over reinvention: the timer lifecycle is `fromTimeout`'s, not
- * redrawn here. `deadlineSub` produces the Sub literal carrying `atMs`; the
- * `subscribe` cell (`subscribeDeadline`) translates `atMs` → a relative delay
- * and delegates the `setTimeout` / `clearTimeout` to `fromTimeout`. The clock
- * read (`Date.now()`) lives only in the subscribe handler — never in a reducer
- * (invariant 2) — and is exercised in tests via vitest fake timers, matching
- * the no-injection convention of the `fromTimeout` / `fromInterval` exemplars.
- *
- * WHAT BACKS THE TIMER IS THE HOST'S CHOICE. `setTimeout` is the universal
- * default, but it is not universal: a Durable Object that hibernates has no
- * live `setTimeout` to wake it, so its deadline must be backed by a `do_alarm`
- * registered on the alarm registry; a test host wants a fake-timer schedule.
- * That backing is the `ArmTimer` seam — `subscribeWith(armTimer)` builds the
- * `subscribe.deadline` cell from a host-plugged timer, and `subscribeDeadline`
- * IS `subscribeWith(setTimeoutArmTimer())`. One deadline surface, three hosts;
- * there is no second Sub type and no second `atMs` anchor to keep in sync.
- *
- * The anchor is what makes the seam safe. `atMs` is ABSOLUTE, so whatever backs
- * it arms to a fixed wall-clock instant: the host computes the gap itself
- * (`atMs - Date.now()`), and on a host that just rehydrated after hibernation
- * that gap is the SHRUNKEN remainder — the deadline honours the original target
- * rather than resetting to a fresh full-length window.
- *
- * Strengthens invariant 4 (external time is a subscription — the deadline is a
- * `Sub` the runtime reconciles, never a `setTimeout` leaked into a reducer) and
- * invariant 7 (identity is explicit — the Sub carries a stable `SubId`, so the
- * reconcile pass leaves it running across transitions instead of churning it).
- */
-
-/**
- * The Sub variant a deadline produces. `atMs` is the absolute target — epoch
- * milliseconds (the `Date.now()` / `Date.parse(...)` scale), NOT a relative
- * delay. It rides on the Sub so the reconcile pass keys identity by `id`
- * alone: the same `id` across transitions means the same armed timer, even if
- * a later `subscriptions(state)` recomputes the literal.
- *
- * Lowercase `"deadline"` discriminant per the Sub naming convention (a source
- * noun that doubles as the SubId family); same shape family as the
- * `TimeoutSubData` the `fromTimeout` factory consumes.
- */
-type DeadlineSub = Sub<"deadline"> & {
-    readonly atMs: number;
-} & DeadlineOpts;
-/**
- * Additive options the `deadlineSub` factory folds onto the Sub literal. This
- * is the extension seam (invariant 5 — composition by reduction): future fields
- * — `repeatMs` for a re-arming deadline, `jitterMs` for spread, etc. — land HERE
- * as optional members, and every existing call site keeps compiling because the
- * factory's third parameter is optional and the fields are `readonly` optionals
- * on `DeadlineSub`. Callers are insulated from the concrete `DeadlineSub` shape:
- * they ask for what they need by name, never positionally, so a shape extension
- * never rewrites the ~13 `deadlineSub(id, atMs)` call sites.
- *
- * Empty today on purpose — the seam exists before the first extension does, so
- * the first field is a one-line additive change, not a 13-site migration.
- */
-type DeadlineOpts = {};
-/**
- * The Msg the deadline dispatches when the wall clock crosses `atMs`. Exported
- * as a tagged shape so consumers can union it into their machine's Msg type and
- * handle it in a reducer cell. `id` lets a reducer disambiguate WHICH deadline
- * fired when a machine arms several at once; `atMs` echoes the target the timer
- * was scheduled against (useful for assertions / observability).
- *
- * Snake-shaped `"deadline_exceeded"` matches the tagged-Msg style this module's
- * orchestrator requested; the actor-in-name PascalCase convention
- * (`TimerFiredDeadline`) is the consumer's to apply at their own boundary if
- * they prefer — `deadlineExceeded(...)` only fixes the wire shape, not the
- * consumer's local dialect.
- */
-type DeadlineExceeded = {
-    readonly type: "deadline_exceeded";
-    readonly id: string;
-    readonly atMs: number;
-};
-/**
- * Build a deadline Sub literal. Pure data — no clock read, no timer; the timer
- * is armed later by the `subscribe` cell. `id` is branded via `subId(...)` so
- * accidental raw-string drift fails at the type level (invariant 7).
- *
- * Return the result directly from `subscriptions(state)` while the deadline
- * should be armed; drop it (return `[]`, or stop returning this id) to disarm —
- * the reconcile pass calls the cleanup, clearing the pending timer before it
- * fires. That is the "cancel on state exit" lifecycle, identical to
- * `fromTimeout`'s.
- *
- * @param id   Stable identity for this deadline. Same `id` across transitions =
- *             same armed timer (no churn). Use distinct ids for distinct
- *             deadlines on the same machine.
- * @param atMs Absolute target in epoch milliseconds (e.g. `Date.now() + 900_000`
- *             for a 15-minute guard, or a persisted `expiresAt`).
- * @param opts Optional additive fields folded onto the Sub literal (see
- *             {@link DeadlineOpts}). Omit it for the common case; pass it when a
- *             future field (e.g. `repeatMs`) needs to ride on the deadline. The
- *             optionality is the future-proofing seam — extending the shape
- *             never breaks an existing `deadlineSub(id, atMs)` call site.
- */
-declare function deadlineSub(id: string, atMs: number, opts?: DeadlineOpts): DeadlineSub;
-/**
- * The host-plugged timer backing. Given the deadline's stable `id`, its
- * absolute `atMs`, and the Msg to fire, arm the platform-appropriate timer
- * (DO alarm registry, `setTimeout`, fake timer) and return a cleanup that
- * cancels the pending fire.
- *
- * `id` is the Sub's reconcile id — a registry-backed host (the DO alarm slot)
- * keys its entry on `id` so the cleanup deletes the EXACT entry the substrate
- * reconciled. A `setTimeout`-backed host ignores `id` (the closure holds the
- * handle).
- *
- * The host computes the gap itself: `atMs - Date.now()` is the REMAINING time.
- * On a host that just rehydrated after hibernation that gap is the shrunken
- * remainder — the deadline is NOT reset to its full length. That recomputation
- * is the reason `atMs` rides on the Sub as an absolute instant rather than a
- * delay: the anchor is what every backing agrees on.
- */
-type ArmTimer<M> = (id: SubId, atMs: number, msg: M, dispatch: (msg: M) => void) => () => void;
-/**
- * Build the `subscribe["deadline"]` cell from a host-plugged `armTimer`. This
- * module owns the Sub shape, the anchor, and the Msg; the HOST owns what backs
- * the timer. The returned handler reads `id` + `atMs` off the Sub, builds the
- * `deadlineExceeded(...)` Msg, and hands all three to `armTimer`.
- *
- * Use it when `setTimeout` is the wrong backing — most concretely a Durable
- * Object, which hibernates and must register a `do_alarm` instead:
- *
- *   subscribe: {
- *     deadline: subscribeWith((id, atMs, msg, dispatch) =>
- *       alarms.register(id, atMs, () => dispatch(msg)),
- *     ),
- *   }
- *
- * For the `setTimeout` default, use {@link subscribeDeadline} — it is exactly
- * `subscribeWith(setTimeoutArmTimer())`, so there is one deadline surface and
- * one anchor, not a second one per host.
- */
-declare function subscribeWith(armTimer: ArmTimer<DeadlineExceeded>): SubscribeHandler<DeadlineSub, DeadlineExceeded, unknown>;
-/**
- * The `setTimeout` timer backing — for node / browser / any host whose timer is
- * a plain `setTimeout`. Arms for the REMAINING time (`max(0, atMs - Date.now())`,
- * floored at 0 so an already-past deadline fires on the NEXT tick rather than
- * synchronously inside the reconcile pass), so a deadline re-derived after a
- * rehydrate fires at the original instant, not a fresh full window.
- *
- * Composes on `fromTimeout` rather than redrawing `setTimeout` /
- * `clearTimeout`: this package has ONE timer lifecycle, and the arm-timer seam
- * plugs into it instead of forking it. A hibernating host does NOT use this —
- * it plugs its own `armTimer` (a `do_alarm` registration) into
- * {@link subscribeWith}.
- */
-declare function setTimeoutArmTimer(): ArmTimer<DeadlineExceeded>;
-/**
- * The `subscribe["deadline"]` cell for the DEFAULT `setTimeout` backing. Arms a
- * one-shot timer for the remaining delay `max(0, atMs - Date.now())` and
- * dispatches `deadlineExceeded(...)` when it fires; returns a cleanup that
- * clears the pending timer.
- *
- * It is `subscribeWith(setTimeoutArmTimer())` — the default backing named, not
- * a separate implementation, so the host-plugged path and the default path can
- * never disagree about the anchor.
- *
- * Assign directly to a `Subscribe` cell:
- *
- *   subscribe: {
- *     deadline: subscribeDeadline,
- *   }
- */
-declare const subscribeDeadline: SubscribeHandler<DeadlineSub, DeadlineExceeded, unknown>;
-/**
- * Construct the Msg the deadline dispatches. Exported so consumers can build /
- * assert the same shape (and so the subscribe cell and tests share one
- * constructor rather than two literals that can drift).
- */
-declare function deadlineExceeded(id: string, atMs: number): DeadlineExceeded;
-
-export { type ArmTimer, type DeadlineExceeded, type DeadlineOpts, type DeadlineSub, deadlineExceeded, deadlineSub, setTimeoutArmTimer, subscribeDeadline, subscribeWith };

package/dist/deadline/index.js

@@ -1,6 +0,0 @@
-export { deadlineExceeded, deadlineSub, setTimeoutArmTimer, subscribeDeadline, subscribeWith } from '../chunk-DGE4PV4A.js';
-import '../chunk-2YFLOCWX.js';
-import '../chunk-ZSUUOEPL.js';
-import '../chunk-OOYD44JI.js';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/deadline/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/debounce/index.js

@@ -1,3 +0,0 @@
-export { debounce } from '../chunk-J6527VRQ.js';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/debounce/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/extension/react.d.ts

@@ -1,121 +0,0 @@
-import { ReactNode } from 'react';
-
-/**
- * React adapters for the background TEA runtime.
- *
- * Two layers, both built on the same `bridgeClient`:
- *
- *   1. `useBackgroundRuntime(opts)` — direct hook. One bridge client per
- *      call. Surfaces that only have a single consumer mount it inline.
- *
- *   2. `createBackgroundRuntimeContext<S, M>()` → `{ Provider, useDispatch,
- *      useState, useRuntime }` — factory-style React context. Mounts the
- *      bridge client ONCE inside the Provider; child hooks read `state` /
- *      `dispatch` from context. Surfaces that drill `dispatch` through
- *      multiple component layers, or mount `useBackgroundRuntime` more
- *      than once for the same channel, should use this instead.
- *
- * Why a factory (not a single global context):
- *   - Type safety: each app types it against its own `S` / `M`.
- *   - Tests can mount fresh contexts per test (no module-level state to
- *     reset).
- *   - Multiple-runtimes case: an app COULD theoretically have two
- *     background-shaped runtimes (e.g. one per channel); the factory
- *     pattern doesn't preclude it.
- *
- * Hook lifecycle (`useBackgroundRuntime`) — preserved from the prior
- * single-export module:
- *   1. `useSyncExternalStore` subscribes to broadcasts via
- *      `bridgeClient.subscribe`, reading the latest state via
- *      `bridgeClient.getSnapshot`. Reference stability is owned by the
- *      bridge — `getSnapshot` returns the SAME `S` until a new broadcast
- *      overwrites it, so React doesn't loop.
- *   2. A one-shot `hydrate()` call seeds `latestState` before the first
- *      broadcast arrives. The hydrate side-effect runs in an effect so the
- *      first render shows `null` and the subsequent render flips to the
- *      hydrated snapshot (or stays null if the host is still booting).
- *   3. `dispatch(msg)` sends `:dispatch` envelopes.
- *
- * On unmount: `useSyncExternalStore` removes the listener; the host's
- * bridge stays installed.
- *
- * Canon §3.1: React adapters use `useSyncExternalStore`, not
- * `useState + useEffect`. `useMachine` and `useRuntime` already follow this
- * — `useBackgroundRuntime` (and by extension the Provider) does too. One
- * Way to Do Each Thing.
- *
- * NOTE: This is a separate entry from the main `index.ts` so apps that
- * never need React don't drag react into their type graph. The React
- * adapter peer-depends on react (you must have it installed in the app).
- */
-
-interface UseBackgroundRuntimeOpts<S> {
-    channel: string;
-    /**
-     * REQUIRED parse for inbound `state` payloads. Forwarded to
-     * `bridgeClient` — see `BridgeClientOpts.parseState`. Surfaces own this
-     * because the chrome.runtime boundary is `unknown` (Inv 8). Returning
-     * `null` drops the payload silently.
-     */
-    parseState: (raw: unknown) => S | null;
-}
-interface UseBackgroundRuntimeResult<S, M> {
-    /** Latest snapshot from the host. `null` until the first hydrate response
-     * or the first broadcast arrives. Surfaces SHOULD render a placeholder
-     * for the null window. */
-    state: S | null;
-    /** Send a msg to the host runtime. Resolves once the host's dispatch
-     * settles. */
-    dispatch(msg: M): Promise<void>;
-}
-declare function useBackgroundRuntime<S, M extends {
-    type: string;
-}>({ channel, parseState, }: UseBackgroundRuntimeOpts<S>): UseBackgroundRuntimeResult<S, M>;
-interface BackgroundRuntimeContext<S, M> {
-    /**
-     * Wrap a subtree to share a single background-runtime bridge client.
-     * `opts` is forwarded verbatim to `useBackgroundRuntime` — same channel,
-     * same parse contract.
-     */
-    Provider: (props: {
-        opts: UseBackgroundRuntimeOpts<S>;
-        children: ReactNode;
-    }) => ReactNode;
-    /**
-     * Returns the dispatch function bound to this Provider's bridge client.
-     * Reference is stable across renders (per `useBackgroundRuntime`'s
-     * `useCallback`), so passing it to memoized children won't churn them.
-     */
-    useDispatch: () => (msg: M) => Promise<void>;
-    /**
-     * Returns a slice of the latest state. `selector` defaults to identity
-     * (returns the whole `S | null` snapshot). Selectors run on every state
-     * change — surfaces with expensive transforms should memoize the
-     * selector at call site.
-     *
-     * Returns `null` until the first hydrate / broadcast lands when the
-     * selector is identity; for non-identity selectors the return type is
-     * `T` and the caller's selector decides how to handle the pre-hydrate
-     * `null` snapshot.
-     */
-    useState: {
-        (): S | null;
-        <T>(selector: (state: S | null) => T): T;
-    };
-    /**
-     * Escape hatch — returns the full `{ state, dispatch }` pair as-is.
-     * Useful for consumers that want both the snapshot and the dispatch
-     * fn in a single hook call (e.g. effects that read state THEN
-     * dispatch in response).
-     *
-     * Not a `@demlik/tea` `Runtime<S, M>` — the bridge surface is a thinner
-     * client. This hook returns the same shape as `useBackgroundRuntime`,
-     * just sourced from context instead of mounting a fresh client.
-     */
-    useRuntime: () => UseBackgroundRuntimeResult<S, M>;
-}
-declare function createBackgroundRuntimeContext<S, M extends {
-    type: string;
-}>(): BackgroundRuntimeContext<S, M>;
-
-export { type BackgroundRuntimeContext, type UseBackgroundRuntimeOpts, type UseBackgroundRuntimeResult, createBackgroundRuntimeContext, useBackgroundRuntime };

package/dist/extension/react.js

@@ -1,75 +0,0 @@
-import { bridgeClient, passThroughMsg } from '../chunk-L57ZOT5K.js';
-import '../chunk-G5E74IJB.js';
-import '../chunk-ZSUUOEPL.js';
-import '../chunk-OOYD44JI.js';
-import { useRef, useSyncExternalStore, useEffect, useCallback, createContext, useMemo, useContext } from 'react';
-import { jsx } from 'react/jsx-runtime';
-
-function useBackgroundRuntime({
-  channel,
-  parseState
-}) {
-  const clientRef = useRef(null);
-  if (clientRef.current === null) {
-    clientRef.current = bridgeClient({
-      channel,
-      parseState,
-      parseMsg: passThroughMsg
-    });
-  }
-  const client = clientRef.current;
-  const state = useSyncExternalStore(
-    client.subscribe,
-    client.getSnapshot,
-    client.getSnapshot
-  );
-  useEffect(() => {
-    client.hydrate().catch(() => {
-    });
-  }, [client]);
-  const dispatch = useCallback(
-    async (msg) => {
-      await client.dispatch(msg);
-    },
-    [client]
-  );
-  return { state, dispatch };
-}
-var PROVIDER_ERROR = "createBackgroundRuntimeContext: hook used outside its Provider. Wrap the consumer in <BackgroundRuntime.Provider opts={...}>.";
-function createBackgroundRuntimeContext() {
-  const Ctx = createContext(null);
-  function Provider({
-    opts,
-    children
-  }) {
-    const result = useBackgroundRuntime(opts);
-    const value = useMemo(
-      () => ({ state: result.state, dispatch: result.dispatch }),
-      [result.state, result.dispatch]
-    );
-    return /* @__PURE__ */ jsx(Ctx.Provider, { value, children });
-  }
-  function useRuntime() {
-    const ctx = useContext(Ctx);
-    if (ctx === null) throw new Error(PROVIDER_ERROR);
-    return ctx;
-  }
-  function useDispatch() {
-    return useRuntime().dispatch;
-  }
-  function useStateHook(selector) {
-    const { state } = useRuntime();
-    if (selector === void 0) return state;
-    return selector(state);
-  }
-  return {
-    Provider,
-    useDispatch,
-    useState: useStateHook,
-    useRuntime
-  };
-}
-
-export { createBackgroundRuntimeContext, useBackgroundRuntime };
-//# sourceMappingURL=react.js.map
-//# sourceMappingURL=react.js.map

package/dist/extension/react.js.map

@@ -1 +0,0 @@
-{"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,45 +0,0 @@
-import { S as Sub } from '../../core-Co0LWkIA.js';
-import { S as SubscribeHandler } from '../../types-XS_miRnB.js';
-import 'zod';
-
-type AlarmSubData = {
-    alarmName: string;
-};
-declare function fromChromeAlarm<S extends Sub & AlarmSubData, M>(msgFn: (alarm: chrome.alarms.Alarm, sub: S) => M | null): SubscribeHandler<S, M, unknown>;
-
-interface ChromeMessageOpts<S extends Sub, M> {
-    /**
-     * Pre-filter — when provided, the factory only dispatches when this
-     * returns `true`. Cheap discriminant checks belong here.
-     */
-    filter?: (message: unknown) => boolean;
-    msgFn: (message: unknown, sender: chrome.runtime.MessageSender, sub: S) => M | null;
-}
-declare function fromChromeMessage<S extends Sub, M>(opts: ChromeMessageOpts<S, M>): SubscribeHandler<S, M, unknown>;
-
-interface ChromeStorageChangeOpts<S extends Sub, M> {
-    area: chrome.storage.AreaName;
-    /**
-     * If provided, only dispatch when at least one of the changed keys
-     * overlaps with this set. Omitting means "any key in the area".
-     */
-    keys?: readonly string[];
-    msgFn: (changes: Record<string, chrome.storage.StorageChange>, sub: S) => M | null;
-}
-declare function fromChromeStorageChange<S extends Sub, M>(opts: ChromeStorageChangeOpts<S, M>): SubscribeHandler<S, M, unknown>;
-
-type TabsEventName = "onActivated" | "onUpdated" | "onRemoved";
-interface ChromeTabsEventOpts<S extends Sub, M> {
-    events: readonly TabsEventName[];
-    /**
-     * If `true`, the factory dispatches a synthetic `msgFn(sub)` once at
-     * subscribe time — useful for "populate tab list on mount" patterns
-     * where the first emission must not wait for chrome to fire an event.
-     * Default `false`.
-     */
-    fireOnMount?: boolean;
-    msgFn: (sub: S) => M | null;
-}
-declare function fromChromeTabsEvent<S extends Sub, M>(opts: ChromeTabsEventOpts<S, M>): SubscribeHandler<S, M, unknown>;
-
-export { type ChromeMessageOpts, type ChromeStorageChangeOpts, type ChromeTabsEventOpts, type TabsEventName, fromChromeAlarm, fromChromeMessage, fromChromeStorageChange, fromChromeTabsEvent };

package/dist/extension/subs/index.js

@@ -1,80 +0,0 @@
-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;
-      dispatchIfPresent(dispatch, msgFn(alarm, sub));
-    };
-    chrome.alarms.onAlarm.addListener(listener);
-    return () => chrome.alarms.onAlarm.removeListener(listener);
-  };
-}
-
-// src/extension/subs/from-chrome-message.ts
-function fromChromeMessage(opts) {
-  return (sub, _ctx, dispatch) => {
-    const listener = (message, sender, _sendResponse) => {
-      if (opts.filter !== void 0 && !opts.filter(message)) return;
-      dispatchIfPresent(dispatch, opts.msgFn(message, sender, sub));
-    };
-    chrome.runtime.onMessage.addListener(listener);
-    return () => {
-      chrome.runtime.onMessage.removeListener(listener);
-    };
-  };
-}
-
-// src/extension/subs/from-chrome-storage-change.ts
-function fromChromeStorageChange(opts) {
-  return (sub, _ctx, dispatch) => {
-    const listener = (changes, areaName) => {
-      if (areaName !== opts.area) return;
-      if (opts.keys !== void 0) {
-        const changedKeys = Object.keys(changes);
-        let overlap = false;
-        for (const k of opts.keys) {
-          if (changedKeys.includes(k)) {
-            overlap = true;
-            break;
-          }
-        }
-        if (!overlap) return;
-      }
-      dispatchIfPresent(dispatch, opts.msgFn(changes, sub));
-    };
-    chrome.storage.onChanged.addListener(listener);
-    return () => {
-      chrome.storage.onChanged.removeListener(listener);
-    };
-  };
-}
-
-// src/extension/subs/from-chrome-tabs-event.ts
-function fromChromeTabsEvent(opts) {
-  return (sub, _ctx, dispatch) => {
-    const installed = [];
-    const listener = () => {
-      dispatchIfPresent(dispatch, opts.msgFn(sub));
-    };
-    for (const event of opts.events) {
-      const emitter = chrome.tabs[event];
-      emitter.addListener(listener);
-      installed.push(event);
-    }
-    if (opts.fireOnMount === true) {
-      dispatchIfPresent(dispatch, opts.msgFn(sub));
-    }
-    return () => {
-      for (const event of installed) {
-        const emitter = chrome.tabs[event];
-        emitter.removeListener(listener);
-      }
-    };
-  };
-}
-
-export { fromChromeAlarm, fromChromeMessage, fromChromeStorageChange, fromChromeTabsEvent };
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

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

@@ -1 +0,0 @@
-{"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"]}