@texuli/core 0.5.0 → 0.7.0

package/dist/markup/markup.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Escaped markup builders (ADR-016): typed element and text nodes that
+ * serialize to XML or HTML. Content only enters through these nodes, so
+ * there is no raw-markup API: every text and attribute value is escaped,
+ * element and attribute names are checked, and URL-valued HTML attributes
+ * accept only a `MarkupUrl` made by `linkUrl` or `imageUrl`, which call the
+ * URL policy with an explicit tier. Serialization is iterative and linear in
+ * the size of the tree.
+ */
+import { type HrefTrust } from '../url/safe-href.js';
+export interface MarkupText {
+    readonly kind: 'text';
+    readonly value: string;
+}
+/** A URL that passed the URL policy. Only `linkUrl` and `imageUrl` make one the serializers accept. */
+export interface MarkupUrl {
+    readonly kind: 'url';
+    readonly value: string;
+}
+export type MarkupAttributeValue = string | number | boolean | MarkupUrl | null | undefined;
+export type MarkupAttribute = readonly [string, string | boolean | MarkupUrl];
+export interface MarkupElement {
+    readonly kind: 'element';
+    readonly name: string;
+    readonly attributes: readonly MarkupAttribute[];
+    readonly children: readonly MarkupNode[];
+}
+export type MarkupNode = MarkupElement | MarkupText;
+/** A child: a node, a string or number (escaped text), a nested list, or a skipped `null`, `undefined` or `false`. */
+export type MarkupChild = MarkupNode | string | number | null | undefined | false | readonly MarkupChild[];
+export interface XmlSerializeOptions {
+    /** Prefix the UTF-8 declaration (`standalone="yes"`, as Office packages use). Default true. */
+    declaration?: boolean;
+    /** An allowlist for element and attribute names, on top of the XML name grammar. */
+    allow?: (name: string, what: 'element' | 'attribute') => boolean;
+}
+export interface HtmlSerializeOptions {
+    /** Prefix `<!doctype html>`. Default false. */
+    doctype?: boolean;
+}
+/**
+ * The HTML elements `serializeHtml` writes: document structure, text,
+ * lists, tables, links and images. No scripts, styles, frames, objects,
+ * forms, templates, SVG or MathML.
+ */
+export declare const HTML_ELEMENTS: ReadonlySet<string>;
+/** HTML attributes that hold a URL: only a `MarkupUrl` value is written. */
+export declare const HTML_URL_ATTRIBUTES: ReadonlySet<string>;
+/** A link URL through `safeHref` at `trust`, or `null` when the policy refuses it. */
+export declare function linkUrl(value: string, trust: HrefTrust): MarkupUrl | null;
+/** An image URL through `safeImageSrc` at `trust`, or `null` when the policy refuses it. */
+export declare function imageUrl(value: string, trust: HrefTrust): MarkupUrl | null;
+/** True only for a URL `linkUrl` or `imageUrl` made (a hand-built object is not one). */
+export declare function isMarkupUrl(value: unknown): value is MarkupUrl;
+/**
+ * Drop characters XML 1.0 cannot carry: C0 controls other than tab,
+ * newline and carriage return, U+FFFE and U+FFFF, and unpaired surrogates.
+ */
+export declare function sanitizeMarkupChars(value: string): string;
+export declare function escapeMarkupText(value: string): string;
+export declare function escapeMarkupAttribute(value: string): string;
+export declare function text(value: string | number): MarkupText;
+/** Build an element. String and number children become escaped text; nullish and `false` children are skipped. */
+export declare function el(name: string, attributes?: Readonly<Record<string, MarkupAttributeValue>>, ...children: MarkupChild[]): MarkupElement;
+/** Serialize to XML: booleans become `1` and `0` (the Office convention); childless elements self-close. */
+export declare function serializeXml(root: MarkupElement, options?: XmlSerializeOptions): string;
+/**
+ * Serialize to HTML: only `HTML_ELEMENTS`, no event handler or `srcdoc`
+ * attributes, URL attributes only from `linkUrl` or `imageUrl`, booleans as
+ * bare attributes, and void elements without an end tag.
+ */
+export declare function serializeHtml(root: MarkupElement, options?: HtmlSerializeOptions): string;

