@wow-two-beta/ui-vue 0.0.2

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

@@ -0,0 +1,7 @@
+export { deferred, type Deferred } from './Deferred';
+export { TimeoutError, withTimeout, type WithTimeoutOptions } from './Timeout';
+export { AbortError, abortable, withAbort } from './Abort';
+export { pLimit, mapLimit, type Limiter } from './Limit';
+export { retryAsync, type RetryAsyncOptions } from './Retry';
+export { debounceAsync, throttleAsync, type DebouncedAsync, type ThrottledAsync } from './Rate';
+export { sequential, allSettledValues } from './Combinators';

package/dist/foundation/async/index.js

@@ -0,0 +1,290 @@
+import { t as toError } from "../../chunks/ToError-CyTBsmLO.js";
+import { i as isAbortError } from "../../chunks/ErrorRecognizers-oTklha6D.js";
+import { DefaultRetryPolicy, shouldRetry, computeRetryDelay } from "../resilience/index.js";
+function deferred() {
+  let resolve;
+  let reject;
+  const promise = new Promise((promiseResolve, promiseReject) => {
+    resolve = promiseResolve;
+    reject = promiseReject;
+  });
+  return { promise, resolve, reject };
+}
+class AbortError extends Error {
+  /** Creates a cancellation error; pass `cause` to preserve the signal's abort reason. */
+  constructor(message = "The operation was aborted.", options) {
+    super(message, options);
+    this.name = "AbortError";
+  }
+}
+function abortErrorFor(signal) {
+  const reason = signal.reason;
+  return reason === void 0 ? new AbortError() : new AbortError(void 0, { cause: reason });
+}
+function abortable(promise, signal) {
+  if (signal === void 0) return Promise.resolve(promise);
+  if (signal.aborted) return Promise.reject(abortErrorFor(signal));
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      reject(abortErrorFor(signal));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      }
+    );
+  });
+}
+function withAbort(signal, fn) {
+  if (signal.aborted) return Promise.reject(abortErrorFor(signal));
+  let started;
+  try {
+    started = fn(signal);
+  } catch (error) {
+    return Promise.reject(error);
+  }
+  return abortable(Promise.resolve(started), signal);
+}
+class TimeoutError extends Error {
+  /** Creates a deadline error. */
+  constructor(message = "The operation timed out.", options) {
+    super(message, options);
+    this.name = "TimeoutError";
+  }
+}
+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));
+  return new Promise((resolve, reject) => {
+    let timer;
+    let abortListener;
+    const cleanup = () => {
+      if (timer !== void 0) {
+        clearTimeout(timer);
+        timer = void 0;
+      }
+      if (signal !== void 0 && abortListener !== void 0) {
+        signal.removeEventListener("abort", abortListener);
+        abortListener = void 0;
+      }
+    };
+    timer = setTimeout(() => {
+      timer = void 0;
+      cleanup();
+      try {
+        onTimeout?.();
+      } catch {
+      }
+      reject(new TimeoutError(message ?? `Operation timed out after ${ms}ms`));
+    }, ms);
+    if (signal !== void 0) {
+      const listener = () => {
+        cleanup();
+        reject(abortErrorFor(signal));
+      };
+      abortListener = listener;
+      signal.addEventListener("abort", listener, { once: true });
+    }
+    promise.then(
+      (value) => {
+        cleanup();
+        resolve(value);
+      },
+      (error) => {
+        cleanup();
+        reject(error);
+      }
+    );
+  });
+}
+function pLimit(concurrency) {
+  const limit = Math.max(1, Math.floor(concurrency));
+  const queue = [];
+  let active = 0;
+  function drain() {
+    if (active >= limit) return;
+    const start = queue.shift();
+    if (start !== void 0) start();
+  }
+  function run(fn) {
+    return new Promise((resolve, reject) => {
+      const start = () => {
+        active += 1;
+        void (async () => {
+          try {
+            resolve(await fn());
+          } catch (error) {
+            reject(error);
+          } finally {
+            active -= 1;
+            drain();
+          }
+        })();
+      };
+      if (active < limit) start();
+      else queue.push(start);
+    });
+  }
+  return {
+    run,
+    activeCount: () => active,
+    pendingCount: () => queue.length,
+    concurrency: limit
+  };
+}
+function mapLimit(items, concurrency, fn) {
+  const list = [...items];
+  const limiter = pLimit(concurrency);
+  return Promise.all(list.map((item, index) => limiter.run(() => fn(item, index))));
+}
+function readErrorStatus(error) {
+  if (typeof error !== "object" || error === null) return 0;
+  try {
+    const status = error.status;
+    return typeof status === "number" && Number.isFinite(status) ? status : 0;
+  } catch {
+    return 0;
+  }
+}
+function isAborted(signal) {
+  return signal?.aborted === true;
+}
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (ms <= 0 || isAborted(signal)) {
+      resolve();
+      return;
+    }
+    let timer;
+    const finish = () => {
+      if (timer !== void 0) {
+        clearTimeout(timer);
+        timer = void 0;
+      }
+      signal?.removeEventListener("abort", finish);
+      resolve();
+    };
+    timer = setTimeout(finish, ms);
+    signal?.addEventListener("abort", finish, { once: true });
+  });
+}
+async function retryAsync(fn, options = {}) {
+  const policy = options.policy ?? DefaultRetryPolicy;
+  const signal = options.signal;
+  let failures = 0;
+  let previousDelayMs = 0;
+  for (; ; ) {
+    if (signal !== void 0 && isAborted(signal)) throw abortErrorFor(signal);
+    try {
+      return await fn(failures + 1);
+    } catch (caught) {
+      if (isAbortError(caught)) throw toError(caught);
+      if (signal !== void 0 && isAborted(signal)) throw abortErrorFor(signal);
+      const status = readErrorStatus(caught);
+      if (!shouldRetry(policy, failures, status)) throw toError(caught);
+      const attempt = failures + 1;
+      const delayMs = computeRetryDelay(policy, attempt, previousDelayMs);
+      policy.onRetry?.({ attempt, error: caught, status, delayMs });
+      await sleep(delayMs, signal);
+      if (signal !== void 0 && isAborted(signal)) throw abortErrorFor(signal);
+      previousDelayMs = delayMs;
+      failures = attempt;
+    }
+  }
+}
+function debounceAsync(fn, ms) {
+  let timer;
+  let waiters = [];
+  let nextCall;
+  const invoke = () => {
+    timer = void 0;
+    const call = nextCall;
+    const parked = waiters;
+    nextCall = void 0;
+    waiters = [];
+    if (call === void 0) return;
+    void (async () => {
+      try {
+        const result = await fn(...call.args);
+        for (const waiter of parked) waiter.resolve(result);
+      } catch (error) {
+        for (const waiter of parked) waiter.reject(error);
+      }
+    })();
+  };
+  const debounced = (...args) => {
+    nextCall = { args };
+    const waiter = deferred();
+    waiters.push(waiter);
+    if (timer !== void 0) clearTimeout(timer);
+    timer = setTimeout(invoke, ms);
+    return waiter.promise;
+  };
+  return Object.assign(debounced, {
+    cancel: () => {
+      if (timer !== void 0) {
+        clearTimeout(timer);
+        timer = void 0;
+      }
+      const parked = waiters;
+      waiters = [];
+      nextCall = void 0;
+      for (const waiter of parked) waiter.reject(new AbortError("Debounced call cancelled."));
+    }
+  });
+}
+function throttleAsync(fn, ms) {
+  let timer;
+  let inFlight;
+  const throttled = (...args) => {
+    if (inFlight !== void 0) return inFlight;
+    const started = (async () => fn(...args))();
+    inFlight = started;
+    timer = setTimeout(() => {
+      timer = void 0;
+      inFlight = void 0;
+    }, ms);
+    return started;
+  };
+  return Object.assign(throttled, {
+    cancel: () => {
+      if (timer !== void 0) {
+        clearTimeout(timer);
+        timer = void 0;
+      }
+      inFlight = void 0;
+    }
+  });
+}
+async function sequential(tasks) {
+  const results = [];
+  for (const task of tasks) results.push(await task());
+  return results;
+}
+async function allSettledValues(promises) {
+  const results = await Promise.allSettled([...promises]);
+  return results.flatMap((result) => result.status === "fulfilled" ? [result.value] : []);
+}
+export {
+  AbortError,
+  TimeoutError,
+  abortable,
+  allSettledValues,
+  debounceAsync,
+  deferred,
+  mapLimit,
+  pLimit,
+  retryAsync,
+  sequential,
+  throttleAsync,
+  withAbort,
+  withTimeout
+};
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +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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"}

