@wow-two-beta/ui-vue 0.0.2

package/dist/foundation/animation/Flip.d.ts

@@ -0,0 +1,90 @@
+import { AnimateOptions, AnimationHandle } from './Animate';
+/**
+ * A geometry snapshot — the fields of a `DOMRect` this slice actually uses. Deliberately a plain readonly
+ * object rather than a `DOMRect`: it is structurally comparable, serializable, and constructible by hand in a
+ * node test without a layout engine.
+ */
+export interface RectLike {
+    /** Distance from the viewport's left edge, in pixels. */
+    readonly x: number;
+    /** Distance from the viewport's top edge, in pixels. */
+    readonly y: number;
+    /** Border-box width in pixels. */
+    readonly width: number;
+    /** Border-box height in pixels. */
+    readonly height: number;
+}
+/** The "Invert" step's output — the transform that maps the element's new box back onto its old one. */
+export interface FlipTransform {
+    /** Horizontal offset in pixels (old left minus new left). */
+    readonly translateX: number;
+    /** Vertical offset in pixels (old top minus new top). */
+    readonly translateY: number;
+    /** Horizontal scale factor (old width over new width). `1` when the width did not change. */
+    readonly scaleX: number;
+    /** Vertical scale factor (old height over new height). `1` when the height did not change. */
+    readonly scaleY: number;
+}
+/** Tunes a FLIP play. A subset of `AnimateOptions` — `fill`/`delay`/`iterations` are fixed by the technique. */
+export type FlipOptions = Pick<AnimateOptions, 'duration' | 'easing' | 'reducedMotion'>;
+/** The transform of an element that did not move or resize — the no-op FLIP. */
+export declare const IDENTITY_FLIP_TRANSFORM: FlipTransform;
+/**
+ * Snapshots an element's current viewport geometry — the "First" (and, inside `playFlip`, the "Last") step.
+ *
+ * Reads `left`/`top` rather than `x`/`y`: they are identical for a `getBoundingClientRect()` result (which is
+ * never negative-width) and are present on every host and on hand-rolled test doubles.
+ *
+ * @param element The node to measure. `null`/`undefined` or a node without the method (SSR) yields `null`.
+ * @returns A plain rect snapshot, or `null` when there is nothing measurable.
+ */
+export declare function measureRect(element: Element | null | undefined): RectLike | null;
+/**
+ * The "Invert" step, and the whole of the FLIP algorithm: the transform that visually returns an element from
+ * its `last` box to its `first` box. Pure — no DOM, no side effects, safe in node.
+ *
+ * Every result field is finite. Non-finite inputs and a zero-size `last` fall back to the identity component
+ * (`0` for a translate, `1` for a scale) rather than propagating `Infinity`/`NaN` into a CSS transform.
+ *
+ * @param first Geometry before the layout change.
+ * @param last Geometry after the layout change.
+ * @returns The inverting translate + scale.
+ */
+export declare function computeFlipTransform(first: RectLike, last: RectLike): FlipTransform;
+/**
+ * Whether a transform is close enough to identity that playing it would be a wasted animation.
+ *
+ * @param transform The computed invert.
+ * @param epsilon Tolerance for sub-pixel layout noise. Defaults to `0.01`.
+ * @returns `true` when the element effectively did not move or resize.
+ */
+export declare function isIdentityFlip(transform: FlipTransform, epsilon?: number): boolean;
+/**
+ * Renders a transform as a CSS `transform` value — `translate(…px, …px) scale(…, …)`.
+ *
+ * Translate precedes scale on purpose: CSS applies transform functions left to right, so the element is moved
+ * in its own untransformed coordinate space and the scale then pivots at `transform-origin` (`top left`).
+ * Reversing them would scale the translation distance too.
+ *
+ * @param transform The computed invert.
+ * @returns The CSS value string.
+ */
+export declare function formatFlipTransform(transform: FlipTransform): string;
+/**
+ * The "Last / Invert / Play" half of FLIP: measures where `element` is NOW, computes the transform back to
+ * `first`, and animates that transform away to identity.
+ *
+ * Call it after the DOM change has been committed but before paint (a layout effect) — see `useFlip`.
+ *
+ * Returns a no-op handle, animating nothing, when: the element or `first` is missing; the element cannot be
+ * measured; the element did not effectively move (`isIdentityFlip`); or motion is off (`reducedMotion`, or a
+ * `duration` of `0`). That last case is the correct reduced-motion outcome for a LAYOUT animation — the DOM is
+ * ALREADY in its final state, so doing nothing IS jumping to the final state. Unlike `animate`, no final
+ * keyframe is committed inline, precisely so the element is left with no `transform` residue.
+ *
+ * @param element The node whose layout changed.
+ * @param first The geometry snapshot taken before the change.
+ * @param options Duration, easing, and the reduced-motion switch.
+ * @returns A handle for the play, settled immediately when nothing was animated.
+ */
+export declare function playFlip(element: Element | null | undefined, first: RectLike | null | undefined, options?: FlipOptions): AnimationHandle;

package/dist/foundation/animation/UseFlip.d.ts

@@ -0,0 +1,22 @@
+import { MaybeRefOrGetter, WatchSource } from 'vue';
+import { FlipOptions } from './Flip';
+/** Tunes a `useFlip` binding. Same knobs as `playFlip`, plus an on/off switch for the whole binding. */
+export interface UseFlipOptions extends FlipOptions {
+    /** Whether the binding animates at all. `false` still keeps the snapshot current. Defaults to `true`. */
+    readonly enabled?: boolean;
+}
+/**
+ * FLIP-animates a single element across a layout-affecting change.
+ *
+ * Pass the sources that cause the change (the sort key, the collapsed flag, the filter). On every change the
+ * composable animates the element from where it was in the previous commit to where it is now, before the
+ * browser paints.
+ *
+ * Takes the element as a ref or getter rather than handing one back, so a `useTemplateRef` drops straight in.
+ * SSR-safe: nothing is measured until `onMounted`.
+ *
+ * @param target The element whose layout changes.
+ * @param deps The watch source(s) whose change signals "the layout just moved".
+ * @param options Duration, easing, the reduced-motion override, and `enabled`. Read at play time.
+ */
+export declare function useFlip<T extends Element = HTMLElement>(target: MaybeRefOrGetter<T | null | undefined>, deps: WatchSource | readonly WatchSource[], options?: MaybeRefOrGetter<UseFlipOptions>): void;

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

@@ -0,0 +1,4 @@
+export { animate, applyFinalKeyframe, noopAnimationHandle, ANIMATION_DEFAULTS, type AnimateOptions, type AnimationHandle, type AnimationKeyframes, } from './Animate';
+export { measureRect, computeFlipTransform, isIdentityFlip, formatFlipTransform, playFlip, IDENTITY_FLIP_TRANSFORM, type FlipOptions, type FlipTransform, type RectLike, } from './Flip';
+export { useFlip, type UseFlipOptions } from './UseFlip';
+export { AnimatedLayout, type AnimatedLayoutProps } from './AnimatedLayout';

package/dist/foundation/animation/index.js

