@reticlehq/browser 3.7.0 → 3.8.1

package/dist/dom/dom-ignore.js

@@ -1,4 +1,6 @@
 import { RETICLE_OVERLAY_SELECTOR } from '@reticlehq/core';
+import { capturedRootOf } from './shadow-registry.js';
+import { isVisible } from './visibility.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 = '';
@@ -22,28 +24,81 @@ export function isReticleOverlay(el) {
 }
 const HUD_DOCK = '[data-reticle-dock]';
 export function isUnobserved(el) {
-    if (!isReticleOverlay(el))
+    if (!isReticleOverlay(el)) {
         return false;
+    }
     return !exposed() || null === el.closest(HUD_DOCK);
 }
 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);
+        const dialog = (root ?? portal).querySelector(NEXT_DIALOG);
+        if (null !== dialog && isVisible(dialog)) {
+            return { name: FrameworkErrorDialog.NEXT, host: portal };
+        }
+    }
+    const light = doc.querySelector(NEXT_DIALOG);
+    if (null === light || !isVisible(light)) {
+        return undefined;
+    }
+    return { 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))) {
-        if (el.closest(RETICLE_OVERLAY) !== null)
+        if (el.closest(RETICLE_OVERLAY) !== null) {
             continue;
-        if (el instanceof HTMLElement && (el.hidden || null !== el.closest('[hidden]')))
+        }
+        if (el instanceof HTMLElement && (el.hidden || null !== el.closest('[hidden]'))) {
             continue;
-        if (el instanceof HTMLElement && 'none' === getComputedStyle(el).display)
+        }
+        if (el instanceof HTMLElement && 'none' === getComputedStyle(el).display) {
             continue;
+        }
         return true;
     }
     return false;

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-finders.d.ts

@@ -0,0 +1,6 @@
+import { type ElementQuery } from '@reticlehq/core';
+export declare function elementsUnder(container: HTMLElement): HTMLElement[];
+export declare function isNonRendered(el: Element): boolean;
+export declare function isHiddenNativeOption(el: HTMLElement): boolean;
+export declare function queryByRoleAndName(container: HTMLElement, role: string, name: string | undefined): HTMLElement[];
+export declare function findIn(container: HTMLElement, query: ElementQuery): HTMLElement[];

package/dist/dom/query-finders.js