package/dist/foundation/clipboard/ClipboardPermission.d.ts

@@ -0,0 +1,17 @@
+import { PermissionQueryState } from '../notifications/QueryPermission';
+/** Which half of the clipboard a permission query is about. */
+export type ClipboardPermissionMode = 'read' | 'write';
+/**
+ * Reads the browser's recorded permission for clipboard reading or writing.
+ *
+ * Returns `unsupported` wherever the Permissions API is absent or does not implement the name — which is most
+ * browsers, including all of Firefox and Safari. Read that as "unknown", never as "denied": the capability is
+ * frequently available where the QUERY is not.
+ *
+ * A one-shot snapshot; the browser fires no event on this promise.
+ *
+ * Never throws, never rejects.
+ *
+ * @param mode `'read'` for `clipboard-read`, `'write'` for `clipboard-write`.
+ */
+export declare function getClipboardPermission(mode: ClipboardPermissionMode): Promise<PermissionQueryState>;

package/dist/foundation/clipboard/ClipboardResult.d.ts

@@ -0,0 +1,102 @@
+/**
+ * The ways a clipboard operation ends without producing a payload. Shared by {@link ClipboardWriteResult} and
+ * both read results, so one `switch` renders every error path in the slice.
+ *
+ * - `denied` — the platform refused: permission not granted, the paste prompt dismissed, or no user gesture
+ *   behind the call.
+ * - `unsupported` — no Clipboard API here: SSR, a non-secure context, or an engine without the method. A
+ *   capability fact, not a failure — nothing went wrong, the road is simply not there.
+ * - `failed` — anything else, carrying the normalized `Error`.
+ */
+export type ClipboardFailure = {
+    readonly status: 'denied';
+    readonly error: Error;
+} | {
+    readonly status: 'unsupported';
+} | {
+    readonly status: 'failed';
+    readonly error: Error;
+};
+/** The outcome of a clipboard write — `copied` on success, otherwise a {@link ClipboardFailure}. */
+export type ClipboardWriteResult = {
+    readonly status: 'copied';
+} | ClipboardFailure;
+/** The `status` discriminant of a {@link ClipboardWriteResult} — for a consumer's own switch or status→copy map. */
+export type ClipboardWriteStatus = ClipboardWriteResult['status'];
+/** One MIME-typed payload read off the system clipboard. */
+export interface ClipboardReadItem {
+    /** The MIME type the platform reported — `text/plain`, `text/html`, `image/png`, … */
+    readonly type: string;
+    /** The payload itself. Read it with `blob.text()` for textual types, or hand it to `URL.createObjectURL`. */
+    readonly blob: Blob;
+}
+/**
+ * The outcome of a clipboard text read. `read` carries the text — an empty clipboard reads as `''`, which is a
+ * successful read of nothing rather than a failure.
+ */
+export type ClipboardReadTextResult = {
+    readonly status: 'read';
+    readonly text: string;
+} | ClipboardFailure;
+/** The outcome of a multi-format clipboard read. `read` carries one entry per MIME type the platform offered. */
+export type ClipboardReadItemsResult = {
+    readonly status: 'read';
+    readonly items: readonly ClipboardReadItem[];
+} | ClipboardFailure;
+/** The `status` discriminant shared by both read results. */
+export type ClipboardReadStatus = ClipboardReadTextResult['status'];
+/** Tunes a clipboard read. */
+export interface ClipboardReadOptions {
+    /**
+     * Called with the normalized error on a `denied` or `failed` result — the seam for a toast or telemetry hook.
+     * Never called for `unsupported`, which is a capability fact rather than a failure. A throw from this callback
+     * is swallowed. Called at most once per operation, on the final result.
+     */
+    readonly onError?: (error: Error) => void;
+}
+/** Tunes a clipboard write. */
+export interface ClipboardCopyOptions extends ClipboardReadOptions {
+    /**
+     * Whether a write the Clipboard API cannot complete retries through the deprecated
+     * `document.execCommand('copy')` path. Defaults to `false`.
+     *
+     * Opt in for reach — older Safari and any non-secure context have no `navigator.clipboard` at all, and
+     * `execCommand` is the only write available there. Leave it off to stay on standards-track APIs only. See
+     * `LegacyCopy.ts` for the deprecation caveats and for exactly when the retry runs.
+     */
+    readonly legacyFallback?: boolean;
+}
+/** The shape every result family shares, so one reporter can serve every entry point. */
+type ClipboardOutcome = {
+    readonly status: string;
+    readonly error?: Error;
+};
+/**
+ * Checks whether a caught value is the platform refusing rather than breaking — the split behind `denied`.
+ * Exported for the sibling modules; absent from the barrel, where the statuses are the answer callers want.
+ *
+ * @param value The caught value.
+ */
+export declare function isPermissionRefusal(value: unknown): boolean;
+/**
+ * Turns a caught value into the `denied` or `failed` arm it belongs in. Serves reads and writes alike — the
+ * returned {@link ClipboardFailure} is assignable to every result union in the slice. Exported for the sibling
+ * modules; absent from the barrel. Never throws: `toError` is total.
+ *
+ * @param error The caught value.
+ */
+export declare function toClipboardFailure(error: unknown): ClipboardFailure;
+/**
+ * Hands a consumer's callback the failure carried by `result`, absorbing a throw from the callback itself. A
+ * reporter that throws must not convert a typed result into an unhandled rejection.
+ *
+ * Called once per entry point, on the FINAL result — so a write that degrades through the legacy fallback
+ * reports the outcome the caller receives, not each intermediate attempt. Exported for the sibling modules;
+ * absent from the barrel.
+ *
+ * @param result The outcome about to be returned.
+ * @param onError The consumer's reporter, if they supplied one.
+ * @returns `result`, unchanged — so a call site can `return reportClipboardOutcome(...)`.
+ */
+export declare function reportClipboardOutcome<TResult extends ClipboardOutcome>(result: TResult, onError: ((error: Error) => void) | undefined): TResult;
+export {};