@@ -0,0 +1,241 @@
+import { T as TransitionExtensions } from "../../chunks/TransitionExtensions-hFi80JX2.js";
+import { onMounted, watch, onScopeDispose, toValue, defineComponent, ref, onUpdated, h, cloneVNode } from "vue";
+import { u as useReducedMotion } from "../../chunks/useReducedMotion-B9LqQ3UT.js";
+const ANIMATION_DEFAULTS = {
+  /** Default run length in milliseconds. */
+  duration: TransitionExtensions.duration.default,
+  /** Default easing curve — Tailwind `ease-out`. */
+  easing: "cubic-bezier(0, 0, 0.2, 1)"
+};
+const NON_STYLE_KEYFRAME_KEYS = /* @__PURE__ */ new Set(["offset", "easing", "composite"]);
+const noop = () => {
+};
+function noopAnimationHandle() {
+  return { finished: Promise.resolve(), cancel: noop, finish: noop, pause: noop, play: noop };
+}
+function inlineStyleOf(element) {
+  const styled = element;
+  return styled.style ?? null;
+}
+function setStyleProperty(style, property, value) {
+  if (property.includes("-")) {
+    style.setProperty(property, value);
+    return;
+  }
+  style[property] = value;
+}
+function lastValueOf(value) {
+  return Array.isArray(value) ? value.at(-1) : value;
+}
+function applyFinalKeyframe(element, keyframes) {
+  const style = inlineStyleOf(element);
+  if (!style) return;
+  if (Array.isArray(keyframes)) {
+    const last = keyframes.at(-1);
+    if (!last) return;
+    for (const [property, value] of Object.entries(last)) {
+      if (NON_STYLE_KEYFRAME_KEYS.has(property) || value === null || value === void 0) continue;
+      setStyleProperty(style, property, String(value));
+    }
+    return;
+  }
+  for (const [property, value] of Object.entries(keyframes)) {
+    if (NON_STYLE_KEYFRAME_KEYS.has(property)) continue;
+    const resolved = lastValueOf(value);
+    if (resolved === null || resolved === void 0) continue;
+    setStyleProperty(style, property, String(resolved));
+  }
+}
+function animate(element, keyframes, options = {}) {
+  if (!element) return noopAnimationHandle();
+  const {
+    duration = ANIMATION_DEFAULTS.duration,
+    easing = ANIMATION_DEFAULTS.easing,
+    delay = 0,
+    fill = "none",
+    iterations = 1,
+    reducedMotion = false
+  } = options;
+  if (reducedMotion || duration <= 0 || typeof element.animate !== "function") {
+    applyFinalKeyframe(element, keyframes);
+    return noopAnimationHandle();
+  }
+  const animation = element.animate(keyframes, { duration, easing, delay, fill, iterations });
+  const finished = new Promise((resolve) => {
+    const settle = () => resolve();
+    animation.addEventListener("finish", settle, { once: true });
+    animation.addEventListener("cancel", settle, { once: true });
+    animation.addEventListener("remove", settle, { once: true });
+  });
+  return {
+    finished,
+    cancel: () => animation.cancel(),
+    finish: () => {
+      try {
+        animation.finish();
+      } catch {
+      }
+    },
+    pause: () => animation.pause(),
+    play: () => animation.play()
+  };
+}
+const IDENTITY_FLIP_TRANSFORM = {
+  translateX: 0,
+  translateY: 0,
+  scaleX: 1,
+  scaleY: 1
+};
+const FLIP_EPSILON = 0.01;
+function finiteOr(value, fallback) {
+  return Number.isFinite(value) ? value : fallback;
+}
+function safeScale(firstSize, lastSize) {
+  if (!Number.isFinite(firstSize) || !Number.isFinite(lastSize) || lastSize === 0) return 1;
+  return finiteOr(firstSize / lastSize, 1);
+}
+function measureRect(element) {
+  if (!element || typeof element.getBoundingClientRect !== "function") return null;
+  const rect = element.getBoundingClientRect();
+  return { x: rect.left, y: rect.top, width: rect.width, height: rect.height };
+}
+function computeFlipTransform(first, last) {
+  return {
+    translateX: finiteOr(first.x - last.x, 0),
+    translateY: finiteOr(first.y - last.y, 0),
+    scaleX: safeScale(first.width, last.width),
+    scaleY: safeScale(first.height, last.height)
+  };
+}
+function isIdentityFlip(transform, epsilon = FLIP_EPSILON) {
+  return Math.abs(transform.translateX) < epsilon && Math.abs(transform.translateY) < epsilon && Math.abs(transform.scaleX - 1) < epsilon && Math.abs(transform.scaleY - 1) < epsilon;
+}
+function formatFlipTransform(transform) {
+  const { translateX, translateY, scaleX, scaleY } = transform;
+  return `translate(${translateX}px, ${translateY}px) scale(${scaleX}, ${scaleY})`;
+}
+function playFlip(element, first, options = {}) {
+  if (!element || !first) return noopAnimationHandle();
+  if (options.reducedMotion || options.duration !== void 0 && options.duration <= 0) {
+    return noopAnimationHandle();
+  }
+  const last = measureRect(element);
+  if (!last) return noopAnimationHandle();
+  const transform = computeFlipTransform(first, last);
+  if (isIdentityFlip(transform)) return noopAnimationHandle();
+  const inverted = formatFlipTransform(transform);
+  return animate(
+    element,
+    [
+      { transform: inverted, transformOrigin: "top left" },
+      { transform: "none", transformOrigin: "top left" }
+    ],
+    { duration: options.duration, easing: options.easing, fill: "none" }
+  );
+}
+function useFlip(target, deps, options = {}) {
+  const prefersReducedMotion = useReducedMotion();
+  let previousRect = null;
+  let handle = null;
+  function cancel() {
+    handle?.cancel();
+    handle = null;
+  }
+  function snapshotAndPlay() {
+    const element = toValue(target);
+    if (!element) return;
+    cancel();
+    const last = measureRect(element);
+    const first = previousRect;
+    previousRect = last;
+    const { enabled = true, reducedMotion, ...flip } = toValue(options);
+    if (!enabled || !first) return;
+    handle = playFlip(element, first, {
+      ...flip,
+      reducedMotion: reducedMotion ?? prefersReducedMotion.value
+    });
+  }
+  onMounted(snapshotAndPlay);
+  watch(deps, snapshotAndPlay, { flush: "post" });
+  onScopeDispose(cancel);
+}
+const FLIP_KEY_ATTRIBUTE = "data-flip-key";
+const AnimatedLayout = defineComponent({
+  name: "AnimatedLayout",
+  props: {
+    /** Whether layout animation is active. Defaults to `true`. */
+    enabled: { type: Boolean, default: true },
+    /** Animation duration in milliseconds. Falls through to `playFlip`. */
+    duration: { type: Number, default: void 0 },
+    /** Timing function. Falls through to `playFlip`. */
+    easing: { type: String, default: void 0 },
+    /** Forces the reduced-motion branch either way, overriding the media query. */
+    reducedMotion: { type: Boolean, default: void 0 }
+  },
+  slots: Object,
+  setup(props, { slots }) {
+    const container = ref(null);
+    const rects = /* @__PURE__ */ new Map();
+    const prefersReducedMotion = useReducedMotion();
+    let handles = [];
+    function cancel() {
+      for (const handle of handles) handle.cancel();
+      handles = [];
+    }
+    function measureAndPlay() {
+      const element = container.value;
+      if (!element) return;
+      cancel();
+      const measured = [];
+      for (const child of Array.from(element.children)) {
+        const key = child.getAttribute(FLIP_KEY_ATTRIBUTE);
+        if (key === null) continue;
+        const rect = measureRect(child);
+        if (rect) measured.push({ element: child, key, rect });
+      }
+      const previous = new Map(rects);
+      rects.clear();
+      for (const { key, rect } of measured) rects.set(key, rect);
+      if (!props.enabled) return;
+      for (const { element: child, key } of measured) {
+        const first = previous.get(key);
+        if (!first) continue;
+        handles.push(
+          playFlip(child, first, {
+            duration: props.duration,
+            easing: props.easing,
+            reducedMotion: props.reducedMotion ?? prefersReducedMotion.value
+          })
+        );
+      }
+    }
+    onMounted(measureAndPlay);
+    onUpdated(measureAndPlay);
+    onScopeDispose(cancel);
+    return () => {
+      const children = slots.default?.() ?? [];
+      return h(
+        "div",
+        { ref: container },
+        children.map(
+          (child, index) => cloneVNode(child, { [FLIP_KEY_ATTRIBUTE]: String(child.key ?? index) })
+        )
+      );
+    };
+  }
+});
+export {
+  ANIMATION_DEFAULTS,
+  AnimatedLayout,
+  IDENTITY_FLIP_TRANSFORM,
+  animate,
+  applyFinalKeyframe,
+  computeFlipTransform,
+  formatFlipTransform,
+  isIdentityFlip,
+  measureRect,
+  noopAnimationHandle,
+  playFlip,
+  useFlip
+};
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/foundation/animation/Animate.ts","../../../src/foundation/animation/Flip.ts","../../../src/foundation/animation/UseFlip.ts","../../../src/foundation/animation/AnimatedLayout.ts"],"sourcesContent":["// The WAAPI seam of the animation vector — one way to start an animation, one handle shape to control it.\n//\n// WHY a wrapper at all, when `element.animate()` already exists:\n//\n//  - THREE FAILURE MODES COLLAPSE INTO ONE PATH. A null element (SSR, an unattached ref), a host without WAAPI\n//    (Safari < 13.1, jsdom), and a reduced-motion user all want the same outcome: the state change lands, the\n//    tween does not. Each caller would otherwise re-derive that branch — and most would forget one of the three.\n//\n//  - `finished` NEVER REJECTS. The native `Animation.finished` promise rejects with an `AbortError` when the\n//    animation is cancelled, so every `await` needs a try/catch and every un-awaited handle risks an unhandled\n//    rejection. Here `finished` SETTLES — on finish, on cancel, or on browser removal — because the only thing\n//    callers actually want to know is \"the animation is no longer running, run cleanup\". It resolves `void`; a\n//    caller that must distinguish the two reads the element's state, not the promise.\n//\n//  - DURATION 0 IS THE REDUCED-MOTION CONTRACT. `reducedMotion: true` and `duration: 0` take the exact same\n//    branch: commit the final keyframe synchronously and return a settled handle. Reduced motion means \"skip the\n//    tween\", never \"skip the state change\" — an element that was going to end up opaque still ends up opaque.\n//\n// `reducedMotion` is an explicit OPTION, not a `useReducedMotion()` call inside. That keeps `animate` a pure\n// function usable outside Vue (an imperative controller, a node test) and leaves exactly one place — the\n// composable layer — that reads the media query. See `UseFlip.ts` for the Vue side that wires the two together.\n\nimport { TransitionExtensions } from '../utils';\n\n/** A keyframe list (`[{ opacity: '0' }, { opacity: '1' }]`) or a property-indexed map (`{ opacity: ['0', '1'] }`). */\nexport type AnimationKeyframes = Keyframe[] | PropertyIndexedKeyframes;\n\n/** Tunes a single `animate()` call. Mirrors the subset of `KeyframeAnimationOptions` this slice commits to. */\nexport interface AnimateOptions {\n  /** Run length in milliseconds. `0` (or less) commits the final keyframe instantly. Defaults to `200`. */\n  readonly duration?: number;\n\n  /** CSS easing function (`'ease-out'`, a `cubic-bezier(…)`). Defaults to the house ease-out curve. */\n  readonly easing?: string;\n\n  /** Milliseconds to wait before the first frame. Defaults to `0`. */\n  readonly delay?: number;\n\n  /** Whether the animated values persist outside the active window. Defaults to `'none'` — no style residue. */\n  readonly fill?: FillMode;\n\n  /** How many times the keyframes run. Defaults to `1`. */\n  readonly iterations?: number;\n\n  /** When `true`, skip the tween and commit the final keyframe immediately. Defaults to `false`. */\n  readonly reducedMotion?: boolean;\n}\n\n/** The control surface returned by every entry point in this slice. Always safe to call, even on a no-op handle. */\nexport interface AnimationHandle {\n  /**\n   * Settles when the animation stops running — finished, cancelled, or removed by the browser.\n   * Never rejects, so it is safe to `await` without a try/catch and safe to ignore entirely.\n   */\n  readonly finished: Promise<void>;\n\n  /** Stops the animation and reverts to the element's own styles. Settles `finished`. */\n  cancel(): void;\n\n  /** Jumps to the end of the animation. No-op on an infinite-iteration animation, which cannot finish. */\n  finish(): void;\n\n  /** Suspends playback at the current time. */\n  pause(): void;\n\n  /** Resumes playback (or restarts a finished animation). */\n  play(): void;\n}\n\n/**\n * Motion defaults for the slice. `duration` reuses `TransitionExtensions.duration.default` (200ms) — the\n * single existing motion constant in this codebase — so a WAAPI tween and a CSS presence transition agree.\n * `easing` mirrors Tailwind's `ease-out` (the curve `ScrollViewport` already animates with); there is no\n * easing token in `foundation/themes` to consume, so this is the slice's declaration of one.\n */\nexport const ANIMATION_DEFAULTS = {\n  /** Default run length in milliseconds. */\n  duration: TransitionExtensions.duration.default,\n  /** Default easing curve — Tailwind `ease-out`. */\n  easing: 'cubic-bezier(0, 0, 0.2, 1)',\n} as const;\n\n/** Keyframe keys that configure the frame rather than name a CSS property — never written to `style`. */\nconst NON_STYLE_KEYFRAME_KEYS: ReadonlySet<string> = new Set(['offset', 'easing', 'composite']);\n\nconst noop = (): void => {};\n\n/**\n * An already-settled handle for the paths that never start an animation (no element, no WAAPI, reduced motion,\n * a no-op FLIP). Callers branch on nothing — `await handle.finished` resolves and `cancel()` is harmless.\n */\nexport function noopAnimationHandle(): AnimationHandle {\n  return { finished: Promise.resolve(), cancel: noop, finish: noop, pause: noop, play: noop };\n}\n\n/**\n * The element's inline style declaration, or `null` for a node that has none (a bare `Element`, a text node\n * reached through a loose cast). `HTMLElement` and `SVGElement` both qualify; nothing else is assumed.\n */\nexport function inlineStyleOf(element: Element): CSSStyleDeclaration | null {\n  const styled = element as Partial<ElementCSSInlineStyle>;\n  return styled.style ?? null;\n}\n\n/** Writes one CSS property inline, routing custom (`--x`) and kebab-case names through `setProperty`. */\nfunction setStyleProperty(style: CSSStyleDeclaration, property: string, value: string): void {\n  if (property.includes('-')) {\n    style.setProperty(property, value);\n    return;\n  }\n  // camelCase names (`backgroundColor`) are accessors on the declaration, not `setProperty` keys.\n  (style as unknown as Record<string, string>)[property] = value;\n}\n\n/** Reads the last defined value of a property-indexed keyframe entry (`['0', '1']` → `'1'`; `'1'` → `'1'`). */\nfunction lastValueOf(value: string | string[] | number | null | (number | null)[] | undefined) {\n  return Array.isArray(value) ? value.at(-1) : value;\n}\n\n/**\n * Commits the final frame of `keyframes` as inline styles — the instant-jump branch shared by reduced motion,\n * `duration: 0`, and hosts without WAAPI. Frame-config keys (`offset`/`easing`/`composite`) and `null` values\n * are skipped; a `null` in a keyframe means \"use the underlying value\", which is what NOT writing achieves.\n */\nexport function applyFinalKeyframe(element: Element, keyframes: AnimationKeyframes): void {\n  const style = inlineStyleOf(element);\n  if (!style) return;\n\n  if (Array.isArray(keyframes)) {\n    const last = keyframes.at(-1);\n    if (!last) return;\n    for (const [property, value] of Object.entries(last)) {\n      if (NON_STYLE_KEYFRAME_KEYS.has(property) || value === null || value === undefined) continue;\n      setStyleProperty(style, property, String(value));\n    }\n    return;\n  }\n\n  for (const [property, value] of Object.entries(keyframes)) {\n    if (NON_STYLE_KEYFRAME_KEYS.has(property)) continue;\n    const resolved = lastValueOf(value);\n    if (resolved === null || resolved === undefined) continue;\n    setStyleProperty(style, property, String(resolved));\n  }\n}\n\n/**\n * Animates `element` through `keyframes` and returns a handle to control it.\n *\n * Falls back to committing the final keyframe instantly — with a settled handle, never a throw — when the\n * element is missing, the host has no `element.animate`, `reducedMotion` is set, or `duration` is `0`.\n *\n * @param element The target node. `null`/`undefined` (SSR, an unattached ref) yields a no-op handle.\n * @param keyframes The frames to run, in either WAAPI shape.\n * @param options Timing and the reduced-motion switch.\n * @returns A handle whose `finished` promise settles when the animation stops running.\n */\nexport function animate(\n  element: Element | null | undefined,\n  keyframes: AnimationKeyframes,\n  options: AnimateOptions = {},\n): AnimationHandle {\n  if (!element) return noopAnimationHandle();\n\n  const {\n    duration = ANIMATION_DEFAULTS.duration,\n    easing = ANIMATION_DEFAULTS.easing,\n    delay = 0,\n    fill = 'none',\n    iterations = 1,\n    reducedMotion = false,\n  } = options;\n\n  if (reducedMotion || duration <= 0 || typeof element.animate !== 'function') {\n    applyFinalKeyframe(element, keyframes);\n    return noopAnimationHandle();\n  }\n\n  const animation = element.animate(keyframes, { duration, easing, delay, fill, iterations });\n\n  // Event-based rather than `animation.finished`, whose rejection on cancel would surface as an unhandled\n  // rejection for any caller that does not await. Subscribing synchronously after `animate()` cannot miss an\n  // event — the animation is play-pending until at least the next frame.\n  const finished = new Promise<void>((resolve) => {\n    const settle = (): void => resolve();\n    animation.addEventListener('finish', settle, { once: true });\n    animation.addEventListener('cancel', settle, { once: true });\n    animation.addEventListener('remove', settle, { once: true });\n  });\n\n  return {\n    finished,\n    cancel: () => animation.cancel(),\n    finish: () => {\n      try {\n        animation.finish();\n      } catch {\n        // `finish()` throws InvalidStateError on an infinite-iteration animation, which has no end to jump to.\n      }\n    },\n    pause: () => animation.pause(),\n    play: () => animation.play(),\n  };\n}\n","// FLIP — First, Last, Invert, Play. The technique for animating a layout change that the browser has already\n// committed: snapshot the geometry BEFORE the change (\"First\"), let the change happen, measure again (\"Last\"),\n// apply the transform that visually puts the element back where it was (\"Invert\"), then animate that transform\n// away (\"Play\"). The element ends at its real layout position, and only compositor-cheap `transform` was\n// animated — never `top`/`left`/`width`, which reflow every frame.\n//\n// NON-OBVIOUS DECISIONS:\n//\n//  - THE MATH IS SEPARATE FROM THE DOM. `computeFlipTransform` takes two plain rects and returns four numbers.\n//    That is the whole algorithm, and it is exhaustively unit-testable in node with hand-built rects — no\n//    browser, no layout engine, no flake. `measureRect` and `playFlip` are the thin DOM shell around it.\n//\n//  - `transform-origin: top left`. The translate is derived from the rects' top-left corners, so the scale must\n//    pivot there too. With the CSS default (`50% 50%`) a scaled element drifts by half the size delta and the\n//    inverted frame no longer overlays the original position — the single most common FLIP bug.\n//\n//  - NO INLINE INVERT, NO CLEANUP. The inverted transform is the FIRST KEYFRAME, not an inline style. A\n//    play-pending WAAPI animation already applies its first frame in the next style recalc, so there is no\n//    unstyled flash to guard against; and with `fill: 'none'` the element is left with ZERO inline residue when\n//    the animation ends or is cancelled. The inline-then-clear variant has to race its own cleanup against a\n//    paint at the end and can strand a `transform` on the node if the handle is dropped.\n//\n//  - DIVISION IS GUARDED, ALWAYS. A \"last\" rect of zero width/height is routine — a `display: none` ancestor,\n//    an element measured mid-unmount, a collapsed flex child. Dividing by it yields `Infinity`, which becomes\n//    `scale(Infinity)`, which WAAPI rejects. Every ratio here falls back to `1` unless it is finite.\n\nimport {\n  animate,\n  noopAnimationHandle,\n  type AnimateOptions,\n  type AnimationHandle,\n} from './Animate';\n\n/**\n * A geometry snapshot — the fields of a `DOMRect` this slice actually uses. Deliberately a plain readonly\n * object rather than a `DOMRect`: it is structurally comparable, serializable, and constructible by hand in a\n * node test without a layout engine.\n */\nexport interface RectLike {\n  /** Distance from the viewport's left edge, in pixels. */\n  readonly x: number;\n  /** Distance from the viewport's top edge, in pixels. */\n  readonly y: number;\n  /** Border-box width in pixels. */\n  readonly width: number;\n  /** Border-box height in pixels. */\n  readonly height: number;\n}\n\n/** The \"Invert\" step's output — the transform that maps the element's new box back onto its old one. */\nexport interface FlipTransform {\n  /** Horizontal offset in pixels (old left minus new left). */\n  readonly translateX: number;\n  /** Vertical offset in pixels (old top minus new top). */\n  readonly translateY: number;\n  /** Horizontal scale factor (old width over new width). `1` when the width did not change. */\n  readonly scaleX: number;\n  /** Vertical scale factor (old height over new height). `1` when the height did not change. */\n  readonly scaleY: number;\n}\n\n/** Tunes a FLIP play. A subset of `AnimateOptions` — `fill`/`delay`/`iterations` are fixed by the technique. */\nexport type FlipOptions = Pick<AnimateOptions, 'duration' | 'easing' | 'reducedMotion'>;\n\n/** The transform of an element that did not move or resize — the no-op FLIP. */\nexport const IDENTITY_FLIP_TRANSFORM: FlipTransform = {\n  translateX: 0,\n  translateY: 0,\n  scaleX: 1,\n  scaleY: 1,\n};\n\n/** Below this, a translate (px) or a scale delta is invisible and not worth an animation. */\nconst FLIP_EPSILON = 0.01;\n\n/** Returns `value` when it is a usable number, else `fallback` — the guard every rect field passes through. */\nfunction finiteOr(value: number, fallback: number): number {\n  return Number.isFinite(value) ? value : fallback;\n}\n\n/**\n * Old size over new size, guarded. Returns `1` whenever the ratio would not be a finite number — a zero-size\n * \"last\" rect (collapsed/hidden element) would otherwise produce `Infinity`, and a `NaN` input `NaN`.\n */\nfunction safeScale(firstSize: number, lastSize: number): number {\n  if (!Number.isFinite(firstSize) || !Number.isFinite(lastSize) || lastSize === 0) return 1;\n  return finiteOr(firstSize / lastSize, 1);\n}\n\n/**\n * Snapshots an element's current viewport geometry — the \"First\" (and, inside `playFlip`, the \"Last\") step.\n *\n * Reads `left`/`top` rather than `x`/`y`: they are identical for a `getBoundingClientRect()` result (which is\n * never negative-width) and are present on every host and on hand-rolled test doubles.\n *\n * @param element The node to measure. `null`/`undefined` or a node without the method (SSR) yields `null`.\n * @returns A plain rect snapshot, or `null` when there is nothing measurable.\n */\nexport function measureRect(element: Element | null | undefined): RectLike | null {\n  if (!element || typeof element.getBoundingClientRect !== 'function') return null;\n  const rect = element.getBoundingClientRect();\n  return { x: rect.left, y: rect.top, width: rect.width, height: rect.height };\n}\n\n/**\n * The \"Invert\" step, and the whole of the FLIP algorithm: the transform that visually returns an element from\n * its `last` box to its `first` box. Pure — no DOM, no side effects, safe in node.\n *\n * Every result field is finite. Non-finite inputs and a zero-size `last` fall back to the identity component\n * (`0` for a translate, `1` for a scale) rather than propagating `Infinity`/`NaN` into a CSS transform.\n *\n * @param first Geometry before the layout change.\n * @param last Geometry after the layout change.\n * @returns The inverting translate + scale.\n */\nexport function computeFlipTransform(first: RectLike, last: RectLike): FlipTransform {\n  return {\n    translateX: finiteOr(first.x - last.x, 0),\n    translateY: finiteOr(first.y - last.y, 0),\n    scaleX: safeScale(first.width, last.width),\n    scaleY: safeScale(first.height, last.height),\n  };\n}\n\n/**\n * Whether a transform is close enough to identity that playing it would be a wasted animation.\n *\n * @param transform The computed invert.\n * @param epsilon Tolerance for sub-pixel layout noise. Defaults to `0.01`.\n * @returns `true` when the element effectively did not move or resize.\n */\nexport function isIdentityFlip(transform: FlipTransform, epsilon: number = FLIP_EPSILON): boolean {\n  return (\n    Math.abs(transform.translateX) < epsilon &&\n    Math.abs(transform.translateY) < epsilon &&\n    Math.abs(transform.scaleX - 1) < epsilon &&\n    Math.abs(transform.scaleY - 1) < epsilon\n  );\n}\n\n/**\n * Renders a transform as a CSS `transform` value — `translate(…px, …px) scale(…, …)`.\n *\n * Translate precedes scale on purpose: CSS applies transform functions left to right, so the element is moved\n * in its own untransformed coordinate space and the scale then pivots at `transform-origin` (`top left`).\n * Reversing them would scale the translation distance too.\n *\n * @param transform The computed invert.\n * @returns The CSS value string.\n */\nexport function formatFlipTransform(transform: FlipTransform): string {\n  const { translateX, translateY, scaleX, scaleY } = transform;\n  return `translate(${translateX}px, ${translateY}px) scale(${scaleX}, ${scaleY})`;\n}\n\n/**\n * The \"Last / Invert / Play\" half of FLIP: measures where `element` is NOW, computes the transform back to\n * `first`, and animates that transform away to identity.\n *\n * Call it after the DOM change has been committed but before paint (a layout effect) — see `useFlip`.\n *\n * Returns a no-op handle, animating nothing, when: the element or `first` is missing; the element cannot be\n * measured; the element did not effectively move (`isIdentityFlip`); or motion is off (`reducedMotion`, or a\n * `duration` of `0`). That last case is the correct reduced-motion outcome for a LAYOUT animation — the DOM is\n * ALREADY in its final state, so doing nothing IS jumping to the final state. Unlike `animate`, no final\n * keyframe is committed inline, precisely so the element is left with no `transform` residue.\n *\n * @param element The node whose layout changed.\n * @param first The geometry snapshot taken before the change.\n * @param options Duration, easing, and the reduced-motion switch.\n * @returns A handle for the play, settled immediately when nothing was animated.\n */\nexport function playFlip(\n  element: Element | null | undefined,\n  first: RectLike | null | undefined,\n  options: FlipOptions = {},\n): AnimationHandle {\n  if (!element || !first) return noopAnimationHandle();\n  if (options.reducedMotion || (options.duration !== undefined && options.duration <= 0)) {\n    return noopAnimationHandle();\n  }\n\n  const last = measureRect(element);\n  if (!last) return noopAnimationHandle();\n\n  const transform = computeFlipTransform(first, last);\n  if (isIdentityFlip(transform)) return noopAnimationHandle();\n\n  const inverted = formatFlipTransform(transform);\n  return animate(\n    element,\n    [\n      { transform: inverted, transformOrigin: 'top left' },\n      { transform: 'none', transformOrigin: 'top left' },\n    ],\n    { duration: options.duration, easing: options.easing, fill: 'none' },\n  );\n}\n","// The Vue binding for FLIP: snapshot geometry across an update, animate the difference.\n//\n// WHY `flush: 'post'` AND NOT A DEFAULT WATCHER — this is the whole reason the composable exists:\n//\n//   A pre-flush watcher runs BEFORE Vue patches the DOM, so a rect measured there is the OLD box and the FLIP\n//   has nothing to invert. A `flush: 'post'` watcher runs after the patch but still inside the same tick, so\n//   the invert lands in the same frame as the layout change and the first thing the user sees is the\n//   animation's first frame. This is the exact counterpart of the original's `useLayoutEffect`: post-commit,\n//   pre-paint. There is no correct pre-flush version of this composable.\n//\n// HOW THE SNAPSHOT SURVIVES THE UPDATE: there is no \"before the change\" callback. Instead the composable\n// measures at the END of every run and keeps that rect in a closure variable. On the next `deps` change the\n// variable still holds the PREVIOUS commit's geometry — that is \"First\" — and a fresh measurement is \"Last\".\n// So the snapshot is always one commit old by construction, which is exactly what FLIP wants.\n//\n// `onMounted` SEEDS THE FIRST SNAPSHOT and animates nothing: a mount is an enter transition, which is\n// `foundation/primitives`' `Presence`, not this slice. It is also why nothing here runs in an immediate\n// watcher — `measureRect` reads the element's box, and there is no element on the server.\n//\n// Reduced motion is read here (`useReducedMotion`) rather than inside `playFlip`, keeping the pure layer\n// Vue-free. An explicit `reducedMotion` option still wins, so a consumer can force either behaviour.\n\nimport {\n  onMounted,\n  onScopeDispose,\n  toValue,\n  watch,\n  type MaybeRefOrGetter,\n  type WatchSource,\n} from 'vue';\n\nimport { useReducedMotion } from '../hooks';\n\nimport type { AnimationHandle } from './Animate';\nimport { measureRect, playFlip, type FlipOptions, type RectLike } from './Flip';\n\n/** Tunes a `useFlip` binding. Same knobs as `playFlip`, plus an on/off switch for the whole binding. */\nexport interface UseFlipOptions extends FlipOptions {\n  /** Whether the binding animates at all. `false` still keeps the snapshot current. Defaults to `true`. */\n  readonly enabled?: boolean;\n}\n\n/**\n * FLIP-animates a single element across a layout-affecting change.\n *\n * Pass the sources that cause the change (the sort key, the collapsed flag, the filter). On every change the\n * composable animates the element from where it was in the previous commit to where it is now, before the\n * browser paints.\n *\n * Takes the element as a ref or getter rather than handing one back, so a `useTemplateRef` drops straight in.\n * SSR-safe: nothing is measured until `onMounted`.\n *\n * @param target The element whose layout changes.\n * @param deps The watch source(s) whose change signals \"the layout just moved\".\n * @param options Duration, easing, the reduced-motion override, and `enabled`. Read at play time.\n */\nexport function useFlip<T extends Element = HTMLElement>(\n  target: MaybeRefOrGetter<T | null | undefined>,\n  deps: WatchSource | readonly WatchSource[],\n  options: MaybeRefOrGetter<UseFlipOptions> = {},\n): void {\n  const prefersReducedMotion = useReducedMotion();\n\n  let previousRect: RectLike | null = null;\n  let handle: AnimationHandle | null = null;\n\n  function cancel(): void {\n    handle?.cancel();\n    handle = null;\n  }\n\n  function snapshotAndPlay(): void {\n    const element = toValue(target);\n    if (!element) return;\n\n    cancel();\n\n    // Measure BEFORE playing: `playFlip` re-reads the same (still-clean) layout, and doing it in this order\n    // means the stored snapshot is the element's real post-change box, never a transformed one.\n    const last = measureRect(element);\n    const first = previousRect;\n    previousRect = last;\n\n    const { enabled = true, reducedMotion, ...flip } = toValue(options);\n    if (!enabled || !first) return;\n\n    handle = playFlip(element, first, {\n      ...flip,\n      reducedMotion: reducedMotion ?? prefersReducedMotion.value,\n    });\n  }\n\n  // Seeds the first snapshot without animating — and keeps every DOM read off the server.\n  onMounted(snapshotAndPlay);\n  // `deps` is the consumer's own list: it names the state whose change moves the element. `target` and the\n  // options are read through `toValue` precisely so they cannot (and must not) widen it.\n  watch(deps as WatchSource | WatchSource[], snapshotAndPlay, { flush: 'post' });\n  onScopeDispose(cancel);\n}\n","// The multi-child FLIP: a container that animates its children to their new positions whenever their order or\n// count changes. List reordering, filtering, sorting, drag-drop settle.\n//\n// AUTHORED AS `defineComponent` IN PLAIN TS, not as an SFC, because its whole job is vnode manipulation — it\n// clones each slot child to stamp an identity attribute on it, which a template cannot express. Same shape as\n// `foundation/primitives`' `Slot` / `Presence`.\n//\n// DELIBERATELY SMALL. It is `useFlip`'s loop, not a layout engine — no enter/exit choreography, no shared-element\n// transitions, no spring physics. Children that mount or unmount simply appear/disappear at their final spot\n// (`Presence` is the primitive for enter/exit); only the SURVIVING children are animated, which is precisely the\n// case CSS cannot do at all.\n//\n// NON-OBVIOUS DECISIONS:\n//\n//  - IDENTITY COMES FROM `key`, NOT DOM ORDER. Order is the thing that changes, so a positional index cannot\n//    identify a child across updates. Each child vnode is cloned with a `data-flip-key` carrying its Vue key,\n//    and rects are stored in a `Map` under it. The cost: a child must let unknown attributes fall through to\n//    its DOM node — intrinsic elements (`<li>`, `<div>`) do this for free, a component must keep the default\n//    `inheritAttrs: true` and render a single root. An unkeyed child gets a positional key and so is not\n//    tracked across a reorder; that is inherent (Vue cannot track it either), not a gap to fix here.\n//\n//  - THE TRIGGER IS `onUpdated`, NOT A WATCHER. The trigger is \"the children rendered differently\", which is\n//    not expressible as a watch source — comparing children by value each update costs more than the two\n//    `getBoundingClientRect` reads the hook does, and `playFlip` short-circuits when nothing moved. `onMounted`\n//    and `onUpdated` both run after the patch and before paint, which is what FLIP requires.\n//\n//  - MEASURE ALL, THEN PLAY ALL. Two passes, not one interleaved loop: starting an animation on child 1 dirties\n//    style state, so measuring child 2 afterwards would force a fresh layout recalc per child (layout thrash on\n//    a long list).\n\nimport {\n  cloneVNode,\n  defineComponent,\n  h,\n  onMounted,\n  onScopeDispose,\n  onUpdated,\n  ref,\n  type PropType,\n  type SlotsType,\n  type StyleValue,\n  type VNode,\n} from 'vue';\n\nimport { useReducedMotion } from '../hooks';\n\nimport type { AnimationHandle } from './Animate';\nimport { measureRect, playFlip, type FlipOptions, type RectLike } from './Flip';\n\n/** The attribute carrying each child's Vue key onto its DOM node, so rects survive a reorder. */\nconst FLIP_KEY_ATTRIBUTE = 'data-flip-key';\n\n/** Props for `AnimatedLayout`. */\nexport interface AnimatedLayoutProps extends FlipOptions {\n  /** Whether layout animation is active. Defaults to `true`. */\n  readonly enabled?: boolean;\n\n  /** Class for the container element. */\n  readonly class?: unknown;\n\n  /** Inline styles for the container element. */\n  readonly style?: StyleValue;\n}\n\n/**\n * FLIP-animates its children to their new positions when the list reorders, filters, or resizes.\n *\n * Renders one plain `<div>` wrapper and clones each slot child with a `data-flip-key`; all layout (flex, grid,\n * list) stays with the consumer via `class` / `style`, which fall through as ordinary attributes.\n *\n * Under `prefers-reduced-motion` — or `:enabled=\"false\"`, or an explicit `reducedMotion` — children jump\n * straight to their new positions with no transform applied and no residue left behind.\n */\nexport const AnimatedLayout = defineComponent({\n  name: 'AnimatedLayout',\n\n  props: {\n    /** Whether layout animation is active. Defaults to `true`. */\n    enabled: { type: Boolean, default: true },\n    /** Animation duration in milliseconds. Falls through to `playFlip`. */\n    duration: { type: Number, default: undefined },\n    /** Timing function. Falls through to `playFlip`. */\n    easing: { type: String, default: undefined },\n    /** Forces the reduced-motion branch either way, overriding the media query. */\n    reducedMotion: { type: Boolean as PropType<boolean | undefined>, default: undefined },\n  },\n\n  slots: Object as SlotsType<{ default?: () => VNode[] }>,\n\n  setup(props, { slots }) {\n    const container = ref<HTMLDivElement | null>(null);\n    const rects = new Map<string, RectLike>();\n    const prefersReducedMotion = useReducedMotion();\n\n    let handles: AnimationHandle[] = [];\n\n    function cancel(): void {\n      for (const handle of handles) handle.cancel();\n      handles = [];\n    }\n\n    function measureAndPlay(): void {\n      const element = container.value;\n      if (!element) return;\n\n      cancel();\n\n      // Pass 1 — measure every tracked child while layout is still clean.\n      const measured: Array<{ element: Element; key: string; rect: RectLike }> = [];\n      for (const child of Array.from(element.children)) {\n        const key = child.getAttribute(FLIP_KEY_ATTRIBUTE);\n        if (key === null) continue;\n        const rect = measureRect(child);\n        if (rect) measured.push({ element: child, key, rect });\n      }\n\n      const previous = new Map(rects);\n      rects.clear();\n      for (const { key, rect } of measured) rects.set(key, rect);\n\n      if (!props.enabled) return;\n\n      // Pass 2 — play. A child with no previous rect is new; it stays put at its final position.\n      for (const { element: child, key } of measured) {\n        const first = previous.get(key);\n        if (!first) continue;\n        handles.push(\n          playFlip(child, first, {\n            duration: props.duration,\n            easing: props.easing,\n            reducedMotion: props.reducedMotion ?? prefersReducedMotion.value,\n          }),\n        );\n      }\n    }\n\n    // Both run after the patch and before paint — the two seams a FLIP can legally measure in.\n    onMounted(measureAndPlay);\n    onUpdated(measureAndPlay);\n    onScopeDispose(cancel);\n\n    return () => {\n      const children = slots.default?.() ?? [];\n      return h(\n        'div',\n        { ref: container },\n        children.map((child, index) =>\n          cloneVNode(child, { [FLIP_KEY_ATTRIBUTE]: String(child.key ?? index) }),\n        ),\n      );\n    };\n  },\n});\n"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,33 @@
+/**
+ * The cancellation error every helper in this slice rejects with. Named `AbortError` so `isAbortError`
+ * from `foundation/errors` recognizes it.
+ *
+ * Prefer `isAbortError(caught)` over `caught instanceof AbortError`: a cancellation that originates in
+ * `fetch` is a `DOMException`, not this class, and only the name-keyed recognizer catches both.
+ */
+export declare class AbortError extends Error {
+    /** Creates a cancellation error; pass `cause` to preserve the signal's abort reason. */
+    constructor(message?: string, options?: ErrorOptions);
+}
+/**
+ * Builds the {@link AbortError} for a fired signal, preserving `signal.reason` as `cause`. Internal to the
+ * slice; not barrelled — consumers construct {@link AbortError} directly.
+ */
+export declare function abortErrorFor(signal: AbortSignal): AbortError;
+/**
+ * Races a promise against a signal, rejecting with an {@link AbortError} the moment the signal fires.
+ *
+ * An already-aborted signal rejects without attaching a listener. The abort listener is removed on every
+ * exit path. Remember the header's warning: `promise` keeps running after an abort — its eventual result
+ * is dropped.
+ */
+export declare function abortable<T>(promise: PromiseLike<T>, signal?: AbortSignal): Promise<T>;
+/**
+ * Runs `fn` under a signal, handing it the signal so it can cancel the underlying work for real, and
+ * rejecting with an {@link AbortError} if the signal fires first.
+ *
+ * The preferred entry point over {@link abortable}: `fn` is never invoked at all when the signal is
+ * already aborted, so no work starts that is known to be unwanted. A synchronous throw from `fn` surfaces
+ * as a rejection, never as a synchronous throw at the call site.
+ */
+export declare function withAbort<T>(signal: AbortSignal, fn: (signal: AbortSignal) => PromiseLike<T> | T): Promise<T>;

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

