@demlik/tea 0.19.0 → 0.20.0

package/dist/effect/index.d.ts

@@ -1,7 +1,126 @@
-export { C as CellErrors, c as EffectBootingRuntime, E as EffectInterpret, d as EffectInterpretCell, e as EffectRunOptions, f as EffectRunner, g as EffectRuntime, a as EffectSubscribe, I as InterpretServices, h as Stopped, i as StoreFailed, b as SubscribeServices, r as run } from '../index-BnsAqn0-.js';
+import { Scope, Effect } from 'effect';
+import { C as Cmd, S as Sub, M as Machine } from '../core-CtvAyPpH.js';
+import { E as EffectRuntime, S as StoreFailed } from '../run-fiBe7pOG.js';
+export { C as CellErrors, a as EffectBootingRuntime, b as EffectInterpret, c as EffectInterpretCell, d as EffectRunOptions, e as EffectRunner, f as EffectSubscribe, I as InterpretServices, g as Stopped, h as SubscribeServices, r as run } from '../run-fiBe7pOG.js';
+import '@standard-schema/spec';
+import '../runtime-types-DEluQgGO.js';
 import 'effect/Cause';
 import 'effect/Types';
-import 'effect';
-import '../core-Ce9ncpuv.js';
-import '@standard-schema/spec';
-import '../runtime-types-BKg2CGMx.js';
+
+/**
+ * Helpers for running child machines under a parent on the Effect engine
+ * (#556, ruling R1.1 of #554).
+ *
+ * tea still runs one machine per `run` and keeps no table of runs (#312). A
+ * host that builds a tree of runs keeps its own table, ids and Msg names, and
+ * hands the steps that race to these functions: `spawn` starts a child and
+ * enrols it as one step, `stop` stops one child, and `tell` sends the parent a
+ * notice it may no longer take.
+ */
+
+/**
+ * Hand `msg` to a run only when its State has a cell for it, and drop it when
+ * the run no longer takes it.
+ *
+ * `machine` is the machine `runtime` runs. The dispatch lands a moment after
+ * the check, so a State that changed in between refuses the Msg with a
+ * `NoCellError`, and a run that stopped refuses it with `Stopped`. Both mean
+ * the run no longer takes the notice, so both are dropped and `tell` succeeds.
+ * A failed save stays a `StoreFailed`, and a hand-written cell's declared
+ * failure stays that failure.
+ *
+ * ```ts
+ * yield* tell(parent, parentRun, { type: "child_stopped", id });
+ * ```
+ */
+declare const tell: <S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx, E extends {
+    type: string;
+} = never, Err = never>(machine: Machine<S, M, C, U, Ctx>, runtime: EffectRuntime<S, M, E, Err>, msg: NoInfer<M>) => Effect.Effect<void, Err | StoreFailed>;
+/**
+ * The host's own steps of a {@link spawn}. The host owns the table of
+ * children, their ids and the parent's Msg names; `spawn` owns the order the
+ * steps run in and keeps an interrupt from landing between them.
+ */
+interface SpawnSteps<A, E = never, R = never> {
+    /**
+     * Start the child and return what the host keeps for it. It runs with the
+     * child's scope provided, so a `run(machine, opts)` in it belongs to that
+     * scope, and so does anything else it acquires. `scope` is the same scope,
+     * for a host that keeps it to stop the child with `stop`. A failure
+     * closes the child's scope, which runs `remove` and `notify`.
+     */
+    readonly start: (scope: Scope.Closeable) => Effect.Effect<A, E, R>;
+    /** Add the started child to the host's table. */
+    readonly enrol: (child: A) => Effect.Effect<unknown>;
+    /**
+     * Take the child out of the host's table. It runs when the child's scope
+     * closes, after its run has stopped, whether or not `enrol` ran, so it must
+     * be safe on a child the table does not hold.
+     */
+    readonly remove: Effect.Effect<unknown>;
+    /**
+     * Say the child stopped, usually a {@link tell} to the parent. It runs
+     * after `remove`, on a fiber of its own that the closing scope never waits
+     * for, so it may wait on the parent.
+     *
+     * It cannot fail: nothing reads that fiber, so the step itself handles what
+     * its notice can fail with, such as the `StoreFailed` of a `tell`. A defect
+     * in it is not observed by `spawn` and ends the fiber unseen.
+     */
+    readonly notify: Effect.Effect<unknown>;
+}
+/**
+ * Start a child in a scope forked from `parentScope` and enrol it in the
+ * host's table, as one uninterruptible step. Stop a child with `stop`,
+ * or by closing its scope; closing `parentScope` stops every child spawned
+ * under it.
+ *
+ * What it guarantees, with no guard in host code:
+ *
+ *   - the table never holds a child whose scope has closed. The fork, the
+ *     removal finalizer, `start` and `enrol` all happen or none do, and a
+ *     child whose scope closed before `enrol` is removed again;
+ *   - closing a child never waits for the parent. `notify` runs on a detached
+ *     fiber, so a parent Cmd handler can stop a child;
+ *   - `remove` runs after the child's run has stopped.
+ *
+ * Nothing reads the fiber `notify` runs on, so `spawn` reports no failure of
+ * it and `notify` is typed to have none. The host handles what its notice can
+ * fail with inside the step, as the `Effect.catch` below does for a parent
+ * whose save failed. A defect in `notify` ends that fiber unseen.
+ *
+ * `child.run.stop()` is not one of the two ways to stop a child. It stops the
+ * run and leaves the scope open, so the entry stays in the table and the
+ * parent is not told.
+ *
+ * ```ts
+ * const child = yield* spawn(parentScope, {
+ *   start: (scope) =>
+ *     Effect.map(run(worker, {}), (run) => ({ run, scope })),
+ *   enrol: (child) => Effect.sync(() => children.set(id, child)),
+ *   remove: Effect.sync(() => children.delete(id)),
+ *   notify: tell(parent, parentRun, { type: "child_stopped", id }).pipe(
+ *     Effect.catch((failure) => Effect.logError("notice failed", failure)),
+ *   ),
+ * });
+ * ```
+ */
+declare const spawn: <A, E = never, R = never>(parentScope: Scope.Scope, steps: SpawnSteps<A, E, R>) => Effect.Effect<A, E, Exclude<R, Scope.Scope>>;
+/**
+ * Stop one child that `spawn` started. `scope` is the child's scope,
+ * the one its `start` was handed.
+ *
+ * It closes that scope, so the child's run stops, `remove` takes the entry
+ * out of the host's table and `notify` tells the parent. It does not wait for
+ * `notify`, so a parent Cmd handler can call it. Stopping a child that has
+ * already stopped succeeds and sends no second notice.
+ *
+ * ```ts
+ * yield* stop(child.scope);
+ * ```
+ */
+declare const stop: (scope: Scope.Closeable) => Effect.Effect<void>;
+
+export { EffectRuntime, type SpawnSteps, StoreFailed, spawn, stop, tell };

