@reticlehq/browser 3.7.0 → 3.8.0

package/dist/dom/dom-ignore.js

@@ -1,4 +1,5 @@
 import { RETICLE_OVERLAY_SELECTOR } from '@reticlehq/core';
+import { capturedRootOf } from './shadow-registry.js';
 export const RETICLE_OVERLAY = RETICLE_OVERLAY_SELECTOR;
 const DEV_OVERLAYS = '[data-agentation],#__next-build-watcher,nextjs-portal,[data-nextjs-dialog],[data-nextjs-toast]';
 let extraIgnore = '';
@@ -29,12 +30,53 @@ export function isUnobserved(el) {
 export function isReticleUi(node) {
     return node !== null && node.closest(RETICLE_OVERLAY) !== null;
 }
-const HUD_NARRATION = '[data-reticle-log],[data-reticle-harness-log],[data-reticle-chat-pill-text],[data-reticle-agent-said],[data-reticle-agent-note]';
+const HUD_NARRATION = '[data-reticle-log],[data-reticle-harness-log],[data-reticle-chat-pill-text],[data-reticle-agent-said],[data-reticle-agent-note],[data-reticle-act-line]';
 export function isIgnored(el) {
     const ours = exposed() ? HUD_NARRATION : RETICLE_OVERLAY;
     const sel = [ours, DEV_OVERLAYS, extraIgnore].filter((part) => part.length > 0).join(',');
     return el.closest(sel) !== null;
 }
+export function isWordsIgnored(el) {
+    return isIgnored(el) || isReticleOverlay(el);
+}
+export const FrameworkErrorDialog = {
+    NEXT: 'Next.js error dialog',
+    VITE: 'Vite error overlay',
+};
+const NEXT_PORTAL = 'nextjs-portal';
+const NEXT_DIALOG = '[data-nextjs-dialog]';
+const VITE_OVERLAY = 'vite-error-overlay';
+function openFrameworkErrorDialog(doc) {
+    const vite = doc.querySelector(VITE_OVERLAY);
+    if (vite !== null)
+        return { name: FrameworkErrorDialog.VITE, host: vite };
+    for (const portal of Array.from(doc.querySelectorAll(NEXT_PORTAL))) {
+        const root = portal.shadowRoot ?? capturedRootOf(portal);
+        if (null !== (root ?? portal).querySelector(NEXT_DIALOG)) {
+            return { name: FrameworkErrorDialog.NEXT, host: portal };
+        }
+    }
+    const light = doc.querySelector(NEXT_DIALOG);
+    return null === light ? undefined : { name: FrameworkErrorDialog.NEXT, host: light };
+}
+export function dialogCovering(matches) {
+    const first = matches[0];
+    if (first === undefined)
+        return undefined;
+    const dialog = openFrameworkErrorDialog(first.ownerDocument);
+    if (dialog === undefined)
+        return undefined;
+    return matches.some((el) => !isInsideHost(el, dialog.host)) ? dialog.name : undefined;
+}
+function isInsideHost(el, host) {
+    for (let node = el; node !== null;) {
+        if (node === host)
+            return true;
+        const root = node.getRootNode();
+        node = node.parentNode ?? (root instanceof ShadowRoot ? root.host : null);
+    }
+    return false;
+}
 const APP_MODAL = 'dialog[open], [aria-modal="true"]';
 export function appModalOpen(doc) {
     for (const el of Array.from(doc.querySelectorAll(APP_MODAL))) {

package/dist/dom/layout-audit.d.ts

@@ -0,0 +1,15 @@
+export declare const LayoutDefect: {
+    readonly CLIPPED: "clipped";
+    readonly OVERLAP: "overlap";
+    readonly CONTRAST: "contrast";
+};
+export type LayoutDefect = (typeof LayoutDefect)[keyof typeof LayoutDefect];
+export interface LayoutFinding {
+    kind: LayoutDefect;
+    ref: string;
+    what: string;
+    detail: string;
+    value: number;
+    bound: number;
+}
+export declare function auditLayout(root?: Element): LayoutFinding[];

package/dist/dom/layout-audit.js

@@ -0,0 +1,208 @@
+import { refs } from './addressing/refs.js';
+import { getAccessibleName } from './a11y.js';
+import { isIgnored } from './dom-ignore.js';
+export const LayoutDefect = {
+    CLIPPED: 'clipped',
+    OVERLAP: 'overlap',
+    CONTRAST: 'contrast',
+};
+const MAX_FINDINGS = 20;
+const MAX_CONTROLS = 300;
+const WHAT_CHARS = 60;
+const SLACK_PX = 1;
+const OVERLAP_SHARE = 0.25;
+const MIN_CONTRAST = 4.5;
+const MIN_CONTRAST_LARGE = 3;
+const LARGE_PX = 24;
+const LARGE_BOLD_PX = 18.66;
+const BOLD_WEIGHT = 700;
+const CONTROLS = 'button, a[href], input:not([type="hidden"]), select, textarea, [role="button"], [role="link"], [role="tab"], [role="menuitem"]';
+const CLIPPED_AWAY = /rect\(\s*0(px)?[\s,]+0(px)?[\s,]+0(px)?[\s,]+0(px)?\s*\)|inset\(\s*50%/;
+const MIN_BOX_PX = 4;
+const shown = (el) => {
+    const rect = el.getBoundingClientRect();
+    if (rect.width < MIN_BOX_PX || rect.height < MIN_BOX_PX) {
+        return null;
+    }
+    const style = getComputedStyle(el);
+    if ('hidden' === style.visibility || 'none' === style.display || '0' === style.opacity) {
+        return null;
+    }
+    if (CLIPPED_AWAY.test(style.clip) || CLIPPED_AWAY.test(style.clipPath)) {
+        return null;
+    }
+    return rect;
+};
+const whatOf = (el) => (getAccessibleName(el) || (el.textContent ?? ''))
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, WHAT_CHARS);
+const ownText = (el) => [...el.childNodes]
+    .filter((n) => Node.TEXT_NODE === n.nodeType)
+    .map((n) => n.textContent ?? '')
+    .join('')
+    .trim();
+const CUTS = new Set(['hidden', 'clip']);
+const clipped = (el) => {
+    const style = getComputedStyle(el);
+    const wide = el.scrollWidth > el.clientWidth + SLACK_PX && CUTS.has(style.overflowX);
+    const tall = el.scrollHeight > el.clientHeight + SLACK_PX && CUTS.has(style.overflowY);
+    const declared = 'ellipsis' === style.textOverflow ||
+        ('' !== style.getPropertyValue('-webkit-line-clamp') &&
+            'none' !== style.getPropertyValue('-webkit-line-clamp'));
+    if (declared || (!wide && !tall)) {
+        return null;
+    }
+    return wide
+        ? {
+            detail: `${String(el.scrollWidth)}px of text in a ${String(el.clientWidth)}px box, cut with no ellipsis`,
+            value: el.scrollWidth,
+            bound: el.clientWidth,
+        }
+        : {
+            detail: `${String(el.scrollHeight)}px of text in a ${String(el.clientHeight)}px box, cut with no line clamp`,
+            value: el.scrollHeight,
+            bound: el.clientHeight,
+        };
+};
+const RGB = /rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:[\s,/]+([\d.]+%?))?\s*\)/;
+const parse = (value) => {
+    const m = RGB.exec(value);
+    if (null === m) {
+        return null;
+    }
+    const alphaRaw = m[4];
+    let alpha = 1;
+    if (alphaRaw !== undefined) {
+        alpha = alphaRaw.endsWith('%') ? Number(alphaRaw.slice(0, -1)) / 100 : Number(alphaRaw);
+    }
+    return [Number(m[1]), Number(m[2]), Number(m[3]), alpha];
+};
+const luminance = ([r, g, b]) => {
+    const lin = (c) => {
+        const s = c / 255;
+        return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+};
+const over = (top, under) => {
+    const a = top[3];
+    return [
+        top[0] * a + under[0] * (1 - a),
+        top[1] * a + under[1] * (1 - a),
+        top[2] * a + under[2] * (1 - a),
+        1,
+    ];
+};
+const backdrop = (el) => {
+    const layers = [];
+    for (let at = el; null !== at; at = at.parentElement) {
+        const style = getComputedStyle(at);
+        if ('none' !== style.backgroundImage && '' !== style.backgroundImage) {
+            return null;
+        }
+        const colour = parse(style.backgroundColor);
+        if (null !== colour && colour[3] > 0) {
+            layers.push(colour);
+            if (1 === colour[3]) {
+                break;
+            }
+        }
+    }
+    return layers.reduceRight((under, top) => over(top, under), [255, 255, 255, 1]);
+};
+const contrastOf = (el) => {
+    const style = getComputedStyle(el);
+    const fg = parse(style.color);
+    const bg = backdrop(el);
+    if (null === fg || null === bg) {
+        return null;
+    }
+    const text = over(fg, bg);
+    const [hi, lo] = [luminance(text), luminance(bg)].sort((a, b) => b - a);
+    const size = Number.parseFloat(style.fontSize);
+    const weight = Number.parseInt(style.fontWeight, 10);
+    const large = size >= LARGE_PX || (size >= LARGE_BOLD_PX && weight >= BOLD_WEIGHT);
+    return { ratio: (hi + 0.05) / (lo + 0.05), min: large ? MIN_CONTRAST_LARGE : MIN_CONTRAST };
+};
+const seenAt = (x, y, ...els) => {
+    if ('function' !== typeof document.elementFromPoint) {
+        return true;
+    }
+    const top = document.elementFromPoint(x, y);
+    return null !== top && els.some((el) => el === top || el.contains(top));
+};
+const INSET_PX = 2;
+const visible = (el, r) => [
+    [r.left + r.width / 2, r.top + r.height / 2],
+    [r.left + INSET_PX, r.top + INSET_PX],
+    [r.right - INSET_PX, r.top + INSET_PX],
+    [r.left + INSET_PX, r.bottom - INSET_PX],
+    [r.right - INSET_PX, r.bottom - INSET_PX],
+].some(([x = 0, y = 0]) => seenAt(x, y, el));
+const share = (a, b) => {
+    const w = Math.min(a.right, b.right) - Math.max(a.left, b.left);
+    const h = Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top);
+    if (w <= 0 || h <= 0) {
+        return 0;
+    }
+    return (w * h) / Math.min(a.width * a.height, b.width * b.height);
+};
+export function auditLayout(root = document.body) {
+    const found = [];
+    const add = (kind, el, measured) => {
+        if (found.length < MAX_FINDINGS) {
+            found.push({ kind, ref: refs.refFor(el), what: whatOf(el), ...measured });
+        }
+    };
+    for (const el of root.querySelectorAll('*')) {
+        if (found.length >= MAX_FINDINGS) {
+            break;
+        }
+        if (isIgnored(el) || '' === ownText(el)) {
+            continue;
+        }
+        const rect = shown(el);
+        if (null === rect || !seenAt(rect.left + rect.width / 2, rect.top + rect.height / 2, el)) {
+            continue;
+        }
+        const cut = clipped(el);
+        if (null !== cut) {
+            add(LayoutDefect.CLIPPED, el, cut);
+        }
+        const contrast = contrastOf(el);
+        if (null !== contrast && contrast.ratio < contrast.min) {
+            add(LayoutDefect.CONTRAST, el, {
+                detail: `contrast ${contrast.ratio.toFixed(2)}:1, under ${String(contrast.min)}:1`,
+                value: Math.round(contrast.ratio * 100) / 100,
+                bound: contrast.min,
+            });
+        }
+    }
+    const controls = [...root.querySelectorAll(CONTROLS)]
+        .filter((el) => !isIgnored(el))
+        .slice(0, MAX_CONTROLS)
+        .flatMap((el) => {
+        const rect = shown(el);
+        return null === rect ? [] : [{ el, rect }];
+    });
+    for (const [i, a] of controls.entries()) {
+        for (const b of controls.slice(i + 1)) {
+            if (found.length >= MAX_FINDINGS) {
+                return found;
+            }
+            if (a.el.contains(b.el) || b.el.contains(a.el)) {
+                continue;
+            }
+            const covered = share(a.rect, b.rect);
+            if (covered >= OVERLAP_SHARE && visible(a.el, a.rect) && visible(b.el, b.rect)) {
+                add(LayoutDefect.OVERLAP, a.el, {
+                    detail: `drawn over "${whatOf(b.el)}" (${refs.refFor(b.el)})`,
+                    value: Math.round(covered * 100) / 100,
+                    bound: OVERLAP_SHARE,
+                });
+            }
+        }
+    }
+    return found;
+}

package/dist/dom/paint-context.d.ts

@@ -4,3 +4,18 @@ export interface PaintContextEntry {
     readonly value: string;
 }
 export declare function paintContextOf(el: Element): PaintContextEntry[];
+export type VisibleBounds = Pick<DOMRect, 'left' | 'right' | 'top' | 'bottom' | 'width' | 'height'>;
+export interface VisibilityInfo {
+    hidden: boolean;
+    style: CSSStyleDeclaration | null;
+    parent: Element | null;
+    clipX: boolean;
+    clipY: boolean;
+    scrollX: boolean;
+    scrollY: boolean;
+    hasClipping: boolean;
+    clipBox?: VisibleBounds;
+}
+export declare function overflowAxes(style: CSSStyleDeclaration | null): [string, string];
+export declare function clippingBox(el: Element, info: VisibilityInfo): VisibleBounds;
+export declare function scrolledInto(b: VisibleBounds, port: VisibleBounds, alongX: boolean, alongY: boolean): VisibleBounds;

package/dist/dom/paint-context.js

@@ -1,3 +1,4 @@
+import { isHtmlElement } from './realm.js';
 const PAINT_PROPERTIES = [
     'filter',
     'opacity',
@@ -36,3 +37,80 @@ export function paintContextOf(el) {
     }
     return found;
 }
+export function overflowAxes(style) {
+    const shorthand = style?.overflow ?? '';
+    const [x = 'visible', y = x] = ('' === shorthand ? 'visible' : shorthand).split(/\s+/);
+    return [
+        null === style || '' === style.overflowX ? x : style.overflowX,
+        null === style || '' === style.overflowY ? y : style.overflowY,
+    ];
+}
+export function clippingBox(el, info) {
+    if (info.clipBox !== undefined) {
+        return info.clipBox;
+    }
+    const rect = el.getBoundingClientRect();
+    const style = info.style;
+    const px = (value) => Number.parseFloat(value ?? '') || 0;
+    const border = (value, kind) => kind === undefined || '' === kind || 'none' === kind || 'hidden' === kind ? 0 : px(value);
+    const scaleX = isHtmlElement(el) && el.offsetWidth > 0 ? rect.width / el.offsetWidth : 1;
+    const scaleY = isHtmlElement(el) && el.offsetHeight > 0 ? rect.height / el.offsetHeight : 1;
+    const left = isHtmlElement(el) && el.offsetWidth > 0
+        ? rect.left + el.clientLeft * scaleX
+        : rect.left + border(style?.borderLeftWidth, style?.borderLeftStyle);
+    const top = isHtmlElement(el) && el.offsetHeight > 0
+        ? rect.top + el.clientTop * scaleY
+        : rect.top + border(style?.borderTopWidth, style?.borderTopStyle);
+    const right = isHtmlElement(el) && el.offsetWidth > 0
+        ? left + el.clientWidth * scaleX
+        : rect.right - border(style?.borderRightWidth, style?.borderRightStyle);
+    const bottom = isHtmlElement(el) && el.offsetHeight > 0
+        ? top + el.clientHeight * scaleY
+        : rect.bottom - border(style?.borderBottomWidth, style?.borderBottomStyle);
+    const margin = (style?.overflowClipMargin ?? '').split(/\s+/);
+    const outset = px(margin.at(-1));
+    const borderBox = margin.includes('border-box');
+    const contentBox = margin.includes('content-box');
+    const [x, y] = overflowAxes(style);
+    const clipLeft = 'clip' === x
+        ? (borderBox ? rect.left : left + (contentBox ? px(style?.paddingLeft) * scaleX : 0)) -
+            outset * scaleX
+        : left;
+    const clipRight = 'clip' === x
+        ? (borderBox ? rect.right : right - (contentBox ? px(style?.paddingRight) * scaleX : 0)) +
+            outset * scaleX
+        : right;
+    const clipTop = 'clip' === y
+        ? (borderBox ? rect.top : top + (contentBox ? px(style?.paddingTop) * scaleY : 0)) -
+            outset * scaleY
+        : top;
+    const clipBottom = 'clip' === y
+        ? (borderBox ? rect.bottom : bottom - (contentBox ? px(style?.paddingBottom) * scaleY : 0)) +
+            outset * scaleY
+        : bottom;
+    info.clipBox = {
+        left: clipLeft,
+        right: clipRight,
+        top: clipTop,
+        bottom: clipBottom,
+        width: clipRight - clipLeft,
+        height: clipBottom - clipTop,
+    };
+    return info.clipBox;
+}
+export function scrolledInto(b, port, alongX, alongY) {
+    const axis = (lo, hi, size, from, to) => {
+        if (hi > from && lo < to) {
+            return [lo, hi];
+        }
+        const span = Math.min(size, to - from);
+        return lo >= to ? [to - span, to] : [from, from + span];
+    };
+    const [left, right] = alongX
+        ? axis(b.left, b.right, b.width, port.left, port.right)
+        : [b.left, b.right];
+    const [top, bottom] = alongY
+        ? axis(b.top, b.bottom, b.height, port.top, port.bottom)
+        : [b.top, b.bottom];
+    return { left, right, top, bottom, width: right - left, height: bottom - top };
+}

package/dist/dom/query.d.ts

@@ -1,5 +1,6 @@
 import { ElementState, type ElementQuery, type MatchResult, type QueryResult } from '@reticlehq/core';
+export declare function isHiddenNativeOption(el: HTMLElement): boolean;
 export declare const ATTR_VALUE_MAX = 512;
-export declare function matchQuery(query: ElementQuery, state?: ElementState, limit?: number, wholePhrase?: boolean): MatchResult;
+export declare function matchQuery(query: ElementQuery, state?: ElementState, limit?: number, wholePhrase?: boolean, diagnose?: boolean): MatchResult;
 export declare function elementsMatching(query: ElementQuery): HTMLElement[];
 export declare function runQuery(query: ElementQuery, limit?: number): QueryResult;

package/dist/dom/query.js

@@ -1,13 +1,16 @@
 import { ALTERNATIVE_TESTID_ATTRS, DEFAULT_TESTID_ATTR, DATA_RETICLE_SOURCE_ATTR, ElementState, QueryBy, REDACTED_VALUE, TRANSPORT_LIMITS, } from '@reticlehq/core';
 import { isActionTarget, isElement, isFrame, isInput, isSelect, isTextArea } from './realm.js';
 import { capturedRootOf } from './shadow-registry.js';
-import { getAccessibleName, getRole, describe, getStates, isInViewport, isVisible, } from './a11y.js';
-import { isIgnored, isReticleOverlay } from './dom-ignore.js';
+import { getAccessibleName, getRole, describe, getStates, isHiddenByAriaOnly, isInViewport, isRenderedOutsideAriaHidden, isVisible, } from './a11y.js';
+import { dialogCovering, isIgnored, isReticleOverlay, isWordsIgnored } from './dom-ignore.js';
 import { isSensitiveKey } from '../security/serialization.js';
 import { declaredTestids } from '../registry/capabilities.js';
 import { identifyComponent } from '../registry/stores/adapters.js';
 import { refs } from './addressing/refs.js';
 import { getTestIdAttr, readTestId, testIdSelector } from './addressing/testid-attr.js';
+import { stableSelectorFor } from './stable-selector.js';
+import { exactVisibleText, fuzzyVisibleText, normaliseVisibleText, comparableText, foldTypography, paintedCase, textMatches, unreadableMatch, } from './text-match.js';
+import { pageRoute } from '../security/page-location.js';
 const SOURCE_ATTR = DATA_RETICLE_SOURCE_ATTR;
 const MAX_PRESENT_TESTIDS = 12;
 const MAX_COMPONENT_CANDIDATES = 2000;
@@ -16,22 +19,6 @@ function elementsUnder(container) {
     const self = Node.ELEMENT_NODE === container.nodeType ? [container] : [];
     return [...self, ...Array.from(container.querySelectorAll('*'))];
 }
-function normaliseVisibleText(value) {
-    return value.replace(/\s+/g, ' ').trim().normalize('NFC');
-}
-function fuzzyVisibleText(actual, expected) {
-    return normaliseVisibleText(actual)
-        .toLowerCase()
-        .includes(normaliseVisibleText(expected).toLowerCase());
-}
-function textMatches(actual, query, expected) {
-    if (true !== query.matchCase)
-        return fuzzyVisibleText(actual, expected);
-    return normaliseVisibleText(actual).includes(normaliseVisibleText(expected));
-}
-function exactVisibleText(actual, expected) {
-    return normaliseVisibleText(actual) === normaliseVisibleText(expected);
-}
 const NON_RENDERED_TAGS = ['script', 'style', 'template', 'noscript'];
 function isNonRendered(el) {
     return NON_RENDERED_TAGS.includes(el.tagName.toLowerCase());
@@ -50,7 +37,7 @@ function directText(el) {
         .join('');
 }
 function visibleTextOf(el, memo) {
-    if (isNonRendered(el) || isIgnored(el))
+    if (isNonRendered(el) || isWordsIgnored(el))
         return '';
     const visible = isVisible(el, memo);
     const apart = laysOutApart(el);
@@ -139,21 +126,57 @@ function matchesRole(actual, queried) {
         return true;
     return false;
 }
+const OPTION_ROLE = 'option';
+const HTML_OPTION_TAG = 'option';
+const HTML_SELECT_TAG = 'select';
+const VISUALLY_HIDDEN_MAX_PX = 1;
+export function isHiddenNativeOption(el) {
+    if (HTML_OPTION_TAG !== el.localName)
+        return false;
+    const select = el.closest(HTML_SELECT_TAG);
+    if (!isSelect(select))
+        return false;
+    if (!isVisible(select))
+        return true;
+    return isVisuallyHiddenBox(select);
+}
+function isVisuallyHiddenBox(select) {
+    const box = select.getBoundingClientRect();
+    return (box.width > 0 &&
+        box.height > 0 &&
+        box.width <= VISUALLY_HIDDEN_MAX_PX &&
+        box.height <= VISUALLY_HIDDEN_MAX_PX);
+}
+function preferVisibleActionableOption(role, matches) {
+    if (OPTION_ROLE !== role)
+        return matches;
+    const kept = matches.filter((el) => !isHiddenNativeOption(el));
+    return kept.length === matches.length ? matches : kept;
+}
 function queryByRoleAndName(container, role, name) {
-    return elementsUnder(container).filter((el) => matchesRole(getRole(el), role) &&
+    const matched = elementsUnder(container).filter((el) => matchesRole(getRole(el), role) &&
         (name === undefined || exactVisibleText(getAccessibleName(el), name)));
+    return preferVisibleActionableOption(role, matched);
 }
 function queryByText(container, value, query) {
-    return elementsUnder(container).filter((el) => textMatches(directText(el), query, value));
+    return elementsUnder(container).filter((el) => {
+        const own = directText(el);
+        if (textMatches(own, query, value))
+            return true;
+        if (true !== query.matchCase || !fuzzyVisibleText(own, value))
+            return false;
+        const painted = paintedCase(el, own);
+        return painted !== undefined && textMatches(painted, query, value);
+    });
 }
 function queryByLabel(container, value) {
-    const expected = normaliseVisibleText(value).toLowerCase();
+    const expected = comparableText(value).toLowerCase();
     const exact = [];
     const fuzzy = [];
     for (const el of elementsUnder(container)) {
         if (!semanticNameTarget(el))
             continue;
-        const name = normaliseVisibleText(getAccessibleName(el)).toLowerCase();
+        const name = comparableText(getAccessibleName(el)).toLowerCase();
         if (!name.includes(expected))
             continue;
         (name === expected ? exact : fuzzy).push(el);
@@ -264,11 +287,12 @@ function findCandidates(query) {
     }
     const seen = new Set();
     const out = [];
+    const ignored = wantedTextOf(query) === undefined ? isIgnored : isWordsIgnored;
     const collect = (els) => {
         for (const el of els) {
             if (seen.has(el))
                 continue;
-            if (isIgnored(el))
+            if (ignored(el))
                 continue;
             seen.add(el);
             out.push(el);
@@ -297,7 +321,7 @@ function inState(el, state, memo) {
     return getStates(el, isVisible(el, memo)).includes(state);
 }
 const MAX_DESCRIBED = TRANSPORT_LIMITS.MAX_COLLECTION_ITEMS;
-export function matchQuery(query, state, limit = MAX_DESCRIBED, wholePhrase = true) {
+export function matchQuery(query, state, limit = MAX_DESCRIBED, wholePhrase = true, diagnose = true) {
     const found = findCandidates(query);
     const scopeMissing = found.scopeMissing;
     const wanted = wholePhrase && textOnly(query) ? wantedTextOf(query) : undefined;
@@ -321,12 +345,16 @@ export function matchQuery(query, state, limit = MAX_DESCRIBED, wholePhrase = tr
         const projected = projectAttrs(el, attrs);
         return projected === undefined ? base : { ...base, attrs: projected };
     });
+    const covered = dialogCovering(filtered);
+    const unreadable = wantedTextOf(query) === undefined ? undefined : unreadableMatch(described);
     return {
         matched: filtered.length > 0,
         count: filtered.length,
         elements: descriptors,
         ...(scopeMissing ? { scopeMissing: true } : {}),
-        ...(0 === filtered.length ? { hint: buildEmptyHint(query) } : {}),
+        ...(covered === undefined ? {} : { coveredBy: covered }),
+        ...(unreadable === undefined ? {} : { unreadable }),
+        ...(0 === filtered.length ? { hint: buildEmptyHint(query, state, diagnose) } : {}),
     };
 }
 function resolveLabelledBy(el) {
@@ -414,7 +442,7 @@ function splitTextOwner(container, wanted, query) {
     return best;
 }
 function caseOnlyMatch(container, wanted) {
-    const target = normaliseVisibleText(wanted).toLowerCase();
+    const target = comparableText(wanted).toLowerCase();
     if (0 === target.length)
         return undefined;
     const memo = new Map();
@@ -422,7 +450,7 @@ function caseOnlyMatch(container, wanted) {
         if (isIgnored(el))
             continue;
         const text = normaliseVisibleText(visibleTextOf(el, memo));
-        const at = text.toLowerCase().indexOf(target);
+        const at = foldTypography(text).toLowerCase().indexOf(target);
         if (-1 !== at)
             return text.slice(at, at + target.length);
     }
@@ -450,7 +478,7 @@ function nameNearMisses(container, query) {
     const wanted = query.name;
     if (role === undefined || wanted === undefined || 0 === wanted.length)
         return [];
-    const target = normaliseVisibleText(wanted).toLowerCase();
+    const target = comparableText(wanted).toLowerCase();
     if (0 === target.length)
         return [];
     const out = [];
@@ -460,7 +488,7 @@ function nameNearMisses(container, query) {
         const name = normaliseVisibleText(getAccessibleName(el));
         if (0 === name.length)
             continue;
-        const folded = name.toLowerCase();
+        const folded = foldTypography(name).toLowerCase();
         if (!folded.includes(target) && !target.includes(folded))
             continue;
         if (!out.includes(name))
@@ -483,7 +511,32 @@ function testidFoundUnder(container, query) {
     }
     return undefined;
 }
-function buildEmptyHint(query) {
+function textInAriaHidden(container, wanted) {
+    let inAriaHidden = false;
+    for (const el of elementsUnder(container)) {
+        if (isIgnored(el))
+            continue;
+        if (!isHiddenByAriaOnly(el))
+            continue;
+        if (fuzzyVisibleText(el.textContent ?? '', wanted)) {
+            inAriaHidden = true;
+            break;
+        }
+    }
+    if (!inAriaHidden)
+        return false;
+    const memo = new Map();
+    for (const el of elementsUnder(container)) {
+        if (isIgnored(el))
+            continue;
+        if (!isRenderedOutsideAriaHidden(el))
+            continue;
+        if (fuzzyVisibleText(visibleTextOf(el, memo), wanted))
+            return false;
+    }
+    return true;
+}
+function buildEmptyHint(query, state, diagnose = true) {
     const container = resolveContainer(query.scope).container ?? document.body;
     const all = container.querySelectorAll(testIdSelector());
     const present = [];
@@ -500,7 +553,7 @@ function buildEmptyHint(query) {
     }
     const registered = declaredTestids();
     const knownEmptyState = present.some((id) => registered.includes(id));
-    const route = `${location.pathname}${location.search}`;
+    const route = pageRoute(false);
     const hint = {
         route,
         presentTestids: present,
@@ -511,14 +564,24 @@ function buildEmptyHint(query) {
     const wanted = wantedTextOf(query);
     if (wanted !== undefined) {
         const owner = splitTextOwner(container, wanted, query);
-        if (owner !== undefined)
-            hint.splitText = describe(owner);
+        if (owner !== undefined) {
+            const described = describe(owner);
+            const selector = stableSelectorFor(owner);
+            hint.splitText = selector === undefined ? described : { ...described, selector };
+        }
         else if (true === query.matchCase) {
             const shown = caseOnlyMatch(container, wanted);
             if (shown !== undefined)
                 hint.caseMiss = shown;
         }
     }
+    if (diagnose &&
+        wanted !== undefined &&
+        hint.splitText === undefined &&
+        (state === undefined || ElementState.VISIBLE === state || ElementState.IN_VIEWPORT === state)) {
+        if (textInAriaHidden(container, wanted))
+            hint.ariaHiddenMatch = true;
+    }
     const near = nameNearMisses(container, query);
     if (near.length > 0)
         hint.nameNearMiss = near;

package/dist/dom/shadow-registry.d.ts

@@ -5,3 +5,4 @@ export declare function isCaptured(host: Element): boolean;
 export declare function capturedRootOf(host: Element): ShadowRoot | null;
 export declare function onShadowRoot(listener: (root: ShadowRoot) => void): () => void;
 export declare function installShadowRegistry(): () => void;
+export declare function parentAcrossShadowBoundary(el: Element): Element | null;