@@ -0,0 +1,17 @@
+/**
+ * Runs `tasks` one at a time, in order, resolving to their results in that same order.
+ *
+ * STOPS AT THE FIRST FAILURE: the rejecting task's error propagates and no later task is started, because a
+ * task in a sequence generally assumes its predecessor succeeded. Use `mapLimit(tasks, 1, …)` instead when
+ * every task must run regardless of the others' outcomes.
+ */
+export declare function sequential<T>(tasks: Iterable<() => PromiseLike<T> | T>): Promise<T[]>;
+/**
+ * Awaits every promise and resolves to the values of the ones that fulfilled, in input order, silently
+ * dropping the rejections.
+ *
+ * Never rejects — the "best effort, partial results are fine" counterpart to `Promise.all`: warming a
+ * cache, hydrating optional widgets, fanning out to mirrors. Note that failures are DISCARDED, not
+ * reported; use `Promise.allSettled` directly when a caller needs to know what broke.
+ */
+export declare function allSettledValues<T>(promises: Iterable<PromiseLike<T>>): Promise<T[]>;

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

@@ -0,0 +1,18 @@
+/** A promise whose settlement is controlled from outside its executor. */
+export interface Deferred<T> {
+    /** The promise handed to waiters. Settles when {@link resolve} or {@link reject} is called. */
+    readonly promise: Promise<T>;
+    /** Fulfils {@link promise}. A second call (after either settler) is a no-op, per promise semantics. */
+    readonly resolve: (value: T | PromiseLike<T>) => void;
+    /** Rejects {@link promise}. A second call (after either settler) is a no-op, per promise semantics. */
+    readonly reject: (reason?: unknown) => void;
+}
+/**
+ * Creates a {@link Deferred} — a promise you settle later, from anywhere.
+ *
+ * Reach for it when the code that settles is not the code that creates: a scheduler that starts a task
+ * once a slot frees, an event listener that resolves on the next message, a debounce that answers many
+ * callers from one invocation. When the work is already a promise, wrap it directly — a deferred adds a
+ * layer that can be forgotten unsettled.
+ */
+export declare function deferred<T>(): Deferred<T>;

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

