@demlik/tea 0.12.0 → 0.14.0

package/dist/{durable-effects-D8SqU_if.d.ts → durable-effects-B0-qGQDy.d.ts}

@@ -1,4 +1,4 @@
-import { C as Cmd } from './core-Bjc0bS8j.js';
+import { C as Cmd } from './core-CTzMJ82M.js';
 
 /**
  * @demlik/tea/do — the durable pending-effects ledger (substrate primitive #1).
@@ -91,7 +91,7 @@ interface OwedEffect<E> {
     readonly id: DeliveryId;
     readonly effect: E;
 }
-/** The empty ledger — the fold's seed (a fresh actor owes nothing). */
+/** The empty ledger — the fold's starting value (a fresh actor owes nothing). */
 declare function emptyLedger<E>(): PendingEffectsLedger<E>;
 /**
  * Apply ONE ledger event — the reducer at the heart of the fold.

package/dist/extension/index.d.ts

@@ -1,6 +1,9 @@
-import { R as Runtime, S as Store } from '../runtime-types-Bxc637bp.js';
+import { R as Runtime, S as Store } from '../runtime-types-LWDoi943.js';
+import { ReactNode } from 'react';
+import { S as Sub } from '../core-CTzMJ82M.js';
+import { S as SubscribeHandler } from '../types-DP3f5NIl.js';
 import 'better-result';
-import '../core-Bjc0bS8j.js';
+import 'zod';
 
 /**
  * Runtime bridge — expose a `@demlik/tea` runtime running in one chrome context
@@ -205,6 +208,291 @@ declare function bridgeTabClient<S, M extends {
     type: string;
 }>({ tabId, channel, parseState, parseMsg, }: BridgeTabClientOpts<S, M>): BridgeClient<S, M>;
 
+/**
+ * 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>;
+
+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>;
+
+/**
+ * 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;
+
 /**
  * @packageDocumentation
  * @demlik/tea/extension — Chrome service-worker host adapter for @demlik/tea.
@@ -238,7 +526,17 @@ declare function bridgeTabClient<S, M extends {
  *
  * `area` defaults to `chrome.storage.local` for production. Tests pass a
  * `fakeChrome().storage.local` in.
+ *
+ * **Not fenced, deliberately (#143).** This is the one shipped factory that
+ * does not implement `FencedStore<S>`, and it opts out rather than faking a
+ * generation counter: `chrome.storage` offers no atomic compare-and-swap and no
+ * cross-context lock, so a version cell here would be read-then-written with a
+ * real race between the two — a fence that reports success while both writers
+ * win, which is worse than no fence. The honest guarantee is the one the
+ * platform gives: a single background service worker per extension is the
+ * single writer, and that is a precondition to keep, not one this store can
+ * enforce. See `docs/explanation/durability-model.md`.
  */
 declare function chromeStorageStore<S>(key: string, parse: (raw: unknown) => S | null, area?: chrome.storage.StorageArea): Store<S>;
 
-export { type BridgeClient, type BridgeClientOpts, type BridgeRuntimeOpts, type BridgeTabClientOpts, bridgeClient, bridgeRuntime, bridgeTabClient, chromeStorageStore, passThroughMsg };
+export { type BackgroundRuntimeContext, type BridgeClient, type BridgeClientOpts, type BridgeRuntimeOpts, type BridgeTabClientOpts, type ChromeMessageOpts, type ChromeStorageChangeOpts, type ChromeTabsEventOpts, type FakeChrome, type TabsEventName, type UseBackgroundRuntimeOpts, type UseBackgroundRuntimeResult, bridgeClient, bridgeRuntime, bridgeTabClient, chromeStorageStore, createBackgroundRuntimeContext, fakeChrome, fromChromeAlarm, fromChromeMessage, fromChromeStorageChange, fromChromeTabsEvent, passThroughMsg, useBackgroundRuntime };