@@ -0,0 +1,216 @@
+import { DATA_RETICLE_SOURCE_ATTR, QueryBy } from '@reticlehq/core';
+import { isInput, isSelect, isTextArea } from './realm.js';
+import { getAccessibleName, getRole } from './a11y.js';
+import { isVisible } from './visibility.js';
+import { identifyComponent } from '../registry/stores/adapters.js';
+import { readTestId, testIdSelector } from './addressing/testid-attr.js';
+import { exactVisibleText, fuzzyVisibleText, comparableText, paintedCase, textMatches, } from './text-match.js';
+const SOURCE_ATTR = DATA_RETICLE_SOURCE_ATTR;
+const MAX_COMPONENT_CANDIDATES = 2000;
+const componentCandidateSelector = () => `[${SOURCE_ATTR}], ${testIdSelector()}, button, a, input, select, textarea, [role]`;
+export function elementsUnder(container) {
+    const self = Node.ELEMENT_NODE === container.nodeType ? [container] : [];
+    return [...self, ...Array.from(container.querySelectorAll('*'))];
+}
+const NON_RENDERED_TAGS = ['script', 'style', 'template', 'noscript'];
+export function isNonRendered(el) {
+    return NON_RENDERED_TAGS.includes(el.tagName.toLowerCase());
+}
+function directText(el) {
+    if (isInput(el)) {
+        const type = el.type.toLowerCase();
+        if ('submit' === type || 'button' === type || 'reset' === type) {
+            return el.value;
+        }
+    }
+    if (isNonRendered(el)) {
+        return '';
+    }
+    return Array.from(el.childNodes)
+        .filter((node) => Node.TEXT_NODE === node.nodeType)
+        .map((node) => node.textContent ?? '')
+        .join('');
+}
+function semanticNameTarget(el) {
+    if (isInput(el) || isTextArea(el) || isSelect(el)) {
+        return true;
+    }
+    const tag = el.tagName.toLowerCase();
+    return ('button' === tag ||
+        'meter' === tag ||
+        'output' === tag ||
+        'progress' === tag ||
+        el.hasAttribute('aria-label') ||
+        el.hasAttribute('aria-labelledby'));
+}
+function findBySource(container, source) {
+    const prefix = `${source.file}:${source.line}:`.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    try {
+        return Array.from(container.querySelectorAll(`[${SOURCE_ATTR}^="${prefix}"]`));
+    }
+    catch {
+        return [];
+    }
+}
+function findByComponentName(container, component) {
+    const out = [];
+    let scanned = 0;
+    for (const el of Array.from(container.querySelectorAll(componentCandidateSelector()))) {
+        if (scanned >= MAX_COMPONENT_CANDIDATES) {
+            break;
+        }
+        scanned += 1;
+        const info = identifyComponent(el);
+        if (info !== null && info.componentStack[0] === component) {
+            out.push(el);
+        }
+    }
+    return out;
+}
+function findByComponent(container, query) {
+    if (query.source !== undefined) {
+        const bySource = findBySource(container, query.source);
+        if (bySource.length > 0) {
+            return bySource;
+        }
+    }
+    if (query.component !== undefined && query.component.length > 0) {
+        return findByComponentName(container, query.component);
+    }
+    return [];
+}
+function matchesRole(actual, queried) {
+    if (actual === queried) {
+        return true;
+    }
+    if ('textbox' === queried && 'searchbox' === actual) {
+        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;
+}
+export function queryByRoleAndName(container, role, name) {
+    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) => {
+        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 = comparableText(value).toLowerCase();
+    const exact = [];
+    const fuzzy = [];
+    for (const el of elementsUnder(container)) {
+        if (!semanticNameTarget(el)) {
+            continue;
+        }
+        const name = comparableText(getAccessibleName(el)).toLowerCase();
+        if (!name.includes(expected)) {
+            continue;
+        }
+        (name === expected ? exact : fuzzy).push(el);
+    }
+    return exact.length > 0 ? exact : fuzzy;
+}
+function queryByPlaceholder(container, value) {
+    return elementsUnder(container).filter((el) => {
+        const placeholder = el.getAttribute('placeholder');
+        return placeholder !== null && fuzzyVisibleText(placeholder, value);
+    });
+}
+function queryByTestId(container, value) {
+    return elementsUnder(container).filter((el) => readTestId(el) === value);
+}
+function queryByAlt(container, value) {
+    return elementsUnder(container).filter((el) => {
+        const alt = el.getAttribute('alt');
+        return alt !== null && fuzzyVisibleText(alt, value);
+    });
+}
+export function findIn(container, query) {
+    const by = query.by;
+    const value = query.value;
+    if (by !== undefined && value !== undefined) {
+        switch (by) {
+            case QueryBy.ROLE:
+                return queryByRoleAndName(container, value, query.name);
+            case QueryBy.TEXT:
+                return queryByText(container, value, query);
+            case QueryBy.LABEL:
+                return queryByLabel(container, value);
+            case QueryBy.PLACEHOLDER:
+                return queryByPlaceholder(container, value);
+            case QueryBy.TESTID:
+                return queryByTestId(container, value);
+            case QueryBy.ALT:
+                return queryByAlt(container, value);
+            case QueryBy.COMPONENT:
+                return findByComponent(container, { ...query, component: query.component ?? value });
+            default:
+                throw new Error(`unsupported query strategy '${String(by)}' - use one of: ${Object.values(QueryBy).join(', ')}`);
+        }
+    }
+    if (query.component !== undefined || query.source !== undefined) {
+        return findByComponent(container, query);
+    }
+    if (query.role !== undefined) {
+        return queryByRoleAndName(container, query.role, query.name);
+    }
+    if (query.text !== undefined) {
+        return queryByText(container, query.text, query);
+    }
+    if (query.label !== undefined) {
+        return queryByLabel(container, query.label);
+    }
+    if (query.placeholder !== undefined) {
+        return queryByPlaceholder(container, query.placeholder);
+    }
+    if (query.testid !== undefined) {
+        return queryByTestId(container, query.testid);
+    }
+    if (query.alt !== undefined) {
+        return queryByAlt(container, query.alt);
+    }
+    return [];
+}

package/dist/dom/query.d.ts

@@ -1,5 +1,5 @@
 import { ElementState, type ElementQuery, type MatchResult, type QueryResult } from '@reticlehq/core';
 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;