@@ -0,0 +1,36 @@
+/** A bounded-concurrency scheduler — hand it tasks, it runs at most N at a time. */
+export interface Limiter {
+    /**
+     * Schedules `fn`, resolving with its result once it has run. Tasks start in submission order as slots
+     * free; the returned promise settles on the task's own outcome, and a synchronous throw from `fn`
+     * surfaces as a rejection.
+     */
+    readonly run: <T>(fn: () => PromiseLike<T> | T) => Promise<T>;
+    /** How many tasks are running right now — never above the configured concurrency. */
+    readonly activeCount: () => number;
+    /** How many tasks are queued, waiting for a slot. */
+    readonly pendingCount: () => number;
+    /** The cap this limiter enforces, after clamping. */
+    readonly concurrency: number;
+}
+/**
+ * Creates a {@link Limiter} that runs at most `concurrency` tasks at once.
+ *
+ * One limiter per resource is the intent — a limiter is a budget for a specific bottleneck (an API's rate
+ * limit, the connection pool, CPU-bound decode work), so sharing one across unrelated work couples them.
+ * `concurrency` is clamped to at least `1`; a fractional value is floored.
+ */
+export declare function pLimit(concurrency: number): Limiter;
+/**
+ * Maps `items` through `fn` with at most `concurrency` calls in flight, resolving to the results **in input
+ * order** regardless of which finished first.
+ *
+ * The bounded `Promise.all`, INCLUDING its failure semantics: the returned promise rejects at the first
+ * failure, but every remaining task still runs. They were all submitted up front, and the limiter's queue
+ * has no knowledge of the rejection — so a failure reports early without cancelling the batch behind it.
+ *
+ * That is the right default for a `Promise.all` shape, and the wrong one when a later task depends on an
+ * earlier one: use `sequential`, which genuinely stops. Pass a `signal` down through `fn` when the
+ * remaining work must actually be cancellable, or reach for `allSettledValues` when partial success is fine.
+ */
+export declare function mapLimit<TItem, TResult>(items: Iterable<TItem>, concurrency: number, fn: (item: TItem, index: number) => PromiseLike<TResult> | TResult): Promise<TResult[]>;

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