package/dist/markup/markup.js

@@ -0,0 +1,233 @@
+/**
+ * Escaped markup builders (ADR-016): typed element and text nodes that
+ * serialize to XML or HTML. Content only enters through these nodes, so
+ * there is no raw-markup API: every text and attribute value is escaped,
+ * element and attribute names are checked, and URL-valued HTML attributes
+ * accept only a `MarkupUrl` made by `linkUrl` or `imageUrl`, which call the
+ * URL policy with an explicit tier. Serialization is iterative and linear in
+ * the size of the tree.
+ */
+import { safeHref } from "../url/safe-href.js";
+import { safeImageSrc } from "../url-policy/safe-image-src.js";
+const XML_NAME = /^[A-Za-z_][A-Za-z0-9._-]*(?::[A-Za-z_][A-Za-z0-9._-]*)?$/;
+const HTML_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const HTML_ATTRIBUTE = /^[a-z][a-z0-9]*(?:[-:][a-z0-9]+)*$/;
+/**
+ * The HTML elements `serializeHtml` writes: document structure, text,
+ * lists, tables, links and images. No scripts, styles, frames, objects,
+ * forms, templates, SVG or MathML.
+ */
+export const HTML_ELEMENTS = new Set(('html head body title meta main article section header footer nav aside div span p br hr ' +
+    'h1 h2 h3 h4 h5 h6 strong b em i u s del ins code pre kbd samp small sub sup mark blockquote ' +
+    'q cite abbr time ul ol li dl dt dd a img figure figcaption table caption thead tbody tfoot ' +
+    'tr th td colgroup col center font address details summary wbr').split(' '));
+/** HTML elements written without children or an end tag. */
+const HTML_VOID = new Set(['br', 'hr', 'img', 'meta', 'col', 'wbr']);
+/** HTML attributes that hold a URL: only a `MarkupUrl` value is written. */
+export const HTML_URL_ATTRIBUTES = new Set(('href src srcset action formaction poster cite data background xlink:href ping manifest ' +
+    'codebase longdesc usemap lowsrc dynsrc').split(' '));
+/** HTML attributes no output carries: event handlers are refused by prefix, these by name. */
+const HTML_DENIED_ATTRIBUTES = new Set(['srcdoc', 'http-equiv', 'is', 'nonce']);
+const urls = new WeakSet();
+function makeUrl(value) {
+    if (value === undefined)
+        return null;
+    const url = Object.freeze({ kind: 'url', value });
+    urls.add(url);
+    return url;
+}
+/** A link URL through `safeHref` at `trust`, or `null` when the policy refuses it. */
+export function linkUrl(value, trust) {
+    return makeUrl(safeHref(value, trust));
+}
+/** An image URL through `safeImageSrc` at `trust`, or `null` when the policy refuses it. */
+export function imageUrl(value, trust) {
+    return makeUrl(safeImageSrc(value, trust));
+}
+/** True only for a URL `linkUrl` or `imageUrl` made (a hand-built object is not one). */
+export function isMarkupUrl(value) {
+    return typeof value === 'object' && value !== null && urls.has(value);
+}
+/**
+ * Drop characters XML 1.0 cannot carry: C0 controls other than tab,
+ * newline and carriage return, U+FFFE and U+FFFF, and unpaired surrogates.
+ */
+export function sanitizeMarkupChars(value) {
+    // Fast path: most text has nothing to drop.
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: matching the controls is the point.
+    if (!/[\u0000-\u0008\u000b\u000c\u000e-\u001f\ud800-\udfff￾￿]/.test(value))
+        return value;
+    let out = '';
+    for (const character of value) {
+        const code = character.codePointAt(0) ?? 0;
+        if (code === 0x09 || code === 0x0a || code === 0x0d)
+            out += character;
+        else if (code < 0x20 || code === 0xfffe || code === 0xffff)
+            continue;
+        else if (code >= 0xd800 && code <= 0xdfff)
+            continue;
+        else
+            out += character;
+    }
+    return out;
+}
+export function escapeMarkupText(value) {
+    return sanitizeMarkupChars(value)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+export function escapeMarkupAttribute(value) {
+    return escapeMarkupText(value)
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;')
+        .replace(/\t/g, '&#9;')
+        .replace(/\n/g, '&#10;')
+        .replace(/\r/g, '&#13;');
+}
+export function text(value) {
+    return { kind: 'text', value: String(value) };
+}
+function pushChildren(out, children) {
+    // Iterative flattening, so a deeply nested child list cannot overflow the stack.
+    const stack = [children, 0];
+    while (stack.length > 0) {
+        const index = stack.pop();
+        const list = stack.pop();
+        if (index >= list.length)
+            continue;
+        stack.push(list, index + 1);
+        const child = list[index];
+        if (child === null || child === undefined || child === false)
+            continue;
+        if (Array.isArray(child))
+            stack.push(child, 0);
+        else if (typeof child === 'string' || typeof child === 'number')
+            out.push(text(child));
+        else
+            out.push(child);
+    }
+}
+function assertXmlName(name, what) {
+    if (typeof name !== 'string' || !XML_NAME.test(name)) {
+        throw new TypeError(`Invalid markup ${what} name: ${JSON.stringify(name)}`);
+    }
+}
+/** Build an element. String and number children become escaped text; nullish and `false` children are skipped. */
+export function el(name, attributes = {}, ...children) {
+    assertXmlName(name, 'element');
+    const attrs = [];
+    for (const key of Object.keys(attributes)) {
+        const value = attributes[key];
+        if (value === undefined || value === null)
+            continue;
+        assertXmlName(key, 'attribute');
+        if (typeof value === 'number') {
+            if (!Number.isFinite(value))
+                throw new TypeError(`Attribute ${key} must be a finite number.`);
+            attrs.push([key, String(value)]);
+        }
+        else if (typeof value === 'object') {
+            if (!isMarkupUrl(value))
+                throw new TypeError(`Attribute ${key} holds an unchecked URL object.`);
+            attrs.push([key, value]);
+        }
+        else
+            attrs.push([key, value]);
+    }
+    const nodes = [];
+    pushChildren(nodes, children);
+    return { kind: 'element', name, attributes: attrs, children: nodes };
+}
+function walk(root, open, close, leaf) {
+    if (root.kind === 'text')
+        return leaf(root);
+    const parts = [open(root)];
+    const stack = [{ node: root, index: 0 }];
+    while (stack.length > 0) {
+        const frame = stack[stack.length - 1];
+        const child = frame.node.children[frame.index];
+        if (child === undefined) {
+            parts.push(close(frame.node));
+            stack.pop();
+            continue;
+        }
+        frame.index += 1;
+        if (child.kind === 'text')
+            parts.push(leaf(child));
+        else if (child.kind === 'element') {
+            parts.push(open(child));
+            stack.push({ node: child, index: 0 });
+        }
+        else
+            throw new TypeError('Unknown markup node.');
+    }
+    return parts.join('');
+}
+/** Serialize to XML: booleans become `1` and `0` (the Office convention); childless elements self-close. */
+export function serializeXml(root, options = {}) {
+    const allow = options.allow;
+    const check = (name, what) => {
+        assertXmlName(name, what);
+        if (allow && !allow(name, what)) {
+            throw new TypeError(`Markup ${what} not allowed: ${JSON.stringify(name)}`);
+        }
+    };
+    const body = walk(root, (node) => {
+        // Re-check names, so a hand-built node object cannot smuggle markup.
+        check(node.name, 'element');
+        let out = `<${node.name}`;
+        for (const [key, value] of node.attributes) {
+            check(key, 'attribute');
+            const raw = typeof value === 'boolean' ? (value ? '1' : '0') : xmlValue(value);
+            out += ` ${key}="${escapeMarkupAttribute(raw)}"`;
+        }
+        return node.children.length === 0 ? `${out}/>` : `${out}>`;
+    }, (node) => (node.children.length === 0 ? '' : `</${node.name}>`), (node) => escapeMarkupText(String(node.value)));
+    return options.declaration === false
+        ? body
+        : `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n${body}`;
+}
+function xmlValue(value) {
+    if (typeof value === 'string')
+        return value;
+    if (!isMarkupUrl(value))
+        throw new TypeError('Unchecked URL object in markup.');
+    return value.value;
+}
+function htmlAttribute(name, value) {
+    if (!HTML_ATTRIBUTE.test(name) || name.startsWith('on') || HTML_DENIED_ATTRIBUTES.has(name)) {
+        throw new TypeError(`HTML attribute not allowed: ${JSON.stringify(name)}`);
+    }
+    if (HTML_URL_ATTRIBUTES.has(name)) {
+        if (!isMarkupUrl(value)) {
+            throw new TypeError(`HTML attribute ${name} takes a URL from linkUrl or imageUrl.`);
+        }
+        return ` ${name}="${escapeMarkupAttribute(value.value)}"`;
+    }
+    if (typeof value === 'boolean')
+        return value ? ` ${name}` : '';
+    if (typeof value !== 'string')
+        throw new TypeError(`HTML attribute ${name} is not text.`);
+    return ` ${name}="${escapeMarkupAttribute(value)}"`;
+}
+/**
+ * Serialize to HTML: only `HTML_ELEMENTS`, no event handler or `srcdoc`
+ * attributes, URL attributes only from `linkUrl` or `imageUrl`, booleans as
+ * bare attributes, and void elements without an end tag.
+ */
+export function serializeHtml(root, options = {}) {
+    const body = walk(root, (node) => {
+        if (!HTML_NAME.test(node.name) || !HTML_ELEMENTS.has(node.name)) {
+            throw new TypeError(`HTML element not allowed: ${JSON.stringify(node.name)}`);
+        }
+        if (HTML_VOID.has(node.name) && node.children.length > 0) {
+            throw new TypeError(`HTML element ${node.name} takes no children.`);
+        }
+        let out = `<${node.name}`;
+        for (const [key, value] of node.attributes)
+            out += htmlAttribute(key, value);
+        return `${out}>`;
+    }, (node) => (HTML_VOID.has(node.name) ? '' : `</${node.name}>`), (node) => escapeMarkupText(String(node.value)));
+    return options.doctype ? `<!doctype html>${body}` : body;
+}

package/dist/motion/animate.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Animate: the Web Animations wrapper every motion texel plays through
+ * (ADR-013). It clamps timing, applies the motion level and reduced motion,
+ * and commits the end state at once (no frames, `finished` resolves
+ * `"instant"`) whenever motion cannot or must not run: on the server, without
+ * the Web Animations API, on a detached element, at level `none`, under
+ * reduced motion, or with a zero duration.
+ *
+ * Animations use `fill: "none"` (`"backwards"` only while a delay holds the
+ * first frame), so no inline style outlives them; the final state belongs in
+ * classes, attributes or props.
+ */
+import { type MotionLevel, type ReducedMotionPolicy, type ReducedMotionSource } from './preferences.js';
+import { type SpringParams } from './spring.js';
+/** Keyframes in either Web Animations form. */
+export type MotionKeyframes = Keyframe[] | PropertyIndexedKeyframes;
+/** How a motion run ended. */
+export type MotionOutcome = 
+/** Every animation played to its end. */
+'finished'
+/** The end state was committed without frames (see {@link InstantReason}). */
+ | 'instant'
+/** `cancel()` stopped it. */
+ | 'cancelled'
+/** A newer run took over (a reversal, a new measure, a new transition). */
+ | 'interrupted';
+/** Why a run committed instantly. */
+export type InstantReason = 'server' | 'detached' | 'level-none' | 'reduced-motion' | 'no-properties' | 'zero-duration' | 'no-waapi' | 'error' | 'limit';
+/** Reduced motion: a fixed value, a live source, or omitted (read the element's window). */
+export type ReducedMotionInput = boolean | ReducedMotionSource | null | undefined;
+/** Timing and policy shared by every motion texel. */
+export type MotionTiming = {
+    /** Milliseconds, clamped to [0, 1000]; NaN or negative is 0 (instant). Default 200. */
+    duration?: number;
+    /** Milliseconds before the animation starts, clamped like `duration`. Default 0. */
+    delay?: number;
+    /** A CSS easing. Default `cubic-bezier(0.4, 0, 0.2, 1)` (the `standard` token). */
+    easing?: string;
+    /** Play on a spring instead: the duration is its settle time and the easing its `linear()` curve. */
+    spring?: Partial<SpringParams> & {
+        velocity?: number;
+    };
+    /** The already-resolved motion level (see `resolveMotionLevel`). Default `full`. */
+    level?: MotionLevel;
+    /** Reduced motion; omitted reads `prefers-reduced-motion` from the element's window. */
+    reducedMotion?: ReducedMotionInput;
+    /** `instant` (default) commits the end state; `fade` keeps an opacity-only 150 ms fade. */
+    reducedMotionPolicy?: ReducedMotionPolicy;
+};
+/** One running (or already settled) motion. */
+export type MotionRun = {
+    /** Resolves once with the outcome; never rejects. */
+    readonly finished: Promise<MotionOutcome>;
+    /** The live animations (empty when instant). */
+    readonly animations: readonly Animation[];
+    /** Why it committed instantly, or `null` when it animates. */
+    readonly instantReason: InstantReason | null;
+    /** Stop now; no style remains. Resolves `finished` with `"cancelled"`. */
+    cancel: () => void;
+    /** Jump to the end. Resolves `finished` with `"finished"`. */
+    finish: () => void;
+};
+export type AnimateOptions = MotionTiming & {
+    /** Called once with the outcome, before `finished` resolves. */
+    onFinish?: (outcome: MotionOutcome) => void;
+};
+/** Default duration (the `base` token) and easing (the `standard` token). */
+export declare const DEFAULT_MOTION_DURATION = 200;
+export declare const DEFAULT_MOTION_EASING = "cubic-bezier(0.4, 0, 0.2, 1)";
+/** Resolved, clamped plan for one animation. */
+export type ResolvedMotion = {
+    readonly instant: true;
+    readonly reason: InstantReason;
+} | {
+    readonly instant: false;
+    readonly keyframes: MotionKeyframes;
+    readonly duration: number;
+    readonly delay: number;
+    readonly easing: string;
+};
+/** Keyframes without movement or scale (what `subtle` plays). `null` when nothing is left. */
+export declare function withoutTravel(keyframes: MotionKeyframes): MotionKeyframes | null;
+/**
+ * Resolve keyframes and timing for one element: the level, reduced motion,
+ * clamping and the environment checks, without starting anything.
+ */
+export declare function resolveMotion(element: Element | null | undefined, keyframes: MotionKeyframes, timing?: MotionTiming): ResolvedMotion;
+/** Start a resolved plan; `null` when the browser refuses it (an invalid easing, say). */
+export declare function startAnimation(element: Element, plan: Extract<ResolvedMotion, {
+    instant: false;
+}>, extra?: {
+    endDelay?: number;
+}): Animation | null;
+/**
+ * Settle a set of animations as one run. With no animations the run is
+ * instant: `onFinish` fires synchronously and `finished` resolves `"instant"`.
+ */
+export declare function createRun(animations: readonly Animation[], onFinish?: (outcome: MotionOutcome) => void, instantReason?: InstantReason | null): MotionRun & {
+    interrupt: () => void;
+};
+/**
+ * Animate one element through the Web Animations API with the motion level
+ * and reduced motion applied.
+ *
+ * @example
+ * const run = animate(card, [{ opacity: 0 }, { opacity: 1 }], { duration: 150 });
+ * await run.finished; // "finished", or "instant" under reduced motion
+ */
+export declare function animate(element: Element | null | undefined, keyframes: MotionKeyframes, options?: AnimateOptions): MotionRun;

package/dist/motion/animate.js

@@ -0,0 +1,225 @@
+/**
+ * Animate: the Web Animations wrapper every motion texel plays through
+ * (ADR-013). It clamps timing, applies the motion level and reduced motion,
+ * and commits the end state at once (no frames, `finished` resolves
+ * `"instant"`) whenever motion cannot or must not run: on the server, without
+ * the Web Animations API, on a detached element, at level `none`, under
+ * reduced motion, or with a zero duration.
+ *
+ * Animations use `fill: "none"` (`"backwards"` only while a delay holds the
+ * first frame), so no inline style outlives them; the final state belongs in
+ * classes, attributes or props.
+ */
+import { getOwnerWindow } from "../env/index.js";
+import { prefersReducedMotion } from "../presence/presence.js";
+import { motionDuration, REDUCED_FADE_MS, } from "./preferences.js";
+import { springEasing } from "./spring.js";
+/** Default duration (the `base` token) and easing (the `standard` token). */
+export const DEFAULT_MOTION_DURATION = 200;
+export const DEFAULT_MOTION_EASING = 'cubic-bezier(0.4, 0, 0.2, 1)';
+const SPRING_FALLBACK_EASING = 'cubic-bezier(0.2, 0, 0, 1)';
+/** Properties that move or scale: dropped at level `subtle`. */
+const TRAVEL = new Set([
+    'transform',
+    'transformOrigin',
+    'translate',
+    'scale',
+    'rotate',
+    'offsetDistance',
+]);
+const META = new Set(['offset', 'easing', 'composite']);
+function filterKeyframes(keyframes, keep) {
+    let any = false;
+    if (Array.isArray(keyframes)) {
+        const out = keyframes.map((frame) => {
+            const next = {};
+            for (const [key, value] of Object.entries(frame ?? {})) {
+                if (META.has(key) || keep(key)) {
+                    next[key] = value;
+                    if (!META.has(key))
+                        any = true;
+                }
+            }
+            return next;
+        });
+        return any ? out : null;
+    }
+    if (!keyframes || typeof keyframes !== 'object')
+        return null;
+    const out = {};
+    for (const [key, value] of Object.entries(keyframes)) {
+        if (META.has(key) || keep(key)) {
+            out[key] = value;
+            if (!META.has(key))
+                any = true;
+        }
+    }
+    return any ? out : null;
+}
+/** Keyframes without movement or scale (what `subtle` plays). `null` when nothing is left. */
+export function withoutTravel(keyframes) {
+    return filterKeyframes(keyframes, (property) => !TRAVEL.has(property));
+}
+function opacityOnly(keyframes) {
+    return filterKeyframes(keyframes, (property) => property === 'opacity');
+}
+function readReduced(input, win) {
+    if (typeof input === 'boolean')
+        return input;
+    if (input && typeof input.get === 'function')
+        return input.get() === true;
+    return prefersReducedMotion(win ?? null, false);
+}
+function supportsLinear(win) {
+    try {
+        const css = win?.CSS;
+        return css?.supports?.('animation-timing-function', 'linear(0, 1)') === true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve keyframes and timing for one element: the level, reduced motion,
+ * clamping and the environment checks, without starting anything.
+ */
+export function resolveMotion(element, keyframes, timing = {}) {
+    const win = element ? getOwnerWindow(element) : undefined;
+    if (!element || !win)
+        return { instant: true, reason: 'server' };
+    if (!element.isConnected)
+        return { instant: true, reason: 'detached' };
+    const level = timing.level ?? 'full';
+    if (level === 'none')
+        return { instant: true, reason: 'level-none' };
+    let frames = keyframes;
+    let duration;
+    let delay;
+    let easing = typeof timing.easing === 'string' && timing.easing ? timing.easing : DEFAULT_MOTION_EASING;
+    if (readReduced(timing.reducedMotion, win)) {
+        if (timing.reducedMotionPolicy !== 'fade')
+            return { instant: true, reason: 'reduced-motion' };
+        frames = opacityOnly(keyframes);
+        duration = REDUCED_FADE_MS;
+        delay = 0;
+        easing = 'linear';
+    }
+    else {
+        if (level === 'subtle')
+            frames = withoutTravel(keyframes);
+        if (timing.spring) {
+            const spring = springEasing(timing.spring, { velocity: timing.spring.velocity ?? 0 });
+            duration = motionDuration(spring.durationMs, level);
+            easing = supportsLinear(win) ? spring.easing : SPRING_FALLBACK_EASING;
+        }
+        else {
+            duration = motionDuration(timing.duration ?? DEFAULT_MOTION_DURATION, level);
+        }
+        delay = motionDuration(timing.delay ?? 0, level);
+    }
+    if (!frames)
+        return { instant: true, reason: 'no-properties' };
+    if (duration <= 0)
+        return { instant: true, reason: 'zero-duration' };
+    if (typeof element.animate !== 'function') {
+        return { instant: true, reason: 'no-waapi' };
+    }
+    return { instant: false, keyframes: frames, duration, delay, easing };
+}
+/** Start a resolved plan; `null` when the browser refuses it (an invalid easing, say). */
+export function startAnimation(element, plan, extra = {}) {
+    try {
+        const animation = element.animate(plan.keyframes, {
+            duration: plan.duration,
+            delay: plan.delay,
+            endDelay: extra.endDelay ?? 0,
+            easing: plan.easing,
+            fill: plan.delay > 0 ? 'backwards' : 'none',
+        });
+        // A cancelled animation rejects `finished`; never leave that unhandled.
+        animation?.finished?.catch(() => { });
+        return animation ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Settle a set of animations as one run. With no animations the run is
+ * instant: `onFinish` fires synchronously and `finished` resolves `"instant"`.
+ */
+export function createRun(animations, onFinish, instantReason = null) {
+    let settled = false;
+    let resolve = () => { };
+    const finished = new Promise((r) => {
+        resolve = r;
+    });
+    const settle = (outcome) => {
+        if (settled)
+            return;
+        settled = true;
+        onFinish?.(outcome);
+        resolve(outcome);
+    };
+    const stopAll = (outcome) => {
+        settle(outcome);
+        for (const animation of animations) {
+            try {
+                animation.cancel();
+            }
+            catch {
+                // A cancelled animation stays cancelled.
+            }
+        }
+    };
+    if (animations.length === 0) {
+        settle('instant');
+    }
+    else {
+        let remaining = animations.length;
+        for (const animation of animations) {
+            animation.finished.then(() => {
+                remaining -= 1;
+                if (remaining === 0)
+                    settle('finished');
+            }, () => settle('cancelled'));
+        }
+    }
+    return {
+        finished,
+        animations,
+        instantReason: animations.length === 0 ? (instantReason ?? 'zero-duration') : null,
+        cancel: () => stopAll('cancelled'),
+        interrupt: () => stopAll('interrupted'),
+        finish() {
+            if (settled)
+                return;
+            for (const animation of animations) {
+                try {
+                    animation.finish();
+                }
+                catch {
+                    // An animation that cannot finish is cancelled below.
+                    animation.cancel();
+                }
+            }
+            settle('finished');
+        },
+    };
+}
+/**
+ * Animate one element through the Web Animations API with the motion level
+ * and reduced motion applied.
+ *
+ * @example
+ * const run = animate(card, [{ opacity: 0 }, { opacity: 1 }], { duration: 150 });
+ * await run.finished; // "finished", or "instant" under reduced motion
+ */
+export function animate(element, keyframes, options = {}) {
+    const plan = resolveMotion(element, keyframes, options);
+    if (plan.instant || !element) {
+        return createRun([], options.onFinish, plan.instant ? plan.reason : 'server');
+    }
+    const animation = startAnimation(element, plan);
+    return createRun(animation ? [animation] : [], options.onFinish, animation ? null : 'error');
+}