package/dist/foundation/clipboard/ClipboardSupport.d.ts

@@ -0,0 +1,55 @@
+/** The `ClipboardItem` constructor, narrowed to the one overload this slice calls. */
+export type ClipboardItemConstructor = new (items: Record<string, Blob>) => ClipboardItem;
+/**
+ * Reads `navigator.clipboard` if it is there and usable. Guarded end-to-end; returns `undefined` under SSR.
+ * Exported for the sibling modules; absent from the barrel.
+ */
+export declare function clipboardApi(): Clipboard | undefined;
+/** The Clipboard API methods this slice calls. */
+export type ClipboardMethodName = 'writeText' | 'write' | 'readText' | 'read';
+/**
+ * Resolves one of the Clipboard API's methods, bound to the clipboard object, or `undefined` when this engine
+ * does not implement it. The single gate every operation passes through. Exported for the sibling modules;
+ * absent from the barrel.
+ *
+ * Bound rather than returned bare: a caller invoking a detached `writeText` would lose its receiver and get a
+ * `TypeError` ("Illegal invocation") from the real implementation.
+ *
+ * @param name The method to resolve — `writeText`, `write`, `readText`, or `read`.
+ */
+export declare function clipboardMethod<TName extends ClipboardMethodName>(name: TName): Clipboard[TName] | undefined;
+/**
+ * Reads the `ClipboardItem` constructor, which multi-format writes need and which Node and older Safari lack.
+ * Exported for the sibling modules; absent from the barrel.
+ */
+export declare function clipboardItemConstructor(): ClipboardItemConstructor | undefined;
+/**
+ * Whether plain-text copying is available — `navigator.clipboard.writeText`.
+ *
+ * `false` under SSR, in a non-secure context, and on engines predating the Clipboard API. It does NOT predict
+ * the permission: a copy can still come back `denied` if the call has no user gesture behind it. Treat it as
+ * "is the road there", not "will the trip succeed".
+ */
+export declare function canCopy(): boolean;
+/**
+ * Whether multi-format copying is available — `navigator.clipboard.write` plus a `ClipboardItem` constructor.
+ * Strictly narrower than {@link canCopy}: every engine shipped `writeText` first.
+ */
+export declare function canCopyItems(): boolean;
+/**
+ * Whether reading from the clipboard is available — `navigator.clipboard.readText`.
+ *
+ * `false` in Firefox, which does not expose reading to page script at all, and under SSR. Even where it is
+ * `true`, the read needs a user gesture and shows an explicit paste prompt. If all you need is the payload the
+ * user just pasted, do not read at all — handle the `paste` event with `getPasteItems`, which needs no
+ * permission and no prompt.
+ */
+export declare function canReadClipboard(): boolean;
+/**
+ * Whether the deprecated `document.execCommand('copy')` path is available — the only write that exists in a
+ * non-secure context or on older Safari. Requires a document; `false` under SSR.
+ *
+ * A `true` here does not mean the copy will succeed: `execCommand` still requires the call to sit inside a user
+ * gesture, and reports its own refusal by returning `false`.
+ */
+export declare function canLegacyCopy(): boolean;