@@ -0,0 +1,31 @@
+/** A trailing-edge debounced async function, plus the cancel that makes it unmount-safe. */
+export interface DebouncedAsync<TArgs extends unknown[], TResult> {
+    /** Schedules an invocation `ms` from now, replacing any pending one. Resolves with the latest invocation's result. */
+    (...args: TArgs): Promise<TResult>;
+    /** Drops the pending invocation and rejects parked callers with an `AbortError`. Safe to call when idle. */
+    readonly cancel: () => void;
+}
+/** A leading-edge throttled async function, plus the cancel that makes it unmount-safe. */
+export interface ThrottledAsync<TArgs extends unknown[], TResult> {
+    /** Invokes immediately when the window is open; otherwise returns the in-flight window's promise. */
+    (...args: TArgs): Promise<TResult>;
+    /** Closes the current window early and clears its timer. Safe to call when idle. */
+    readonly cancel: () => void;
+}
+/**
+ * Debounces an async function on the trailing edge: a burst of calls collapses into ONE invocation, `ms`
+ * after the last call, using the last call's arguments.
+ *
+ * Every caller in the burst — superseded ones included — resolves with that single invocation's result, so
+ * no promise is ever left unsettled (see the header; this is the whole point). A rejection likewise fans
+ * out to all of them. Call `cancel()` on unmount.
+ */
+export declare function debounceAsync<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => PromiseLike<TResult> | TResult, ms: number): DebouncedAsync<TArgs, TResult>;
+/**
+ * Throttles an async function on the leading edge: the first call runs immediately, and every call within
+ * the next `ms` is suppressed — receiving the leading call's promise rather than triggering its own.
+ *
+ * The window opens again `ms` after the leading call, whether or not it has settled. Call `cancel()` on
+ * unmount to clear the window timer.
+ */
+export declare function throttleAsync<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => PromiseLike<TResult> | TResult, ms: number): ThrottledAsync<TArgs, TResult>;

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