package/dist/effect/index.js

@@ -1,6 +1,35 @@
-export { Stopped, StoreFailed, run } from '../chunk-I7E7AD2S.js';
-import '../chunk-AHW2CLPT.js';
-import '../chunk-JVE2LBFJ.js';
-import '../chunk-AIIXV4XB.js';
+export { Stopped, StoreFailed, run } from '../chunk-AIXC33SE.js';
+import '../chunk-UHAQ4PI6.js';
+import '../chunk-A73IJ27X.js';
+import { acceptedTypes, NoCellError } from '../chunk-RKVUVALV.js';
+import { Effect, Scope, Exit } from 'effect';
+
+var tell = (machine, runtime, msg) => Effect.suspend(
+  () => acceptedTypes(machine, runtime.getState()).includes(msg.type) ? runtime.dispatch(msg) : Effect.void
+).pipe(
+  Effect.catchTag("Stopped", () => Effect.void),
+  Effect.catchDefect(
+    (defect) => defect instanceof NoCellError ? Effect.void : Effect.die(defect)
+  )
+);
+var spawn = (parentScope, steps) => Effect.uninterruptible(
+  Effect.gen(function* () {
+    const scope = yield* Scope.fork(parentScope);
+    yield* Scope.addFinalizer(
+      scope,
+      Effect.andThen(steps.remove, Effect.forkDetach(steps.notify))
+    );
+    const child = yield* steps.start(scope).pipe(
+      Scope.provide(scope),
+      Effect.onError((cause) => Scope.close(scope, Exit.failCause(cause)))
+    );
+    yield* steps.enrol(child);
+    if (scope.state._tag === "Closed") yield* steps.remove;
+    return child;
+  })
+);
+var stop = (scope) => Scope.close(scope, Exit.void);
+
+export { spawn, stop, tell };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/effect/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}
+{"version":3,"sources":["../../src/effect/children.ts"],"names":[],"mappings":";;;;;;AAgCO,IAAM,IAAA,GAAO,CASlB,OAAA,EACA,OAAA,EACA,QAEA,MAAA,CAAO,OAAA;AAAA,EAAQ,MACb,aAAA,CAAc,OAAA,EAAS,OAAA,CAAQ,UAAU,CAAA,CAAE,QAAA,CAAS,GAAA,CAAI,IAAI,CAAA,GACxD,OAAA,CAAQ,QAAA,CAAS,GAAG,IACpB,MAAA,CAAO;AACb,CAAA,CAAE,IAAA;AAAA,EACA,MAAA,CAAO,QAAA,CAAS,SAAA,EAAW,MAAM,OAAO,IAAI,CAAA;AAAA,EAC5C,MAAA,CAAO,WAAA;AAAA,IAAY,CAAC,WAClB,MAAA,YAAkB,WAAA,GAAc,OAAO,IAAA,GAAO,MAAA,CAAO,IAAI,MAAM;AAAA;AAEnE;AAwEK,IAAM,KAAA,GAAQ,CACnB,WAAA,EACA,KAAA,KAEA,MAAA,CAAO,eAAA;AAAA,EACL,MAAA,CAAO,IAAI,aAAa;AACtB,IAAA,MAAM,KAAA,GAAQ,OAAO,KAAA,CAAM,IAAA,CAAK,WAAW,CAAA;AAG3C,IAAA,OAAO,KAAA,CAAM,YAAA;AAAA,MACX,KAAA;AAAA,MACA,MAAA,CAAO,QAAQ,KAAA,CAAM,MAAA,EAAQ,OAAO,UAAA,CAAW,KAAA,CAAM,MAAM,CAAC;AAAA,KAC9D;AACA,IAAA,MAAM,KAAA,GAAQ,OAAO,KAAA,CAAM,KAAA,CAAM,KAAK,CAAA,CAAE,IAAA;AAAA,MACtC,KAAA,CAAM,QAAQ,KAAK,CAAA;AAAA,MACnB,MAAA,CAAO,OAAA,CAAQ,CAAC,KAAA,KAAU,KAAA,CAAM,KAAA,CAAM,KAAA,EAAO,IAAA,CAAK,SAAA,CAAU,KAAK,CAAC,CAAC;AAAA,KACrE;AACA,IAAA,OAAO,KAAA,CAAM,MAAM,KAAK,CAAA;AAExB,IAAA,IAAI,KAAA,CAAM,KAAA,CAAM,IAAA,KAAS,QAAA,SAAiB,KAAA,CAAM,MAAA;AAChD,IAAA,OAAO,KAAA;AAAA,EACT,CAAC;AACH;AAeK,IAAM,OAAO,CAAC,KAAA,KACnB,MAAM,KAAA,CAAM,KAAA,EAAO,KAAK,IAAI","file":"index.js","sourcesContent":["/**\n * Helpers for running child machines under a parent on the Effect engine\n * (#556, ruling R1.1 of #554).\n *\n * tea still runs one machine per `run` and keeps no table of runs (#312). A\n * host that builds a tree of runs keeps its own table, ids and Msg names, and\n * hands the steps that race to these functions: `spawn` starts a child and\n * enrols it as one step, `stop` stops one child, and `tell` sends the parent a\n * notice it may no longer take.\n */\n\nimport { Effect, Exit, Scope } from \"effect\";\nimport type { Cmd, Machine, Sub } from \"../pure/core\";\nimport { acceptedTypes, NoCellError } from \"../pure/core\";\nimport type { StoreFailed } from \"./failures\";\nimport type { EffectRuntime } from \"./handle\";\n\n/**\n * Hand `msg` to a run only when its State has a cell for it, and drop it when\n * the run no longer takes it.\n *\n * `machine` is the machine `runtime` runs. The dispatch lands a moment after\n * the check, so a State that changed in between refuses the Msg with a\n * `NoCellError`, and a run that stopped refuses it with `Stopped`. Both mean\n * the run no longer takes the notice, so both are dropped and `tell` succeeds.\n * A failed save stays a `StoreFailed`, and a hand-written cell's declared\n * failure stays that failure.\n *\n * ```ts\n * yield* tell(parent, parentRun, { type: \"child_stopped\", id });\n * ```\n */\nexport const tell = <\n  S,\n  M extends { type: string },\n  C extends Cmd,\n  U extends Sub,\n  Ctx,\n  E extends { type: string } = never,\n  Err = never,\n>(\n  machine: Machine<S, M, C, U, Ctx>,\n  runtime: EffectRuntime<S, M, E, Err>,\n  msg: NoInfer<M>,\n): Effect.Effect<void, Err | StoreFailed> =>\n  Effect.suspend(() =>\n    acceptedTypes(machine, runtime.getState()).includes(msg.type)\n      ? runtime.dispatch(msg)\n      : Effect.void,\n  ).pipe(\n    Effect.catchTag(\"Stopped\", () => Effect.void),\n    Effect.catchDefect((defect) =>\n      defect instanceof NoCellError ? Effect.void : Effect.die(defect),\n    ),\n  ) as Effect.Effect<void, Err | StoreFailed>;\n\n/**\n * The host's own steps of a {@link spawn}. The host owns the table of\n * children, their ids and the parent's Msg names; `spawn` owns the order the\n * steps run in and keeps an interrupt from landing between them.\n */\nexport interface SpawnSteps<A, E = never, R = never> {\n  /**\n   * Start the child and return what the host keeps for it. It runs with the\n   * child's scope provided, so a `run(machine, opts)` in it belongs to that\n   * scope, and so does anything else it acquires. `scope` is the same scope,\n   * for a host that keeps it to stop the child with `stop`. A failure\n   * closes the child's scope, which runs `remove` and `notify`.\n   */\n  readonly start: (scope: Scope.Closeable) => Effect.Effect<A, E, R>;\n  /** Add the started child to the host's table. */\n  readonly enrol: (child: A) => Effect.Effect<unknown>;\n  /**\n   * Take the child out of the host's table. It runs when the child's scope\n   * closes, after its run has stopped, whether or not `enrol` ran, so it must\n   * be safe on a child the table does not hold.\n   */\n  readonly remove: Effect.Effect<unknown>;\n  /**\n   * Say the child stopped, usually a {@link tell} to the parent. It runs\n   * after `remove`, on a fiber of its own that the closing scope never waits\n   * for, so it may wait on the parent.\n   *\n   * It cannot fail: nothing reads that fiber, so the step itself handles what\n   * its notice can fail with, such as the `StoreFailed` of a `tell`. A defect\n   * in it is not observed by `spawn` and ends the fiber unseen.\n   */\n  readonly notify: Effect.Effect<unknown>;\n}\n\n/**\n * Start a child in a scope forked from `parentScope` and enrol it in the\n * host's table, as one uninterruptible step. Stop a child with `stop`,\n * or by closing its scope; closing `parentScope` stops every child spawned\n * under it.\n *\n * What it guarantees, with no guard in host code:\n *\n *   - the table never holds a child whose scope has closed. The fork, the\n *     removal finalizer, `start` and `enrol` all happen or none do, and a\n *     child whose scope closed before `enrol` is removed again;\n *   - closing a child never waits for the parent. `notify` runs on a detached\n *     fiber, so a parent Cmd handler can stop a child;\n *   - `remove` runs after the child's run has stopped.\n *\n * Nothing reads the fiber `notify` runs on, so `spawn` reports no failure of\n * it and `notify` is typed to have none. The host handles what its notice can\n * fail with inside the step, as the `Effect.catch` below does for a parent\n * whose save failed. A defect in `notify` ends that fiber unseen.\n *\n * `child.run.stop()` is not one of the two ways to stop a child. It stops the\n * run and leaves the scope open, so the entry stays in the table and the\n * parent is not told.\n *\n * ```ts\n * const child = yield* spawn(parentScope, {\n *   start: (scope) =>\n *     Effect.map(run(worker, {}), (run) => ({ run, scope })),\n *   enrol: (child) => Effect.sync(() => children.set(id, child)),\n *   remove: Effect.sync(() => children.delete(id)),\n *   notify: tell(parent, parentRun, { type: \"child_stopped\", id }).pipe(\n *     Effect.catch((failure) => Effect.logError(\"notice failed\", failure)),\n *   ),\n * });\n * ```\n */\nexport const spawn = <A, E = never, R = never>(\n  parentScope: Scope.Scope,\n  steps: SpawnSteps<A, E, R>,\n): Effect.Effect<A, E, Exclude<R, Scope.Scope>> =>\n  Effect.uninterruptible(\n    Effect.gen(function* () {\n      const scope = yield* Scope.fork(parentScope);\n      // Added before `start`, so it runs after everything `start` put in the\n      // scope has been released, the child's run included.\n      yield* Scope.addFinalizer(\n        scope,\n        Effect.andThen(steps.remove, Effect.forkDetach(steps.notify)),\n      );\n      const child = yield* steps.start(scope).pipe(\n        Scope.provide(scope),\n        Effect.onError((cause) => Scope.close(scope, Exit.failCause(cause))),\n      );\n      yield* steps.enrol(child);\n      // A scope that closed under `start` ran `remove` before `enrol`.\n      if (scope.state._tag === \"Closed\") yield* steps.remove;\n      return child;\n    }),\n  );\n\n/**\n * Stop one child that `spawn` started. `scope` is the child's scope,\n * the one its `start` was handed.\n *\n * It closes that scope, so the child's run stops, `remove` takes the entry\n * out of the host's table and `notify` tells the parent. It does not wait for\n * `notify`, so a parent Cmd handler can call it. Stopping a child that has\n * already stopped succeeds and sends no second notice.\n *\n * ```ts\n * yield* stop(child.scope);\n * ```\n */\nexport const stop = (scope: Scope.Closeable): Effect.Effect<void> =>\n  Scope.close(scope, Exit.void);\n"]}

