@demlik/tea 0.13.0 → 0.14.0

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":";;;AA+BO,SAAS,gBACd,KAAA,EACiC;AACjC,EAAA,OAAO,CAAC,GAAA,EAAK,IAAA,EAAM,QAAA,KAAa;AAC9B,IAAA,MAAM,QAAA,GAAW,CAAC,KAAA,KAAqC;AAIrD,MAAA,IAAI,KAAA,CAAM,IAAA,KAAS,GAAA,CAAI,SAAA,EAAW;AAClC,MAAA,iBAAA,CAAkB,QAAA,EAAU,KAAA,CAAM,KAAA,EAAO,GAAG,CAAC,CAAA;AAAA,IAC/C,CAAA;AACA,IAAA,MAAA,CAAO,MAAA,CAAO,OAAA,CAAQ,WAAA,CAAY,QAAQ,CAAA;AAC1C,IAAA,OAAO,MAAM,MAAA,CAAO,MAAA,CAAO,OAAA,CAAQ,eAAe,QAAQ,CAAA;AAAA,EAC5D,CAAA;AACF;;;ACQO,SAAS,kBACd,IAAA,EACiC;AACjC,EAAA,OAAO,CAAC,GAAA,EAAK,IAAA,EAAM,QAAA,KAAa;AAC9B,IAAA,MAAM,QAAA,GAAW,CACf,OAAA,EACA,MAAA,EACA,aAAA,KACS;AACT,MAAA,IAAI,KAAK,MAAA,KAAW,MAAA,IAAa,CAAC,IAAA,CAAK,MAAA,CAAO,OAAO,CAAA,EAAG;AACxD,MAAA,iBAAA,CAAkB,UAAU,IAAA,CAAK,KAAA,CAAM,OAAA,EAAS,MAAA,EAAQ,GAAG,CAAC,CAAA;AAAA,IAI9D,CAAA;AACA,IAAA,MAAA,CAAO,OAAA,CAAQ,SAAA,CAAU,WAAA,CAAY,QAAQ,CAAA;AAC7C,IAAA,OAAO,MAAM;AACX,MAAA,MAAA,CAAO,OAAA,CAAQ,SAAA,CAAU,cAAA,CAAe,QAAQ,CAAA;AAAA,IAClD,CAAA;AAAA,EACF,CAAA;AACF;;;ACxBO,SAAS,wBACd,IAAA,EACiC;AACjC,EAAA,OAAO,CAAC,GAAA,EAAK,IAAA,EAAM,QAAA,KAAa;AAC9B,IAAA,MAAM,QAAA,GAAW,CACf,OAAA,EACA,QAAA,KACS;AACT,MAAA,IAAI,QAAA,KAAa,KAAK,IAAA,EAAM;AAC5B,MAAA,IAAI,IAAA,CAAK,SAAS,MAAA,EAAW;AAI3B,QAAA,MAAM,WAAA,GAAc,MAAA,CAAO,IAAA,CAAK,OAAO,CAAA;AACvC,QAAA,IAAI,OAAA,GAAU,KAAA;AACd,QAAA,KAAA,MAAW,CAAA,IAAK,KAAK,IAAA,EAAM;AACzB,UAAA,IAAI,WAAA,CAAY,QAAA,CAAS,CAAC,CAAA,EAAG;AAC3B,YAAA,OAAA,GAAU,IAAA;AACV,YAAA;AAAA,UACF;AAAA,QACF;AACA,QAAA,IAAI,CAAC,OAAA,EAAS;AAAA,MAChB;AACA,MAAA,iBAAA,CAAkB,QAAA,EAAU,IAAA,CAAK,KAAA,CAAM,OAAA,EAAS,GAAG,CAAC,CAAA;AAAA,IACtD,CAAA;AACA,IAAA,MAAA,CAAO,OAAA,CAAQ,SAAA,CAAU,WAAA,CAAY,QAAQ,CAAA;AAC7C,IAAA,OAAO,MAAM;AACX,MAAA,MAAA,CAAO,OAAA,CAAQ,SAAA,CAAU,cAAA,CAAe,QAAQ,CAAA;AAAA,IAClD,CAAA;AAAA,EACF,CAAA;AACF;;;ACdO,SAAS,oBACd,IAAA,EACiC;AACjC,EAAA,OAAO,CAAC,GAAA,EAAK,IAAA,EAAM,QAAA,KAAa;AAC9B,IAAA,MAAM,YAA6B,EAAC;AACpC,IAAA,MAAM,WAA4B,MAAM;AACtC,MAAA,iBAAA,CAAkB,QAAA,EAAU,IAAA,CAAK,KAAA,CAAM,GAAG,CAAC,CAAA;AAAA,IAC7C,CAAA;AAEA,IAAA,KAAA,MAAW,KAAA,IAAS,KAAK,MAAA,EAAQ;AAK/B,MAAA,MAAM,OAAA,GAAU,MAAA,CAAO,IAAA,CACrB,KACF,CAAA;AACA,MAAA,OAAA,CAAQ,YAAY,QAAQ,CAAA;AAC5B,MAAA,SAAA,CAAU,KAAK,KAAK,CAAA;AAAA,IACtB;AAEA,IAAA,IAAI,IAAA,CAAK,gBAAgB,IAAA,EAAM;AAC7B,MAAA,iBAAA,CAAkB,QAAA,EAAU,IAAA,CAAK,KAAA,CAAM,GAAG,CAAC,CAAA;AAAA,IAC7C;AAEA,IAAA,OAAO,MAAM;AACX,MAAA,KAAA,MAAW,SAAS,SAAA,EAAW;AAC7B,QAAA,MAAM,OAAA,GAAU,MAAA,CAAO,IAAA,CACrB,KACF,CAAA;AACA,QAAA,OAAA,CAAQ,eAAe,QAAQ,CAAA;AAAA,MACjC;AAAA,IACF,CAAA;AAAA,EACF,CAAA;AACF","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/extension/test-utils.d.ts

