@reticlehq/browser 3.6.0 → 3.7.0

package/dist/dom/a11y.js

@@ -277,6 +277,7 @@ export function getStates(el, visible = isVisible(el)) {
         states.push(ElementState.FOCUSED);
     return states;
 }
+const SENSITIVE_AUTOCOMPLETE = /\b(cc-|current-password|new-password|one-time-code)/i;
 export function isSensitiveField(el) {
     if (!isInput(el) && !isTextArea(el) && !isSelect(el)) {
         return false;
@@ -289,7 +290,7 @@ export function isSensitiveField(el) {
         el.getAttribute(DEFAULT_TESTID_ATTR) ?? '',
         el.getAttribute('aria-label') ?? '',
     ];
-    const sensitiveAutocomplete = /current-password|new-password|cc-number|cc-csc|one-time-code/i.test(autocomplete);
+    const sensitiveAutocomplete = SENSITIVE_AUTOCOMPLETE.test(autocomplete);
     return ((isInput(el) && 'password' === el.type.toLowerCase()) ||
         sensitiveAutocomplete ||
         identifiers.some(isSensitiveKey));
@@ -297,7 +298,7 @@ export function isSensitiveField(el) {
 export function getValue(el) {
     if (isInput(el) || isTextArea(el) || isSelect(el)) {
         if (isSensitiveField(el))
-            return REDACTED_VALUE;
+            return '' === el.value ? '' : REDACTED_VALUE;
         return el.value;
     }
     const valueNow = el.getAttribute('aria-valuenow');
@@ -318,16 +319,18 @@ function stalledFade(el) {
         return false;
     return el.getAnimations().some((a) => 'running' === a.playState || a.pending);
 }
-function selfHidden(el) {
-    if ('true' === el.getAttribute('aria-hidden'))
+const OVERLAY_ARIA_HIDDEN = 'data-aria-hidden';
+function hiddenByAnOverlay(el) {
+    return el.hasAttribute(OVERLAY_ARIA_HIDDEN);
+}
+function selfHidden(el, style) {
+    if ('true' === el.getAttribute('aria-hidden') && !hiddenByAnOverlay(el))
         return true;
     if (isHtmlElement(el) && el.hidden)
         return true;
     if (hiddenInsideClosedDetails(el))
         return true;
-    const view = el.ownerDocument.defaultView;
-    if (view !== null) {
-        const style = view.getComputedStyle(el);
+    if (style !== null) {
         if ('none' === style.display ||
             'hidden' === style.visibility ||
             'collapse' === style.visibility) {
@@ -360,13 +363,252 @@ function parentAcrossShadowBoundary(el) {
     const host = el.getRootNode().host;
     return host ?? null;
 }
+const CLIPPING_OVERFLOW = new Set(['hidden', 'clip']);
+const SCROLLING_OVERFLOW = new Set(['auto', 'scroll']);
+const NON_CLIPPING_DISPLAY = new Set([
+    'contents',
+    'table-row',
+    'table-row-group',
+    'table-header-group',
+    'table-footer-group',
+    'table-column',
+    'table-column-group',
+]);
+const TRANSFORM_CONTAINING_BLOCK_PROPERTIES = new Set([
+    'transform',
+    'translate',
+    'rotate',
+    'scale',
+    'perspective',
+]);
+const CONTAINING_BLOCK_PROPERTIES = new Set([
+    ...TRANSFORM_CONTAINING_BLOCK_PROPERTIES,
+    'filter',
+    'backdrop-filter',
+]);
+const CONTAINING_BLOCK_CONTAIN = new Set(['layout', 'paint', 'strict', 'content']);
+const REPLACED_INLINE_TAGS = new Set([
+    'img',
+    'video',
+    'audio',
+    'canvas',
+    'iframe',
+    'embed',
+    'object',
+    'input',
+    'textarea',
+    'select',
+]);
+const visibilityInfoMemos = new WeakMap();
+function visibilityInfoMemo(memo) {
+    if (memo === undefined)
+        return new Map();
+    let info = visibilityInfoMemos.get(memo);
+    if (info === undefined) {
+        info = new Map();
+        visibilityInfoMemos.set(memo, info);
+    }
+    return info;
+}
+function ownVisibilityInfo(el, memo) {
+    let info = memo.get(el);
+    if (info === undefined) {
+        const style = el.ownerDocument.defaultView?.getComputedStyle(el) ?? null;
+        if (selfHidden(el, style)) {
+            info = {
+                hidden: true,
+                style,
+                parent: null,
+                clipX: false,
+                clipY: false,
+                scrollX: false,
+                scrollY: false,
+                hasClipping: false,
+            };
+            memo.set(el, info);
+            return info;
+        }
+        const parent = parentAcrossShadowBoundary(el);
+        const inherited = null === parent ? undefined : ownVisibilityInfo(parent, memo);
+        const [overflowX, overflowY] = overflowAxes(style);
+        const root = el.ownerDocument.documentElement;
+        const viewportOverflow = el === root ||
+            (el === el.ownerDocument.body &&
+                overflowAxes(ownVisibilityInfo(root, memo).style).every((axis) => 'visible' === axis));
+        const hasClipBox = !viewportOverflow &&
+            !NON_CLIPPING_DISPLAY.has(style?.display ?? '') &&
+            !(isHtmlElement(el) && 'inline' === style?.display);
+        const clipX = hasClipBox && CLIPPING_OVERFLOW.has(overflowX);
+        const clipY = hasClipBox && CLIPPING_OVERFLOW.has(overflowY);
+        info = {
+            hidden: true === inherited?.hidden,
+            style,
+            parent,
+            clipX,
+            clipY,
+            scrollX: hasClipBox && SCROLLING_OVERFLOW.has(overflowX),
+            scrollY: hasClipBox && SCROLLING_OVERFLOW.has(overflowY),
+            hasClipping: clipX || clipY || true === inherited?.hasClipping,
+        };
+        memo.set(el, info);
+    }
+    return info;
+}
+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,
+    ];
+}
+function positionedContainingBlock(el, fixed, memo) {
+    for (let parent = ownVisibilityInfo(el, memo).parent; parent !== null; parent = ownVisibilityInfo(parent, memo).parent) {
+        const style = ownVisibilityInfo(parent, memo).style;
+        if (null === style || 'contents' === style.display)
+            continue;
+        if (!fixed && '' !== style.position && 'static' !== style.position)
+            return parent;
+        const transformable = !('inline' === style.display &&
+            isHtmlElement(parent) &&
+            !REPLACED_INLINE_TAGS.has(parent.localName)) &&
+            'table-column' !== style.display &&
+            'table-column-group' !== style.display;
+        const applies = (property) => transformable || !TRANSFORM_CONTAINING_BLOCK_PROPERTIES.has(property);
+        if ([...CONTAINING_BLOCK_PROPERTIES].some((property) => {
+            const value = style.getPropertyValue(property);
+            return applies(property) && '' !== value && 'none' !== value;
+        }) ||
+            style.willChange
+                .split(',')
+                .some((property) => CONTAINING_BLOCK_PROPERTIES.has(property.trim()) && applies(property.trim())) ||
+            (transformable &&
+                !NON_CLIPPING_DISPLAY.has(style.display) &&
+                (style.contain.split(/\s+/).some((value) => CONTAINING_BLOCK_CONTAIN.has(value)) ||
+                    'auto' === style.contentVisibility)))
+            return parent;
+    }
+    return null;
+}
+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;
+}
+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 };
+}
+function visibleBounds(el, memo, initial, throughScrollers = false) {
+    let bounds = initial;
+    const target = ownVisibilityInfo(el, memo);
+    if (target.hidden)
+        return null;
+    if (null === target.parent || !ownVisibilityInfo(target.parent, memo).hasClipping)
+        return bounds;
+    let clipFrom;
+    for (let current = el; current !== null; current = ownVisibilityInfo(current, memo).parent) {
+        const info = ownVisibilityInfo(current, memo);
+        if (info.hidden)
+            return null;
+        if (current === clipFrom)
+            clipFrom = undefined;
+        const style = info.style;
+        if (throughScrollers &&
+            current !== el &&
+            undefined === clipFrom &&
+            (info.scrollX || info.scrollY)) {
+            bounds ??= el.getBoundingClientRect();
+            if (bounds.width > 0 && bounds.height > 0) {
+                bounds = scrolledInto(bounds, clippingBox(current, info), info.scrollX, info.scrollY);
+            }
+        }
+        if (current !== el && undefined === clipFrom && (info.clipX || info.clipY)) {
+            bounds ??= el.getBoundingClientRect();
+            if (bounds.width > 0 && bounds.height > 0) {
+                const clip = clippingBox(current, info);
+                const left = info.clipX ? Math.max(bounds.left, clip.left) : bounds.left;
+                const right = info.clipX ? Math.min(bounds.right, clip.right) : bounds.right;
+                const top = info.clipY ? Math.max(bounds.top, clip.top) : bounds.top;
+                const bottom = info.clipY ? Math.min(bounds.bottom, clip.bottom) : bounds.bottom;
+                if (right <= left || bottom <= top)
+                    return null;
+                bounds = { left, right, top, bottom, width: right - left, height: bottom - top };
+            }
+        }
+        if (clipFrom === undefined && ('absolute' === style?.position || 'fixed' === style?.position)) {
+            clipFrom = positionedContainingBlock(current, 'fixed' === style?.position, memo);
+        }
+    }
+    return bounds;
+}
 export function isInViewport(el, memo) {
     if (!isVisible(el, memo))
         return false;
     const view = el.ownerDocument.defaultView;
     if (null === view)
         return false;
-    const r = el.getBoundingClientRect();
+    const r = visibleBounds(el, visibilityInfoMemo(memo), el.getBoundingClientRect());
+    if (null === r || undefined === r)
+        return false;
     if (r.width <= 0 || r.height <= 0)
         return false;
     return r.bottom > 0 && r.right > 0 && r.top < view.innerHeight && r.left < view.innerWidth;
@@ -377,8 +619,7 @@ export function isVisible(el, memo) {
     const cached = memo?.get(el);
     if (cached !== undefined)
         return cached;
-    const parent = parentAcrossShadowBoundary(el);
-    const result = !selfHidden(el) && (null === parent || isVisible(parent, memo));
+    const result = visibleBounds(el, visibilityInfoMemo(memo), undefined, true) !== null;
     if (memo !== undefined)
         memo.set(el, result);
     return result;

package/dist/dom/addressing/coverage-markers.d.ts

@@ -0,0 +1,6 @@
+export declare function coverageMarkers(doc: Document): string[];
+export declare function notApplicableFor(page: {
+    buildPlugin: boolean;
+    adapters: readonly string[];
+    markers: readonly string[];
+}): string[];

package/dist/dom/addressing/coverage-markers.js

@@ -0,0 +1,13 @@
+import { CoverageMarker, SOURCE_MAPPING_CAPABILITY, DATA_RETICLE_SOURCE_ATTR, RETICLE_OVERLAY_SELECTOR, } from '@reticlehq/core';
+import { testIdSelector } from './testid-attr.js';
+const appCarries = (doc, selector) => Array.from(doc.querySelectorAll(selector)).some((el) => null === el.closest(RETICLE_OVERLAY_SELECTOR));
+export function coverageMarkers(doc) {
+    return [
+        ...(appCarries(doc, `[${DATA_RETICLE_SOURCE_ATTR}]`) ? [CoverageMarker.SOURCE] : []),
+        ...(appCarries(doc, testIdSelector()) ? [CoverageMarker.TESTID] : []),
+    ];
+}
+export function notApplicableFor(page) {
+    const couldStamp = page.buildPlugin || 0 < page.adapters.length || page.markers.includes(CoverageMarker.SOURCE);
+    return couldStamp ? [] : [SOURCE_MAPPING_CAPABILITY];
+}

package/dist/dom/dom-ignore.d.ts

@@ -1,8 +1,10 @@
 export declare const RETICLE_OVERLAY: string;
 export declare function setPresenterVisible(visible: boolean): void;
+export declare function setPresenterViewer(harness: boolean): void;
 export declare function isPresenterVisible(): boolean;
 export declare function setIgnoreSelectors(selectors: string[]): void;
 export declare function isReticleOverlay(el: Element): boolean;
+export declare function isUnobserved(el: Element): boolean;
 export declare function isReticleUi(node: Element | null): boolean;
 export declare function isIgnored(el: Element): boolean;
 export declare function appModalOpen(doc: Document): boolean;

package/dist/dom/dom-ignore.js

@@ -1,10 +1,16 @@
-export const RETICLE_OVERLAY = '[data-reticle-overlay],[data-reticle-cursor],[data-reticle-hud],[data-reticle-glow],[data-reticle-mark],[data-reticle-blocker],[data-reticle-tour]';
+import { RETICLE_OVERLAY_SELECTOR } from '@reticlehq/core';
+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 = '';
 let presenterVisible = false;
 export function setPresenterVisible(visible) {
     presenterVisible = visible;
 }
+let harnessViewing = false;
+export function setPresenterViewer(harness) {
+    harnessViewing = harness;
+}
+const exposed = () => presenterVisible && !harnessViewing;
 export function isPresenterVisible() {
     return presenterVisible;
 }
@@ -14,11 +20,18 @@ export function setIgnoreSelectors(selectors) {
 export function isReticleOverlay(el) {
     return el.closest(RETICLE_OVERLAY) !== null;
 }
+const HUD_DOCK = '[data-reticle-dock]';
+export function isUnobserved(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]';
 export function isIgnored(el) {
-    const ours = presenterVisible ? '' : RETICLE_OVERLAY;
+    const ours = exposed() ? HUD_NARRATION : RETICLE_OVERLAY;
     const sel = [ours, DEV_OVERLAYS, extraIgnore].filter((part) => part.length > 0).join(',');
     return el.closest(sel) !== null;
 }

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): MatchResult;
+export declare function matchQuery(query: ElementQuery, state?: ElementState, limit?: number, wholePhrase?: boolean): MatchResult;
 export declare function elementsMatching(query: ElementQuery): HTMLElement[];
 export declare function runQuery(query: ElementQuery, limit?: number): QueryResult;

package/dist/dom/query.js

@@ -24,6 +24,11 @@ function fuzzyVisibleText(actual, expected) {
         .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);
 }
@@ -45,17 +50,29 @@ function directText(el) {
         .join('');
 }
 function visibleTextOf(el, memo) {
-    if (isNonRendered(el) || isIgnored(el) || !isVisible(el, memo))
+    if (isNonRendered(el) || isIgnored(el))
         return '';
+    const visible = isVisible(el, memo);
+    const apart = laysOutApart(el);
     let text = '';
     for (const node of Array.from(el.childNodes)) {
-        if (Node.TEXT_NODE === node.nodeType)
+        if (Node.TEXT_NODE === node.nodeType && visible)
             text += node.textContent ?? '';
-        else if (isElement(node))
-            text += visibleTextOf(node, memo);
+        else if (isElement(node)) {
+            const own = visibleTextOf(node, memo);
+            text += apart || ownBox(node) ? ` ${own} ` : own;
+        }
     }
     return text;
 }
+function laysOutApart(el) {
+    const display = el.ownerDocument.defaultView?.getComputedStyle(el).display ?? '';
+    return display.includes('flex') || display.includes('grid');
+}
+function ownBox(el) {
+    const display = el.ownerDocument.defaultView?.getComputedStyle(el).display ?? 'inline';
+    return !display.startsWith('inline') && 'contents' !== display;
+}
 function semanticNameTarget(el) {
     if (isInput(el) || isTextArea(el) || isSelect(el))
         return true;
@@ -126,11 +143,22 @@ function queryByRoleAndName(container, role, name) {
     return elementsUnder(container).filter((el) => matchesRole(getRole(el), role) &&
         (name === undefined || exactVisibleText(getAccessibleName(el), name)));
 }
-function queryByText(container, value) {
-    return elementsUnder(container).filter((el) => fuzzyVisibleText(directText(el), value));
+function queryByText(container, value, query) {
+    return elementsUnder(container).filter((el) => textMatches(directText(el), query, value));
 }
 function queryByLabel(container, value) {
-    return elementsUnder(container).filter((el) => semanticNameTarget(el) && fuzzyVisibleText(getAccessibleName(el), value));
+    const expected = normaliseVisibleText(value).toLowerCase();
+    const exact = [];
+    const fuzzy = [];
+    for (const el of elementsUnder(container)) {
+        if (!semanticNameTarget(el))
+            continue;
+        const name = normaliseVisibleText(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) => {
@@ -155,7 +183,7 @@ function findIn(container, query) {
             case QueryBy.ROLE:
                 return queryByRoleAndName(container, value, query.name);
             case QueryBy.TEXT:
-                return queryByText(container, value);
+                return queryByText(container, value, query);
             case QueryBy.LABEL:
                 return queryByLabel(container, value);
             case QueryBy.PLACEHOLDER:
@@ -177,7 +205,7 @@ function findIn(container, query) {
         return queryByRoleAndName(container, query.role, query.name);
     }
     if (query.text !== undefined)
-        return queryByText(container, query.text);
+        return queryByText(container, query.text, query);
     if (query.label !== undefined)
         return queryByLabel(container, query.label);
     if (query.placeholder !== undefined)
@@ -229,7 +257,7 @@ function findCandidates(query) {
         if (query.scope === undefined)
             return { candidates: [], scopeMissing };
         if (query.text !== undefined &&
-            !fuzzyVisibleText(visibleTextOf(container, new Map()), query.text)) {
+            !textMatches(visibleTextOf(container, new Map()), query, query.text)) {
             return { candidates: [], scopeMissing };
         }
         return { candidates: isIgnored(container) ? [] : [container], scopeMissing };
@@ -269,10 +297,13 @@ 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) {
+export function matchQuery(query, state, limit = MAX_DESCRIBED, wholePhrase = true) {
     const found = findCandidates(query);
-    const elements = found.candidates;
     const scopeMissing = found.scopeMissing;
+    const wanted = wholePhrase && textOnly(query) ? wantedTextOf(query) : undefined;
+    const scope = 0 === found.candidates.length ? resolveContainer(query.scope).container : null;
+    const owner = null === scope || wanted === undefined ? undefined : splitTextOwner(scope, wanted, query);
+    const elements = owner === undefined ? found.candidates : [owner];
     const visMemo = new Map();
     const filtered = state === undefined ? elements : elements.filter((el) => inState(el, state, visMemo));
     const attrs = query.attrs;
@@ -363,14 +394,14 @@ function buildPresentRegions(query) {
     }
     return regions;
 }
-function splitTextOwner(container, wanted) {
+function splitTextOwner(container, wanted, query) {
     let best;
     let bestDepth = -1;
     const memo = new Map();
     for (const el of elementsUnder(container)) {
         if (isIgnored(el))
             continue;
-        if (!fuzzyVisibleText(visibleTextOf(el, memo), wanted))
+        if (!textMatches(visibleTextOf(el, memo), query, wanted))
             continue;
         let depth = 0;
         for (let parent = el.parentElement; parent !== null; parent = parent.parentElement)
@@ -382,6 +413,32 @@ function splitTextOwner(container, wanted) {
     }
     return best;
 }
+function caseOnlyMatch(container, wanted) {
+    const target = normaliseVisibleText(wanted).toLowerCase();
+    if (0 === target.length)
+        return undefined;
+    const memo = new Map();
+    for (const el of elementsUnder(container)) {
+        if (isIgnored(el))
+            continue;
+        const text = normaliseVisibleText(visibleTextOf(el, memo));
+        const at = text.toLowerCase().indexOf(target);
+        if (-1 !== at)
+            return text.slice(at, at + target.length);
+    }
+    return undefined;
+}
+const TEXT_ONLY_FIELDS = new Set([
+    'text',
+    'matchCase',
+    'scope',
+    'by',
+    'value',
+]);
+function textOnly(query) {
+    return ((query.by === undefined || QueryBy.TEXT === query.by) &&
+        Object.keys(query).every((key) => TEXT_ONLY_FIELDS.has(key)));
+}
 function wantedTextOf(query) {
     if (query.text !== undefined)
         return query.text;
@@ -453,9 +510,14 @@ function buildEmptyHint(query) {
     };
     const wanted = wantedTextOf(query);
     if (wanted !== undefined) {
-        const owner = splitTextOwner(container, wanted);
+        const owner = splitTextOwner(container, wanted, query);
         if (owner !== undefined)
             hint.splitText = describe(owner);
+        else if (true === query.matchCase) {
+            const shown = caseOnlyMatch(container, wanted);
+            if (shown !== undefined)
+                hint.caseMiss = shown;
+        }
     }
     const near = nameNearMisses(container, query);
     if (near.length > 0)
@@ -469,7 +531,7 @@ export function elementsMatching(query) {
     return findCandidates(query).candidates;
 }
 export function runQuery(query, limit) {
-    const result = matchQuery(query, undefined, limit);
+    const result = matchQuery(query, undefined, limit, false);
     const scopeFields = true === result.scopeMissing ? { scopeMissing: true } : {};
     if (0 === result.elements.length) {
         return {

package/dist/dom/render-page.d.ts

@@ -0,0 +1,12 @@
+export declare const MASK = "\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022";
+export type RenderResult = {
+    ok: true;
+    width: number;
+    height: number;
+    chunks: string[];
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function cloneForRender(doc: Document): HTMLElement;
+export declare function renderPage(): Promise<RenderResult>;