package/dist/extension/index.d.ts

@@ -1,7 +1,7 @@
-import { R as Runtime, M as Migrated, S as Store } from '../runtime-types-BKg2CGMx.js';
+import { R as Runtime, M as Migrated, S as Store } from '../runtime-types-DEluQgGO.js';
 import { ReactNode } from 'react';
-import { c as Sub } from '../core-Ce9ncpuv.js';
-import { S as SubscribeHandler } from '../types-SzNSHKlV.js';
+import { S as Sub } from '../core-CtvAyPpH.js';
+import { S as SubscribeHandler } from '../types-CXNzlbAg.js';
 import '@standard-schema/spec';
 
 /**
@@ -35,6 +35,10 @@ import '@standard-schema/spec';
  * delivery guarantees should layer their own retry, not bake it here.
  */
 
+/**
+ * Options for `bridgeRuntime`: the `channel` name, the required `parseMsg` for
+ * inbound Msgs, and an optional `serialize` for the state sent to surfaces.
+ */
 interface BridgeRuntimeOpts<S, M, V = S> {
     channel: string;
     /**
@@ -125,6 +129,11 @@ declare function bridgeRuntime<S, M extends {
  * the documented exception, chosen explicitly.)
  */
 declare function passThroughMsg<M>(raw: unknown): M | null;
+/**
+ * A surface's handle on the background runtime: hydrate the current state,
+ * dispatch Msgs, and subscribe to state broadcasts. `bridgeClient` and
+ * `bridgeTabClient` return one.
+ */
 interface BridgeClient<S, M> {
     /** Send the hydrate request; resolves with the initial snapshot (or null
      * if the host is still booting OR the response failed to parse). Also
@@ -144,6 +153,10 @@ interface BridgeClient<S, M> {
      * underlying state hasn't changed since the prior call. */
     getSnapshot(): S | null;
 }
+/**
+ * Options for `bridgeClient`: the `channel` name and the required parsers for
+ * inbound state and Msgs.
+ */
 interface BridgeClientOpts<S, M> {
     channel: string;
     /**
@@ -168,9 +181,17 @@ interface BridgeClientOpts<S, M> {
      */
     parseMsg: (raw: unknown) => M | null;
 }
+/**
+ * Create a `BridgeClient` for a popup, side panel or content script, which
+ * talks to the background runtime over `chrome.runtime` messages.
+ */
 declare function bridgeClient<S, M extends {
     type: string;
 }>({ channel, parseState, parseMsg, }: BridgeClientOpts<S, M>): BridgeClient<S, M>;
+/**
+ * Options for `bridgeTabClient`: the target `tabId`, the `channel` name, and
+ * the required parsers.
+ */
 interface BridgeTabClientOpts<S, M> {
     tabId: number;
     channel: string;
@@ -256,6 +277,10 @@ declare function bridgeTabClient<S, M extends {
  * adapter peer-depends on react (you must have it installed in the app).
  */
 
+/**
+ * Options for `useBackgroundRuntime`: the `channel` name and the required
+ * `parseState`.
+ */
 interface UseBackgroundRuntimeOpts<S> {
     channel: string;
     /**
@@ -266,6 +291,10 @@ interface UseBackgroundRuntimeOpts<S> {
      */
     parseState: (raw: unknown) => S | null;
 }
+/**
+ * What `useBackgroundRuntime` returns: the latest `state`, which is `null`
+ * until the first one arrives, and `dispatch`.
+ */
 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
@@ -275,9 +304,18 @@ interface UseBackgroundRuntimeResult<S, M> {
      * settles. */
     dispatch(msg: M): Promise<void>;
 }
+/**
+ * React hook for an extension surface: it subscribes to the background
+ * runtime's state and returns it with a `dispatch`. Use it in a popup or side
+ * panel component.
+ */
 declare function useBackgroundRuntime<S, M extends {
     type: string;
 }>({ channel, parseState, }: UseBackgroundRuntimeOpts<S>): UseBackgroundRuntimeResult<S, M>;
+/**
+ * What `createBackgroundRuntimeContext` returns: a `Provider`, plus the
+ * `useState`, `useDispatch` and `useRuntime` hooks that read from it.
+ */
 interface BackgroundRuntimeContext<S, M> {
     /**
      * Wrap a subtree to share a single background-runtime bridge client.
@@ -321,6 +359,11 @@ interface BackgroundRuntimeContext<S, M> {
      */
     useRuntime: () => UseBackgroundRuntimeResult<S, M>;
 }
+/**
+ * Create a React context that shares one background-runtime connection across a
+ * component tree. Use it instead of calling `useBackgroundRuntime` in several
+ * components.
+ */
 declare function createBackgroundRuntimeContext<S, M extends {
     type: string;
 }>(): BackgroundRuntimeContext<S, M>;
@@ -328,8 +371,17 @@ declare function createBackgroundRuntimeContext<S, M extends {
 type AlarmSubData = {
     readonly alarmName: string;
 };
+/**
+ * Build a Sub runner that dispatches `msgFn(alarm, sub)` when the
+ * `chrome.alarms` alarm named `sub.deps.alarmName` fires. It only listens;
+ * create and clear the alarm with Cmds.
+ */
 declare function fromChromeAlarm<S extends Sub<string, AlarmSubData>, M>(msgFn: (alarm: chrome.alarms.Alarm, sub: S) => M | null): SubscribeHandler<S, M, unknown>;
 
+/**
+ * Options for `fromChromeMessage`: an optional `filter`, and the `msgFn` that
+ * maps a runtime message to a Msg.
+ */
 interface ChromeMessageOpts<S extends Sub, M> {
     /**
      * Pre-filter — when provided, the factory only dispatches when this
@@ -338,8 +390,16 @@ interface ChromeMessageOpts<S extends Sub, M> {
     filter?: (message: unknown) => boolean;
     msgFn: (message: unknown, sender: chrome.runtime.MessageSender, sub: S) => M | null;
 }
+/**
+ * Build a Sub runner that dispatches a Msg for each `chrome.runtime.onMessage`
+ * message that passes the filter. It never sends a response.
+ */
 declare function fromChromeMessage<S extends Sub, M>(opts: ChromeMessageOpts<S, M>): SubscribeHandler<S, M, unknown>;
 
+/**
+ * Options for `fromChromeStorageChange`: the storage `area`, an optional `keys`
+ * filter, and the `msgFn` that maps the changes to a Msg.
+ */
 interface ChromeStorageChangeOpts<S extends Sub, M> {
     area: chrome.storage.AreaName;
     /**
@@ -349,9 +409,18 @@ interface ChromeStorageChangeOpts<S extends Sub, M> {
     keys?: readonly string[];
     msgFn: (changes: Record<string, chrome.storage.StorageChange>, sub: S) => M | null;
 }
+/**
+ * Build a Sub runner that dispatches a Msg when keys change in a
+ * `chrome.storage` area.
+ */
 declare function fromChromeStorageChange<S extends Sub, M>(opts: ChromeStorageChangeOpts<S, M>): SubscribeHandler<S, M, unknown>;
 
+/** The `chrome.tabs` events `fromChromeTabsEvent` can listen to. */
 type TabsEventName = "onActivated" | "onUpdated" | "onRemoved";
+/**
+ * Options for `fromChromeTabsEvent`: which tab `events` to listen to, whether
+ * to fire once on mount, and the `msgFn` that builds the Msg.
+ */
 interface ChromeTabsEventOpts<S extends Sub, M> {
     events: readonly TabsEventName[];
     /**
@@ -363,6 +432,10 @@ interface ChromeTabsEventOpts<S extends Sub, M> {
     fireOnMount?: boolean;
     msgFn: (sub: S) => M | null;
 }
+/**
+ * Build a Sub runner that dispatches `msgFn(sub)` whenever one of the chosen
+ * `chrome.tabs` events fires.
+ */
 declare function fromChromeTabsEvent<S extends Sub, M>(opts: ChromeTabsEventOpts<S, M>): SubscribeHandler<S, M, unknown>;
 
 /**
@@ -384,6 +457,10 @@ 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;
+/**
+ * The in-memory `chrome` stand-in `fakeChrome` returns, with `__test.fire*`
+ * helpers that drive its events from a test.
+ */
 interface FakeChrome {
     storage: {
         local: chrome.storage.StorageArea;
@@ -490,6 +567,10 @@ interface FakeChrome {
         fireTabRemoved(tabId: number, removeInfo: chrome.tabs.OnRemovedInfo): void;
     };
 }
+/**
+ * Create an in-memory fake of the `chrome` APIs this adapter uses. Use it to
+ * test extension machines without a browser.
+ */
 declare function fakeChrome(): FakeChrome;
 
 /**

package/dist/extension/index.js

@@ -1,5 +1,5 @@
-import { historyTracker, dispatchIfPresent } from '../chunk-FNGZMVIT.js';
-import { describeError } from '../chunk-AIIXV4XB.js';
+import { historyTracker, dispatchIfPresent } from '../chunk-DVNXEB7V.js';
+import { describeError } from '../chunk-RKVUVALV.js';
 import { useRef, useSyncExternalStore, useEffect, useCallback, createContext, useMemo, useContext } from 'react';
 import { jsx } from 'react/jsx-runtime';