@@ -1,128 +0,0 @@
-/**
- * In-memory `chrome.*` mock for tests in this package and any downstream
- * consumer that wants to test against `chromeStorageStore` behavior without
- * a real chrome environment.
- *
- * Currently exposes `chrome.storage.local`, `chrome.runtime` (sendMessage +
- * onMessage), and `chrome.tabs` (sendMessage). The `runtime` and `tabs`
- * surfaces are used by the runtime-bridge tests (`bridge.ts`) to round-trip
- * envelopes between a host runtime and a surface client (sw↔surface) and
- * between a sw client and a per-tab content-script runtime (sw↔content).
- *
- * Extend additional surfaces (alarms, windows, …) only when real consumer
- * tests reach for them — earn each surface through a concrete need.
- */
-type StorageChangeListener = (changes: Record<string, chrome.storage.StorageChange>, areaName: chrome.storage.AreaName) => void;
-type AlarmListener = (alarm: chrome.alarms.Alarm) => void;
-type TabActivatedListener = (info: chrome.tabs.OnActivatedInfo) => void;
-type TabUpdatedListener = (tabId: number, changeInfo: chrome.tabs.OnUpdatedInfo, tab: chrome.tabs.Tab) => void;
-type TabRemovedListener = (tabId: number, removeInfo: chrome.tabs.OnRemovedInfo) => void;
-interface FakeChrome {
-    storage: {
-        local: chrome.storage.StorageArea;
-        /**
-         * Top-level `chrome.storage.onChanged` event. Fires for ANY area; consumer
-         * filters by the `areaName` arg. Real chrome semantics: every `set` /
-         * `remove` / `clear` that materially changes a key emits a single
-         * `changes` map keyed by the changed keys.
-         */
-        onChanged: {
-            addListener(listener: StorageChangeListener): void;
-            removeListener(listener: StorageChangeListener): void;
-            hasListener(listener: StorageChangeListener): boolean;
-            hasListeners(): boolean;
-        };
-    };
-    runtime: {
-        sendMessage: typeof chrome.runtime.sendMessage;
-        onMessage: typeof chrome.runtime.onMessage;
-    };
-    tabs: {
-        sendMessage: typeof chrome.tabs.sendMessage;
-        /**
-         * `chrome.tabs.onActivated` — fires when the active tab in a window
-         * changes. The fake only models the listener registry; tests drive
-         * fires via `__test.fireTabActivated(info)`.
-         */
-        onActivated: {
-            addListener(listener: TabActivatedListener): void;
-            removeListener(listener: TabActivatedListener): void;
-            hasListener(listener: TabActivatedListener): boolean;
-            hasListeners(): boolean;
-        };
-        /**
-         * `chrome.tabs.onUpdated` — fires when a tab is updated (url, title,
-         * status, etc.). Tests drive fires via `__test.fireTabUpdated(...)`.
-         */
-        onUpdated: {
-            addListener(listener: TabUpdatedListener): void;
-            removeListener(listener: TabUpdatedListener): void;
-            hasListener(listener: TabUpdatedListener): boolean;
-            hasListeners(): boolean;
-        };
-        /**
-         * `chrome.tabs.onRemoved` — fires when a tab is closed. Tests drive
-         * fires via `__test.fireTabRemoved(...)`.
-         */
-        onRemoved: {
-            addListener(listener: TabRemovedListener): void;
-            removeListener(listener: TabRemovedListener): void;
-            hasListener(listener: TabRemovedListener): boolean;
-            hasListeners(): boolean;
-        };
-    };
-    /**
-     * `chrome.alarms` — the MV3 periodic timer primitive. The fake tracks
-     * created alarms in a Map keyed by name, models `create` (dedupe by
-     * name) + `clear` (remove from map), and exposes `onAlarm` as a
-     * standard listener registry. Tests drive fires via
-     * `__test.fireAlarm(name)`.
-     */
-    alarms: {
-        create(name: string, alarmInfo: chrome.alarms.AlarmCreateInfo): void;
-        /**
-         * `chrome.alarms.get(name)` — resolves to the Alarm shape Chrome would
-         * return (with `scheduledTime` synthesized at lookup time), or
-         * undefined if no alarm with that name exists. Mirrors the contract
-         * the `ensureQueueAlarm` SW-module-top-level helper checks ("is this
-         * alarm already present with the right period?") — see
-         * the extension's background entrypoint.
-         */
-        get(name: string): Promise<chrome.alarms.Alarm | undefined>;
-        clear(name: string): Promise<boolean>;
-        onAlarm: {
-            addListener(listener: AlarmListener): void;
-            removeListener(listener: AlarmListener): void;
-            hasListener(listener: AlarmListener): boolean;
-            hasListeners(): boolean;
-        };
-    };
-    /**
-     * Test helpers — not part of the real chrome surface. Lets tests
-     * simulate a content script issuing `chrome.runtime.sendMessage` from
-     * inside a specific tab (chrome auto-tags `sender.tab.id` in that
-     * direction) and remove a tab so `chrome.tabs.sendMessage` rejects
-     * the way real chrome does when the receiver is gone.
-     */
-    __test: {
-        /** Simulate a content-script broadcast tagged with `sender.tab.id`. */
-        sendFromTab(tabId: number, message: unknown): Promise<unknown>;
-        /** Mark a tab as gone — `chrome.tabs.sendMessage(tabId, …)` will reject. */
-        removeTab(tabId: number): void;
-        /** Mark a tab as alive (default for any tabId that hasn't been removed). */
-        addTab(tabId: number): void;
-        /** Fire an alarm — invokes every onAlarm listener with `{ name, ...}`. */
-        fireAlarm(name: string): void;
-        /** Snapshot the alarm registry — tests assert on created/cleared alarms. */
-        getAlarms(): readonly string[];
-        /** Fire `chrome.tabs.onActivated` — drives every listener. */
-        fireTabActivated(info: chrome.tabs.OnActivatedInfo): void;
-        /** Fire `chrome.tabs.onUpdated` — drives every listener. */
-        fireTabUpdated(tabId: number, changeInfo: chrome.tabs.OnUpdatedInfo, tab: chrome.tabs.Tab): void;
-        /** Fire `chrome.tabs.onRemoved` — drives every listener. */
-        fireTabRemoved(tabId: number, removeInfo: chrome.tabs.OnRemovedInfo): void;
-    };
-}
-declare function fakeChrome(): FakeChrome;
-
-export { type FakeChrome, fakeChrome };