@wow-two-beta/ui-vue 0.0.4 → 0.0.6

package/dist/foundation/async/index.js

@@ -1,6 +1,7 @@
-import { t as toError } from "../../chunks/ToError-CyTBsmLO.js";
-import { i as isAbortError } from "../../chunks/ErrorRecognizers-oTklha6D.js";
+import { t as toError } from "../../chunks/ToError-vXncXe19.js";
+import { i as isAbortError } from "../../chunks/ErrorRecognizers-DO2SHD6N.js";
 import { DefaultRetryPolicy, shouldRetry, computeRetryDelay } from "../resilience/index.js";
+import { u } from "../../chunks/UseDebounceHandler-BIZgvvGp.js";
 function deferred() {
   let resolve;
   let reject;
@@ -23,13 +24,16 @@ function abortErrorFor(signal) {
 }
 function abortable(promise, signal) {
   if (signal === void 0) return Promise.resolve(promise);
-  if (signal.aborted) return Promise.reject(abortErrorFor(signal));
+  if (signal.aborted) {
+    void Promise.resolve(promise).catch(() => void 0);
+    return Promise.reject(abortErrorFor(signal));
+  }
   return new Promise((resolve, reject) => {
     const onAbort = () => {
       reject(abortErrorFor(signal));
     };
     signal.addEventListener("abort", onAbort, { once: true });
-    promise.then(
+    void Promise.resolve(promise).then(
       (value) => {
         signal.removeEventListener("abort", onAbort);
         resolve(value);
@@ -61,7 +65,7 @@ class TimeoutError extends Error {
 function withTimeout(promise, ms, options = {}) {
   const { signal, onTimeout, message } = options;
   if (!Number.isFinite(ms) || ms <= 0) return abortable(promise, signal);
-  if (signal?.aborted === true) return Promise.reject(abortErrorFor(signal));
+  if (signal?.aborted === true) return abortable(promise, signal);
   return new Promise((resolve, reject) => {
     let timer;
     let abortListener;
@@ -92,7 +96,7 @@ function withTimeout(promise, ms, options = {}) {
       abortListener = listener;
       signal.addEventListener("abort", listener, { once: true });
     }
-    promise.then(
+    void Promise.resolve(promise).then(
       (value) => {
         cleanup();
         resolve(value);
@@ -105,6 +109,7 @@ function withTimeout(promise, ms, options = {}) {
   });
 }
 function pLimit(concurrency) {
+  if (Number.isNaN(concurrency)) throw new RangeError("Concurrency must be a number.");
   const limit = Math.max(1, Math.floor(concurrency));
   const queue = [];
   let active = 0;
@@ -284,6 +289,7 @@ export {
   retryAsync,
   sequential,
   throttleAsync,
+  u as useDebounceHandler,
   withAbort,
   withTimeout
 };

package/dist/foundation/async/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/foundation/async/Deferred.ts","../../../src/foundation/async/Abort.ts","../../../src/foundation/async/Timeout.ts","../../../src/foundation/async/Limit.ts","../../../src/foundation/async/Retry.ts","../../../src/foundation/async/Rate.ts","../../../src/foundation/async/Combinators.ts"],"sourcesContent":["// The externally-settled promise — a promise plus the `resolve` / `reject` that close over it, handed back\n// to the caller instead of trapped inside an executor. Every other helper in this slice needs it: `pLimit`\n// hands a queued task's settlers to a scheduler that runs later, and `debounceAsync` parks N callers'\n// settlers until one trailing invocation resolves them all.\n//\n// Why hand-rolled rather than `Promise.withResolvers()`: that landed in ES2024, and this package targets\n// ES2022 with a browser support floor below it. The shape is deliberately identical, so this file becomes\n// a one-line delegation the day the floor moves.\n//\n// Non-obvious decision: the executor runs SYNCHRONOUSLY inside the `Promise` constructor, so `resolve` and\n// `reject` are always assigned before the constructor returns. TypeScript cannot see that through the\n// closure, hence the `!` assertions — the alternative (`| undefined` fields plus a guard on every call\n// site) would push a lie about the runtime into every consumer.\n\n/** A promise whose settlement is controlled from outside its executor. */\nexport interface Deferred<T> {\n  /** The promise handed to waiters. Settles when {@link resolve} or {@link reject} is called. */\n  readonly promise: Promise<T>;\n\n  /** Fulfils {@link promise}. A second call (after either settler) is a no-op, per promise semantics. */\n  readonly resolve: (value: T | PromiseLike<T>) => void;\n\n  /** Rejects {@link promise}. A second call (after either settler) is a no-op, per promise semantics. */\n  readonly reject: (reason?: unknown) => void;\n}\n\n/**\n * Creates a {@link Deferred} — a promise you settle later, from anywhere.\n *\n * Reach for it when the code that settles is not the code that creates: a scheduler that starts a task\n * once a slot frees, an event listener that resolves on the next message, a debounce that answers many\n * callers from one invocation. When the work is already a promise, wrap it directly — a deferred adds a\n * layer that can be forgotten unsettled.\n */\nexport function deferred<T>(): Deferred<T> {\n  let resolve!: (value: T | PromiseLike<T>) => void;\n  let reject!: (reason?: unknown) => void;\n\n  const promise = new Promise<T>((promiseResolve, promiseReject) => {\n    resolve = promiseResolve;\n    reject = promiseReject;\n  });\n\n  return { promise, resolve, reject };\n}\n","// Cancellation seam — turns an `AbortSignal` into a promise rejection, for the vast majority of async work\n// that has no native `signal` parameter of its own (only `fetch` and a handful of platform APIs do).\n//\n// THE ALREADY-ABORTED CASE IS THE ONE EVERYONE FORGETS. A signal handed in already aborted fires no `abort`\n// event — the event has been and gone. Code that only calls `addEventListener` therefore waits forever on a\n// signal that is *already* cancelled, which is the worst possible reading of \"cancelled\". Both helpers here\n// check `signal.aborted` FIRST, before any listener is attached, and `withAbort` never even invokes `fn`.\n//\n// ABORTING DETACHES THE CALLER; IT DOES NOT CANCEL THE WORK. Nothing here can stop an already-running\n// promise — that power does not exist in the promise model. The underlying operation runs to completion and\n// its result is discarded. Pass the signal INTO the operation (`withAbort` hands it to `fn` for exactly\n// this) whenever the operation can honour one; otherwise accept that an aborted `abortable` leaves work\n// running in the background.\n//\n// WE ALWAYS REJECT WITH OUR OWN `AbortError`, NEVER WITH `signal.reason`, which is a deliberate deviation\n// from `signal.throwIfAborted()`. `abort(reason)` accepts ANY value, so forwarding it would let an abort\n// arrive as, say, a plain `Error` that `isAbortError` does not recognize — and an unrecognized abort is a\n// live bug: `retryAsync` would retry a cancelled call, and `UploadQueue` would mark a cancel as a failure.\n// The invariant that every consumer keys on (`isAbortError(caught) === true` for every cancellation) is\n// worth more than reason pass-through, so the reason is preserved on `cause` instead of in the identity.\n//\n// LISTENER DISCIPLINE: every listener is `{ once: true }` (self-removing when it fires) AND explicitly\n// removed on both settle paths. A signal outlives the call it cancels — one long-lived signal driving\n// hundreds of short calls would otherwise accumulate a listener per call and leak every closure it holds.\n\n/**\n * The cancellation error every helper in this slice rejects with. Named `AbortError` so `isAbortError`\n * from `foundation/errors` recognizes it.\n *\n * Prefer `isAbortError(caught)` over `caught instanceof AbortError`: a cancellation that originates in\n * `fetch` is a `DOMException`, not this class, and only the name-keyed recognizer catches both.\n */\nexport class AbortError extends Error {\n  /** Creates a cancellation error; pass `cause` to preserve the signal's abort reason. */\n  constructor(message = 'The operation was aborted.', options?: ErrorOptions) {\n    super(message, options);\n    this.name = 'AbortError';\n  }\n}\n\n/**\n * Builds the {@link AbortError} for a fired signal, preserving `signal.reason` as `cause`. Internal to the\n * slice; not barrelled — consumers construct {@link AbortError} directly.\n */\nexport function abortErrorFor(signal: AbortSignal): AbortError {\n  const reason: unknown = signal.reason;\n  return reason === undefined ? new AbortError() : new AbortError(undefined, { cause: reason });\n}\n\n/**\n * Races a promise against a signal, rejecting with an {@link AbortError} the moment the signal fires.\n *\n * An already-aborted signal rejects without attaching a listener. The abort listener is removed on every\n * exit path. Remember the header's warning: `promise` keeps running after an abort — its eventual result\n * is dropped.\n */\nexport function abortable<T>(promise: PromiseLike<T>, signal?: AbortSignal): Promise<T> {\n  if (signal === undefined) return Promise.resolve(promise);\n  if (signal.aborted) return Promise.reject(abortErrorFor(signal));\n\n  return new Promise<T>((resolve, reject) => {\n    const onAbort = (): void => {\n      reject(abortErrorFor(signal));\n    };\n    signal.addEventListener('abort', onAbort, { once: true });\n\n    // Both handlers detach the listener before settling. Redundant with `once` on the abort path, and\n    // load-bearing on every other path: a promise that resolves normally must not leave a listener behind.\n    promise.then(\n      (value) => {\n        signal.removeEventListener('abort', onAbort);\n        resolve(value);\n      },\n      (error: unknown) => {\n        signal.removeEventListener('abort', onAbort);\n        reject(error);\n      },\n    );\n  });\n}\n\n/**\n * Runs `fn` under a signal, handing it the signal so it can cancel the underlying work for real, and\n * rejecting with an {@link AbortError} if the signal fires first.\n *\n * The preferred entry point over {@link abortable}: `fn` is never invoked at all when the signal is\n * already aborted, so no work starts that is known to be unwanted. A synchronous throw from `fn` surfaces\n * as a rejection, never as a synchronous throw at the call site.\n */\nexport function withAbort<T>(signal: AbortSignal, fn: (signal: AbortSignal) => PromiseLike<T> | T): Promise<T> {\n  if (signal.aborted) return Promise.reject(abortErrorFor(signal));\n\n  let started: PromiseLike<T> | T;\n  try {\n    started = fn(signal);\n  } catch (error) {\n    return Promise.reject(error);\n  }\n  return abortable(Promise.resolve(started), signal);\n}\n","// The deadline primitive `foundation/resilience` does not have. That slice models RETRIES over HTTP statuses\n// (`shouldRetry(policy, count, status)` · `computeRetryDelay`) and deliberately owns no timeout, so every\n// caller needing \"fail if this takes longer than N ms\" had to hand-roll one — `foundation/workers`'\n// `WorkerClient` did exactly that for its per-call deadline. This is the shared implementation; retry and\n// timeout stay orthogonal, and a caller wanting both composes them (`retryAsync` around `withTimeout`).\n//\n// THE TIMER MUST DIE ON EVERY EXIT PATH, which is the entire reason this is a shared primitive rather than\n// four lines inlined per call site. A pending `setTimeout` is a live handle: in node it keeps the event loop\n// alive (a CLI that finished its work hangs until the longest deadline elapses), and in a browser it pins\n// every closure it captures — the promise, its result, whatever the callback closes over — for the full\n// duration. A fast-resolving call under a 30s deadline therefore leaks for 30s unless the timer is cleared,\n// and the leak scales with request volume. So `cleanup` runs on resolve, on reject, on abort, and on the\n// deadline itself; the test asserts `vi.getTimerCount() === 0` on both settle paths.\n//\n// Non-obvious decisions:\n// - A non-positive or non-finite `ms` means NO DEADLINE, matching `WorkerClient`'s reading, rather than\n//   \"expire immediately\". `withTimeout(p, config.timeoutMs ?? 0)` then degrades to a plain pass-through\n//   instead of failing every call, which is the safer wrong-config behaviour.\n// - `onTimeout` exists because rejecting the caller does NOT stop the underlying work (see `Abort.ts`).\n//   It is the hook where you abort the real operation — `onTimeout: () => controller.abort()`.\n// - A THROW FROM `onTimeout` IS SWALLOWED. It fires while the timeout rejection is being built; letting it\n//   escape would replace a precise `TimeoutError` with an unrelated failure from a cleanup hook, and the\n//   caller would never learn the deadline was the actual cause.\n\nimport { abortErrorFor, abortable } from './Abort';\n\n/**\n * The deadline error {@link withTimeout} rejects with. Named `TimeoutError` — the same name\n * `AbortSignal.timeout()` uses — so `isTimeoutError` from `foundation/errors` recognizes it.\n *\n * Prefer `isTimeoutError(caught)` over `caught instanceof TimeoutError`: a deadline from the platform is a\n * `DOMException`, not this class, and only the name-keyed recognizer catches both.\n */\nexport class TimeoutError extends Error {\n  /** Creates a deadline error. */\n  constructor(message = 'The operation timed out.', options?: ErrorOptions) {\n    super(message, options);\n    this.name = 'TimeoutError';\n  }\n}\n\n/** Configures a {@link withTimeout} call. Every member is optional. */\nexport interface WithTimeoutOptions {\n  /** Cancels the wait early, rejecting with an `AbortError`. Honoured synchronously when already aborted. */\n  readonly signal?: AbortSignal;\n\n  /**\n   * Fires when the deadline lapses, before the rejection — the seam for stopping the underlying work,\n   * which the timeout itself cannot do (`onTimeout: () => controller.abort()`). A throw here is swallowed\n   * so it cannot mask the {@link TimeoutError}.\n   */\n  readonly onTimeout?: () => void;\n\n  /** Overrides the rejection message. Defaults to `Operation timed out after {ms}ms`. */\n  readonly message?: string;\n}\n\n/**\n * Rejects with a {@link TimeoutError} if `promise` has not settled within `ms`, and clears its timer on\n * every exit path — resolve, reject, abort, and lapse alike.\n *\n * The promise keeps running after a timeout; use `options.onTimeout` to abort the work behind it. A\n * non-positive or non-finite `ms` applies no deadline.\n */\nexport function withTimeout<T>(promise: PromiseLike<T>, ms: number, options: WithTimeoutOptions = {}): Promise<T> {\n  const { signal, onTimeout, message } = options;\n\n  if (!Number.isFinite(ms) || ms <= 0) return abortable(promise, signal);\n  if (signal?.aborted === true) return Promise.reject(abortErrorFor(signal));\n\n  return new Promise<T>((resolve, reject) => {\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    let abortListener: (() => void) | undefined;\n\n    /** The single teardown every exit path runs: kill the timer, detach the listener, both idempotent. */\n    const cleanup = (): void => {\n      if (timer !== undefined) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n      if (signal !== undefined && abortListener !== undefined) {\n        signal.removeEventListener('abort', abortListener);\n        abortListener = undefined;\n      }\n    };\n\n    timer = setTimeout(() => {\n      // Already fired — blank the handle first so `cleanup` does not clear a dead timer.\n      timer = undefined;\n      cleanup();\n      try {\n        onTimeout?.();\n      } catch {\n        // Swallowed by contract: a failing cleanup hook must not replace the timeout as the reported cause.\n      }\n      reject(new TimeoutError(message ?? `Operation timed out after ${ms}ms`));\n    }, ms);\n\n    if (signal !== undefined) {\n      const listener = (): void => {\n        cleanup();\n        reject(abortErrorFor(signal));\n      };\n      abortListener = listener;\n      signal.addEventListener('abort', listener, { once: true });\n    }\n\n    promise.then(\n      (value) => {\n        cleanup();\n        resolve(value);\n      },\n      (error: unknown) => {\n        cleanup();\n        reject(error);\n      },\n    );\n  });\n}\n","// Bounded concurrency — run N tasks at once out of an unbounded submission stream. The gap this fills:\n// `Promise.all` starts EVERYTHING at once, which is fine for 5 items and a self-inflicted outage for 500\n// (browsers stall past ~6 connections per host, servers rate-limit, memory holds every in-flight payload).\n//\n// `foundation/uploads`' `UploadQueue` already implements this privately (its `controllers` map is the pool\n// and `pump` is the scheduler) — it predates this slice and is NOT edited from here. Whether it should\n// later delegate is noted in the barrel; nothing in this file assumes it will.\n//\n// ORDER IS GUARANTEED FOR START, NOT FOR COMPLETION, and the distinction is the whole contract. Tasks begin\n// in submission order — a FIFO queue drained one entry per freed slot — but a slow first task finishes after\n// a fast second one. Any caller that needs results in input order must key them by index rather than by\n// arrival, which is exactly what `mapLimit` does via `Promise.all`.\n//\n// Non-obvious decisions:\n// - `active` is incremented SYNCHRONOUSLY inside `start`, before `fn` is called, so the counter can never\n//   lag behind reality. Incrementing after an `await` would open a window where two tasks both observe a\n//   free slot and the cap is briefly exceeded — the bug a test that only checks final results never sees.\n// - `fn` is invoked inside an async IIFE, so a task that throws SYNCHRONOUSLY rejects its own promise\n//   instead of taking down the scheduler. Without it, one bad task leaks a permanently-held slot and the\n//   pool deadlocks at N-1, then N-2, until nothing runs.\n// - The slot is freed in `finally` and `drain` is called there, so the pump advances on failure exactly as\n//   it does on success.\n// - The queue is drained with `shift()`. O(n) per drain in principle; irrelevant against the cost of the\n//   async work being scheduled, and it keeps the pool a dozen readable lines.\n\n/** A bounded-concurrency scheduler — hand it tasks, it runs at most N at a time. */\nexport interface Limiter {\n  /**\n   * Schedules `fn`, resolving with its result once it has run. Tasks start in submission order as slots\n   * free; the returned promise settles on the task's own outcome, and a synchronous throw from `fn`\n   * surfaces as a rejection.\n   */\n  readonly run: <T>(fn: () => PromiseLike<T> | T) => Promise<T>;\n\n  /** How many tasks are running right now — never above the configured concurrency. */\n  readonly activeCount: () => number;\n\n  /** How many tasks are queued, waiting for a slot. */\n  readonly pendingCount: () => number;\n\n  /** The cap this limiter enforces, after clamping. */\n  readonly concurrency: number;\n}\n\n/**\n * Creates a {@link Limiter} that runs at most `concurrency` tasks at once.\n *\n * One limiter per resource is the intent — a limiter is a budget for a specific bottleneck (an API's rate\n * limit, the connection pool, CPU-bound decode work), so sharing one across unrelated work couples them.\n * `concurrency` is clamped to at least `1`; a fractional value is floored.\n */\nexport function pLimit(concurrency: number): Limiter {\n  const limit = Math.max(1, Math.floor(concurrency));\n  const queue: (() => void)[] = [];\n  let active = 0;\n\n  /** Starts the next queued task when a slot is free. Called once per completion, and once per submission. */\n  function drain(): void {\n    if (active >= limit) return;\n    const start = queue.shift();\n    if (start !== undefined) start();\n  }\n\n  function run<T>(fn: () => PromiseLike<T> | T): Promise<T> {\n    return new Promise<T>((resolve, reject) => {\n      const start = (): void => {\n        // Claimed before `fn` runs — see the header on why an async increment would breach the cap.\n        active += 1;\n        void (async (): Promise<void> => {\n          try {\n            resolve(await fn());\n          } catch (error) {\n            reject(error);\n          } finally {\n            active -= 1;\n            drain();\n          }\n        })();\n      };\n\n      if (active < limit) start();\n      else queue.push(start);\n    });\n  }\n\n  return {\n    run,\n    activeCount: () => active,\n    pendingCount: () => queue.length,\n    concurrency: limit,\n  };\n}\n\n/**\n * Maps `items` through `fn` with at most `concurrency` calls in flight, resolving to the results **in input\n * order** regardless of which finished first.\n *\n * The bounded `Promise.all`, INCLUDING its failure semantics: the returned promise rejects at the first\n * failure, but every remaining task still runs. They were all submitted up front, and the limiter's queue\n * has no knowledge of the rejection — so a failure reports early without cancelling the batch behind it.\n *\n * That is the right default for a `Promise.all` shape, and the wrong one when a later task depends on an\n * earlier one: use `sequential`, which genuinely stops. Pass a `signal` down through `fn` when the\n * remaining work must actually be cancellable, or reach for `allSettledValues` when partial success is fine.\n */\nexport function mapLimit<TItem, TResult>(\n  items: Iterable<TItem>,\n  concurrency: number,\n  fn: (item: TItem, index: number) => PromiseLike<TResult> | TResult,\n): Promise<TResult[]> {\n  const list = [...items];\n  const limiter = pLimit(concurrency);\n  // `Promise.all` preserves positional order, so the result array matches `list` even though completion\n  // order does not — this is why the limiter's start-order guarantee is enough.\n  return Promise.all(list.map((item, index) => limiter.run(() => fn(item, index))));\n}\n","// Retry for any async function — the generic sibling of the retry loop `UploadQueue` runs over its\n// transport.\n//\n// NO BACKOFF MATH LIVES HERE, BY RULE. `shouldRetry` decides whether to go again and `computeRetryDelay`\n// sizes the wait, both from `foundation/resilience` — the same primitives `foundation/http`'s client,\n// `/query`, and `uploads` already use. So a retried call in this slice backs off IDENTICALLY to every other\n// retry in the app, and tuning the policy in one place moves all of them. Re-deriving exponential-with-\n// jitter here would be a second, silently diverging implementation of the one thing the resilience slice\n// exists to own. The only timing code below is a plain abortable `setTimeout` that waits the delay it is\n// HANDED; it never computes one.\n//\n// `shouldRetry` IS STATUS-DRIVEN, so a caught failure is read for a numeric `status` — structurally, so an\n// `ApiError` from `foundation/http`, an `UploadHttpError`, and a hand-rolled `{ status: 503 }` all\n// interoperate without this slice depending on the HTTP layer. No status ⇒ `0` ⇒ transient under the\n// default policy, which is the right default for the generic case: a `TypeError` from a dropped connection\n// retries, a deliberate `400` does not.\n//\n// A CANCELLED CALL IS NEVER RETRIED. `isAbortError` short-circuits before the retry decision, plus a direct\n// `signal.aborted` check for work that rejects with something else after an abort. Retrying through a\n// cancel would make every cancel button a lie — the user's intent outranks the policy.\n//\n// Non-obvious decisions:\n// - THE BACKOFF WAIT IS ABORTABLE. A 30s cap with a non-abortable sleep means a cancel is ignored for up to\n//   30s; the wait resolves early on abort and the loop re-checks `signal.aborted` immediately after.\n// - The rethrow goes through `toError`, which passes a real `Error` through BY IDENTITY (an `ApiError` stays\n//   an `ApiError`, subclass intact) and only normalizes a non-`Error` throw. The caller is therefore\n//   guaranteed an `Error` in `catch` without losing what was actually thrown.\n// - `fn` receives the 1-based attempt number — enough for logging or an attempt-tagged idempotency key\n//   without the caller keeping a counter alongside.\n\nimport { isAbortError, toError } from '../errors';\nimport { DefaultRetryPolicy, computeRetryDelay, shouldRetry, type RetryPolicy } from '../resilience';\n\nimport { abortErrorFor } from './Abort';\n\n/**\n * Reads the HTTP status a caught failure carries, for `shouldRetry`. Returns `0` — the \"network / unknown\"\n * status the default policy treats as transient — when the value has no numeric `status`. Guarded, so a\n * throwing getter reads as absent rather than failing inside a `catch` block.\n */\nfunction readErrorStatus(error: unknown): number {\n  if (typeof error !== 'object' || error === null) return 0;\n  try {\n    const status: unknown = (error as { status?: unknown }).status;\n    return typeof status === 'number' && Number.isFinite(status) ? status : 0;\n  } catch {\n    return 0;\n  }\n}\n\n/**\n * Reads `signal.aborted` freshly.\n *\n * Not inlined, and not merely a style choice: `signal.aborted` is a mutable flag that flips at any moment,\n * but TypeScript's control-flow analysis treats it like a stable property. After one `if (signal?.aborted)`\n * check the type narrows to `false` for the rest of the function, and every later check — the ones AFTER an\n * `await`, which are the whole point — becomes a compile error for comparing non-overlapping types. Routing\n * each read through a call re-widens it, because a function's return cannot be narrowed by an earlier one.\n */\nfunction isAborted(signal: AbortSignal | undefined): boolean {\n  return signal?.aborted === true;\n}\n\n/**\n * Waits `ms`, resolving early — never rejecting — if `signal` aborts. The caller re-checks `signal.aborted`\n * afterwards. Clears its timer and detaches its listener on both paths.\n */\nfunction sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise<void>((resolve) => {\n    if (ms <= 0 || isAborted(signal)) {\n      resolve();\n      return;\n    }\n\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    const finish = (): void => {\n      if (timer !== undefined) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n      signal?.removeEventListener('abort', finish);\n      resolve();\n    };\n\n    timer = setTimeout(finish, ms);\n    signal?.addEventListener('abort', finish, { once: true });\n  });\n}\n\n/** Configures a {@link retryAsync} call. */\nexport interface RetryAsyncOptions {\n  /** The policy driving the decision and the delays. Defaults to `DefaultRetryPolicy` from `foundation/resilience`. */\n  readonly policy?: RetryPolicy;\n\n  /** Cancels the retry loop, including mid-backoff. Rejects with an `AbortError`; an in-flight attempt is not recalled. */\n  readonly signal?: AbortSignal;\n}\n\n/**\n * Runs `fn`, retrying transient failures per the policy — attempts, backoff, and jitter all decided by\n * `foundation/resilience`.\n *\n * `fn` gets the 1-based attempt number. An `AbortError` is never retried, and neither is a failure whose\n * `status` the policy considers non-transient. Rejects with the last failure once retries are exhausted.\n *\n * `fn` must be idempotent-safe to call again — this is the caller's judgement, not something the helper can\n * check. Wrap `fn` in `withTimeout` when a hung attempt should also count as a failure; the two compose in\n * that order so each attempt gets its own deadline.\n */\nexport async function retryAsync<T>(\n  fn: (attempt: number) => PromiseLike<T> | T,\n  options: RetryAsyncOptions = {},\n): Promise<T> {\n  const policy = options.policy ?? DefaultRetryPolicy;\n  const signal = options.signal;\n\n  /** Failures so far — `shouldRetry`'s `failureCount`, and one less than the next attempt's number. */\n  let failures = 0;\n  /** The previous delay, which decorrelated jitter needs to walk forward. */\n  let previousDelayMs = 0;\n\n  for (;;) {\n    if (signal !== undefined && isAborted(signal)) throw abortErrorFor(signal);\n\n    try {\n      return await fn(failures + 1);\n    } catch (caught) {\n      // Cancellation outranks the policy, in both shapes: the call rejected with an abort, or the signal\n      // fired and the call rejected with something else entirely.\n      if (isAbortError(caught)) throw toError(caught);\n      if (signal !== undefined && isAborted(signal)) throw abortErrorFor(signal);\n\n      const status = readErrorStatus(caught);\n      if (!shouldRetry(policy, failures, status)) throw toError(caught);\n\n      const attempt = failures + 1;\n      const delayMs = computeRetryDelay(policy, attempt, previousDelayMs);\n      policy.onRetry?.({ attempt, error: caught, status, delayMs });\n\n      await sleep(delayMs, signal);\n      if (signal !== undefined && isAborted(signal)) throw abortErrorFor(signal);\n\n      previousDelayMs = delayMs;\n      failures = attempt;\n    }\n  }\n}\n","// Rate shaping for async functions — collapse a burst into one call (`debounceAsync`), or cap a hot path to\n// one call per window (`throttleAsync`). Search-as-you-type, autosave-on-keystroke, save-on-scroll.\n//\n// THE SUBTLE PART, AND THE REASON THESE ARE NOT THE USUAL DEBOUNCE WRAPPED IN A PROMISE: a debounced async\n// call must decide what to tell the callers it SUPERSEDES. Typing \"abc\" produces three calls and one\n// invocation, so two promises are left over. The naive implementation — keep the latest deferred, drop the\n// rest — leaves those two promises PERMANENTLY UNSETTLED. That is a silent leak with no error and no log:\n// every `await` on them is parked forever, holding its whole continuation (component state, closures,\n// request payloads) alive for the life of the page, and `try/finally` cleanup around such an await never\n// runs. In a UI it reads as a spinner that never stops on a request nobody can point to.\n//\n// So EVERY superseded caller resolves with the LATEST invocation's result. Semantically honest — a debounce\n// promises \"the answer as of when you stopped typing\", and all three callers asked the same question, so\n// they get the same answer — and it makes the promise leak structurally impossible: the waiter list is\n// drained on every exit path. If a caller must distinguish its own invocation from a shared one, debounce\n// is the wrong primitive; use the raw call plus an abort signal.\n//\n// Non-obvious decisions:\n// - Both wrappers expose `cancel()`, which is what makes them safe to unmount. It clears the pending timer\n//   and REJECTS parked waiters with an `AbortError` rather than leaving them hanging — the same leak in a\n//   different disguise. `isAbortError` recognizes it, so an effect's cleanup path swallows it normally.\n// - `debounceAsync` is TRAILING-EDGE and `throttleAsync` is LEADING-EDGE, which is the useful pairing rather\n//   than a symmetry oversight: debounce answers \"the user stopped, act on the final state\", throttle answers\n//   \"act now, then ignore the flood\".\n// - A rejection from `fn` fans out to every waiter it represented. They were all answered by that one call,\n//   so they all learn it failed.\n// - `throttleAsync` shares the in-flight promise for the whole window, so suppressed callers get the leading\n//   call's result rather than `undefined` — no caller has to handle a \"was skipped\" case that would\n//   otherwise infect its return type.\n\nimport { AbortError } from './Abort';\nimport { deferred, type Deferred } from './Deferred';\n\n/** A trailing-edge debounced async function, plus the cancel that makes it unmount-safe. */\nexport interface DebouncedAsync<TArgs extends unknown[], TResult> {\n  /** Schedules an invocation `ms` from now, replacing any pending one. Resolves with the latest invocation's result. */\n  (...args: TArgs): Promise<TResult>;\n\n  /** Drops the pending invocation and rejects parked callers with an `AbortError`. Safe to call when idle. */\n  readonly cancel: () => void;\n}\n\n/** A leading-edge throttled async function, plus the cancel that makes it unmount-safe. */\nexport interface ThrottledAsync<TArgs extends unknown[], TResult> {\n  /** Invokes immediately when the window is open; otherwise returns the in-flight window's promise. */\n  (...args: TArgs): Promise<TResult>;\n\n  /** Closes the current window early and clears its timer. Safe to call when idle. */\n  readonly cancel: () => void;\n}\n\n/**\n * Debounces an async function on the trailing edge: a burst of calls collapses into ONE invocation, `ms`\n * after the last call, using the last call's arguments.\n *\n * Every caller in the burst — superseded ones included — resolves with that single invocation's result, so\n * no promise is ever left unsettled (see the header; this is the whole point). A rejection likewise fans\n * out to all of them. Call `cancel()` on unmount.\n */\nexport function debounceAsync<TArgs extends unknown[], TResult>(\n  fn: (...args: TArgs) => PromiseLike<TResult> | TResult,\n  ms: number,\n): DebouncedAsync<TArgs, TResult> {\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  let waiters: Deferred<TResult>[] = [];\n  let nextCall: { readonly args: TArgs } | undefined;\n\n  /** Fires the trailing invocation and answers every caller parked behind it. */\n  const invoke = (): void => {\n    timer = undefined;\n    const call = nextCall;\n    const parked = waiters;\n    // Reset BEFORE awaiting: calls arriving while `fn` is in flight belong to the next window, and must not\n    // be answered by this invocation's result.\n    nextCall = undefined;\n    waiters = [];\n    if (call === undefined) return;\n\n    void (async (): Promise<void> => {\n      try {\n        const result = await fn(...call.args);\n        for (const waiter of parked) waiter.resolve(result);\n      } catch (error) {\n        for (const waiter of parked) waiter.reject(error);\n      }\n    })();\n  };\n\n  const debounced = (...args: TArgs): Promise<TResult> => {\n    nextCall = { args };\n    const waiter = deferred<TResult>();\n    waiters.push(waiter);\n\n    if (timer !== undefined) clearTimeout(timer);\n    timer = setTimeout(invoke, ms);\n    return waiter.promise;\n  };\n\n  return Object.assign(debounced, {\n    cancel: (): void => {\n      if (timer !== undefined) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n      const parked = waiters;\n      waiters = [];\n      nextCall = undefined;\n      for (const waiter of parked) waiter.reject(new AbortError('Debounced call cancelled.'));\n    },\n  });\n}\n\n/**\n * Throttles an async function on the leading edge: the first call runs immediately, and every call within\n * the next `ms` is suppressed — receiving the leading call's promise rather than triggering its own.\n *\n * The window opens again `ms` after the leading call, whether or not it has settled. Call `cancel()` on\n * unmount to clear the window timer.\n */\nexport function throttleAsync<TArgs extends unknown[], TResult>(\n  fn: (...args: TArgs) => PromiseLike<TResult> | TResult,\n  ms: number,\n): ThrottledAsync<TArgs, TResult> {\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  let inFlight: Promise<TResult> | undefined;\n\n  const throttled = (...args: TArgs): Promise<TResult> => {\n    if (inFlight !== undefined) return inFlight;\n\n    // The async IIFE normalizes a synchronous throw from `fn` into a rejection, so a suppressed caller and\n    // the leading caller always receive the same shape.\n    const started = (async (): Promise<TResult> => fn(...args))();\n    inFlight = started;\n\n    timer = setTimeout(() => {\n      timer = undefined;\n      inFlight = undefined;\n    }, ms);\n\n    return started;\n  };\n\n  return Object.assign(throttled, {\n    cancel: (): void => {\n      if (timer !== undefined) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n      inFlight = undefined;\n    },\n  });\n}\n","// Two combinators, and only two — the set is deliberately tight because the platform already ships\n// `Promise.all` / `race` / `any` / `allSettled`, and a slice that re-wraps them earns nothing while making\n// consumers learn a second vocabulary for the same operations. Each one here justifies itself by removing a\n// specific piece of boilerplate that the platform makes every caller write:\n//\n// - `sequential(tasks)` — `Promise.all` starts everything at once, and there is NO platform combinator for\n//   \"one at a time, in order\". Hand-rolled it is a `for...of` with an accumulator and an `await` in the loop\n//   that lint rules flag; and the obvious clever versions (`reduce` over a promise chain) are hard to read\n//   and easy to get wrong. Needed whenever tasks are order-dependent — sequential migrations, an animation\n//   queue, a rate-limited endpoint that tolerates exactly one call at a time.\n//\n// - `allSettledValues(promises)` — `Promise.allSettled` hands back a DISCRIMINATED UNION array, so every\n//   caller writing \"give me whatever succeeded, drop the rest\" repeats the same filter-then-map on\n//   `status === 'fulfilled'`, and repeats the type narrowing that goes with it. This is that line, once.\n//\n// `sequential` IS NOT `mapLimit(tasks, 1, …)`, which is the obvious implementation and the wrong one. A\n// limiter of one gives ORDERING; it does not give SHORT-CIRCUITING. `mapLimit` submits every task up front,\n// so a failure at step 2 rejects the returned promise while the scheduler happily runs steps 3..n — its\n// queue knows nothing about the rejection. For the cases `sequential` exists to serve that is not a nuance\n// but a hazard: run migration 3 after migration 2 failed and the damage is real. So the loop below awaits\n// each task and stops at the first throw, and the delegation is deliberately NOT made. (`mapLimit` keeps\n// `Promise.all` semantics on purpose — a bounded `Promise.all` should behave like one — which is exactly\n// why the two cannot share an implementation.)\n\n/**\n * Runs `tasks` one at a time, in order, resolving to their results in that same order.\n *\n * STOPS AT THE FIRST FAILURE: the rejecting task's error propagates and no later task is started, because a\n * task in a sequence generally assumes its predecessor succeeded. Use `mapLimit(tasks, 1, …)` instead when\n * every task must run regardless of the others' outcomes.\n */\nexport async function sequential<T>(tasks: Iterable<() => PromiseLike<T> | T>): Promise<T[]> {\n  const results: T[] = [];\n  // Serial by construction — the `await` inside the loop IS the feature, not an oversight.\n  for (const task of tasks) results.push(await task());\n  return results;\n}\n\n/**\n * Awaits every promise and resolves to the values of the ones that fulfilled, in input order, silently\n * dropping the rejections.\n *\n * Never rejects — the \"best effort, partial results are fine\" counterpart to `Promise.all`: warming a\n * cache, hydrating optional widgets, fanning out to mirrors. Note that failures are DISCARDED, not\n * reported; use `Promise.allSettled` directly when a caller needs to know what broke.\n */\nexport async function allSettledValues<T>(promises: Iterable<PromiseLike<T>>): Promise<T[]> {\n  const results = await Promise.allSettled([...promises]);\n  // `flatMap` over the union narrows without a type predicate, which `filter` would need.\n  return results.flatMap((result) => (result.status === 'fulfilled' ? [result.value] : []));\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sources":["../../../src/foundation/async/Deferred.ts","../../../src/foundation/async/Abort.ts","../../../src/foundation/async/Timeout.ts","../../../src/foundation/async/Limit.ts","../../../src/foundation/async/Retry.ts","../../../src/foundation/async/Rate.ts","../../../src/foundation/async/Combinators.ts"],"sourcesContent":["// The externally-settled promise — a promise plus the `resolve` / `reject` that close over it, handed back\n// to the caller instead of trapped inside an executor. Every other helper in this slice needs it: `pLimit`\n// hands a queued task's settlers to a scheduler that runs later, and `debounceAsync` parks N callers'\n// settlers until one trailing invocation resolves them all.\n//\n// Why hand-rolled rather than `Promise.withResolvers()`: that landed in ES2024, and this package targets\n// ES2022 with a browser support floor below it. The shape is deliberately identical, so this file becomes\n// a one-line delegation the day the floor moves.\n//\n// Non-obvious decision: the executor runs SYNCHRONOUSLY inside the `Promise` constructor, so `resolve` and\n// `reject` are always assigned before the constructor returns. TypeScript cannot see that through the\n// closure, hence the `!` assertions — the alternative (`| undefined` fields plus a guard on every call\n// site) would push a lie about the runtime into every consumer.\n\n/** A promise whose settlement is controlled from outside its executor. */\nexport interface Deferred<T> {\n  /** The promise handed to waiters. Settles when {@link resolve} or {@link reject} is called. */\n  readonly promise: Promise<T>;\n\n  /** Fulfils {@link promise}. A second call (after either settler) is a no-op, per promise semantics. */\n  readonly resolve: (value: T | PromiseLike<T>) => void;\n\n  /** Rejects {@link promise}. A second call (after either settler) is a no-op, per promise semantics. */\n  readonly reject: (reason?: unknown) => void;\n}\n\n/**\n * Creates a {@link Deferred} — a promise you settle later, from anywhere.\n *\n * Reach for it when the code that settles is not the code that creates: a scheduler that starts a task\n * once a slot frees, an event listener that resolves on the next message, a debounce that answers many\n * callers from one invocation. When the work is already a promise, wrap it directly — a deferred adds a\n * layer that can be forgotten unsettled.\n */\nexport function deferred<T>(): Deferred<T> {\n  let resolve!: (value: T | PromiseLike<T>) => void;\n  let reject!: (reason?: unknown) => void;\n\n  const promise = new Promise<T>((promiseResolve, promiseReject) => {\n    resolve = promiseResolve;\n    reject = promiseReject;\n  });\n\n  return { promise, resolve, reject };\n}\n","// Cancellation seam — turns an `AbortSignal` into a promise rejection, for the vast majority of async work\n// that has no native `signal` parameter of its own (only `fetch` and a handful of platform APIs do).\n//\n// THE ALREADY-ABORTED CASE IS THE ONE EVERYONE FORGETS. A signal handed in already aborted fires no `abort`\n// event — the event has been and gone. Code that only calls `addEventListener` therefore waits forever on a\n// signal that is *already* cancelled, which is the worst possible reading of \"cancelled\". Both helpers here\n// check `signal.aborted` FIRST, before any listener is attached, and `withAbort` never even invokes `fn`.\n//\n// ABORTING DETACHES THE CALLER; IT DOES NOT CANCEL THE WORK. Nothing here can stop an already-running\n// promise — that power does not exist in the promise model. The underlying operation runs to completion and\n// its result is discarded. Pass the signal INTO the operation (`withAbort` hands it to `fn` for exactly\n// this) whenever the operation can honour one; otherwise accept that an aborted `abortable` leaves work\n// running in the background.\n//\n// WE ALWAYS REJECT WITH OUR OWN `AbortError`, NEVER WITH `signal.reason`, which is a deliberate deviation\n// from `signal.throwIfAborted()`. `abort(reason)` accepts ANY value, so forwarding it would let an abort\n// arrive as, say, a plain `Error` that `isAbortError` does not recognize — and an unrecognized abort is a\n// live bug: `retryAsync` would retry a cancelled call, and `UploadQueue` would mark a cancel as a failure.\n// The invariant that every consumer keys on (`isAbortError(caught) === true` for every cancellation) is\n// worth more than reason pass-through, so the reason is preserved on `cause` instead of in the identity.\n//\n// LISTENER DISCIPLINE: every listener is `{ once: true }` (self-removing when it fires) AND explicitly\n// removed on both settle paths. A signal outlives the call it cancels — one long-lived signal driving\n// hundreds of short calls would otherwise accumulate a listener per call and leak every closure it holds.\n\n/**\n * The cancellation error every helper in this slice rejects with. Named `AbortError` so `isAbortError`\n * from `foundation/errors` recognizes it.\n *\n * Prefer `isAbortError(caught)` over `caught instanceof AbortError`: a cancellation that originates in\n * `fetch` is a `DOMException`, not this class, and only the name-keyed recognizer catches both.\n */\nexport class AbortError extends Error {\n  /** Creates a cancellation error; pass `cause` to preserve the signal's abort reason. */\n  constructor(message = 'The operation was aborted.', options?: ErrorOptions) {\n    super(message, options);\n    this.name = 'AbortError';\n  }\n}\n\n/**\n * Builds the {@link AbortError} for a fired signal, preserving `signal.reason` as `cause`. Internal to the\n * slice; not barrelled — consumers construct {@link AbortError} directly.\n */\nexport function abortErrorFor(signal: AbortSignal): AbortError {\n  const reason: unknown = signal.reason;\n  return reason === undefined ? new AbortError() : new AbortError(undefined, { cause: reason });\n}\n\n/**\n * Races a promise against a signal, rejecting with an {@link AbortError} the moment the signal fires.\n *\n * An already-aborted signal rejects without attaching a listener. The abort listener is removed on every\n * exit path. Remember the header's warning: `promise` keeps running after an abort — its eventual result\n * is dropped.\n */\nexport function abortable<T>(promise: PromiseLike<T>, signal?: AbortSignal): Promise<T> {\n  if (signal === undefined) return Promise.resolve(promise);\n  if (signal.aborted) {\n    void Promise.resolve(promise).catch(() => undefined);\n    return Promise.reject(abortErrorFor(signal));\n  }\n\n  return new Promise<T>((resolve, reject) => {\n    const onAbort = (): void => {\n      reject(abortErrorFor(signal));\n    };\n    signal.addEventListener('abort', onAbort, { once: true });\n\n    // Both handlers detach the listener before settling. Redundant with `once` on the abort path, and\n    // load-bearing on every other path: a promise that resolves normally must not leave a listener behind.\n    void Promise.resolve(promise).then(\n      (value) => {\n        signal.removeEventListener('abort', onAbort);\n        resolve(value);\n      },\n      (error: unknown) => {\n        signal.removeEventListener('abort', onAbort);\n        reject(error);\n      },\n    );\n  });\n}\n\n/**\n * Runs `fn` under a signal, handing it the signal so it can cancel the underlying work for real, and\n * rejecting with an {@link AbortError} if the signal fires first.\n *\n * The preferred entry point over {@link abortable}: `fn` is never invoked at all when the signal is\n * already aborted, so no work starts that is known to be unwanted. A synchronous throw from `fn` surfaces\n * as a rejection, never as a synchronous throw at the call site.\n */\nexport function withAbort<T>(signal: AbortSignal, fn: (signal: AbortSignal) => PromiseLike<T> | T): Promise<T> {\n  if (signal.aborted) return Promise.reject(abortErrorFor(signal));\n\n  let started: PromiseLike<T> | T;\n  try {\n    started = fn(signal);\n  } catch (error) {\n    return Promise.reject(error);\n  }\n  return abortable(Promise.resolve(started), signal);\n}\n","// The deadline primitive `foundation/resilience` does not have. That slice models RETRIES over HTTP statuses\n// (`shouldRetry(policy, count, status)` · `computeRetryDelay`) and deliberately owns no timeout, so every\n// caller needing \"fail if this takes longer than N ms\" had to hand-roll one — `foundation/workers`'\n// `WorkerClient` did exactly that for its per-call deadline. This is the shared implementation; retry and\n// timeout stay orthogonal, and a caller wanting both composes them (`retryAsync` around `withTimeout`).\n//\n// THE TIMER MUST DIE ON EVERY EXIT PATH, which is the entire reason this is a shared primitive rather than\n// four lines inlined per call site. A pending `setTimeout` is a live handle: in node it keeps the event loop\n// alive (a CLI that finished its work hangs until the longest deadline elapses), and in a browser it pins\n// every closure it captures — the promise, its result, whatever the callback closes over — for the full\n// duration. A fast-resolving call under a 30s deadline therefore leaks for 30s unless the timer is cleared,\n// and the leak scales with request volume. So `cleanup` runs on resolve, on reject, on abort, and on the\n// deadline itself; the test asserts `vi.getTimerCount() === 0` on both settle paths.\n//\n// Non-obvious decisions:\n// - A non-positive or non-finite `ms` means NO DEADLINE, matching `WorkerClient`'s reading, rather than\n//   \"expire immediately\". `withTimeout(p, config.timeoutMs ?? 0)` then degrades to a plain pass-through\n//   instead of failing every call, which is the safer wrong-config behaviour.\n// - `onTimeout` exists because rejecting the caller does NOT stop the underlying work (see `Abort.ts`).\n//   It is the hook where you abort the real operation — `onTimeout: () => controller.abort()`.\n// - A THROW FROM `onTimeout` IS SWALLOWED. It fires while the timeout rejection is being built; letting it\n//   escape would replace a precise `TimeoutError` with an unrelated failure from a cleanup hook, and the\n//   caller would never learn the deadline was the actual cause.\n\nimport { abortErrorFor, abortable } from './Abort';\n\n/**\n * The deadline error {@link withTimeout} rejects with. Named `TimeoutError` — the same name\n * `AbortSignal.timeout()` uses — so `isTimeoutError` from `foundation/errors` recognizes it.\n *\n * Prefer `isTimeoutError(caught)` over `caught instanceof TimeoutError`: a deadline from the platform is a\n * `DOMException`, not this class, and only the name-keyed recognizer catches both.\n */\nexport class TimeoutError extends Error {\n  /** Creates a deadline error. */\n  constructor(message = 'The operation timed out.', options?: ErrorOptions) {\n    super(message, options);\n    this.name = 'TimeoutError';\n  }\n}\n\n/** Configures a {@link withTimeout} call. Every member is optional. */\nexport interface WithTimeoutOptions {\n  /** Cancels the wait early, rejecting with an `AbortError`. Honoured synchronously when already aborted. */\n  readonly signal?: AbortSignal;\n\n  /**\n   * Fires when the deadline lapses, before the rejection — the seam for stopping the underlying work,\n   * which the timeout itself cannot do (`onTimeout: () => controller.abort()`). A throw here is swallowed\n   * so it cannot mask the {@link TimeoutError}.\n   */\n  readonly onTimeout?: () => void;\n\n  /** Overrides the rejection message. Defaults to `Operation timed out after {ms}ms`. */\n  readonly message?: string;\n}\n\n/**\n * Rejects with a {@link TimeoutError} if `promise` has not settled within `ms`, and clears its timer on\n * every exit path — resolve, reject, abort, and lapse alike.\n *\n * The promise keeps running after a timeout; use `options.onTimeout` to abort the work behind it. A\n * non-positive or non-finite `ms` applies no deadline.\n */\nexport function withTimeout<T>(promise: PromiseLike<T>, ms: number, options: WithTimeoutOptions = {}): Promise<T> {\n  const { signal, onTimeout, message } = options;\n\n  if (!Number.isFinite(ms) || ms <= 0) return abortable(promise, signal);\n  if (signal?.aborted === true) return abortable(promise, signal);\n\n  return new Promise<T>((resolve, reject) => {\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    let abortListener: (() => void) | undefined;\n\n    /** The single teardown every exit path runs: kill the timer, detach the listener, both idempotent. */\n    const cleanup = (): void => {\n      if (timer !== undefined) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n      if (signal !== undefined && abortListener !== undefined) {\n        signal.removeEventListener('abort', abortListener);\n        abortListener = undefined;\n      }\n    };\n\n    timer = setTimeout(() => {\n      // Already fired — blank the handle first so `cleanup` does not clear a dead timer.\n      timer = undefined;\n      cleanup();\n      try {\n        onTimeout?.();\n      } catch {\n        // Swallowed by contract: a failing cleanup hook must not replace the timeout as the reported cause.\n      }\n      reject(new TimeoutError(message ?? `Operation timed out after ${ms}ms`));\n    }, ms);\n\n    if (signal !== undefined) {\n      const listener = (): void => {\n        cleanup();\n        reject(abortErrorFor(signal));\n      };\n      abortListener = listener;\n      signal.addEventListener('abort', listener, { once: true });\n    }\n\n    void Promise.resolve(promise).then(\n      (value) => {\n        cleanup();\n        resolve(value);\n      },\n      (error: unknown) => {\n        cleanup();\n        reject(error);\n      },\n    );\n  });\n}\n","// Bounded concurrency — run N tasks at once out of an unbounded submission stream. The gap this fills:\n// `Promise.all` starts EVERYTHING at once, which is fine for 5 items and a self-inflicted outage for 500\n// (browsers stall past ~6 connections per host, servers rate-limit, memory holds every in-flight payload).\n//\n// `foundation/uploads`' `UploadQueue` already implements this privately (its `controllers` map is the pool\n// and `pump` is the scheduler) — it predates this slice and is NOT edited from here. Whether it should\n// later delegate is noted in the barrel; nothing in this file assumes it will.\n//\n// ORDER IS GUARANTEED FOR START, NOT FOR COMPLETION, and the distinction is the whole contract. Tasks begin\n// in submission order — a FIFO queue drained one entry per freed slot — but a slow first task finishes after\n// a fast second one. Any caller that needs results in input order must key them by index rather than by\n// arrival, which is exactly what `mapLimit` does via `Promise.all`.\n//\n// Non-obvious decisions:\n// - `active` is incremented SYNCHRONOUSLY inside `start`, before `fn` is called, so the counter can never\n//   lag behind reality. Incrementing after an `await` would open a window where two tasks both observe a\n//   free slot and the cap is briefly exceeded — the bug a test that only checks final results never sees.\n// - `fn` is invoked inside an async IIFE, so a task that throws SYNCHRONOUSLY rejects its own promise\n//   instead of taking down the scheduler. Without it, one bad task leaks a permanently-held slot and the\n//   pool deadlocks at N-1, then N-2, until nothing runs.\n// - The slot is freed in `finally` and `drain` is called there, so the pump advances on failure exactly as\n//   it does on success.\n// - The queue is drained with `shift()`. O(n) per drain in principle; irrelevant against the cost of the\n//   async work being scheduled, and it keeps the pool a dozen readable lines.\n\n/** A bounded-concurrency scheduler — hand it tasks, it runs at most N at a time. */\nexport interface Limiter {\n  /**\n   * Schedules `fn`, resolving with its result once it has run. Tasks start in submission order as slots\n   * free; the returned promise settles on the task's own outcome, and a synchronous throw from `fn`\n   * surfaces as a rejection.\n   */\n  readonly run: <T>(fn: () => PromiseLike<T> | T) => Promise<T>;\n\n  /** How many tasks are running right now — never above the configured concurrency. */\n  readonly activeCount: () => number;\n\n  /** How many tasks are queued, waiting for a slot. */\n  readonly pendingCount: () => number;\n\n  /** The cap this limiter enforces, after clamping. */\n  readonly concurrency: number;\n}\n\n/**\n * Creates a {@link Limiter} that runs at most `concurrency` tasks at once.\n *\n * One limiter per resource is the intent — a limiter is a budget for a specific bottleneck (an API's rate\n * limit, the connection pool, CPU-bound decode work), so sharing one across unrelated work couples them.\n * `concurrency` is clamped to at least `1`; a fractional value is floored.\n */\nexport function pLimit(concurrency: number): Limiter {\n  if (Number.isNaN(concurrency)) throw new RangeError('Concurrency must be a number.');\n  const limit = Math.max(1, Math.floor(concurrency));\n  const queue: (() => void)[] = [];\n  let active = 0;\n\n  /** Starts the next queued task when a slot is free. Called once per completion, and once per submission. */\n  function drain(): void {\n    if (active >= limit) return;\n    const start = queue.shift();\n    if (start !== undefined) start();\n  }\n\n  function run<T>(fn: () => PromiseLike<T> | T): Promise<T> {\n    return new Promise<T>((resolve, reject) => {\n      const start = (): void => {\n        // Claimed before `fn` runs — see the header on why an async increment would breach the cap.\n        active += 1;\n        void (async (): Promise<void> => {\n          try {\n            resolve(await fn());\n          } catch (error) {\n            reject(error);\n          } finally {\n            active -= 1;\n            drain();\n          }\n        })();\n      };\n\n      if (active < limit) start();\n      else queue.push(start);\n    });\n  }\n\n  return {\n    run,\n    activeCount: () => active,\n    pendingCount: () => queue.length,\n    concurrency: limit,\n  };\n}\n\n/**\n * Maps `items` through `fn` with at most `concurrency` calls in flight, resolving to the results **in input\n * order** regardless of which finished first.\n *\n * The bounded `Promise.all`, INCLUDING its failure semantics: the returned promise rejects at the first\n * failure, but every remaining task still runs. They were all submitted up front, and the limiter's queue\n * has no knowledge of the rejection — so a failure reports early without cancelling the batch behind it.\n *\n * That is the right default for a `Promise.all` shape, and the wrong one when a later task depends on an\n * earlier one: use `sequential`, which genuinely stops. Pass a `signal` down through `fn` when the\n * remaining work must actually be cancellable, or reach for `allSettledValues` when partial success is fine.\n */\nexport function mapLimit<TItem, TResult>(\n  items: Iterable<TItem>,\n  concurrency: number,\n  fn: (item: TItem, index: number) => PromiseLike<TResult> | TResult,\n): Promise<TResult[]> {\n  const list = [...items];\n  const limiter = pLimit(concurrency);\n  // `Promise.all` preserves positional order, so the result array matches `list` even though completion\n  // order does not — this is why the limiter's start-order guarantee is enough.\n  return Promise.all(list.map((item, index) => limiter.run(() => fn(item, index))));\n}\n","// Retry for any async function — the generic sibling of the retry loop `UploadQueue` runs over its\n// transport.\n//\n// NO BACKOFF MATH LIVES HERE, BY RULE. `shouldRetry` decides whether to go again and `computeRetryDelay`\n// sizes the wait, both from `foundation/resilience` — the same primitives `foundation/http`'s client,\n// `/query`, and `uploads` already use. So a retried call in this slice backs off IDENTICALLY to every other\n// retry in the app, and tuning the policy in one place moves all of them. Re-deriving exponential-with-\n// jitter here would be a second, silently diverging implementation of the one thing the resilience slice\n// exists to own. The only timing code below is a plain abortable `setTimeout` that waits the delay it is\n// HANDED; it never computes one.\n//\n// `shouldRetry` IS STATUS-DRIVEN, so a caught failure is read for a numeric `status` — structurally, so an\n// `ApiError` from `foundation/http`, an `UploadHttpError`, and a hand-rolled `{ status: 503 }` all\n// interoperate without this slice depending on the HTTP layer. No status ⇒ `0` ⇒ transient under the\n// default policy, which is the right default for the generic case: a `TypeError` from a dropped connection\n// retries, a deliberate `400` does not.\n//\n// A CANCELLED CALL IS NEVER RETRIED. `isAbortError` short-circuits before the retry decision, plus a direct\n// `signal.aborted` check for work that rejects with something else after an abort. Retrying through a\n// cancel would make every cancel button a lie — the user's intent outranks the policy.\n//\n// Non-obvious decisions:\n// - THE BACKOFF WAIT IS ABORTABLE. A 30s cap with a non-abortable sleep means a cancel is ignored for up to\n//   30s; the wait resolves early on abort and the loop re-checks `signal.aborted` immediately after.\n// - The rethrow goes through `toError`, which passes a real `Error` through BY IDENTITY (an `ApiError` stays\n//   an `ApiError`, subclass intact) and only normalizes a non-`Error` throw. The caller is therefore\n//   guaranteed an `Error` in `catch` without losing what was actually thrown.\n// - `fn` receives the 1-based attempt number — enough for logging or an attempt-tagged idempotency key\n//   without the caller keeping a counter alongside.\n\nimport { isAbortError, toError } from '../errors';\nimport { DefaultRetryPolicy, computeRetryDelay, shouldRetry, type RetryPolicy } from '../resilience';\n\nimport { abortErrorFor } from './Abort';\n\n/**\n * Reads the HTTP status a caught failure carries, for `shouldRetry`. Returns `0` — the \"network / unknown\"\n * status the default policy treats as transient — when the value has no numeric `status`. Guarded, so a\n * throwing getter reads as absent rather than failing inside a `catch` block.\n */\nfunction readErrorStatus(error: unknown): number {\n  if (typeof error !== 'object' || error === null) return 0;\n  try {\n    const status: unknown = (error as { status?: unknown }).status;\n    return typeof status === 'number' && Number.isFinite(status) ? status : 0;\n  } catch {\n    return 0;\n  }\n}\n\n/**\n * Reads `signal.aborted` freshly.\n *\n * Not inlined, and not merely a style choice: `signal.aborted` is a mutable flag that flips at any moment,\n * but TypeScript's control-flow analysis treats it like a stable property. After one `if (signal?.aborted)`\n * check the type narrows to `false` for the rest of the function, and every later check — the ones AFTER an\n * `await`, which are the whole point — becomes a compile error for comparing non-overlapping types. Routing\n * each read through a call re-widens it, because a function's return cannot be narrowed by an earlier one.\n */\nfunction isAborted(signal: AbortSignal | undefined): boolean {\n  return signal?.aborted === true;\n}\n\n/**\n * Waits `ms`, resolving early — never rejecting — if `signal` aborts. The caller re-checks `signal.aborted`\n * afterwards. Clears its timer and detaches its listener on both paths.\n */\nfunction sleep(ms: number, signal?: AbortSignal): Promise<void> {\n  return new Promise<void>((resolve) => {\n    if (ms <= 0 || isAborted(signal)) {\n      resolve();\n      return;\n    }\n\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    const finish = (): void => {\n      if (timer !== undefined) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n      signal?.removeEventListener('abort', finish);\n      resolve();\n    };\n\n    timer = setTimeout(finish, ms);\n    signal?.addEventListener('abort', finish, { once: true });\n  });\n}\n\n/** Configures a {@link retryAsync} call. */\nexport interface RetryAsyncOptions {\n  /** The policy driving the decision and the delays. Defaults to `DefaultRetryPolicy` from `foundation/resilience`. */\n  readonly policy?: RetryPolicy;\n\n  /** Cancels the retry loop, even mid-backoff. Rejects with an `AbortError`; an in-flight attempt is not recalled. */\n  readonly signal?: AbortSignal;\n}\n\n/**\n * Runs `fn`, retrying transient failures per the policy — attempts, backoff, and jitter all decided by\n * `foundation/resilience`.\n *\n * `fn` gets the 1-based attempt number. An `AbortError` is never retried, and neither is a failure whose\n * `status` the policy considers non-transient. Rejects with the last failure once retries are exhausted.\n *\n * `fn` must be idempotent-safe to call again — this is the caller's judgement, not something the helper can\n * check. Wrap `fn` in `withTimeout` when a hung attempt should also count as a failure; the two compose in\n * that order so each attempt gets its own deadline.\n */\nexport async function retryAsync<T>(\n  fn: (attempt: number) => PromiseLike<T> | T,\n  options: RetryAsyncOptions = {},\n): Promise<T> {\n  const policy = options.policy ?? DefaultRetryPolicy;\n  const signal = options.signal;\n\n  /** Failures so far — `shouldRetry`'s `failureCount`, and one less than the next attempt's number. */\n  let failures = 0;\n  /** The previous delay, which decorrelated jitter needs to walk forward. */\n  let previousDelayMs = 0;\n\n  for (;;) {\n    if (signal !== undefined && isAborted(signal)) throw abortErrorFor(signal);\n\n    try {\n      return await fn(failures + 1);\n    } catch (caught) {\n      // Cancellation outranks the policy, in both shapes: the call rejected with an abort, or the signal\n      // fired and the call rejected with something else entirely.\n      if (isAbortError(caught)) throw toError(caught);\n      if (signal !== undefined && isAborted(signal)) throw abortErrorFor(signal);\n\n      const status = readErrorStatus(caught);\n      if (!shouldRetry(policy, failures, status)) throw toError(caught);\n\n      const attempt = failures + 1;\n      const delayMs = computeRetryDelay(policy, attempt, previousDelayMs);\n      policy.onRetry?.({ attempt, error: caught, status, delayMs });\n\n      await sleep(delayMs, signal);\n      if (signal !== undefined && isAborted(signal)) throw abortErrorFor(signal);\n\n      previousDelayMs = delayMs;\n      failures = attempt;\n    }\n  }\n}\n","// Rate shaping for async functions — collapse a burst into one call (`debounceAsync`), or cap a hot path to\n// one call per window (`throttleAsync`). Search-as-you-type, autosave-on-keystroke, save-on-scroll.\n//\n// THE SUBTLE PART, AND THE REASON THESE ARE NOT THE USUAL DEBOUNCE WRAPPED IN A PROMISE: a debounced async\n// call must decide what to tell the callers it SUPERSEDES. Typing \"abc\" produces three calls and one\n// invocation, so two promises are left over. The naive implementation — keep the latest deferred, drop the\n// rest — leaves those two promises PERMANENTLY UNSETTLED. That is a silent leak with no error and no log:\n// every `await` on them is parked forever, holding its whole continuation (component state, closures,\n// request payloads) alive for the life of the page, and `try/finally` cleanup around such an await never\n// runs. In a UI it reads as a spinner that never stops on a request nobody can point to.\n//\n// So EVERY superseded caller resolves with the LATEST invocation's result. Semantically honest — a debounce\n// promises \"the answer as of when you stopped typing\", and all three callers asked the same question, so\n// they get the same answer — and it makes the promise leak structurally impossible: the waiter list is\n// drained on every exit path. If a caller must distinguish its own invocation from a shared one, debounce\n// is the wrong primitive; use the raw call plus an abort signal.\n//\n// Non-obvious decisions:\n// - Both wrappers expose `cancel()`, which is what makes them safe to unmount. It clears the pending timer\n//   and REJECTS parked waiters with an `AbortError` rather than leaving them hanging — the same leak in a\n//   different disguise. `isAbortError` recognizes it, so an effect's cleanup path swallows it normally.\n// - `debounceAsync` is TRAILING-EDGE and `throttleAsync` is LEADING-EDGE, which is the useful pairing rather\n//   than a symmetry oversight: debounce answers \"the user stopped, act on the final state\", throttle answers\n//   \"act now, then ignore the flood\".\n// - A rejection from `fn` fans out to every waiter it represented. They were all answered by that one call,\n//   so they all learn it failed.\n// - `throttleAsync` shares the in-flight promise for the whole window, so suppressed callers get the leading\n//   call's result rather than `undefined` — no caller has to handle a \"was skipped\" case that would\n//   otherwise infect its return type.\n\nimport { AbortError } from './Abort';\nimport { deferred, type Deferred } from './Deferred';\n\n/** A trailing-edge debounced async function, plus the cancel that makes it unmount-safe. */\nexport interface DebouncedAsync<TArgs extends unknown[], TResult> {\n  /** Schedules an invocation `ms` from now, replacing any pending one. Resolves with the latest invocation's result. */\n  (...args: TArgs): Promise<TResult>;\n\n  /** Drops the pending invocation and rejects parked callers with an `AbortError`. Safe to call when idle. */\n  readonly cancel: () => void;\n}\n\n/** A leading-edge throttled async function, plus the cancel that makes it unmount-safe. */\nexport interface ThrottledAsync<TArgs extends unknown[], TResult> {\n  /** Invokes immediately when the window is open; otherwise returns the in-flight window's promise. */\n  (...args: TArgs): Promise<TResult>;\n\n  /** Closes the current window early and clears its timer. Safe to call when idle. */\n  readonly cancel: () => void;\n}\n\n/**\n * Debounces an async function on the trailing edge: a burst of calls collapses into ONE invocation, `ms`\n * after the last call, using the last call's arguments.\n *\n * Every caller in the burst — superseded ones included — resolves with that single invocation's result, so\n * no promise is ever left unsettled (see the header; this is the whole point). A rejection likewise fans\n * out to all of them. Call `cancel()` on unmount.\n */\nexport function debounceAsync<TArgs extends unknown[], TResult>(\n  fn: (...args: TArgs) => PromiseLike<TResult> | TResult,\n  ms: number,\n): DebouncedAsync<TArgs, TResult> {\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  let waiters: Deferred<TResult>[] = [];\n  let nextCall: { readonly args: TArgs } | undefined;\n\n  /** Fires the trailing invocation and answers every caller parked behind it. */\n  const invoke = (): void => {\n    timer = undefined;\n    const call = nextCall;\n    const parked = waiters;\n    // Reset BEFORE awaiting: calls arriving while `fn` is in flight belong to the next window, and must not\n    // be answered by this invocation's result.\n    nextCall = undefined;\n    waiters = [];\n    if (call === undefined) return;\n\n    void (async (): Promise<void> => {\n      try {\n        const result = await fn(...call.args);\n        for (const waiter of parked) waiter.resolve(result);\n      } catch (error) {\n        for (const waiter of parked) waiter.reject(error);\n      }\n    })();\n  };\n\n  const debounced = (...args: TArgs): Promise<TResult> => {\n    nextCall = { args };\n    const waiter = deferred<TResult>();\n    waiters.push(waiter);\n\n    if (timer !== undefined) clearTimeout(timer);\n    timer = setTimeout(invoke, ms);\n    return waiter.promise;\n  };\n\n  return Object.assign(debounced, {\n    cancel: (): void => {\n      if (timer !== undefined) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n      const parked = waiters;\n      waiters = [];\n      nextCall = undefined;\n      for (const waiter of parked) waiter.reject(new AbortError('Debounced call cancelled.'));\n    },\n  });\n}\n\n/**\n * Throttles an async function on the leading edge: the first call runs immediately, and every call within\n * the next `ms` is suppressed — receiving the leading call's promise rather than triggering its own.\n *\n * The window opens again `ms` after the leading call, whether or not it has settled. Call `cancel()` on\n * unmount to clear the window timer.\n */\nexport function throttleAsync<TArgs extends unknown[], TResult>(\n  fn: (...args: TArgs) => PromiseLike<TResult> | TResult,\n  ms: number,\n): ThrottledAsync<TArgs, TResult> {\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  let inFlight: Promise<TResult> | undefined;\n\n  const throttled = (...args: TArgs): Promise<TResult> => {\n    if (inFlight !== undefined) return inFlight;\n\n    // The async IIFE normalizes a synchronous throw from `fn` into a rejection, so a suppressed caller and\n    // the leading caller always receive the same shape.\n    const started = (async (): Promise<TResult> => fn(...args))();\n    inFlight = started;\n\n    timer = setTimeout(() => {\n      timer = undefined;\n      inFlight = undefined;\n    }, ms);\n\n    return started;\n  };\n\n  return Object.assign(throttled, {\n    cancel: (): void => {\n      if (timer !== undefined) {\n        clearTimeout(timer);\n        timer = undefined;\n      }\n      inFlight = undefined;\n    },\n  });\n}\n","// Two combinators, and only two — the set is deliberately tight because the platform already ships\n// `Promise.all` / `race` / `any` / `allSettled`, and a slice that re-wraps them earns nothing while making\n// consumers learn a second vocabulary for the same operations. Each one here justifies itself by removing a\n// specific piece of boilerplate that the platform makes every caller write:\n//\n// - `sequential(tasks)` — `Promise.all` starts everything at once, and there is NO platform combinator for\n//   \"one at a time, in order\". Hand-rolled it is a `for...of` with an accumulator and an `await` in the loop\n//   that lint rules flag; and the obvious clever versions (`reduce` over a promise chain) are hard to read\n//   and easy to get wrong. Needed whenever tasks are order-dependent — sequential migrations, an animation\n//   queue, a rate-limited endpoint that tolerates exactly one call at a time.\n//\n// - `allSettledValues(promises)` — `Promise.allSettled` hands back a DISCRIMINATED UNION array, so every\n//   caller writing \"give me whatever succeeded, drop the rest\" repeats the same filter-then-map on\n//   `status === 'fulfilled'`, and repeats the type narrowing that goes with it. This is that line, once.\n//\n// `sequential` IS NOT `mapLimit(tasks, 1, …)`, which is the obvious implementation and the wrong one. A\n// limiter of one gives ORDERING; it does not give SHORT-CIRCUITING. `mapLimit` submits every task up front,\n// so a failure at step 2 rejects the returned promise while the scheduler happily runs steps 3..n — its\n// queue knows nothing about the rejection. For the cases `sequential` exists to serve that is not a nuance\n// but a hazard: run migration 3 after migration 2 failed and the damage is real. So the loop below awaits\n// each task and stops at the first throw, and the delegation is deliberately NOT made. (`mapLimit` keeps\n// `Promise.all` semantics on purpose — a bounded `Promise.all` should behave like one — which is exactly\n// why the two cannot share an implementation.)\n\n/**\n * Runs `tasks` one at a time, in order, resolving to their results in that same order.\n *\n * STOPS AT THE FIRST FAILURE: the rejecting task's error propagates and no later task is started, because a\n * task in a sequence generally assumes its predecessor succeeded. Use `mapLimit(tasks, 1, …)` instead when\n * every task must run regardless of the others' outcomes.\n */\nexport async function sequential<T>(tasks: Iterable<() => PromiseLike<T> | T>): Promise<T[]> {\n  const results: T[] = [];\n  // Serial by construction — the `await` inside the loop IS the feature, not an oversight.\n  for (const task of tasks) results.push(await task());\n  return results;\n}\n\n/**\n * Awaits every promise and resolves to the values of the ones that fulfilled, in input order, silently\n * dropping the rejections.\n *\n * Never rejects — the \"best effort, partial results are fine\" counterpart to `Promise.all`: warming a\n * cache, hydrating optional widgets, fanning out to mirrors. Note that failures are DISCARDED, not\n * reported; use `Promise.allSettled` directly when a caller needs to know what broke.\n */\nexport async function allSettledValues<T>(promises: Iterable<PromiseLike<T>>): Promise<T[]> {\n  const results = await Promise.allSettled([...promises]);\n  // `flatMap` over the union narrows without a type predicate, which `filter` would need.\n  return results.flatMap((result) => (result.status === 'fulfilled' ? [result.value] : []));\n}\n"],"names":[],"mappings":"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"}

package/dist/foundation/channels/LeaderElection.d.ts

@@ -0,0 +1,97 @@
+import { Guid } from '../identifiers';
+import { SyncChannel, SyncChannelOptions } from './SyncChannel';
+/**
+ * Carries the election's traffic. Each signal repeats its sender's id in the payload rather than relying on the
+ * envelope, so the messages stay self-describing when read in devtools or replayed through another transport.
+ */
+export type LeaderSignal = 
+/** Asserts live leadership; resets every follower's expiry watchdog. */
+{
+    readonly kind: 'heartbeat';
+    readonly id: Guid;
+}
+/** Announces a bid for the empty throne; a live leader answers it with a heartbeat. */
+ | {
+    readonly kind: 'claim';
+    readonly id: Guid;
+}
+/** Surrenders leadership deliberately, so peers re-elect at once instead of waiting out the expiry. */
+ | {
+    readonly kind: 'resign';
+    readonly id: Guid;
+};
+/** Names a participant's position in the election. */
+export declare const LeaderRole: {
+    /** Watches a live leader's heartbeat and re-elects when the lease expires. The state every tab starts in. */
+    readonly Follower: "follower";
+    /** Has bid for the empty throne and is waiting out the claim window for a rival or a live leader. */
+    readonly Candidate: "candidate";
+    /** Holds the lease and does the work; heartbeats until it resigns, closes, or crashes. */
+    readonly Leader: "leader";
+};
+/** Names a participant's position in the election. */
+export type LeaderRole = (typeof LeaderRole)[keyof typeof LeaderRole];
+/** Defines the options that tune an election's timing and transport. */
+export interface LeaderElectionOptions {
+    /** Sets how often the leader re-asserts, in milliseconds; defaults to 1000. */
+    readonly heartbeatInterval?: number;
+    /** Sets how long a follower tolerates silence before claiming, in milliseconds; defaults to 3500. */
+    readonly timeout?: number;
+    /** Sets how long a candidate collects rival claims, in milliseconds; defaults to 150. */
+    readonly claimWindow?: number;
+    /**
+     * Supplies the channel to run on instead of opening one — the seam tests use to join a `memorySyncHub`. An
+     * injected channel is NOT closed by `close`; its owner keeps that duty.
+     */
+    readonly channel?: SyncChannel<LeaderSignal>;
+    /** Tunes the channel opened when `channel` is omitted; ignored when one is supplied. */
+    readonly channelOptions?: SyncChannelOptions;
+}
+/** Represents this tab's participation in a named election. */
+export interface LeaderElection {
+    /** Identifies this participant — the same id as the underlying channel's endpoint. */
+    readonly id: Guid;
+    /** Reports whether this tab currently holds the lease. */
+    readonly isLeader: boolean;
+    /** Reports this tab's position — `candidate` is the transient state inside a claim window. */
+    readonly role: LeaderRole;
+    /**
+     * Registers `listener` for the moment this tab takes leadership. Fires IMMEDIATELY and synchronously if it is
+     * already the leader when subscribing, so a late subscriber cannot miss the transition it was waiting for.
+     *
+     * @param listener - Invoked on becoming leader; a throw is swallowed.
+     * @returns An idempotent disposer.
+     */
+    onBecomeLeader(listener: () => void): () => void;
+    /**
+     * Registers `listener` for the moment this tab loses leadership — superseded by a lower id, or after
+     * `release`. Not fired by `close`, which is a teardown rather than a state change.
+     *
+     * @param listener - Invoked on losing leadership; a throw is swallowed.
+     * @returns An idempotent disposer.
+     */
+    onLoseLeader(listener: () => void): () => void;
+    /**
+     * Surrenders leadership deliberately and tells peers to re-elect at once. This tab stays in the election and
+     * may win again later — typically after `timeout`, by which point a peer has long since taken over.
+     */
+    release(): void;
+    /**
+     * Leaves the election entirely: resigns first if leading, then drops every timer and listener. Idempotent.
+     * Does not fire `onLoseLeader`. Closes the underlying channel only when this election opened it.
+     */
+    close(): void;
+}
+/**
+ * Joins the named election, in which exactly one participating tab holds leadership at a time.
+ *
+ * Leadership is a lease kept alive by a heartbeat, so a tab that dies without resigning is superseded once its
+ * lease expires — the reclaim path is the reason this exists. Ties are broken by lowest id, which for the
+ * time-ordered v7 ids minted here means the longest-open tab wins. Starts campaigning immediately; nothing
+ * throws, and under SSR or with no cross-tab transport the sole participant simply becomes leader.
+ *
+ * @param name - Election name; tabs sharing it on the origin compete for one leadership.
+ * @param options - Timing, and the channel to run on.
+ * @returns The participant handle: state, transition events, `release`, and `close`.
+ */
+export declare function createLeaderElection(name: string, options?: LeaderElectionOptions): LeaderElection;

package/dist/foundation/channels/SyncChannel.d.ts

@@ -0,0 +1,76 @@
+import { Guid } from '../identifiers';
+import { StorageBroker } from '../storage';
+/**
+ * Wraps one posted payload with the metadata the dispatch path needs — who sent it, in what order, and when.
+ * Written to the wire by both real transports so the receiving rules are identical across them.
+ */
+export interface SyncEnvelope<TMessage> {
+    /** Identifies the tab that posted the message; the receiver drops an envelope whose sender is itself. */
+    readonly sender: Guid;
+    /** Counts posts from this sender, starting at 0 — makes each fallback write unique and each delivery de-dupable. */
+    readonly seq: number;
+    /** Records the post time in epoch milliseconds, as read from the channel's clock. */
+    readonly timestamp: number;
+    /** Carries the caller's payload, unvalidated at runtime — see this file's header. */
+    readonly message: TMessage;
+}
+/**
+ * Receives a message from another tab. The payload comes first because it is what nearly every caller wants;
+ * the envelope follows for the rare consumer that needs the sender or the ordering metadata.
+ */
+export type SyncListener<TMessage> = (message: TMessage, envelope: SyncEnvelope<TMessage>) => void;
+/**
+ * Names the delivery mechanisms a channel can sit on. `auto` picks the best one available and is the default;
+ * the explicit values exist for tests and for a consumer that deliberately wants the weaker path.
+ */
+export declare const SyncTransport: {
+    /** Requests the best mechanism available here; never the answer a channel reports back. */
+    readonly Auto: "auto";
+    /** Pins delivery to `BroadcastChannel` — real messages, no storage write per post. */
+    readonly Broadcast: "broadcast";
+    /** Pins delivery to the `storage` event — the weaker fallback, for browsers without `BroadcastChannel`. */
+    readonly Storage: "storage";
+    /** Pins delivery to nothing: posts are dropped and no listener ever fires. The SSR and test-double path. */
+    readonly Inert: "inert";
+};
+/** Names the delivery mechanisms a channel can sit on. */
+export type SyncTransport = (typeof SyncTransport)[keyof typeof SyncTransport];
+/** Names the transport a channel actually resolved to — `auto` is a request, never an answer. */
+export type ResolvedSyncTransport = Exclude<SyncTransport, typeof SyncTransport.Auto>;
+/** Defines the options that tune how a sync channel finds its peers. */
+export interface SyncChannelOptions {
+    /**
+     * Selects the delivery mechanism; defaults to `auto` (`broadcast` → `storage` → `inert`). An explicit choice
+     * that is unavailable in this environment degrades to the next one down rather than throwing.
+     */
+    readonly transport?: SyncTransport;
+    /** Supplies the persistence seam the `storage` fallback writes through; defaults to `localStorageStorageBroker`. */
+    readonly broker?: StorageBroker;
+    /** Prefixes the `storage` fallback's key, isolating one app's channels from another's; defaults to `wow-two.sync`. */
+    readonly keyPrefix?: string;
+    /** Pins this endpoint's tab id instead of minting one — for deterministic tie-breaks in tests. */
+    readonly id?: Guid;
+    /** Supplies the clock stamped onto each envelope; defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * Represents one tab's endpoint on a named cross-tab channel. Every method is total: posting on a closed
+ * channel, subscribing after close, or running with no browser APIs at all are ordinary states that answer
+ * quietly instead of throwing.
+ */
+export interface SyncChannel<TMessage> {
+    /** Names the channel; every endpoint sharing this name on the origin is a peer. */
+    readonly name: string;
+    /** Identifies this endpoint (this tab) — stable for the channel's lifetime. */
+    readonly id: Guid;
+    /** Reports the mechanism this endpoint resolved to; `inert` means no peer will ever be reached. */
+    readonly transport: ResolvedSyncTransport;
+    /** Reports whether `close` has run — a closed channel neither sends nor delivers. */
+    readonly closed: boolean;
+    /** Sends `message` to every OTHER endpoint on the channel; never delivers to this one, and never throws. */
+    post(message: TMessage): void;
+    /** Registers `listener` for messages from other tabs; returns an idempotent disposer that unsubscribes it. */
+    subscribe(listener: SyncListener<TMessage>): () => void;
+    /** Detaches every listener and releases the underlying transport; idempotent. */
+    close(): void;
+}

package/dist/foundation/channels/hooks/UseBroadcastState.d.ts

@@ -0,0 +1,31 @@
+import { MaybeRefOrGetter, WritableComputedRef } from 'vue';
+import { SyncChannelOptions } from '../SyncChannel';
+/** A setter accepting a next value or an updater fn. */
+export type SetBroadcastState<T> = (next: T | ((previous: T) => T)) => void;
+/** The mirrored-state handle — a writable value plus the explicit setter it delegates to. */
+export interface BroadcastStateControls<T> {
+    /**
+     * The mirrored value. Writable: `value.value = next` runs the same path as `setValue(next)`, so it drops
+     * straight into `v-model`. The updater-fn form is `setValue`'s alone — a `v-model` write is always a value.
+     */
+    readonly value: WritableComputedRef<T>;
+    /** Sets the next value locally and announces it to every peer. Accepts a value or an updater fn. */
+    readonly setValue: SetBroadcastState<T>;
+}
+/**
+ * Manages a piece of reactive state mirrored live across every open tab, without persisting it anywhere.
+ *
+ * Setting the value here sets it in every other tab holding the same `key`; a tab that opens later asks its
+ * peers for the current value on mount. Nothing is written to storage, so the value vanishes when the last tab
+ * closes — read this file's header for the split with `usePersistentState`, which is the durable counterpart.
+ *
+ * SSR-safe: no channel is opened on the server, so the value is simply `initial` and the setter is local.
+ *
+ * @typeParam T - The mirrored value; must survive the transport (JSON-only on the `storage` fallback).
+ * @param key - Identifies the shared value; tabs sharing it on this origin mirror each other. A ref or getter
+ *   re-opens the channel on change.
+ * @param initial - The value before any peer answers, and the value when no other tab is open. Read once.
+ * @param options - Channel configuration, read once when the channel opens.
+ * @returns The writable value and its setter.
+ */
+export declare function useBroadcastState<T>(key: MaybeRefOrGetter<string>, initial: T, options?: SyncChannelOptions): BroadcastStateControls<T>;

package/dist/foundation/channels/hooks/UseLeaderElection.d.ts

@@ -0,0 +1,25 @@
+import { MaybeRefOrGetter, ShallowRef } from 'vue';
+import { Guid } from '../../identifiers';
+import { LeaderElectionOptions } from '../LeaderElection';
+/** Reports this tab's standing in an election, as reactive state. */
+export interface LeaderElectionState {
+    /** Reports whether this tab currently holds leadership; false before mount and under SSR. */
+    readonly isLeader: Readonly<ShallowRef<boolean>>;
+    /** Identifies this participant, or null before the election is joined (pre-mount, SSR). */
+    readonly id: Readonly<ShallowRef<Guid | null>>;
+    /** Surrenders leadership deliberately, handing over to a peer; a no-op when not leading. */
+    readonly release: () => void;
+}
+/**
+ * Joins the named leader election for the lifetime of the scope, updating when this tab gains or loses
+ * leadership.
+ *
+ * Exactly one participating tab leads at a time; a tab that dies is superseded once its lease expires. Use it to
+ * elect the single tab that opens the socket, runs the poll, or shows the notification.
+ *
+ * @param name - Election name; tabs sharing it on this origin compete for one leadership. A ref or getter
+ *   re-joins on change.
+ * @param options - Timing and channel configuration, read once when the election is joined.
+ * @returns The current standing plus `release`.
+ */
+export declare function useLeaderElection(name: MaybeRefOrGetter<string>, options?: LeaderElectionOptions): LeaderElectionState;

package/dist/foundation/channels/hooks/UseSyncChannel.d.ts

@@ -0,0 +1,16 @@
+import { MaybeRefOrGetter } from 'vue';
+import { SyncChannelOptions, SyncListener } from '../SyncChannel';
+/**
+ * Opens a cross-tab channel for the lifetime of the scope and subscribes `onMessage` to it.
+ *
+ * The returned `post` sends to every OTHER tab on the channel, never back into this one. Before mount and after
+ * disposal — and under SSR, where no channel is ever opened — `post` is a silent no-op, so a handler firing at
+ * an awkward moment needs no guard.
+ *
+ * @typeParam TMessage - The payload shape agreed between tabs.
+ * @param name - Channel name; every tab using it on this origin is a peer. A ref or getter re-opens on change.
+ * @param onMessage - Invoked for each message from another tab.
+ * @param options - Transport and storage configuration, read once when the channel opens.
+ * @returns The `post` function.
+ */
+export declare function useSyncChannel<TMessage>(name: MaybeRefOrGetter<string>, onMessage?: SyncListener<TMessage>, options?: SyncChannelOptions): (message: TMessage) => void;

package/dist/foundation/channels/index.d.ts

@@ -0,0 +1,7 @@
+export type { ResolvedSyncTransport, SyncChannel, SyncChannelOptions, SyncEnvelope, SyncListener, SyncTransport, } from './SyncChannel';
+export { createSyncChannel } from './CreateSyncChannel';
+export { memorySyncHub, type MemorySyncHub } from './MemorySyncHub';
+export { createLeaderElection, type LeaderElection, type LeaderElectionOptions, type LeaderRole, type LeaderSignal, } from './LeaderElection';
+export { useSyncChannel } from './hooks/UseSyncChannel';
+export { useLeaderElection, type LeaderElectionState } from './hooks/UseLeaderElection';
+export { useBroadcastState, type SetBroadcastState, type BroadcastStateControls } from './hooks/UseBroadcastState';