@cplieger/actions 1.1.6 → 2.0.0

package/README.md

@@ -7,7 +7,7 @@
 
 > Declarative UI-actions framework with lifecycle management, retry, debounce, and polling.
 
-A standalone TypeScript library for defining and dispatching UI actions with full lifecycle support: optimistic updates, automatic retry with backoff, scope serialization, dedupe collapsing, notification wiring, and a registry for observability. Zero runtime dependencies — notification display and streaming transport are injected by the consumer via small interfaces.
+A standalone TypeScript library for defining and dispatching UI actions with full lifecycle support: optimistic updates, automatic retry with backoff, scope serialization, dedupe collapsing, notification wiring, polling, button-feedback helpers, and a registry for observability. Built on [`@cplieger/reactive`](https://github.com/cplieger/reactive) — action pending-state is signal-backed, so `isPending`/`pendingCount` are reactive and `bindLoadingState` is a plain effect over them. Notification display and streaming transport are injected by the consumer via small interfaces.
 
 ## Install
 
@@ -99,12 +99,14 @@ const action = apiAction({
 - `transportAction(def)` — create a transport/SSE-backed action
 - `debouncedDispatch(action, opts)` — debounce wrapper
 - `pollAction(action, args, opts)` — interval polling with pause/backoff
-- `bindLoadingState(name, el, opts?)` — bind element disabled state to action pending
-- `subscribeToActions(fn)` — subscribe to all lifecycle events
-- `subscribeByName(name, fn)` — subscribe to lifecycle events for a single action name
+- `bindLoadingState(name, el, opts?)` — bind an element's disabled/aria-busy state to action pending; a reactive effect over the pending signals
+- `pollUntil(step, opts)` — poll until a terminal condition (wait-then-poll, `until` predicate, `maxAttempts`/`timeoutMs` budgets, backoff-on-transient); returns `{status:'done'|'timeout'|'aborted'}`. A standalone sibling to `pollAction` for one-shot terminal-state waits.
+- `withAsyncFeedback(btn, fn, opts?)` — per-button async feedback (spinner → ✓/✗ → restore) with a re-entry guard + sr-only announce + injectable glyphs. `target?: HTMLElement` runs the cycle on a child slot via in-place element replacement (siblings/label untouched); `resetMs: 0` persists the outcome glyph (no auto-revert).
+- `subscribeToActions(fn)` — subscribe to all lifecycle events (discrete event stream)
+- `subscribeByName(name, fn)` — subscribe to lifecycle events for a single action name (discrete event stream)
 - `getActionLog()` — read the recent action log (for devtools/debugging)
-- `pendingCount(names?)` — query pending action count
-- `isPending(name)` — O(1) check if a named action is in-flight
+- `pendingCount(names?)` — pending action count; reactive (tracks inside an effect)
+- `isPending(name)` — check if a named action is in-flight; reactive (tracks inside an effect)
 - `registerCleanup(fn)` — register teardown hooks for page unload
 - `ActionError` — structured error class with status/code
 - `retryNetwork` — preset retry classifier for transient failures
@@ -114,6 +116,29 @@ const action = apiAction({
 - `API_TIMEOUT_MS` — default API request timeout (30 000 ms)
 - `RETRY_STANDARD` — standard retry config (2 retries, 300ms)
 
+### Test utilities (`@cplieger/actions/testing`)
+
+The `./testing` subpath exports test-only helpers. Import only from test code:
+
+```typescript
+import { resetActionFramework } from "@cplieger/actions/testing";
+
+beforeEach(() => {
+  resetActionFramework();
+});
+```
+
+- `resetActionFramework()` — clear every framework state slot (define, registry, cleanup, api, transport, notifier). Call from `beforeEach()` to isolate tests.
+
+> **Breaking change in v2.0:** the `./src/*` deep-import escape hatch was removed
+> from `package.json` exports. Consumers that previously reached into
+> `@cplieger/actions/src/define`, `…/src/registry`, `…/src/cleanup`,
+> `…/src/api`, `…/src/transport`, or `…/src/notifier` to call
+> `_resetForTest`/`_resetApiConfigForTest`/`_resetTransportForTest`/
+> `_resetNotifierForTest` must migrate to
+> `@cplieger/actions/testing` for `resetActionFramework()`, or to the
+> public surface for everything else.
+
 ### Definition-level callbacks (TanStack Query pattern)
 
 `ActionDefinition` supports `onSuccess`, `onError`, and `onSettled` callbacks that fire on every dispatch without the caller needing to pass them each time:

package/jsr.json

@@ -1,8 +1,9 @@
 {
   "name": "@cplieger/actions",
-  "version": "1.1.6",
+  "version": "2.0.0",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./testing": "./src/testing.ts"
   },
   "publish": {
     "include": [

package/package.json

@@ -1,24 +1,27 @@
 {
   "name": "@cplieger/actions",
-  "version": "1.1.6",
+  "version": "2.0.0",
   "type": "module",
   "sideEffects": false,
   "exports": {
     ".": "./src/index.ts",
-    "./src/*": "./src/*"
+    "./testing": "./src/testing.ts"
   },
   "scripts": {
     "typecheck": "tsgo -project tsconfig.json",
     "typecheck:tests": "tsgo -project tsconfig.test.json",
     "test": "vitest --run"
   },
+  "dependencies": {
+    "@cplieger/reactive": "1.1.0"
+  },
   "devDependencies": {
     "@eslint/js": "10.0.1",
     "@types/node": "24.13.1",
     "@vitest/coverage-v8": "4.1.8",
     "eslint": "10.4.1",
     "fast-check": "4.8.0",
-    "happy-dom": "20.10.1",
+    "happy-dom": "20.10.2",
     "prettier": "3.8.3",
     "typescript-eslint": "8.60.1",
     "vitest": "4.1.8"

package/src/async-feedback.ts

@@ -0,0 +1,240 @@
+// withAsyncFeedback: per-button async feedback. Shows a spinner during the
+// operation, a ✓ on success / ✗ on error, then reverts. Disables the button
+// while pending and guards against re-entry.
+//
+// Works for both icon-only buttons (action pills) and text buttons. The
+// button's original child nodes and disabled state are snapshotted and
+// restored when the feedback cycle resets. State is exposed as
+// `data-async-status` on the button so CSS or tests can observe it without
+// parsing innerHTML.
+//
+// Promoted from vibekit's async-button.ts. The glyphs are injectable so apps
+// with their own icon system (e.g. `<span class="icon icon-check">`) can reuse
+// it; the defaults match vibekit's inline SVGs, making vibekit a zero-visual-
+// change consumer.
+// ---------------------------------------------------------------------------
+
+import { el } from "@cplieger/reactive";
+
+const RESET_MS = 1200;
+
+const DEFAULT_ANNOUNCE = { success: "Action completed", error: "Action failed" } as const;
+
+const CHECK_HTML =
+  '<svg class="btn-async-glyph" width="14" height="14" viewBox="0 0 24 24" fill="none" ' +
+  'stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" ' +
+  'aria-hidden="true"><polyline points="20 6 9 17 4 12"/></svg>';
+
+const X_HTML =
+  '<svg class="btn-async-glyph" width="14" height="14" viewBox="0 0 24 24" fill="none" ' +
+  'stroke="currentColor" stroke-width="3" stroke-linecap="round" ' +
+  'aria-hidden="true"><path d="M18 6L6 18M6 6l12 12"/></svg>';
+
+/** Parse a static SVG string via <template> and return a fresh clone. The
+ *  markup is a library-controlled constant, so a single root element is
+ *  guaranteed. */
+function svgNode(svg: string): Node {
+  const template = document.createElement("template");
+  template.innerHTML = svg;
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- default glyph markup always has a single root element
+  return template.content.firstElementChild!.cloneNode(true);
+}
+
+const defaultRenderPending = (): Node =>
+  el("span", { className: "spinner-sm btn-async-spinner", "aria-hidden": "true" });
+const defaultRenderSuccess = (): Node => svgNode(CHECK_HTML);
+const defaultRenderError = (): Node => svgNode(X_HTML);
+
+/** WeakMap tracking the pending reset timer per button. */
+const resetTimers = new WeakMap<HTMLButtonElement, ReturnType<typeof setTimeout>>();
+
+/** Tracks buttons with an in-flight operation. The re-entry guard keys on
+ *  THIS (not `data-async-status`) so a persisted outcome glyph (resetMs<=0)
+ *  does not permanently block a subsequent dispatch. */
+const inFlight = new WeakSet<HTMLButtonElement>();
+
+/** Lazily-created live region for announcing async-button outcomes. */
+let liveRegion: HTMLElement | null = null;
+
+function announce(message: string): void {
+  if (liveRegion === null) {
+    liveRegion = el("span", {
+      className: "sr-only",
+      "aria-live": "polite",
+      "aria-atomic": "true",
+    });
+    document.body.appendChild(liveRegion);
+  }
+  const region = liveRegion;
+  // Clear then set to ensure re-announcement of identical messages.
+  region.textContent = "";
+  setTimeout(() => {
+    region.textContent = message;
+  }, 50);
+}
+
+/** Options for {@link withAsyncFeedback}. All fields are optional; the glyph
+ *  renderers default to vibekit's inline SVGs. */
+export interface AsyncFeedbackOptions {
+  /** Post-completion glyph hold in ms before the content reverts. Default
+   *  1200. A value of `0` (or any value `<= 0`) means *persist*: the content
+   *  revert is never scheduled, so the success/error glyph stays in place
+   *  indefinitely (a later caller-driven re-render is expected to clear it).
+   *  Under persist the button is still re-enabled and `aria-busy` restored at
+   *  outcome time, but `data-async-status` keeps its terminal `success`/
+   *  `error` value (it is not cleared). Applies to both the whole-button and
+   *  `target` paths. */
+  resetMs?: number;
+  /** When true, prepend the spinner before the existing content (e.g.
+   *  "⟳ Cloning…") instead of replacing the content with just the spinner.
+   *  Default false (icon-only replace). Ignored when {@link target} is set. */
+  keepLabel?: boolean;
+  /** Opt-in: drive a single child slot of the button instead of the button's
+   *  whole content. When provided, the spinner / outcome glyph / reset cycle
+   *  operates on `target` by REPLACING THE ELEMENT IN THE DOM
+   *  (`current.replaceWith(next)`), leaving every other child of `btn` (e.g. a
+   *  text label sibling) untouched. The original `target` node reference is
+   *  kept so a (non-persist) reset restores that exact node. `target` is
+   *  expected to be a descendant of `btn` (not hard-validated). The
+   *  button-level concerns are unchanged: `disabled` toggle, the
+   *  `data-async-status` re-entry guard, `aria-busy`, and the sr-only
+   *  announce all still apply to `btn`. `keepLabel` is irrelevant here and is
+   *  ignored. Default: whole-button (childNodes) mode. */
+  target?: HTMLElement;
+  /** Pending-state node factory. Returns a fresh node per call. */
+  renderPending?: () => Node;
+  /** Success-glyph node factory. Returns a fresh node per call. */
+  renderSuccess?: () => Node;
+  /** Error-glyph node factory. Returns a fresh node per call. */
+  renderError?: () => Node;
+  /** Live-region announcement text, or `false` to disable announcing. */
+  announce?: { readonly success: string; readonly error: string } | false;
+}
+
+/** Run an async function with consistent button feedback. The button is
+ *  disabled during the call. Re-entrant calls (clicking again while a cycle
+ *  is active) are ignored. */
+export async function withAsyncFeedback(
+  btn: HTMLButtonElement,
+  fn: () => Promise<unknown>,
+  opts: AsyncFeedbackOptions = {},
+): Promise<void> {
+  // Guard: reject re-entry only while an operation is in flight. (Keying on
+  // `data-async-status` would deadlock the persist path, whose terminal status
+  // is intentionally never cleared.)
+  if (inFlight.has(btn)) {
+    return;
+  }
+  inFlight.add(btn);
+
+  // Cancel any pending reset timer from a prior cycle to avoid stale restores.
+  const prevTimer = resetTimers.get(btn);
+  if (prevTimer !== undefined) {
+    clearTimeout(prevTimer);
+    resetTimers.delete(btn);
+  }
+
+  const renderPending = opts.renderPending ?? defaultRenderPending;
+  const renderSuccess = opts.renderSuccess ?? defaultRenderSuccess;
+  const renderError = opts.renderError ?? defaultRenderError;
+  const announceCfg = opts.announce ?? DEFAULT_ANNOUNCE;
+
+  // Target mode operates on a single child slot via element replacement and
+  // never snapshots/replaces the button's own childNodes. `originalTarget`
+  // keeps the exact node so a non-persist reset can restore it; `currentSlot`
+  // tracks whichever node currently occupies the slot.
+  const target = opts.target;
+  const useTarget = target !== undefined;
+  const originalTarget: ChildNode | null = useTarget ? target : null;
+  let currentSlot: ChildNode | null = useTarget ? target : null;
+
+  // Replace the live slot node with `next` and track it as the new slot.
+  // Render factories return a single node (Element/Text), both of which are
+  // ChildNode at runtime; the cast reflects that contract.
+  const swapSlot = (next: Node): void => {
+    if (currentSlot === null) {
+      return;
+    }
+    currentSlot.replaceWith(next);
+    currentSlot = next as ChildNode;
+  };
+
+  const origNodes = useTarget ? [] : [...btn.childNodes].map((n) => n.cloneNode(true));
+  const origDisabled = btn.disabled;
+  const origAriaBusy = btn.getAttribute("aria-busy");
+
+  const restoreAriaBusy = (): void => {
+    if (origAriaBusy === null) {
+      btn.removeAttribute("aria-busy");
+    } else {
+      btn.setAttribute("aria-busy", origAriaBusy);
+    }
+  };
+
+  btn.dataset["asyncStatus"] = "pending";
+  btn.disabled = true;
+  btn.setAttribute("aria-busy", "true");
+  if (useTarget) {
+    swapSlot(renderPending());
+  } else if (opts.keepLabel === true) {
+    btn.prepend(renderPending(), document.createTextNode(" "));
+  } else {
+    btn.replaceChildren(renderPending());
+  }
+
+  let ok = true;
+  try {
+    await fn();
+  } catch {
+    ok = false;
+  }
+
+  // The button may have been removed from the DOM by the async operation
+  // (e.g. a re-rendered list). Skip the success/error visual in that case —
+  // the new DOM already reflects the result.
+  if (!btn.isConnected) {
+    inFlight.delete(btn);
+    restoreAriaBusy();
+    delete btn.dataset["asyncStatus"];
+    return;
+  }
+
+  btn.dataset["asyncStatus"] = ok ? "success" : "error";
+  if (useTarget) {
+    swapSlot(ok ? renderSuccess() : renderError());
+  } else {
+    btn.replaceChildren(ok ? renderSuccess() : renderError());
+  }
+  restoreAriaBusy();
+  inFlight.delete(btn);
+  if (announceCfg !== false) {
+    announce(ok ? announceCfg.success : announceCfg.error);
+  }
+
+  // `resetMs <= 0` => persist: skip the content-revert timer entirely. The
+  // glyph stays and `data-async-status` keeps its terminal value, but the
+  // button is re-enabled now (there is no reset callback to do it later).
+  const reset = opts.resetMs ?? RESET_MS;
+  if (reset <= 0) {
+    btn.disabled = origDisabled;
+    return;
+  }
+
+  const timerId = setTimeout(() => {
+    resetTimers.delete(btn);
+    if (!btn.isConnected) {
+      return;
+    }
+    if (useTarget) {
+      if (currentSlot !== null && originalTarget !== null) {
+        currentSlot.replaceWith(originalTarget);
+        currentSlot = originalTarget;
+      }
+    } else {
+      btn.replaceChildren(...origNodes.map((n) => n.cloneNode(true)));
+    }
+    btn.disabled = origDisabled;
+    delete btn.dataset["asyncStatus"];
+  }, reset);
+  resetTimers.set(btn, timerId);
+}

package/src/index.ts

@@ -29,6 +29,10 @@ export {
 // Loading-state helper
 export { bindLoadingState } from "./loading.js";
 
+// Async button-feedback helper
+export { withAsyncFeedback } from "./async-feedback.js";
+export type { AsyncFeedbackOptions } from "./async-feedback.js";
+
 // Cleanup hooks
 export { registerCleanup } from "./cleanup.js";
 
@@ -40,6 +44,10 @@ export type { DebouncedDispatch } from "./debounce.js";
 export { pollAction } from "./poll.js";
 export type { PollOptions } from "./poll.js";
 
+// Poll-until-terminal helper
+export { pollUntil } from "./poll-until.js";
+export type { PollUntilOptions, PollUntilOutcome } from "./poll-until.js";
+
 // Types
 export type {
   Action,

package/src/loading.ts

@@ -1,16 +1,20 @@
 // bindLoadingState: bind a button or input element's disabled / aria-busy
-// state to one or more named actions' pending count.
+// state to one or more named actions' pending state.
 //
 // While ANY of the named actions is pending, the element gets:
 //   - disabled = true
 //   - aria-busy = "true"  (omit by passing { ariaBusy: false })
 //   - optionally an extra CSS class via { pendingClass: "btn-loading" }
 //
-// Returns an unsubscribe function. Call it from the view's teardown
-// hook to stop receiving updates and avoid leaking listeners.
+// Implemented as a reactive effect over the registry's pending signals: it
+// re-runs automatically whenever a bound action's pending state changes, so
+// there is no bespoke subscription here. Returns a dispose function — call it
+// from the view's teardown hook to stop updates and release the element.
 // ---------------------------------------------------------------------------
 
-import { subscribeByName, isPending, pendingCount } from "./registry.js";
+import { effect } from "@cplieger/reactive";
+
+import { isPending, pendingCount } from "./registry.js";
 
 /** Element types that have a `.disabled` writable boolean. */
 type DisableableElement =
@@ -56,6 +60,9 @@ export function bindLoadingState(
   let hadFocus = false;
   let disposed = false;
   let wasConnected = el.isConnected;
+  // Holder so run() can self-dispose the effect on detach without a
+  // forward-referenced `let` (assigned just below, after run() is defined).
+  const handle: { dispose?: () => void } = {};
 
   const resolveBase = (): boolean => {
     if (disabledFn !== undefined) {
@@ -89,21 +96,19 @@ export function bindLoadingState(
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- length checked above
     names.length === 1 ? isPending(names[0]!) : pendingCount(names) > 0;
 
-  // eslint-disable-next-line prefer-const -- assigned after apply() closure is defined
-  let _unsubs: (() => void)[] | undefined;
-
-  const apply = (): void => {
+  // Reactive effect: readPending() tracks the registry's pending signals, so
+  // this re-runs whenever a bound action's pending state changes.
+  const run = (): undefined => {
     if (disposed) {
-      return;
+      return undefined;
     }
     if (wasConnected && !el.isConnected) {
+      // Element left the DOM without an explicit unbind — auto-dispose so we
+      // don't keep it (and the effect) alive. Defer the dispose: `dispose` is
+      // still unset during the effect's own first synchronous run.
       disposed = true;
-      if (_unsubs) {
-        for (const u of _unsubs) {
-          u();
-        }
-      }
-      return;
+      queueMicrotask(() => handle.dispose?.());
+      return undefined;
     }
     if (el.isConnected) {
       wasConnected = true;
@@ -125,6 +130,7 @@ export function bindLoadingState(
       setIdle();
     }
     wasPending = pending;
+    return undefined;
   };
 
   const restore = (): void => {
@@ -134,16 +140,11 @@ export function bindLoadingState(
     }
   };
 
-  apply();
-
-  const unsubs = names.map((name) => subscribeByName(name, apply));
-  _unsubs = unsubs;
+  handle.dispose = effect(run);
 
   return () => {
     disposed = true;
     restore();
-    for (const u of unsubs) {
-      u();
-    }
+    handle.dispose?.();
   };
 }

package/src/poll-until.ts

@@ -0,0 +1,167 @@
+// pollUntil: poll-until-terminal primitive. Sibling to pollAction, but
+// time-boxed rather than a forever periodic refresh: it repeatedly calls
+// `step` on a wait-then-poll cadence until a terminal predicate matches, a
+// max-attempts / wall-clock budget is exhausted, or an AbortSignal fires.
+//
+// Unlike pollAction it deliberately has NO pauseWhenHidden / refreshOnFocus —
+// a device-flow / download-progress poll is a bounded flow the caller drives
+// to completion, not a background refresh that should pause while the tab is
+// hidden. That distinction is the whole reason pollAction does not fit.
+// ---------------------------------------------------------------------------
+
+/** Configuration for {@link pollUntil}. Controls cadence, the terminal
+ *  predicate, optional attempt/time budgets, transient-failure backoff, and
+ *  cancellation. */
+export interface PollUntilOptions<T> {
+  /** Quiet window before each poll in ms. */
+  readonly intervalMs: number;
+  /** Terminal predicate: return true on a result that ends the poll. */
+  readonly until: (result: T) => boolean;
+  /** Stop after this many poll attempts. 0/undefined = unlimited. */
+  readonly maxAttempts?: number;
+  /** Overall wall-clock deadline in ms, measured from the call. */
+  readonly timeoutMs?: number;
+  /** Exponential backoff applied to the wait after consecutive transient
+   *  failures (a null result or a throw). Reset on the next good poll. */
+  readonly backoff?: { readonly factor: number; readonly maxMs: number };
+  /** Called for a non-terminal successful poll (a non-null result that does
+   *  not satisfy `until`). */
+  readonly onPoll?: (result: T) => void;
+  /** Called when a poll is a transient failure (step returned null or threw). */
+  readonly onTransientError?: () => void;
+  /** Abort the poll early. A pre-aborted signal resolves `aborted` without
+   *  ever calling `step`. */
+  readonly signal?: AbortSignal;
+}
+
+/** Terminal outcome of {@link pollUntil}. */
+export type PollUntilOutcome<T> =
+  | { readonly status: "done"; readonly result: T }
+  | { readonly status: "timeout" }
+  | { readonly status: "aborted" };
+
+/** Sleep for `ms`, resolving early (never rejecting) if `signal` fires. The
+ *  caller re-checks `signal.aborted` after waking to decide what to do. */
+function sleepWithSignal(ms: number, signal: AbortSignal): Promise<void> {
+  if (signal.aborted) {
+    return Promise.resolve();
+  }
+  return new Promise<void>((resolve) => {
+    const ac = new AbortController();
+    const t = setTimeout(() => {
+      ac.abort();
+      resolve();
+    }, ms);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(t);
+        ac.abort();
+        resolve();
+      },
+      { signal: ac.signal },
+    );
+  });
+}
+
+/**
+ * Repeatedly call `step` on a wait-then-poll cadence until it yields a
+ * terminal result, a budget is exhausted, or the signal aborts.
+ *
+ * Each iteration waits the current delay (abortable), then polls. A null
+ * result or a throw is a transient failure — `onTransientError` fires and,
+ * when `backoff` is set, the next wait grows. A non-null result resets the
+ * backoff; if it satisfies `until` the poll resolves `done`, otherwise
+ * `onPoll` fires and polling continues.
+ *
+ * @example
+ * ```ts
+ * const outcome = await pollUntil(
+ *   (signal) => apiPoll("/api/device", signal),
+ *   {
+ *     intervalMs: 5000,
+ *     until: (r) => r.status !== "pending",
+ *     maxAttempts: 60,
+ *     backoff: { factor: 2, maxMs: 60_000 },
+ *     signal,
+ *   },
+ * );
+ * ```
+ */
+export async function pollUntil<T>(
+  step: (signal: AbortSignal) => Promise<T | null>,
+  opts: PollUntilOptions<T>,
+): Promise<PollUntilOutcome<T>> {
+  const { intervalMs, until, maxAttempts, timeoutMs, backoff, onPoll, onTransientError } = opts;
+  const signal = opts.signal ?? new AbortController().signal;
+
+  // (1) Pre-aborted: bail before any wait or step call.
+  if (signal.aborted) {
+    return { status: "aborted" };
+  }
+
+  const start = Date.now();
+  let attempts = 0;
+  let failures = 0;
+
+  for (;;) {
+    // (2) Wait the (possibly backed-off) delay, aborting early on signal.
+    const delay =
+      backoff !== undefined && failures > 0
+        ? Math.min(intervalMs * Math.pow(backoff.factor, failures), backoff.maxMs)
+        : intervalMs;
+    await sleepWithSignal(delay, signal);
+
+    // (3) Post-wait gates: abort, then attempt / time budgets.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- aborted flips during the awaited sleep
+    if (signal.aborted) {
+      return { status: "aborted" };
+    }
+    attempts += 1;
+    if (maxAttempts !== undefined && maxAttempts > 0 && attempts > maxAttempts) {
+      return { status: "timeout" };
+    }
+    if (timeoutMs !== undefined && Date.now() - start >= timeoutMs) {
+      return { status: "timeout" };
+    }
+
+    // (4) Poll. A throw or null result is transient: back off and retry.
+    let result: T | null;
+    try {
+      result = await step(signal);
+    } catch {
+      result = null;
+    }
+
+    // Abort that fired during step() wins over treating the (likely null)
+    // result as a transient failure — no spurious onTransientError on teardown.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- aborted flips during the awaited step
+    if (signal.aborted) {
+      return { status: "aborted" };
+    }
+
+    if (result === null) {
+      if (onTransientError !== undefined) {
+        try {
+          onTransientError();
+        } catch (e) {
+          console.error("[pollUntil] onTransientError threw", e);
+        }
+      }
+      failures += 1;
+      continue;
+    }
+
+    failures = 0;
+    if (until(result)) {
+      return { status: "done", result };
+    }
+    if (onPoll !== undefined) {
+      try {
+        onPoll(result);
+      } catch (e) {
+        console.error("[pollUntil] onPoll threw", e);
+      }
+    }
+  }
+}

package/src/registry.ts

@@ -4,8 +4,17 @@
 //
 // Performance: eviction uses a head-pointer + tombstones instead of
 // splice + O(n) index re-computation. record() is O(1) amortized.
+//
+// Pending state (isPending / pendingCount) is mirrored into reactive signals,
+// so it can be read inside an effect — bindLoadingState is a plain effect over
+// these, not a bespoke subscription. The pendingByName Set stays the source of
+// truth for which ids are in flight; the signals expose the derived counts.
+// The lifecycle fan-out below (record → listeners) is a discrete event stream
+// and stays a plain emitter — events are not reactive state.
 // ---------------------------------------------------------------------------
 
+import { signal, batch, SignalMap } from "@cplieger/reactive";
+
 import type { ActionInstance, RegistryListener } from "./types.js";
 
 const MAX_LOG_SIZE = 200;
@@ -24,6 +33,46 @@ let _pendingTotal = 0;
 let _liveCount = 0;
 let _head = 0;
 
+// Reactive mirrors of the pending state. pendingByName remains the source of
+// truth; these signals expose the derived counts so isPending/pendingCount can
+// be read reactively (e.g. by bindLoadingState's effect).
+const pendingSigs = new SignalMap<number>();
+const pendingTotalSig = signal(0);
+
+function addPending(name: string, id: string): void {
+  let s = pendingByName.get(name);
+  if (s === undefined) {
+    s = new Set();
+    pendingByName.set(name, s);
+  }
+  if (s.has(id)) {
+    return;
+  }
+  s.add(id);
+  _pendingTotal++;
+  const size = s.size;
+  batch(() => {
+    pendingSigs.ensure(name, 0).value = size;
+    pendingTotalSig.value = _pendingTotal;
+  });
+}
+
+function removePending(name: string, id: string): void {
+  const s = pendingByName.get(name);
+  if (!s?.delete(id)) {
+    return;
+  }
+  _pendingTotal--;
+  const size = s.size;
+  if (size === 0) {
+    pendingByName.delete(name);
+  }
+  batch(() => {
+    pendingSigs.ensure(name, 0).value = size;
+    pendingTotalSig.value = _pendingTotal;
+  });
+}
+
 function compact(): void {
   while (_head < log.length && log[_head] === null) {
     _head++;
@@ -43,22 +92,9 @@ export function record(instance: ActionInstance): void {
   if (existing !== undefined) {
     const prev = existing.instance;
     if (prev.status === "pending" && instance.status !== "pending") {
-      _pendingTotal--;
-      const s = pendingByName.get(prev.name);
-      if (s !== undefined) {
-        s.delete(instance.id);
-        if (s.size === 0) {
-          pendingByName.delete(prev.name);
-        }
-      }
+      removePending(prev.name, instance.id);
     } else if (prev.status !== "pending" && instance.status === "pending") {
-      _pendingTotal++;
-      let s = pendingByName.get(instance.name);
-      if (s === undefined) {
-        s = new Set();
-        pendingByName.set(instance.name, s);
-      }
-      s.add(instance.id);
+      addPending(instance.name, instance.id);
     }
     log[existing.index] = instance;
     existing.instance = instance;
@@ -87,13 +123,7 @@ export function record(instance: ActionInstance): void {
     idMap.set(instance.id, { instance, index: idx });
     _liveCount++;
     if (instance.status === "pending") {
-      _pendingTotal++;
-      let s = pendingByName.get(instance.name);
-      if (s === undefined) {
-        s = new Set();
-        pendingByName.set(instance.name, s);
-      }
-      s.add(instance.id);
+      addPending(instance.name, instance.id);
     }
     if (_liveCount > MAX_LOG_SIZE) {
       for (let i = _head; i < log.length; i++) {
@@ -111,14 +141,7 @@ export function record(instance: ActionInstance): void {
         const entry = log[i];
         if (entry !== null && entry !== undefined) {
           if (entry.status === "pending") {
-            _pendingTotal--;
-            const s = pendingByName.get(entry.name);
-            if (s !== undefined) {
-              s.delete(entry.id);
-              if (s.size === 0) {
-                pendingByName.delete(entry.name);
-              }
-            }
+            removePending(entry.name, entry.id);
           }
           idMap.delete(entry.id);
           log[i] = null;
@@ -132,6 +155,7 @@ export function record(instance: ActionInstance): void {
   if (_pendingTotal < 0) {
     console.warn("[actions] _pendingTotal went negative — invariant violation; clamping to 0");
     _pendingTotal = 0;
+    pendingTotalSig.value = 0;
   }
   for (const fn of listeners) {
     try {
@@ -191,23 +215,20 @@ export function recentLog(): readonly ActionInstance[] {
  *  debugging panels. Returns a snapshot of all live entries. */
 export const getActionLog = recentLog;
 
-/** O(1) check: true if at least one instance of the named action is pending. */
+/** O(1) check: true if at least one instance of the named action is pending.
+ *  Reactive — reading inside an effect tracks the name's pending signal. */
 export function isPending(name: string): boolean {
-  const s = pendingByName.get(name);
-  return s !== undefined && s.size > 0;
+  return pendingSigs.ensure(name, 0).value > 0;
 }
 
-/** Pending count for action(s). */
+/** Pending count for action(s). Reactive — reads track the relevant signals. */
 export function pendingCount(names?: readonly string[]): number {
   if (names === undefined) {
-    return _pendingTotal;
+    return pendingTotalSig.value;
   }
   let total = 0;
   for (const name of names) {
-    const s = pendingByName.get(name);
-    if (s !== undefined) {
-      total += s.size;
-    }
+    total += pendingSigs.ensure(name, 0).value;
   }
   return total;
 }
@@ -222,4 +243,6 @@ export function _resetForTest(): void {
   listeners.clear();
   namedListeners.clear();
   _pendingTotal = 0;
+  pendingSigs.clearAll();
+  pendingTotalSig.value = 0;
 }

package/src/testing.ts

@@ -0,0 +1,32 @@
+/**
+ * Test-only utilities.
+ *
+ * Public subpath: `import { resetActionFramework } from "@cplieger/actions/testing"`.
+ *
+ * Replaces the previously-undocumented internal deep-imports
+ * (`_resetForTest` / `_resetApiConfigForTest` / `_resetTransportForTest` /
+ * `_resetNotifierForTest`) from `src/{define,registry,cleanup,api,transport,notifier}.ts`.
+ *
+ * Intended for consumer test suites that need to clear all framework state
+ * between tests. NOT for use in production code.
+ */
+
+import { _resetForTest as resetDefine } from "./define.js";
+import { _resetForTest as resetRegistry } from "./registry.js";
+import { _resetForTest as resetCleanup } from "./cleanup.js";
+import { _resetApiConfigForTest as resetApi } from "./api.js";
+import { _resetTransportForTest as resetTransport } from "./transport.js";
+import { _resetNotifierForTest as resetNotifier } from "./notifier.js";
+
+/**
+ * Reset every framework state slot — define, registry, cleanup, api,
+ * transport, notifier. Call from `beforeEach()` in test suites.
+ */
+export function resetActionFramework(): void {
+  resetDefine();
+  resetRegistry();
+  resetCleanup();
+  resetApi();
+  resetTransport();
+  resetNotifier();
+}