@@ -0,0 +1,20 @@
+import { RetryPolicy } from '../resilience';
+/** Configures a {@link retryAsync} call. */
+export interface RetryAsyncOptions {
+    /** The policy driving the decision and the delays. Defaults to `DefaultRetryPolicy` from `foundation/resilience`. */
+    readonly policy?: RetryPolicy;
+    /** Cancels the retry loop, including mid-backoff. Rejects with an `AbortError`; an in-flight attempt is not recalled. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Runs `fn`, retrying transient failures per the policy — attempts, backoff, and jitter all decided by
+ * `foundation/resilience`.
+ *
+ * `fn` gets the 1-based attempt number. An `AbortError` is never retried, and neither is a failure whose
+ * `status` the policy considers non-transient. Rejects with the last failure once retries are exhausted.
+ *
+ * `fn` must be idempotent-safe to call again — this is the caller's judgement, not something the helper can
+ * check. Wrap `fn` in `withTimeout` when a hung attempt should also count as a failure; the two compose in
+ * that order so each attempt gets its own deadline.
+ */
+export declare function retryAsync<T>(fn: (attempt: number) => PromiseLike<T> | T, options?: RetryAsyncOptions): Promise<T>;

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

@@ -0,0 +1,32 @@
+/**
+ * The deadline error {@link withTimeout} rejects with. Named `TimeoutError` — the same name
+ * `AbortSignal.timeout()` uses — so `isTimeoutError` from `foundation/errors` recognizes it.
+ *
+ * Prefer `isTimeoutError(caught)` over `caught instanceof TimeoutError`: a deadline from the platform is a
+ * `DOMException`, not this class, and only the name-keyed recognizer catches both.
+ */
+export declare class TimeoutError extends Error {
+    /** Creates a deadline error. */
+    constructor(message?: string, options?: ErrorOptions);
+}
+/** Configures a {@link withTimeout} call. Every member is optional. */
+export interface WithTimeoutOptions {
+    /** Cancels the wait early, rejecting with an `AbortError`. Honoured synchronously when already aborted. */
+    readonly signal?: AbortSignal;
+    /**
+     * Fires when the deadline lapses, before the rejection — the seam for stopping the underlying work,
+     * which the timeout itself cannot do (`onTimeout: () => controller.abort()`). A throw here is swallowed
+     * so it cannot mask the {@link TimeoutError}.
+     */
+    readonly onTimeout?: () => void;
+    /** Overrides the rejection message. Defaults to `Operation timed out after {ms}ms`. */
+    readonly message?: string;
+}
+/**
+ * Rejects with a {@link TimeoutError} if `promise` has not settled within `ms`, and clears its timer on
+ * every exit path — resolve, reject, abort, and lapse alike.
+ *
+ * The promise keeps running after a timeout; use `options.onTimeout` to abort the work behind it. A
+ * non-positive or non-finite `ms` applies no deadline.
+ */
+export declare function withTimeout<T>(promise: PromiseLike<T>, ms: number, options?: WithTimeoutOptions): Promise<T>;