package/dist/foundation/clipboard/CopyItems.d.ts

@@ -0,0 +1,44 @@
+import { ClipboardCopyOptions, ClipboardWriteResult } from './ClipboardResult';
+/**
+ * The representations of one clipboard entry, keyed by MIME type.
+ *
+ * A `string` value is wrapped in a `Blob` of that same type before it reaches the platform. Engines accept only
+ * a small set of types — `text/plain`, `text/html`, `image/png` are the portable ones; anything else may be
+ * refused with a `failed` result.
+ *
+ * @example
+ * copyItems({ 'text/plain': 'Total: 42', 'text/html': '<b>Total:</b> 42' });
+ */
+export type ClipboardWriteItems = Readonly<Record<string, Blob | string>>;
+/**
+ * Writes several representations of one payload to the clipboard in a single entry, so the paste target can pick
+ * the richest format it understands.
+ *
+ * Needs `navigator.clipboard.write` and a `ClipboardItem` constructor — strictly newer than the `writeText`
+ * behind `copyText`, so `unsupported` is more likely here. With `legacyFallback: true` an unsupported or refused
+ * write degrades to the `text/plain` arm alone, and only when that arm is a literal string.
+ *
+ * Call it from a user gesture. Never throws, never rejects.
+ *
+ * @param items The representations, keyed by MIME type. An empty object resolves to `failed` — a write with no
+ *   payload is a caller mistake, and reporting it as `copied` would claim something reached the clipboard.
+ * @param options Error reporting and the legacy-fallback opt-in.
+ */
+export declare function copyItems(items: ClipboardWriteItems, options?: ClipboardCopyOptions): Promise<ClipboardWriteResult>;
+/**
+ * Writes a single binary payload — a generated image, a canvas export, a downloaded file — to the clipboard.
+ *
+ * The single-format case of {@link copyItems}, and subject to the same support: it needs
+ * `navigator.clipboard.write`, and the legacy fallback cannot serve it (`execCommand` writes text only).
+ *
+ * Engines accept a narrow set of types for binary payloads; `image/png` is the portable one. A type the platform
+ * refuses comes back `failed`.
+ *
+ * Never throws, never rejects.
+ *
+ * @param blob The payload.
+ * @param mimeType The type to write it under. Defaults to the blob's own `type`, then to
+ *   `application/octet-stream` — which most engines refuse, so pass a real type for a typeless blob.
+ * @param options Error reporting. `legacyFallback` has no effect here.
+ */
+export declare function copyBlob(blob: Blob, mimeType?: string, options?: ClipboardCopyOptions): Promise<ClipboardWriteResult>;

package/dist/foundation/clipboard/CopyText.d.ts

@@ -0,0 +1,16 @@
+import { ClipboardCopyOptions, ClipboardWriteResult } from './ClipboardResult';
+/**
+ * Writes `text` to the system clipboard.
+ *
+ * Call it from a user gesture: browsers require transient activation for a clipboard write, and without one the
+ * platform refuses — which surfaces as `denied`, not `unsupported`, since the API was in fact present.
+ *
+ * Resolves to `unsupported` under SSR, in a non-secure context, and on engines with no Clipboard API. Pass
+ * `legacyFallback: true` to retry those through the deprecated `document.execCommand` path.
+ *
+ * Never throws, never rejects.
+ *
+ * @param text The text to place on the clipboard. An empty string is a valid payload — it clears the clipboard.
+ * @param options Error reporting and the legacy-fallback opt-in.
+ */
+export declare function copyText(text: string, options?: ClipboardCopyOptions): Promise<ClipboardWriteResult>;