@setsquare/ui 0.1.0

package/dist/testing/index.js

@@ -0,0 +1,1175 @@
+/**
+ * @setsquare/ui/testing — checks on a rendered page, for use in Playwright (or anything with a
+ * `page.evaluate`). They look at what the browser actually laid out, so they find what the lint rules cannot:
+ * a wrapper without `relative`, a third-party widget, CSS from elsewhere.
+ *
+ * - Positioning: `findUncontainedPositioning`, `findHiddenOverflowScrolls`, `expectPositioningContained`.
+ * - Targets: `findSmallTargets`, `findOverlappingTargets`, `expectTargetsSized` — the target is the element a
+ *   pointer hits (Layer 1), measured as laid out, not the paint inside it.
+ * - Focus: `findInvisibleFocus`, `expectFocusVisible` — every control a keyboard reaches must change on screen
+ *   when it takes focus. These take screenshots, so they need a Playwright page.
+ * - Links: `findUndistinguishedLinks`, `expectLinksDistinguished` — a link in running text must be findable
+ *   without colour (WCAG's F73 and G183), or with `{ underline: true }`, underlined.
+ * - Cursors: `findCursorMismatches`, `expectCursorsMatch` — one cursor rule on every target: the pointer on
+ *   what is pressed, the I-beam on text entry, not-allowed when disabled. These hover, so they need a page
+ *   with a mouse.
+ * - Reflow: `findPageOverflow`, `expectPageReflows` — at the width the page is laid out at, nothing makes it
+ *   scroll sideways or runs off its edge, apart from content in a scroller of its own.
+ * - Text spacing: `findClippedText`, `expectTextUnclipped` — with WCAG 1.4.12's four spacing metrics applied,
+ *   no text is cut off by its box or spills out of one.
+ * - Motion: `findEndlessAnimations`, `expectAnimationsPausable` — nothing moves for more than five seconds
+ *   unless a visible control on the page pauses it.
+ *
+ * The DOM scans are self-contained functions: `page.evaluate(findSmallTargets)` runs them in the page.
+ * Nothing here imports Playwright.
+ */
+/**
+ * Every `position: absolute` element whose containing block lies outside its nearest scroll container
+ * (`overflow: auto | scroll`). Such an element does not scroll with the content it belongs to, and scrolling
+ * it into view scrolls an ancestor instead. Returns [] when the page is clean.
+ */
+export function findUncontainedPositioning(root = document) {
+    const describe = (el) => {
+        if (!el)
+            return 'the page';
+        const id = el.id ? `#${el.id}` : '';
+        const cls = typeof el.className === 'string'
+            ? el.className
+                .split(/\s+/)
+                .filter(Boolean)
+                .slice(0, 3)
+                .map((c) => `.${c}`)
+                .join('')
+            : '';
+        const name = (el.getAttribute('aria-label') ?? el.textContent ?? '')
+            .trim()
+            .replace(/\s+/g, ' ')
+            .slice(0, 40);
+        return `${el.tagName.toLowerCase()}${id}${cls}${name ? ` "${name}"` : ''}`;
+    };
+    const scrollerOf = (el) => {
+        for (let p = el.parentElement; p; p = p.parentElement) {
+            const cs = getComputedStyle(p);
+            if (/(auto|scroll)/.test(cs.overflowX + cs.overflowY))
+                return p;
+        }
+        return null;
+    };
+    const containingBlockOf = (el) => {
+        for (let p = el.parentElement; p; p = p.parentElement) {
+            const cs = getComputedStyle(p);
+            if (cs.position !== 'static' ||
+                cs.transform !== 'none' ||
+                cs.translate !== 'none' ||
+                cs.scale !== 'none' ||
+                cs.rotate !== 'none' ||
+                cs.perspective !== 'none' ||
+                cs.filter !== 'none' ||
+                /layout|paint|strict|content/.test(cs.contain) ||
+                /transform|perspective|filter/.test(cs.willChange) ||
+                cs.containerType === 'size')
+                return p;
+        }
+        return null;
+    };
+    const out = [];
+    for (const el of Array.from(root.querySelectorAll('*'))) {
+        if (getComputedStyle(el).position !== 'absolute')
+            continue;
+        const scroller = scrollerOf(el);
+        if (!scroller)
+            continue;
+        const cb = containingBlockOf(el);
+        if (cb && (cb === scroller || scroller.contains(cb)))
+            continue;
+        const kind = el.querySelector(':scope > input, :scope > button')
+            ? 'hidden-input'
+            : el.classList.contains('sr-only')
+                ? 'sr-only'
+                : el.matches('a[href], button, input, select, textarea, [tabindex]')
+                    ? 'focusable'
+                    : 'other';
+        out.push({
+            element: describe(el),
+            kind,
+            scroller: describe(scroller),
+            containingBlock: describe(cb),
+        });
+    }
+    return out;
+}
+/**
+ * Focus every focusable element, and bring every absolutely positioned element into view the way a screen
+ * reader's cursor or find-in-page would (so not a decorative, aria-hidden one with no text), with each scroll
+ * container scrolled first to its start and then to its
+ * end. Reports every time an `overflow: hidden` element scrolled as a result: content that moved with no way
+ * to scroll it back, which is the blank space at the bottom of the page. Restores scroll positions and focus.
+ */
+export function findHiddenOverflowScrolls(root = document) {
+    const describe = (el) => {
+        if (!el)
+            return 'the page';
+        const id = el.id ? `#${el.id}` : '';
+        const cls = typeof el.className === 'string'
+            ? el.className
+                .split(/\s+/)
+                .filter(Boolean)
+                .slice(0, 3)
+                .map((c) => `.${c}`)
+                .join('')
+            : '';
+        const name = (el.getAttribute('aria-label') ?? el.textContent ?? '')
+            .trim()
+            .replace(/\s+/g, ' ')
+            .slice(0, 40);
+        return `${el.tagName.toLowerCase()}${id}${cls}${name ? ` "${name}"` : ''}`;
+    };
+    const all = Array.from(root.querySelectorAll('*'));
+    const hidden = all.filter((el) => {
+        const cs = getComputedStyle(el);
+        const r = el.getBoundingClientRect();
+        // 1px visually hidden boxes scroll their own input into view; that is harmless and ignored.
+        return /(hidden|clip)/.test(cs.overflowX + cs.overflowY) && r.width > 2 && r.height > 2;
+    });
+    const scrollers = all.filter((el) => {
+        const cs = getComputedStyle(el);
+        return (/(auto|scroll)/.test(cs.overflowX + cs.overflowY) &&
+            (el.scrollHeight > el.clientHeight || el.scrollWidth > el.clientWidth));
+    });
+    // Neither a screen reader's cursor nor find-in-page goes to decorative, aria-hidden boxes with no text, or
+    // into inert content: HTML exposes none of it to assistive technology, and asks find-in-page to ignore it
+    // (a picture of a page, such as a docs preview, is inert).
+    const reachable = (el) => !el.closest('[aria-hidden=true]') || !!el.textContent?.trim();
+    const triggers = all.filter((el) => !el.closest('[inert]') &&
+        (el.matches('a[href], button, input, select, textarea, [tabindex], [contenteditable]') ||
+            (getComputedStyle(el).position === 'absolute' && reachable(el))));
+    // A page with scroll-behavior: smooth would scroll after the reading is taken, and hide what moved.
+    const instant = document.createElement('style');
+    instant.textContent = '* { scroll-behavior: auto !important; }';
+    document.head.append(instant);
+    const saved = new Map();
+    for (const el of [...hidden, ...scrollers, document.scrollingElement])
+        saved.set(el, [el.scrollLeft, el.scrollTop]);
+    const active = document.activeElement;
+    const out = [];
+    const seen = new Set();
+    const positions = scrollers.length
+        ? scrollers.flatMap((s) => [
+            [s, 0],
+            [s, s.scrollHeight],
+        ])
+        : [[null, 0]];
+    for (const el of triggers) {
+        for (const [s, top] of positions) {
+            for (const [h, [x, y]] of saved) {
+                h.scrollLeft = x;
+                h.scrollTop = y;
+            }
+            if (s)
+                s.scrollTop = top;
+            const before = hidden.map((h) => [h.scrollLeft, h.scrollTop]);
+            if (el.matches('a[href], button, input, select, textarea, [tabindex], [contenteditable]'))
+                el.focus();
+            else
+                el.scrollIntoView({ block: 'nearest', inline: 'nearest', behavior: 'instant' });
+            hidden.forEach((h, i) => {
+                const [bx, by] = before[i];
+                if (h.scrollLeft !== bx || h.scrollTop !== by) {
+                    const key = `${describe(el)}|${describe(h)}`;
+                    if (!seen.has(key)) {
+                        seen.add(key);
+                        out.push({
+                            trigger: describe(el),
+                            scrolled: describe(h),
+                            x: h.scrollLeft - bx,
+                            y: h.scrollTop - by,
+                        });
+                    }
+                }
+            });
+        }
+    }
+    for (const [h, [x, y]] of saved) {
+        h.scrollLeft = x;
+        h.scrollTop = y;
+    }
+    active?.focus?.();
+    instant.remove();
+    return out;
+}
+/** Runs both scans in the page. */
+export async function checkPositioning(page) {
+    const uncontained = await page.evaluate(findUncontainedPositioning, undefined);
+    const hiddenOverflowScrolls = await page.evaluate(findHiddenOverflowScrolls, undefined);
+    return { uncontained, hiddenOverflowScrolls };
+}
+/**
+ * Throws, listing every finding, unless the page is clean. Use it after the page reaches the state you want to
+ * check — open the panel, show the errors — since only what is rendered can be checked.
+ *
+ * ```ts
+ * import { expectPositioningContained } from '@setsquare/ui/testing';
+ * test('settings', async ({ page }) => { await page.goto('/settings'); await expectPositioningContained(page); });
+ * ```
+ */
+export async function expectPositioningContained(page) {
+    const { uncontained, hiddenOverflowScrolls } = await checkPositioning(page);
+    if (!uncontained.length && !hiddenOverflowScrolls.length)
+        return;
+    const lines = [
+        ...uncontained.map((u) => `  ${u.kind}: ${u.element}\n    scrolls inside ${u.scroller}, but is positioned against ${u.containingBlock}. Make the scroller 'relative'.`),
+        ...hiddenOverflowScrolls.map((h) => `  ${h.trigger}\n    scrolled ${h.scrolled} by ${h.x}, ${h.y}px, which is overflow:hidden and can't be scrolled back.`),
+    ];
+    throw new Error(`Positioning is not contained (${uncontained.length + hiddenOverflowScrolls.length}):\n${lines.join('\n')}`);
+}
+/**
+ * Every pointer target smaller than the minimum in either axis. A target is an interactive element as laid
+ * out — for a visually hidden input (React Aria's checkbox, radio, switch, slider), the control around it that
+ * a pointer actually hits. Disabled, hidden and aria-hidden elements are skipped, and so are inline elements
+ * (display: inline), which is how this approximates the Inline exception for links in a sentence.
+ * Returns [] when every target is big enough.
+ */
+export function findSmallTargets(options = {}, root = document) {
+    const SELECTOR = 'a[href], button, input:not([type=hidden]), select, textarea, summary, [role=button], [role=link], [role=checkbox], [role=radio], [role=switch], [role=tab], [role=menuitem], [role=menuitemcheckbox], [role=menuitemradio], [role=option], [role=slider], [role=spinbutton], [role=treeitem]';
+    const min = options.min ??
+        (parseFloat(getComputedStyle(document.documentElement).getPropertyValue('--target-min')) || 24);
+    const tiny = (el) => {
+        const r = el.getBoundingClientRect();
+        return r.width <= 2 && r.height <= 2;
+    };
+    /** A visually hidden element stands for the nearest ancestor with a size: the control a pointer hits. */
+    const targetOf = (el) => {
+        let hidden = tiny(el);
+        for (let p = el.parentElement, i = 0; p && i < 3 && !hidden; p = p.parentElement, i++)
+            if (tiny(p) && getComputedStyle(p).overflow !== 'visible')
+                hidden = true;
+        if (!hidden)
+            return el;
+        for (let p = el.parentElement; p; p = p.parentElement)
+            if (!tiny(p))
+                return p;
+        return null;
+    };
+    const describe = (el) => {
+        const id = el.id ? `#${el.id}` : '';
+        const cls = typeof el.className === 'string'
+            ? el.className
+                .split(/\s+/)
+                .filter(Boolean)
+                .slice(0, 2)
+                .map((c) => `.${c}`)
+                .join('')
+            : '';
+        const name = (el.getAttribute('aria-label') ?? el.textContent ?? '')
+            .trim()
+            .replace(/\s+/g, ' ')
+            .slice(0, 40);
+        return `${el.tagName.toLowerCase()}${id}${cls}${name ? ` "${name}"` : ''}`;
+    };
+    const seen = new Set();
+    const out = [];
+    for (const found of root.querySelectorAll(SELECTOR)) {
+        if (found.matches(':disabled, [aria-disabled=true], [data-disabled]') ||
+            found.closest('[inert], [aria-hidden=true]'))
+            continue;
+        const el = targetOf(found);
+        if (!el || seen.has(el))
+            continue;
+        seen.add(el);
+        if (options.ignore && (el.matches(options.ignore) || found.matches(options.ignore)))
+            continue;
+        const cs = getComputedStyle(el);
+        if (cs.display === 'inline' || cs.visibility !== 'visible')
+            continue;
+        const r = el.getBoundingClientRect();
+        if (r.width === 0 && r.height === 0)
+            continue;
+        if (r.width < min - 0.5 || r.height < min - 0.5)
+            out.push({
+                element: describe(el),
+                width: Math.round(r.width * 10) / 10,
+                height: Math.round(r.height * 10) / 10,
+            });
+    }
+    return out;
+}
+/**
+ * Pairs of targets whose boxes overlap on screen, where neither contains the other. WCAG's definition of
+ * target leaves the overlapping area out of the measurement, so an overlap can take a target below its
+ * minimum even when its box is big enough. Three-layer controls keep the target in the layout, so they don't
+ * overlap by construction; this finds targets made bigger with an overlay or a negative margin. Only what is
+ * on screen is compared (something scrolled or translated out of view overlaps nothing), and only within one
+ * layer: a toast or popover over the page is left to the focus-obscured checks.
+ */
+export function findOverlappingTargets(root = document) {
+    const SELECTOR = 'a[href], button, input:not([type=hidden]), select, textarea, summary, [role=button], [role=link], [role=checkbox], [role=radio], [role=switch], [role=tab], [role=menuitem], [role=menuitemcheckbox], [role=menuitemradio], [role=option], [role=slider], [role=spinbutton], [role=treeitem]';
+    const tiny = (el) => {
+        const r = el.getBoundingClientRect();
+        return r.width <= 2 && r.height <= 2;
+    };
+    const targetOf = (el) => {
+        let hidden = tiny(el);
+        for (let p = el.parentElement, i = 0; p && i < 3 && !hidden; p = p.parentElement, i++)
+            if (tiny(p) && getComputedStyle(p).overflow !== 'visible')
+                hidden = true;
+        if (!hidden)
+            return el;
+        for (let p = el.parentElement; p; p = p.parentElement)
+            if (!tiny(p))
+                return p;
+        return null;
+    };
+    const describe = (el) => {
+        const name = (el.getAttribute('aria-label') ?? el.textContent ?? '')
+            .trim()
+            .replace(/\s+/g, ' ')
+            .slice(0, 40);
+        return `${el.tagName.toLowerCase()}${name ? ` "${name}"` : ''}`;
+    };
+    /** The part of the box inside the viewport and every clipping ancestor. */
+    const visibleRect = (el) => {
+        const r = el.getBoundingClientRect();
+        let left = Math.max(r.left, 0), top = Math.max(r.top, 0), right = Math.min(r.right, innerWidth), bottom = Math.min(r.bottom, innerHeight);
+        for (let p = el.parentElement; p; p = p.parentElement) {
+            if (getComputedStyle(p).overflow === 'visible')
+                continue;
+            const pr = p.getBoundingClientRect();
+            left = Math.max(left, pr.left);
+            top = Math.max(top, pr.top);
+            right = Math.min(right, pr.right);
+            bottom = Math.min(bottom, pr.bottom);
+        }
+        return { left, top, right, bottom };
+    };
+    /**
+     * The overlay a target sits in: the nearest fixed-position ancestor (a toast region, a modal) or portal at
+     * the top of the body (a popover). An overlay covers the page on purpose, which is a question of focus
+     * being obscured, not of target size, so only targets in the same layer are compared.
+     */
+    const layerOf = (el) => {
+        for (let p = el; p && p !== document.body; p = p.parentElement) {
+            const pos = getComputedStyle(p).position;
+            if (pos === 'fixed' || (p.parentElement === document.body && pos === 'absolute'))
+                return p;
+        }
+        return null;
+    };
+    const targets = [];
+    const seen = new Set();
+    for (const found of root.querySelectorAll(SELECTOR)) {
+        if (found.matches(':disabled') || found.closest('[inert], [aria-hidden=true]'))
+            continue;
+        const el = targetOf(found);
+        if (!el || seen.has(el))
+            continue;
+        seen.add(el);
+        const cs = getComputedStyle(el);
+        if (cs.display === 'inline' || cs.visibility !== 'visible')
+            continue;
+        const r = visibleRect(el);
+        if (r.right - r.left > 0 && r.bottom - r.top > 0)
+            targets.push({ el, layer: layerOf(el), r });
+    }
+    const out = [];
+    for (let i = 0; i < targets.length; i++)
+        for (let j = i + 1; j < targets.length; j++) {
+            const a = targets[i], b = targets[j];
+            if (a.layer !== b.layer || a.el.contains(b.el) || b.el.contains(a.el))
+                continue;
+            const w = Math.min(a.r.right, b.r.right) - Math.max(a.r.left, b.r.left);
+            const h = Math.min(a.r.bottom, b.r.bottom) - Math.max(a.r.top, b.r.top);
+            if (w > 0.5 && h > 0.5)
+                out.push({ a: describe(a.el), b: describe(b.el), area: Math.round(w * h) });
+        }
+    return out;
+}
+/** Throws, listing every finding, unless every target meets the minimum and no two targets overlap. */
+export async function expectTargetsSized(page, options = {}) {
+    const small = await page.evaluate(findSmallTargets, options);
+    const overlaps = await page.evaluate(findOverlappingTargets, undefined);
+    if (!small.length && !overlaps.length)
+        return;
+    throw new Error([
+        `Targets are not sized (${small.length + overlaps.length}):`,
+        ...small.map((t) => `  ${t.element} is ${t.width} × ${t.height}px`),
+        ...overlaps.map((o) => `  ${o.a} overlaps ${o.b} by ${o.area}px²`),
+    ].join('\n'));
+}
+/**
+ * Focuses every control a keyboard can reach, one at a time, and compares a screenshot of it (and `pad` px
+ * around it) with focus on it and with focus somewhere else. An element whose pixels do not change has no
+ * visible focus indicator, which fails WCAG 2.4.7. "Somewhere else" is another control far from this one —
+ * not the page body, because a modal dialog or menu would pull focus straight back. Tooltips are hidden, and
+ * transitions, animations and the text caret are turned off, so only the indicator can make the difference.
+ * This is the check that finds a ring styled on an element that never receives focus.
+ */
+export async function findInvisibleFocus(page, options = {}) {
+    const pad = options.pad ?? 8;
+    const count = await page.evaluate((ignore) => {
+        const style = document.createElement('style');
+        style.setAttribute('data-setsquare-focus-probe-style', '');
+        style.textContent =
+            '*, *::before, *::after { transition: none !important; animation: none !important; caret-color: transparent !important; scroll-behavior: auto !important; } [role=tooltip] { visibility: hidden !important; }';
+        document.head.append(style);
+        const composite = '[role=grid], [role=treegrid], [role=listbox], [role=menu], [role=menubar], [role=tree], [role=tablist], [role=radiogroup], [role=toolbar]';
+        const candidates = [
+            ...document.querySelectorAll('a[href], button, input:not([type=hidden]), select, textarea, summary, [tabindex]'),
+        ].filter((el) => {
+            if (el.matches(':disabled') || el.closest('[inert], [aria-hidden=true]'))
+                return false;
+            // Reached by Tab, or by the arrow keys inside a composite widget.
+            if (el.tabIndex >= 0)
+                return true;
+            return (el.getAttribute('tabindex') === '-1' &&
+                el.hasAttribute('role') &&
+                !!el.parentElement?.closest(composite));
+        });
+        candidates.forEach((el, i) => {
+            el.setAttribute('data-setsquare-focus-probe', String(i));
+            // Not checked, but still somewhere to move focus to: without them, a control in a tight group can have
+            // nowhere clear of its ring to send focus, and its ring falls out of the frame.
+            if (ignore && el.matches(ignore))
+                el.setAttribute('data-setsquare-focus-skip', '');
+        });
+        return candidates.length;
+    }, options.ignore);
+    // Keyboard modality, for React Aria's data-focus-visible and the browser's :focus-visible. (React Aria
+    // ignores Shift and the other modifiers, so it has to be a real key.)
+    await page.keyboard.press('Tab');
+    const out = [];
+    for (let i = 0; i < count; i++) {
+        // 1. Put focus on another control, far from this one, and measure this one where it now sits.
+        const box = await page.evaluate(async (args) => {
+            const frames = () => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)));
+            const el = document.querySelector(`[data-setsquare-focus-probe="${args.i}"]`);
+            if (!el || !el.isConnected || el.hasAttribute('data-setsquare-focus-skip'))
+                return null;
+            el.scrollIntoView({ block: 'nearest', inline: 'nearest', behavior: 'instant' });
+            const tiny = (e) => {
+                const r = e.getBoundingClientRect();
+                return r.width <= 2 && r.height <= 2;
+            };
+            // A visually hidden input stands for its control: measure the control around it.
+            let shown = el;
+            let hidden = tiny(el);
+            for (let p = el.parentElement, k = 0; p && k < 3 && !hidden; p = p.parentElement, k++)
+                if (tiny(p) && getComputedStyle(p).overflow !== 'visible')
+                    hidden = true;
+            if (hidden)
+                for (let p = el.parentElement; p; p = p.parentElement)
+                    if (!tiny(p)) {
+                        shown = p;
+                        break;
+                    }
+            // Where it is when focused (a skip link only appears then) and when not: compare the union of both.
+            el.focus({ preventScroll: true });
+            await frames();
+            const r1 = shown.getBoundingClientRect();
+            const clip = {
+                left: r1.left - args.pad,
+                top: r1.top - args.pad,
+                right: r1.right + args.pad,
+                bottom: r1.bottom + args.pad,
+            };
+            const apart = (or, c) => or.right <= c.left || or.left >= c.right || or.bottom <= c.top || or.top >= c.bottom;
+            const all = [...document.querySelectorAll('[data-setsquare-focus-probe]')]
+                .filter((o) => o !== el && !shown.contains(o) && !o.contains(el))
+                .map((o) => ({
+                o,
+                r: o.getBoundingClientRect(),
+                d: Math.hypot(o.getBoundingClientRect().left - r1.left, o.getBoundingClientRect().top - r1.top),
+            }))
+                .sort((a, b) => b.d - a.d);
+            // Prefer a control clear of the padded area. In a tight stack (menu items) settle for one clear of the
+            // element itself, and compare the element's own box only, so the other's highlight is out of frame.
+            // With no other control at all, keep the padding: nothing else can light up in it, and a ring drawn
+            // outside the element (an outline with an offset) is only in frame with it.
+            let margin = args.pad;
+            let others = all.filter((x) => apart(x.r, clip));
+            if (!others.length && all.length) {
+                margin = 0;
+                others = all.filter((x) => apart(x.r, r1));
+            }
+            let away = false;
+            for (const { o } of others.slice(0, 8)) {
+                o.focus({ preventScroll: true });
+                await frames();
+                if (document.activeElement !== el && !shown.contains(document.activeElement)) {
+                    away = true;
+                    break;
+                }
+            }
+            if (!away) {
+                document.activeElement?.blur();
+                await frames();
+                away = document.activeElement !== el && !shown.contains(document.activeElement);
+            }
+            const r2 = shown.getBoundingClientRect();
+            const left = Math.min(r1.left, r2.left) - margin;
+            const top = Math.min(r1.top, r2.top) - margin;
+            const x = Math.max(0, left);
+            const y = Math.max(0, top);
+            const width = Math.min(innerWidth, Math.max(r1.right, r2.right) + margin) - x;
+            const height = Math.min(innerHeight, Math.max(r1.bottom, r2.bottom) + margin) - y;
+            const role = el.getAttribute('role');
+            const name = (el.getAttribute('aria-label') ?? el.textContent ?? '')
+                .trim()
+                .replace(/\s+/g, ' ')
+                .slice(0, 40);
+            return {
+                x,
+                y,
+                width,
+                height,
+                trapped: !away,
+                described: `${el.tagName.toLowerCase()}${role ? `[role=${role}]` : ''}${name ? ` "${name}"` : ''}`,
+            };
+        }, { i, pad });
+        if (!box)
+            continue;
+        if (box.trapped) {
+            out.push({ element: box.described, reason: 'trapped' });
+            continue;
+        }
+        if (box.width < 1 || box.height < 1) {
+            out.push({ element: box.described, reason: 'offscreen' });
+            continue;
+        }
+        const clip = { x: box.x, y: box.y, width: box.width, height: box.height };
+        const away = await page.screenshot({ clip, animations: 'disabled', caret: 'hide' });
+        // 2. Focus this one. If it hands focus to something inside it (a grid to its first row), that element is
+        //    probed on its own turn.
+        const kept = await page.evaluate(async (n) => {
+            const el = document.querySelector(`[data-setsquare-focus-probe="${n}"]`);
+            if (!el)
+                return false;
+            el.focus({ preventScroll: true });
+            await new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(r)));
+            return document.activeElement === el;
+        }, i);
+        if (!kept)
+            continue;
+        const here = await page.screenshot({ clip, animations: 'disabled', caret: 'hide' });
+        const same = away.length === here.length && away.every((byte, k) => byte === here[k]);
+        if (same)
+            out.push({ element: box.described, reason: 'unchanged' });
+    }
+    await page.evaluate(() => {
+        document.querySelector('style[data-setsquare-focus-probe-style]')?.remove();
+        for (const el of document.querySelectorAll('[data-setsquare-focus-probe]')) {
+            el.removeAttribute('data-setsquare-focus-probe');
+            el.removeAttribute('data-setsquare-focus-skip');
+        }
+    }, undefined);
+    return out;
+}
+/** Throws, listing every control whose focus cannot be seen, unless there are none. `trapped` ones are skipped. */
+export async function expectFocusVisible(page, options = {}) {
+    const found = (await findInvisibleFocus(page, options)).filter((f) => f.reason !== 'trapped');
+    if (!found.length)
+        return;
+    throw new Error([
+        `Focus is not visible on ${found.length} control${found.length === 1 ? '' : 's'}:`,
+        ...found.map((f) => f.reason === 'unchanged'
+            ? `  ${f.element}: nothing on screen changed when it took focus`
+            : `  ${f.element}: took focus but could not be seen`),
+    ].join('\n'));
+}
+/**
+ * Every link in running text that people who can't tell the colours apart could not find. A link counts as
+ * in running text when it is laid out inline and the block around it has words of its own — so navigation,
+ * lists of links and link buttons are left alone, as WCAG's F73 leaves them. A link passes on an underline or
+ * bottom border the text around it doesn't have, a heavier weight (600+ against 200 lighter), italics the
+ * text around it doesn't have, or a colour at least 3:1 against that text (G183). Returns [] when every link
+ * is distinguished.
+ */
+export function findUndistinguishedLinks(options = {}, root = document) {
+    const LINK = 'a[href], [role=link]';
+    const canvas = document.createElement('canvas');
+    canvas.width = canvas.height = 1;
+    const ctx = canvas.getContext('2d', { willReadFrequently: true });
+    /** Any CSS colour as 8-bit sRGB, through the canvas, so oklch and color-mix resolve the way they paint. */
+    const rgba = (colour) => {
+        ctx.clearRect(0, 0, 1, 1);
+        ctx.fillStyle = '#000';
+        ctx.fillStyle = colour;
+        ctx.fillRect(0, 0, 1, 1);
+        const d = ctx.getImageData(0, 0, 1, 1).data;
+        return [d[0], d[1], d[2], d[3] / 255];
+    };
+    const background = (el) => {
+        for (let p = el; p; p = p.parentElement) {
+            const c = rgba(getComputedStyle(p).backgroundColor);
+            if (c[3] > 0.99)
+                return [c[0], c[1], c[2]];
+        }
+        return [255, 255, 255];
+    };
+    const over = (el, colour) => {
+        const [r, g, b, a] = rgba(colour);
+        if (a > 0.99)
+            return [r, g, b];
+        const bg = background(el);
+        return [r * a + bg[0] * (1 - a), g * a + bg[1] * (1 - a), b * a + bg[2] * (1 - a)];
+    };
+    const luminance = ([r, g, b]) => {
+        const f = (v) => {
+            const c = v / 255;
+            return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+        };
+        return 0.2126 * f(r) + 0.7152 * f(g) + 0.0722 * f(b);
+    };
+    const contrast = (a, b) => {
+        const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+        return (hi + 0.05) / (lo + 0.05);
+    };
+    const underlined = (el) => getComputedStyle(el).textDecorationLine.includes('underline');
+    const bordered = (el) => {
+        const cs = getComputedStyle(el);
+        return (!['none', 'hidden'].includes(cs.borderBottomStyle) &&
+            parseFloat(cs.borderBottomWidth) >= 1 &&
+            rgba(cs.borderBottomColor)[3] > 0);
+    };
+    const tiny = (el) => {
+        const r = el.getBoundingClientRect();
+        return r.width <= 2 && r.height <= 2;
+    };
+    const describe = (el) => {
+        const name = (el.textContent ?? '').trim().replace(/\s+/g, ' ').slice(0, 40);
+        return `${el.tagName.toLowerCase()}${el.getAttribute('role') ? `[role=${el.getAttribute('role')}]` : ''}${name ? ` "${name}"` : ''}`;
+    };
+    const out = [];
+    for (const link of root.querySelectorAll(LINK)) {
+        if (options.ignore && link.matches(options.ignore))
+            continue;
+        if (link.closest('[inert], [aria-hidden=true]') || !link.getClientRects().length)
+            continue;
+        const cs = getComputedStyle(link);
+        if (cs.display !== 'inline' || cs.visibility !== 'visible')
+            continue;
+        // The block the sentence is in, and whether it has words outside its links.
+        let block = link.parentElement;
+        while (block && ['inline', 'contents'].includes(getComputedStyle(block).display))
+            block = block.parentElement;
+        if (!block)
+            continue;
+        let words = '';
+        const walker = document.createTreeWalker(block, NodeFilter.SHOW_TEXT);
+        for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+            const parent = n.parentElement;
+            if (!parent || parent.closest(LINK) || parent.closest('[aria-hidden=true]') || tiny(parent))
+                continue;
+            words += n.textContent ?? '';
+        }
+        if (!/[\p{L}\p{N}]/u.test(words))
+            continue;
+        const around = link.parentElement;
+        const ac = getComputedStyle(around);
+        // Decoration isn't inherited in computed style but is painted on descendants, so an underline anywhere
+        // between the link and its block is on the surrounding words too.
+        let aroundUnderlined = false;
+        for (let p = around; p; p = p === block ? null : p.parentElement)
+            if (underlined(p))
+                aroundUnderlined = true;
+        const text = (link.textContent ?? '').trim();
+        const ownUnderline = underlined(link) ||
+            bordered(link) ||
+            [...link.querySelectorAll('*')].some((d) => (underlined(d) || bordered(d)) && (d.textContent ?? '').trim() === text);
+        const hasUnderline = ownUnderline && !aroundUnderlined;
+        const ratio = Math.round(contrast(over(link, cs.color), over(around, ac.color)) * 100) / 100;
+        if (options.underline) {
+            if (!hasUnderline)
+                out.push({ element: describe(link), contrast: ratio, reason: 'no-underline' });
+            continue;
+        }
+        const weight = parseFloat(cs.fontWeight);
+        const bold = weight >= 600 && weight - parseFloat(ac.fontWeight) >= 200;
+        const italic = cs.fontStyle !== 'normal' && ac.fontStyle === 'normal';
+        if (hasUnderline || bold || italic || ratio >= 3)
+            continue;
+        out.push({ element: describe(link), contrast: ratio, reason: 'colour-only' });
+    }
+    return out;
+}
+/** Throws, listing every finding, unless every link in running text can be told apart without colour. */
+export async function expectLinksDistinguished(page, options = {}) {
+    const found = await page.evaluate(findUndistinguishedLinks, options);
+    if (!found.length)
+        return;
+    throw new Error([
+        `Links in running text are not distinguished (${found.length}):`,
+        ...found.map((f) => f.reason === 'no-underline'
+            ? `  ${f.element} has no underline`
+            : `  ${f.element} differs from the text around it only by colour, at ${f.contrast}:1 (needs an underline, bold, italics or 3:1)`),
+    ].join('\n'));
+}
+/**
+ * Hovers every target and reads the cursor at its centre and just inside each corner — the whole of Layer 1,
+ * not only the paint — so a child that resets the cursor, or a target whose edge still shows the arrow, is
+ * found. Hovering first means states that only appear on hover (React Aria's data-hovered) count. Points
+ * covered by another target (a checkbox in a row) are that target's, and are checked on its own turn. A
+ * visually hidden input stands for its label (a checkbox, radio or switch) or, for a range input, the thumb
+ * around it; one with neither (a drop zone's hidden button) has no pointer target and is skipped. No WCAG
+ * criterion covers the cursor: this checks that one rule is applied everywhere.
+ */
+export async function findCursorMismatches(page, options = {}) {
+    const probes = await page.evaluate((ignore) => {
+        const style = document.createElement('style');
+        style.setAttribute('data-setsquare-cursor-probe-style', '');
+        style.textContent =
+            '[role=tooltip] { visibility: hidden !important; } * { scroll-behavior: auto !important; }';
+        document.head.append(style);
+        const TEXT = 'input:is(:not([type]), [type=text], [type=search], [type=email], [type=url], [type=tel], [type=password], [type=number]), textarea, [contenteditable]:not([contenteditable=false]), [role=spinbutton]';
+        const PRESS = 'a[href], button, input:is([type=button], [type=submit], [type=reset], [type=checkbox], [type=radio], [type=file]), select, summary, [role=button], [role=link], [role=checkbox], [role=radio], [role=switch], [role=tab], [role=menuitem], [role=menuitemcheckbox], [role=menuitemradio], [role=option], [role=treeitem], [role=row][aria-selected], [role=columnheader][aria-sort], th[aria-sort]';
+        const tiny = (el) => {
+            const r = el.getBoundingClientRect();
+            return r.width <= 2 && r.height <= 2;
+        };
+        const hiddenInput = (el) => {
+            if (tiny(el))
+                return true;
+            for (let p = el.parentElement, k = 0; p && k < 3; p = p.parentElement, k++)
+                if (tiny(p) && getComputedStyle(p).overflow !== 'visible')
+                    return true;
+            return false;
+        };
+        const out = [];
+        const seen = new Set();
+        for (const found of document.querySelectorAll(`${PRESS}, ${TEXT}, input[type=range]`)) {
+            if (found.closest('[inert], [aria-hidden=true]') || !found.getClientRects().length)
+                continue;
+            let el = found;
+            if (hiddenInput(found)) {
+                el = null;
+                if (found.matches('input[type=range]')) {
+                    for (let p = found.parentElement; p; p = p.parentElement)
+                        if (!tiny(p)) {
+                            el = p;
+                            break;
+                        }
+                }
+                else {
+                    const label = found.closest('label');
+                    if (label && !tiny(label))
+                        el = label;
+                }
+            }
+            if (!el || seen.has(el))
+                continue;
+            seen.add(el);
+            if (ignore && (el.matches(ignore) || found.matches(ignore)))
+                continue;
+            if (getComputedStyle(el).visibility !== 'visible')
+                continue;
+            const off = (e) => e.matches(':disabled, [aria-disabled=true], [data-disabled]');
+            const disabled = off(found) || off(el) || !!found.closest('fieldset:disabled');
+            const kind = found.matches('[data-pending], [aria-busy=true]')
+                ? 'pending'
+                : disabled && (found.hasAttribute('aria-current') || el.hasAttribute('aria-current'))
+                    ? 'current'
+                    : disabled
+                        ? 'disabled'
+                        : found.matches(TEXT)
+                            ? 'text'
+                            : found.matches('input[type=range]')
+                                ? 'drag'
+                                : found.matches('[aria-readonly=true], input[readonly]') ||
+                                    el.matches('[data-readonly]')
+                                    ? 'readonly'
+                                    : 'press';
+            const role = el.getAttribute('role');
+            const name = (el.getAttribute('aria-label') ?? el.textContent ?? '')
+                .trim()
+                .replace(/\s+/g, ' ')
+                .slice(0, 40);
+            el.setAttribute('data-setsquare-cursor-probe', String(out.length));
+            out.push({
+                i: out.length,
+                kind,
+                described: `${el.tagName.toLowerCase()}${role ? `[role=${role}]` : ''}${name ? ` "${name}"` : ''}`,
+            });
+        }
+        return out;
+    }, options.ignore);
+    const defaults = {
+        press: ['pointer'],
+        text: ['text', 'auto'],
+        drag: ['grab'],
+        disabled: ['not-allowed'],
+        pending: ['wait', 'progress'],
+        readonly: ['default'],
+        current: ['default'],
+    };
+    const out = [];
+    for (const probe of probes) {
+        const setting = options.expect?.[probe.kind];
+        if (setting === false)
+            continue;
+        const expected = setting ?? defaults[probe.kind];
+        const centre = await page.evaluate((i) => {
+            const el = document.querySelector(`[data-setsquare-cursor-probe="${i}"]`);
+            if (!el)
+                return null;
+            el.scrollIntoView({ block: 'nearest', inline: 'nearest', behavior: 'instant' });
+            const r = el.getBoundingClientRect();
+            const left = Math.max(r.left, 0), top = Math.max(r.top, 0), right = Math.min(r.right, innerWidth), bottom = Math.min(r.bottom, innerHeight);
+            if (right - left < 1 || bottom - top < 1)
+                return null;
+            return { x: (left + right) / 2, y: (top + bottom) / 2 };
+        }, probe.i);
+        if (!centre)
+            continue;
+        await page.mouse.move(centre.x, centre.y);
+        const seen = await page.evaluate((i) => {
+            const el = document.querySelector(`[data-setsquare-cursor-probe="${i}"]`);
+            if (!el)
+                return [];
+            const r = el.getBoundingClientRect();
+            const left = Math.max(r.left, 0), top = Math.max(r.top, 0), right = Math.min(r.right, innerWidth), bottom = Math.min(r.bottom, innerHeight);
+            // Just inside each corner, clear of a rounded corner's cut.
+            const inset = Math.min(4, (right - left) / 4, (bottom - top) / 4);
+            const points = [
+                [(left + right) / 2, (top + bottom) / 2, 'centre'],
+                [left + inset, top + inset, 'edge'],
+                [right - inset, top + inset, 'edge'],
+                [left + inset, bottom - inset, 'edge'],
+                [right - inset, bottom - inset, 'edge'],
+            ];
+            const found = [];
+            for (const [x, y, at] of points) {
+                const hit = document.elementFromPoint(x, y);
+                if (!hit)
+                    continue;
+                // Only points where this target is the nearest one to what the pointer is over.
+                const owner = hit.closest('[data-setsquare-cursor-probe]');
+                if (owner !== el)
+                    continue;
+                found.push({ cursor: getComputedStyle(hit).cursor, at });
+            }
+            return found;
+        }, probe.i);
+        const wrong = seen.filter((s) => !expected.includes(s.cursor));
+        if (wrong.length)
+            out.push({
+                element: probe.described,
+                kind: probe.kind,
+                expected,
+                actual: wrong.filter((w, k) => wrong.findIndex((o) => o.cursor === w.cursor && o.at === w.at) === k),
+            });
+    }
+    await page.mouse.move(0, 0);
+    await page.evaluate(() => {
+        document.querySelector('style[data-setsquare-cursor-probe-style]')?.remove();
+        for (const el of document.querySelectorAll('[data-setsquare-cursor-probe]'))
+            el.removeAttribute('data-setsquare-cursor-probe');
+    }, undefined);
+    return out;
+}
+/** Throws, listing every target whose cursor breaks the rule, unless there are none. */
+export async function expectCursorsMatch(page, options = {}) {
+    const found = await findCursorMismatches(page, options);
+    if (!found.length)
+        return;
+    throw new Error([
+        `Cursors do not match (${found.length}):`,
+        ...found.map((f) => `  ${f.element} (${f.kind}): ${f.actual.map((a) => `${a.cursor} at the ${a.at}`).join(', ')}; expected ${f.expected.join(' or ')}`),
+    ].join('\n'));
+}
+/**
+ * Everything that reaches past the right edge of the page at the width it is laid out at: set the viewport
+ * to 320px to check WCAG 1.4.10's reflow width. Content inside its own scroll container (a `ScrollRegion`,
+ * a code block, a data table) is left alone as long as the scroller itself fits, since it scrolls on its own
+ * and the page doesn't; so is content an ancestor clips inside the page, which is that component's business.
+ * `clipped` is only reported for something with words or media in it, so a decorative glow bleeding off the
+ * edge isn't. Fixed-position elements are left out. Only the outermost culprit is reported. Returns [] when
+ * the page fits.
+ */
+export function findPageOverflow(options = {}, root = document) {
+    const describe = (el) => {
+        const id = el.id ? `#${el.id}` : '';
+        const cls = typeof el.className === 'string'
+            ? el.className
+                .split(/\s+/)
+                .filter(Boolean)
+                .slice(0, 3)
+                .map((c) => `.${c}`)
+                .join('')
+            : '';
+        const name = (el.getAttribute('aria-label') ?? el.textContent ?? '')
+            .trim()
+            .replace(/\s+/g, ' ')
+            .slice(0, 40);
+        return `${el.tagName.toLowerCase()}${id}${cls}${name ? ` "${name}"` : ''}`;
+    };
+    const page = document.scrollingElement ?? document.documentElement;
+    const width = document.documentElement.clientWidth;
+    const scrolls = page.scrollWidth > width;
+    // overflow on <html> or <body> clips at the viewport: content past the edge is cut off, not scrolled to.
+    const pageClips = [document.documentElement, document.body].some((e) => /(hidden|clip)/.test(getComputedStyle(e).overflowX));
+    /** Right edge in page coordinates, so a page already scrolled sideways measures the same. */
+    const rightOf = (el) => el.getBoundingClientRect().right + page.scrollLeft;
+    const meaningful = (el) => !el.closest('[aria-hidden=true]') &&
+        (!!el.textContent?.trim() ||
+            !!el.matches('img, svg, video, canvas, iframe, input, select, textarea') ||
+            !!el.querySelector('img, svg, video, canvas, iframe, input, select, textarea'));
+    const out = [];
+    const reported = [];
+    for (const el of Array.from(root.querySelectorAll('*'))) {
+        if (el === document.documentElement || el === document.body)
+            continue;
+        if (options.ignore && el.closest(options.ignore))
+            continue;
+        if (reported.some((r) => r.contains(el)))
+            continue;
+        const r = el.getBoundingClientRect();
+        if (r.width === 0 && r.height === 0)
+            continue;
+        const by = rightOf(el) - width;
+        if (by <= 0.5)
+            continue;
+        // Walk out to whatever decides where this overflow ends up.
+        let fixed = getComputedStyle(el).position === 'fixed';
+        let held = false; // an ancestor inside the page scrolls or clips it: not the page's problem
+        let clipped = false; // an ancestor that runs to the page's edge cuts it off
+        for (let p = el.parentElement; p && p !== document.body; p = p.parentElement) {
+            const cs = getComputedStyle(p);
+            if (cs.position === 'fixed') {
+                fixed = true;
+                break;
+            }
+            if (cs.overflowX === 'visible')
+                continue;
+            const edge = rightOf(p);
+            if (/(auto|scroll)/.test(cs.overflowX)) {
+                if (edge <= width + 0.5) {
+                    held = true; // its own scroller holds it, and the scroller fits
+                    break;
+                }
+                continue; // a scroller that is itself too wide is reported on its own turn
+            }
+            if (edge < width - 1) {
+                held = true; // clipped inside the page: that component's business
+                break;
+            }
+            clipped = true;
+            break;
+        }
+        if (fixed || held)
+            continue;
+        const reason = clipped || pageClips ? 'clipped' : scrolls ? 'scrolls' : null;
+        if (!reason || (reason === 'clipped' && !meaningful(el)))
+            continue;
+        reported.push(el);
+        out.push({ element: describe(el), reason, by: Math.round(by * 10) / 10 });
+    }
+    if (scrolls && !out.some((o) => o.reason === 'scrolls'))
+        out.push({ element: 'the page', reason: 'scrolls', by: page.scrollWidth - width });
+    return out;
+}
+/** Throws, listing every finding, unless the page fits its width. Set the viewport first: 320px for reflow. */
+export async function expectPageReflows(page, options = {}) {
+    const found = await page.evaluate(findPageOverflow, options);
+    if (!found.length)
+        return;
+    throw new Error([
+        `The page doesn't fit its width (${found.length}):`,
+        ...found.map((f) => f.reason === 'scrolls'
+            ? `  ${f.element} reaches ${f.by}px past the edge, so the page scrolls sideways`
+            : `  ${f.element} reaches ${f.by}px past the edge, where an overflow:hidden box cuts it off`),
+    ].join('\n'));
+}
+/**
+ * Applies WCAG 1.4.12's four text-spacing metrics to the whole page — line height 1.5, paragraph spacing
+ * 2em, letter spacing 0.12em, word spacing 0.16em, the way a user's stylesheet or bookmarklet would — and
+ * reports every box whose content now runs out of it further than it did before. Measuring the difference
+ * leaves alone anything that was already clipped on purpose (visually hidden text, a decorative bleed).
+ * Scroll containers are left out too, since their content can still be scrolled to, and so is text that
+ * spills from a box inside a scroller that scrolls that way (code in a code block). Only the innermost box
+ * is reported. Takes the spacing off again before returning. Returns [] when everything still fits.
+ */
+export function findClippedText(options = {}, root = document) {
+    const describe = (el) => {
+        const id = el.id ? `#${el.id}` : '';
+        const cls = typeof el.className === 'string'
+            ? el.className
+                .split(/\s+/)
+                .filter(Boolean)
+                .slice(0, 3)
+                .map((c) => `.${c}`)
+                .join('')
+            : '';
+        const name = (el.getAttribute('aria-label') ?? el.textContent ?? '')
+            .trim()
+            .replace(/\s+/g, ' ')
+            .slice(0, 40);
+        return `${el.tagName.toLowerCase()}${id}${cls}${name ? ` "${name}"` : ''}`;
+    };
+    const boxes = Array.from(root.querySelectorAll('*')).filter((el) => {
+        if (el === document.documentElement || el === document.body)
+            return false;
+        if (options.ignore && el.closest(options.ignore))
+            return false;
+        const cs = getComputedStyle(el);
+        if (cs.display === 'inline' || cs.display === 'contents' || cs.display === 'none')
+            return false;
+        if (/(auto|scroll)/.test(cs.overflowX + cs.overflowY))
+            return false;
+        const r = el.getBoundingClientRect();
+        // 1px visually hidden boxes clip on purpose.
+        return r.width > 2 && r.height > 2 && !!el.textContent?.trim();
+    });
+    const excess = (el) => [
+        Math.max(0, el.scrollWidth - el.clientWidth),
+        Math.max(0, el.scrollHeight - el.clientHeight),
+    ];
+    const before = boxes.map(excess);
+    const style = document.createElement('style');
+    style.setAttribute('data-setsquare-text-spacing', '');
+    style.textContent =
+        '* { line-height: 1.5 !important; letter-spacing: 0.12em !important; word-spacing: 0.16em !important; } p { margin-bottom: 2em !important; }';
+    document.head.append(style);
+    /** Which ways the nearest ancestor that doesn't show its overflow scrolls: text spilled that way is reachable. */
+    const scrollsTo = (el) => {
+        for (let p = el.parentElement; p && p !== document.body; p = p.parentElement) {
+            const cs = getComputedStyle(p);
+            if (cs.overflowX === 'visible' && cs.overflowY === 'visible')
+                continue;
+            return { x: /(auto|scroll)/.test(cs.overflowX), y: /(auto|scroll)/.test(cs.overflowY) };
+        }
+        return { x: false, y: false };
+    };
+    const clips = (el) => {
+        const cs = getComputedStyle(el);
+        return /(hidden|clip)/.test(cs.overflowX + cs.overflowY) || cs.textOverflow === 'ellipsis';
+    };
+    const found = [];
+    boxes.forEach((el, i) => {
+        const [x, y] = excess(el);
+        let dx = x - before[i][0];
+        let dy = y - before[i][1];
+        if (!clips(el)) {
+            const reach = scrollsTo(el);
+            if (reach.x)
+                dx = 0;
+            if (reach.y)
+                dy = 0;
+        }
+        if (dx > 1 || dy > 1)
+            found.push({ el, x: Math.round(dx), y: Math.round(dy) });
+    });
+    const out = found
+        .filter((f) => !found.some((g) => g !== f && f.el.contains(g.el)))
+        .map((f) => ({
+        element: describe(f.el),
+        reason: clips(f.el) ? 'clipped' : 'overflows',
+        x: f.x,
+        y: f.y,
+    }));
+    style.remove();
+    return out;
+}
+/** Throws, listing every finding, unless all the text still fits with WCAG 1.4.12's spacing applied. */
+export async function expectTextUnclipped(page, options = {}) {
+    const found = await page.evaluate(findClippedText, options);
+    if (!found.length)
+        return;
+    throw new Error([
+        `Text doesn't fit with 1.4.12's spacing applied (${found.length}):`,
+        ...found.map((f) => `  ${f.element} ${f.reason === 'clipped' ? 'cuts its text off' : 'spills its text over what follows'} (${f.x} × ${f.y}px more than before)`),
+    ].join('\n'));
+}
+/**
+ * Everything moving on the page that runs longer than `max` (or forever) with no visible control to pause
+ * it. It reads `document.getAnimations()` — CSS animations, CSS transitions and Web Animations that are
+ * running now — and every `<video>` that is playing without its own `controls`. Something counts as paused
+ * by a control when it sits inside an element whose `id` a visible button on the page names in
+ * `data-pauses`; `aria-controls` doesn't count, since a menu button names its panel that way. It can't see
+ * motion drawn by `requestAnimationFrame`, SVG (SMIL)
+ * animation, animated images or canvas, and it only sees what is running when it is called, so call it once
+ * the page has settled and again in each state that starts something. Returns [] when nothing qualifies.
+ */
+export function findEndlessAnimations(options = {}, root = document) {
+    const max = options.max ?? 5000;
+    const describe = (el, pseudo) => {
+        const id = el.id ? `#${el.id}` : '';
+        const cls = typeof el.className === 'string'
+            ? el.className
+                .split(/\s+/)
+                .filter(Boolean)
+                .slice(0, 3)
+                .map((c) => `.${c}`)
+                .join('')
+            : '';
+        const name = (el.getAttribute('aria-label') ?? el.textContent ?? '')
+            .trim()
+            .replace(/\s+/g, ' ')
+            .slice(0, 40);
+        return `${el.tagName.toLowerCase()}${id}${cls}${pseudo ?? ''}${name ? ` "${name}"` : ''}`;
+    };
+    // On screen. aria-hidden doesn't count against it: decorative motion is usually aria-hidden, and still moves.
+    const shown = (el) => el.getClientRects().length > 0 && getComputedStyle(el).visibility === 'visible';
+    // The ids that a visible button someone can use says it pauses.
+    const paused = new Set();
+    for (const b of document.querySelectorAll('button, [role=button]')) {
+        if (!shown(b) || b.closest('[inert], [aria-hidden=true]'))
+            continue;
+        for (const id of (b.getAttribute('data-pauses') ?? '').split(/\s+/))
+            if (id)
+                paused.add(id);
+    }
+    const controlled = (el) => {
+        for (let p = el; p; p = p.parentElement)
+            if (p.id && paused.has(p.id))
+                return true;
+        return false;
+    };
+    const inRoot = (el) => root.contains(el);
+    const out = [];
+    const seen = new Set();
+    for (const a of document.getAnimations()) {
+        if (a.playState !== 'running')
+            continue;
+        const effect = a.effect;
+        const target = effect?.target;
+        if (!target || !inRoot(target) || !shown(target))
+            continue;
+        if (options.ignore && target.closest(options.ignore))
+            continue;
+        const duration = Number(effect.getComputedTiming().activeDuration);
+        if (!(duration > max) || controlled(target))
+            continue;
+        const animation = 'animationName' in a
+            ? String(a.animationName)
+            : 'transitionProperty' in a
+                ? `transition: ${a.transitionProperty}`
+                : 'script';
+        const element = describe(target, effect.pseudoElement);
+        const key = `${element}|${animation}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({ element, animation, duration });
+    }
+    for (const v of root.querySelectorAll('video')) {
+        if (v.paused || v.ended || v.controls || !shown(v))
+            continue;
+        if (options.ignore && v.closest(options.ignore))
+            continue;
+        const duration = v.loop || !Number.isFinite(v.duration) ? Infinity : v.duration * 1000;
+        if (!(duration > max) || controlled(v))
+            continue;
+        out.push({ element: describe(v), animation: 'video', duration });
+    }
+    return out;
+}
+/** Throws, listing every finding, unless everything that moves for longer than `max` can be paused. */
+export async function expectAnimationsPausable(page, options = {}) {
+    const found = await page.evaluate(findEndlessAnimations, options);
+    if (!found.length)
+        return;
+    throw new Error([
+        `Motion runs on with nothing to pause it (${found.length}):`,
+        ...found.map((f) => `  ${f.element}: ${f.animation}, ${f.duration === Infinity ? 'forever' : `${Math.round(f.duration / 100) / 10}s`}`),
+    ].join('\n'));
+}
+//# sourceMappingURL=index.js.map