@reticlehq/browser 3.6.0 → 3.8.0

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,17 +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 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());
@@ -45,17 +37,29 @@ function directText(el) {
         .join('');
 }
 function visibleTextOf(el, memo) {
-    if (isNonRendered(el) || isIgnored(el) || !isVisible(el, memo))
+    if (isNonRendered(el) || isWordsIgnored(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;
@@ -122,15 +126,62 @@ 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) {
-    return elementsUnder(container).filter((el) => fuzzyVisibleText(directText(el), value));
+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) {
-    return elementsUnder(container).filter((el) => semanticNameTarget(el) && fuzzyVisibleText(getAccessibleName(el), 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) => {
@@ -155,7 +206,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 +228,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,18 +280,19 @@ 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 };
     }
     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);
@@ -269,10 +321,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, diagnose = 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;
@@ -290,12 +345,16 @@ export function matchQuery(query, state, limit = MAX_DESCRIBED) {
         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) {
@@ -363,14 +422,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 +441,32 @@ function splitTextOwner(container, wanted) {
     }
     return best;
 }
+function caseOnlyMatch(container, wanted) {
+    const target = comparableText(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 = foldTypography(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;
@@ -393,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 = [];
@@ -403,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))
@@ -426,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 = [];
@@ -443,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,
@@ -453,9 +563,24 @@ function buildEmptyHint(query) {
     };
     const wanted = wantedTextOf(query);
     if (wanted !== undefined) {
-        const owner = splitTextOwner(container, wanted);
-        if (owner !== undefined)
-            hint.splitText = describe(owner);
+        const owner = splitTextOwner(container, wanted, query);
+        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)
@@ -469,7 +594,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>;

package/dist/dom/render-page.js

@@ -0,0 +1,135 @@
+import { isSensitiveKey, STEP_SCREENSHOT } from '@reticlehq/core';
+import { RETICLE_OVERLAY } from './dom-ignore.js';
+export const MASK = '••••••••';
+const BUDGET_CHARS = 240_000;
+const CHUNK_CHARS = 60_000;
+const SHRINK = 0.75;
+const MAX_ATTEMPTS = 4;
+const LOAD_TIMEOUT_MS = 5_000;
+const SVG_NS = 'http://www.w3.org/2000/svg';
+const FALLBACK_BACKGROUND = '#ffffff';
+const JPEG_MIME = 'image/jpeg';
+const DATA_URL_PREFIX = /^data:[^,]*,/;
+function isSecretField(el) {
+    if (el instanceof HTMLInputElement && 'password' === el.type)
+        return true;
+    return [el.name, el.id, el.getAttribute('autocomplete') ?? ''].some((key) => key.length > 0 && isSensitiveKey(key));
+}
+function carryState(from, to) {
+    if (from instanceof HTMLInputElement || from instanceof HTMLTextAreaElement) {
+        const value = isSecretField(from) && from.value.length > 0 ? MASK : from.value;
+        if (from instanceof HTMLTextAreaElement)
+            to.textContent = value;
+        else
+            to.setAttribute('value', value);
+    }
+    if (from instanceof HTMLInputElement) {
+        if (from.checked)
+            to.setAttribute('checked', '');
+        else
+            to.removeAttribute('checked');
+    }
+    if (from instanceof HTMLOptionElement) {
+        if (from.selected)
+            to.setAttribute('selected', '');
+        else
+            to.removeAttribute('selected');
+    }
+}
+function readableCss(doc) {
+    const sheets = [...Array.from(doc.styleSheets), ...(doc.adoptedStyleSheets ?? [])];
+    const parts = [];
+    for (const sheet of sheets) {
+        try {
+            for (const rule of Array.from(sheet.cssRules))
+                parts.push(rule.cssText);
+        }
+        catch {
+        }
+    }
+    return parts.join('\n');
+}
+export function cloneForRender(doc) {
+    const root = doc.documentElement;
+    const clone = root.cloneNode(true);
+    const live = root.querySelectorAll('*');
+    const copied = clone.querySelectorAll('*');
+    live.forEach((el, i) => {
+        const twin = copied[i];
+        if (twin !== undefined)
+            carryState(el, twin);
+    });
+    const dropped = [RETICLE_OVERLAY, 'script', 'noscript', 'link[rel~="stylesheet"]', 'style'];
+    clone.querySelectorAll(dropped.join(',')).forEach((el) => el.remove());
+    const style = doc.createElement('style');
+    style.textContent = readableCss(doc);
+    (clone.querySelector('head') ?? clone).append(style);
+    return clone;
+}
+function backgroundOf(doc) {
+    const view = doc.defaultView;
+    for (const el of [doc.body, doc.documentElement]) {
+        if (null === view || null === el)
+            continue;
+        const colour = view.getComputedStyle(el).backgroundColor;
+        if (colour.length > 0 && 'transparent' !== colour && 'rgba(0, 0, 0, 0)' !== colour)
+            return colour;
+    }
+    return FALLBACK_BACKGROUND;
+}
+function loadImage(url) {
+    return new Promise((resolve, reject) => {
+        const img = new Image();
+        const timer = setTimeout(() => reject(new Error('the page did not render in time')), LOAD_TIMEOUT_MS);
+        img.onload = () => {
+            clearTimeout(timer);
+            resolve(img);
+        };
+        img.onerror = () => {
+            clearTimeout(timer);
+            reject(new Error('the page could not be drawn as an image'));
+        };
+        img.src = url;
+    });
+}
+function chunked(base64) {
+    const out = [];
+    for (let i = 0; i < base64.length; i += CHUNK_CHARS)
+        out.push(base64.slice(i, i + CHUNK_CHARS));
+    return out;
+}
+export async function renderPage() {
+    try {
+        const width = Math.max(1, window.innerWidth);
+        const height = Math.max(1, window.innerHeight);
+        const clone = cloneForRender(document);
+        clone.style.transform = `translate(${String(-window.scrollX)}px, ${String(-window.scrollY)}px)`;
+        const xhtml = new XMLSerializer().serializeToString(clone);
+        const svg = `<svg xmlns="${SVG_NS}" width="${String(width)}" height="${String(height)}">` +
+            `<foreignObject x="0" y="0" width="100%" height="100%">${xhtml}</foreignObject></svg>`;
+        const img = await loadImage(`data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`);
+        const background = backgroundOf(document);
+        let scale = Math.min(1, STEP_SCREENSHOT.MAX_SIDE_PX / Math.max(width, height));
+        for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt += 1, scale *= SHRINK) {
+            const canvas = document.createElement('canvas');
+            canvas.width = Math.max(1, Math.round(width * scale));
+            canvas.height = Math.max(1, Math.round(height * scale));
+            const ctx = canvas.getContext('2d');
+            if (null === ctx)
+                return { ok: false, reason: 'this page has no 2D canvas to draw into' };
+            ctx.fillStyle = background;
+            ctx.fillRect(0, 0, canvas.width, canvas.height);
+            ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
+            const base64 = canvas
+                .toDataURL(JPEG_MIME, STEP_SCREENSHOT.JPEG_QUALITY)
+                .replace(DATA_URL_PREFIX, '');
+            if (base64.length <= BUDGET_CHARS) {
+                return { ok: true, width: canvas.width, height: canvas.height, chunks: chunked(base64) };
+            }
+        }
+        return { ok: false, reason: 'the rendered page was too large to send, even scaled down' };
+    }
+    catch (error) {
+        return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+    }
+}

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;

package/dist/dom/shadow-registry.js

@@ -93,3 +93,30 @@ export function installShadowRegistry() {
         listeners.clear();
     };
 }
+function slotInCapturedClosedRoot(el) {
+    const host = el.parentElement;
+    if (null === host || null !== host.shadowRoot) {
+        return null;
+    }
+    const root = capturedRootOf(host);
+    if (null === root) {
+        return null;
+    }
+    for (const slot of Array.from(root.querySelectorAll('slot'))) {
+        if (slot.assignedElements().includes(el)) {
+            return slot;
+        }
+    }
+    return null;
+}
+export function parentAcrossShadowBoundary(el) {
+    const slot = el.assignedSlot ?? slotInCapturedClosedRoot(el);
+    if (null !== slot) {
+        return slot;
+    }
+    if (null !== el.parentElement) {
+        return el.parentElement;
+    }
+    const host = el.getRootNode().host;
+    return host ?? null;
+}

package/dist/dom/snapshot.d.ts

@@ -1,4 +1,6 @@
 import { SnapshotMode } from '@reticlehq/core';
+import { type LayoutFinding } from './layout-audit.js';
+export declare const INTERACTIVE: Set<string>;
 interface SnapshotStatus {
     route: string;
     title: string;
@@ -11,6 +13,7 @@ interface SnapshotResult {
     nodes: number;
     truncated: boolean;
     scopeMissing?: boolean;
+    audit?: LayoutFinding[];
     leanSkipped?: number;
     hiddenSkipped?: number;
     domElements?: number;
@@ -23,6 +26,8 @@ interface SnapshotOptions {
     maxNodes?: number | undefined;
     maxDepth?: number | undefined;
     includeRoot?: boolean | undefined;
+    ids?: boolean | undefined;
+    audit?: boolean | undefined;
 }
 export declare const MAX_UNREAD_BRANCHES = 50;
 export declare function buildSnapshot(options?: SnapshotOptions): SnapshotResult;