@reticlehq/browser 3.8.2 → 3.9.0

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

@@ -25,6 +25,7 @@ export declare function fireClickSequence(el: ActionTarget, hold?: {
     prevented: boolean;
     heldMs: number;
 }>;
+export declare function scrollIntoViewNow(el: Element, options?: ScrollIntoViewOptions): void;
 export declare function isOffViewport(el: Element, rect: DOMRect): boolean;
 export declare function clickGeometry(el: ActionTarget): ClickGeometry;
 export declare function firePointer(el: Element, type: string, relatedTarget?: EventTarget | null): void;

package/dist/actions/actions-dom.js

@@ -88,6 +88,9 @@ export async function fireClickSequence(el, hold, detail, input = PLAIN_CLICK) {
 function isMeasurable(rect) {
     return rect.width > 0 || rect.height > 0;
 }
+export function scrollIntoViewNow(el, options = {}) {
+    el.scrollIntoView({ ...options, behavior: 'instant' });
+}
 export function isOffViewport(el, rect) {
     const win = el.ownerDocument.defaultView;
     if (null === win) {
@@ -128,7 +131,7 @@ export function clickGeometry(el) {
     }
     let scrolledIntoView = false;
     if (isOffViewport(el, rect) && 'function' === typeof el.scrollIntoView) {
-        el.scrollIntoView({ block: 'center', inline: 'center' });
+        scrollIntoViewNow(el, { block: 'center', inline: 'center' });
         scrolledIntoView = true;
         rect = el.getBoundingClientRect();
     }

package/dist/actions/actions.js

@@ -100,7 +100,7 @@ function optionValueFor(options, named) {
     const byLabel = options.filter((option) => option.label.trim() === named.trim());
     return 1 === byLabel.length ? (byLabel[0]?.value ?? named) : named;
 }
-import { NO_GEOMETRY, fireClickSequence, fireTapSequence, clickGeometry, firePointer, firePointerNonBubbling, dragElement, mouseEventFor, assertNotLeaving, clickInputOf, } from './actions-dom.js';
+import { NO_GEOMETRY, fireClickSequence, fireTapSequence, clickGeometry, firePointer, firePointerNonBubbling, dragElement, mouseEventFor, assertNotLeaving, scrollIntoViewNow, clickInputOf, } from './actions-dom.js';
 import { scrollFrom } from './scroll.js';
 import { clickHitsNoControl } from './click-target.js';
 function enabledOf(el) {
@@ -290,7 +290,7 @@ async function dispatchOther(el, action, args) {
             return !down;
         }
         case ActionType.SCROLL_INTO_VIEW:
-            el.scrollIntoView();
+            scrollIntoViewNow(el);
             return false;
         case ActionType.ZOOM:
             throw new Error(ZOOM_NEEDS_REAL_BROWSER_MSG);
@@ -358,9 +358,19 @@ export async function executeAction(ref, action, args = {}) {
         assertNotLeaving(el);
     }
     const anchor = named ? anchorOf(el) : {};
+    const prevFocus = activeRef(el);
+    if ((ActionType.CLICK === action || ActionType.DBLCLICK === action) && !enabledOf(el)) {
+        const active = el.ownerDocument.activeElement;
+        if (active !== null &&
+            active !== el &&
+            active !== el.ownerDocument.body &&
+            isActionTarget(active)) {
+            active.blur();
+            await Promise.resolve();
+        }
+    }
     const visible = isVisible(el);
     const enabled = enabledOf(el);
-    const prevFocus = activeRef(el);
     const valueBefore = valueOf(el);
     const actedField = watchActedField(el);
     const geometry = CLICK_LIKE.has(action) ? clickGeometry(el) : NO_GEOMETRY;

package/dist/commands/commands.js

@@ -1,4 +1,4 @@
-import { ComponentStateReason, ElementQuerySchema, INSPECT_IN_VIEWPORT_FIELD, INSPECT_REVEAL_ARG, ReticleCommand, SnapshotMode, TRANSPORT_LIMITS, selectPath, capDepth, } from '@reticlehq/core';
+import { ComponentStateReason, ElementQuerySchema, INSPECT_IN_VIEWPORT_FIELD, INSPECT_REVEAL_ARG, MatchArg, ReticleCommand, SnapshotMode, TRANSPORT_LIMITS, selectPath, capDepth, } from '@reticlehq/core';
 import { buildSnapshot } from '../dom/snapshot.js';
 import { paintContextOf } from '../dom/paint-context.js';
 import { matchQuery, runQuery } from '../dom/query.js';
@@ -19,7 +19,7 @@ import { sanitizeWithReport } from '../security/serialization.js';
 import { getCapabilities } from '../registry/capabilities.js';
 import { freezeClock, advanceClock, resetClock, isClockFrozen } from '../timers/clock.js';
 import { scrollContainer } from '../actions/scroll.js';
-import { isOffViewport } from '../actions/actions-dom.js';
+import { isOffViewport, scrollIntoViewNow } from '../actions/actions-dom.js';
 export const RELOAD_CACHE_BUST_PARAM = '_reticle_reload';
 function str(value) {
     return 'string' === typeof value ? value : undefined;
@@ -69,7 +69,7 @@ function inspect(ref, reveal = false) {
         'function' === typeof el.scrollIntoView &&
         isOffViewport(el, el.getBoundingClientRect());
     if (scrolledIntoView) {
-        el.scrollIntoView({ block: 'center', inline: 'center' });
+        scrollIntoViewNow(el, { block: 'center', inline: 'center' });
     }
     const rect = el.getBoundingClientRect();
     const component = identifyComponent(el);
@@ -216,7 +216,7 @@ export function createCommandRegistry() {
         const limit = args['limit'];
         return runQuery(queryFromArgs(args), 'number' === typeof limit ? limit : undefined);
     });
-    reg.set(ReticleCommand.MATCH, (args) => matchQuery(ElementQuerySchema.parse(record(args['query'])), str(args['state']), undefined, undefined, true === args['diagnose']));
+    reg.set(ReticleCommand.MATCH, (args) => matchQuery(ElementQuerySchema.parse(record(args['query'])), str(args['state']), undefined, undefined, true === args['diagnose'], true === args[MatchArg.FULL_TEXT]));
     reg.set(ReticleCommand.ACT, async (args) => {
         const action = str(args['action']) ?? '';
         const result = await executeAction(str(args['ref']) ?? '', action, record(args['args']));

package/dist/dom/a11y.d.ts

@@ -4,4 +4,4 @@ export declare function getAccessibleName(el: Element): string;
 export declare function getStates(el: Element, visible?: boolean): ElementState[];
 export declare function isSensitiveField(el: Element): boolean;
 export declare function getValue(el: Element): string | undefined;
-export declare function describe(el: Element, memo?: Map<Element, boolean>): ElementDescriptor;
+export declare function describe(el: Element, memo?: Map<Element, boolean>, fullText?: boolean): ElementDescriptor;

package/dist/dom/a11y.js

@@ -1,5 +1,5 @@
 import { readTestId } from './addressing/testid-attr.js';
-import { DEFAULT_TESTID_ATTR, ElementState, REDACTED_VALUE, } from '@reticlehq/core';
+import { DEFAULT_TESTID_ATTR, ElementState, REDACTED_VALUE, TRANSPORT_LIMITS, } from '@reticlehq/core';
 import { isButton, isImage, isInput, isMeter, isOutput, isProgress, isSelect, isTextArea, } from './realm.js';
 import { refs } from './addressing/refs.js';
 import { inspectChart } from './chart.js';
@@ -360,14 +360,14 @@ export function getValue(el) {
     const valueNow = el.getAttribute('aria-valuenow');
     return valueNow ?? undefined;
 }
-const MAX_TEXT = 80;
-function getVisibleText(el) {
+function getVisibleText(el, fullText) {
     const text = collapse(el.textContent ?? '');
-    return text.length > MAX_TEXT ? `${text.slice(0, MAX_TEXT)}…` : text;
+    const max = fullText ? TRANSPORT_LIMITS.MAX_FULL_TEXT : TRANSPORT_LIMITS.MAX_DESCRIBED_TEXT;
+    return text.length > max ? `${text.slice(0, max)}…` : text;
 }
-export function describe(el, memo) {
+export function describe(el, memo, fullText = false) {
     const value = getValue(el);
-    const text = getVisibleText(el);
+    const text = getVisibleText(el, fullText);
     const name = getAccessibleName(el);
     const visible = isVisible(el, memo);
     const base = {
@@ -380,7 +380,7 @@ export function describe(el, memo) {
     if (value !== undefined && value.length > 0) {
         base.value = value;
     }
-    if (text.length > 0 && text !== name) {
+    if (text.length > 0 && (fullText || text !== name)) {
         base.text = text;
     }
     const source = formatSource(sourceFromDom(el));

package/dist/dom/query.d.ts

@@ -1,5 +1,8 @@
-import { ElementState, type ElementQuery, type MatchResult, type QueryResult } from '@reticlehq/core';
+import { ElementState, type ElementQuery, type MatchResult, type NearestTarget, type QueryResult } from '@reticlehq/core';
 export declare const ATTR_VALUE_MAX = 512;
-export declare function matchQuery(query: ElementQuery, state?: ElementState, limit?: number, wholePhrase?: boolean, diagnose?: boolean): MatchResult;
+export declare function matchQuery(query: ElementQuery, state?: ElementState, limit?: number, wholePhrase?: boolean, diagnose?: boolean, fullText?: boolean): MatchResult;
+export declare const MAX_NEAREST_NAME = 60;
+export declare function nameSimilarity(a: string, b: string): number;
+export declare function nearestTargets(container: HTMLElement, query: ElementQuery): NearestTarget[];
 export declare function elementsMatching(query: ElementQuery): HTMLElement[];
 export declare function runQuery(query: ElementQuery, limit?: number): QueryResult;

package/dist/dom/query.js

@@ -12,6 +12,7 @@ import { stableSelectorFor } from './stable-selector.js';
 import { fuzzyVisibleText, normaliseVisibleText, comparableText, foldTypography, textMatches, unreadableMatch, } from './text-match.js';
 import { pageRoute } from '../security/page-location.js';
 import { elementsUnder, findIn, isNonRendered, queryByRoleAndName } from './query-finders.js';
+import { INTERACTIVE } from './snapshot.js';
 const MAX_PRESENT_TESTIDS = 12;
 function visibleTextOf(el, memo) {
     if (isNonRendered(el) || isWordsIgnored(el)) {
@@ -149,7 +150,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, diagnose = true) {
+export function matchQuery(query, state, limit = MAX_DESCRIBED, wholePhrase = true, diagnose = true, fullText = false) {
     const found = findCandidates(query);
     const scopeMissing = found.scopeMissing;
     const wanted = wholePhrase && textOnly(query) ? wantedTextOf(query) : undefined;
@@ -159,10 +160,13 @@ export function matchQuery(query, state, limit = MAX_DESCRIBED, wholePhrase = tr
     const visMemo = new Map();
     const filtered = state === undefined ? elements : elements.filter((el) => inState(el, state, visMemo));
     const attrs = query.attrs;
-    const described = filtered.slice(0, Math.max(0, Math.min(limit, MAX_DESCRIBED)));
+    const cap = fullText
+        ? Math.min(MAX_DESCRIBED, TRANSPORT_LIMITS.MAX_FULL_TEXT_ELEMENTS)
+        : MAX_DESCRIBED;
+    const described = filtered.slice(0, Math.max(0, Math.min(limit, cap)));
     const stampViewport = described.length > 1 || ElementState.IN_VIEWPORT === state;
     const descriptors = described.map((el) => {
-        let base = describe(el, visMemo);
+        let base = describe(el, visMemo, fullText);
         if (stampViewport &&
             isInViewport(el, visMemo) &&
             !base.states.includes(ElementState.IN_VIEWPORT)) {
@@ -180,6 +184,7 @@ export function matchQuery(query, state, limit = MAX_DESCRIBED, wholePhrase = tr
         matched: filtered.length > 0,
         count: filtered.length,
         elements: descriptors,
+        ...(fullText ? { fullText: true } : {}),
         ...(scopeMissing ? { scopeMissing: true } : {}),
         ...(covered === undefined ? {} : { coveredBy: covered }),
         ...(unreadable === undefined ? {} : { unreadable }),
@@ -346,6 +351,81 @@ function nameNearMisses(container, query) {
     }
     return out;
 }
+const MAX_NEAREST_TARGETS = 3;
+export const MAX_NEAREST_NAME = 60;
+function bigrams(value) {
+    const padded = ` ${value} `;
+    const out = new Set();
+    for (let i = 0; i < padded.length - 1; i += 1) {
+        out.add(padded.slice(i, i + 2));
+    }
+    return out;
+}
+export function nameSimilarity(a, b) {
+    const left = bigrams(foldTypography(a).toLowerCase());
+    const right = bigrams(foldTypography(b).toLowerCase());
+    let shared = 0;
+    for (const gram of left) {
+        if (right.has(gram)) {
+            shared += 1;
+        }
+    }
+    return (2 * shared) / (left.size + right.size);
+}
+function askedRole(query) {
+    return QueryBy.ROLE === query.by ? query.value : query.role;
+}
+function askedName(query) {
+    const value = QueryBy.ROLE === query.by ? undefined : query.value;
+    const asked = query.name ??
+        value ??
+        query.text ??
+        query.label ??
+        query.placeholder ??
+        query.testid ??
+        query.alt;
+    return asked === undefined ? '' : normaliseVisibleText(asked);
+}
+export function nearestTargets(container, query) {
+    const role = askedRole(query);
+    const name = askedName(query);
+    if (role === undefined && 0 === name.length) {
+        return [];
+    }
+    const memo = new Map();
+    const scored = [];
+    for (const el of elementsUnder(container)) {
+        const elRole = getRole(el);
+        const roleMatch = role !== undefined && elRole === role;
+        if (!roleMatch && !INTERACTIVE.has(elRole)) {
+            continue;
+        }
+        if (isIgnored(el) || !isVisible(el, memo)) {
+            continue;
+        }
+        const elName = normaliseVisibleText(getAccessibleName(el));
+        if (0 === elName.length) {
+            continue;
+        }
+        const score = 0 === name.length ? 0 : nameSimilarity(name, elName);
+        if (!roleMatch && 0 === score) {
+            continue;
+        }
+        scored.push({ el, role: elRole, name: elName, roleMatch, score });
+    }
+    scored.sort((a, b) => Number(b.roleMatch) - Number(a.roleMatch) || b.score - a.score);
+    return scored.slice(0, MAX_NEAREST_TARGETS).map((c) => {
+        const target = {
+            ref: refs.refFor(c.el),
+            role: c.role,
+            name: c.name.slice(0, MAX_NEAREST_NAME),
+        };
+        if (c.name.length > MAX_NEAREST_NAME) {
+            target.nameTruncated = true;
+        }
+        return target;
+    });
+}
 function testidFoundUnder(container, query) {
     if (QueryBy.TESTID !== query.by || undefined === query.value) {
         return undefined;
@@ -452,6 +532,10 @@ function buildEmptyHint(query, state, diagnose = true) {
     if (elsewhere !== undefined) {
         hint.testidFoundUnder = elsewhere;
     }
+    const nearest = diagnose ? nearestTargets(container, query) : [];
+    if (nearest.length > 0) {
+        hint.nearest = nearest;
+    }
     return hint;
 }
 export function elementsMatching(query) {
@@ -464,7 +548,7 @@ export function runQuery(query, limit) {
         return {
             elements: result.elements,
             count: result.count,
-            hint: buildEmptyHint(query),
+            hint: result.hint ?? buildEmptyHint(query),
             ...scopeFields,
         };
     }

package/dist/dom/text-match.js

@@ -1,4 +1,5 @@
 import { parentAcrossShadowBoundary } from './shadow-registry.js';
+import { stalledFade } from './visibility.js';
 export function normaliseVisibleText(value) {
     return value.replace(/\s+/g, ' ').trim().normalize('NFC');
 }
@@ -81,7 +82,7 @@ export function unreadableText(el) {
     let opaque = false;
     for (let node = el; null !== node; node = parentAcrossShadowBoundary(node)) {
         const style = view.getComputedStyle(node);
-        const alpha = Number.parseFloat(style.opacity);
+        const alpha = stalledFade(node) ? 1 : Number.parseFloat(style.opacity);
         opacity *= Number.isNaN(alpha) ? 1 : alpha;
         if (opaque) {
             continue;

package/dist/dom/visibility.d.ts

@@ -1,6 +1,7 @@
 export declare const HTML_DETAILS_TAG = "details";
 export declare const HTML_DETAILS_OPEN_ATTRIBUTE = "open";
 export declare const HTML_SUMMARY_TAG = "summary";
+export declare function stalledFade(el: Element): boolean;
 export declare function isHiddenByAriaOnly(el: Element): boolean;
 export declare function isRenderedOutsideAriaHidden(el: Element): boolean;
 export declare function isInViewport(el: Element, memo?: Map<Element, boolean>): boolean;

package/dist/dom/visibility.js

@@ -1,3 +1,4 @@
+import { RETICLE_OVERLAY_SELECTOR } from '@reticlehq/core';
 import { isHtmlElement } from './realm.js';
 import { parentAcrossShadowBoundary } from './shadow-registry.js';
 import { clippingBox, overflowAxes, scrolledInto, } from './paint-context.js';
@@ -16,15 +17,45 @@ function hiddenInsideClosedDetails(el) {
     const summary = Array.from(details.children).find((child) => HTML_SUMMARY_TAG === child.localName);
     return summary === undefined || !summary.contains(el);
 }
-function stalledFade(el) {
+export function stalledFade(el) {
     if (!el.ownerDocument.hidden || !('getAnimations' in el)) {
         return false;
     }
     return el.getAnimations().some((a) => 'running' === a.playState || a.pending);
 }
 const OVERLAY_ARIA_HIDDEN = 'data-aria-hidden';
+const OPEN_LAYER = '[role="dialog"], [role="alertdialog"], [role="menu"], [role="listbox"], dialog[open], [aria-modal="true"]';
+const UNPAINTED_TAGS = new Set(['script', 'style', 'template', 'noscript', 'link', 'meta']);
 function hiddenByAnOverlay(el) {
-    return el.hasAttribute(OVERLAY_ARIA_HIDDEN);
+    if (el.hasAttribute(OVERLAY_ARIA_HIDDEN)) {
+        return true;
+    }
+    return hiddenByAModalManager(el);
+}
+function hiddenByAModalManager(el) {
+    const body = el.ownerDocument.body;
+    if (el.parentElement !== body) {
+        return false;
+    }
+    const others = Array.from(body.children).filter((child) => child !== el &&
+        !UNPAINTED_TAGS.has(child.localName) &&
+        !child.matches(RETICLE_OVERLAY_SELECTOR));
+    const open = others.filter((child) => 'true' !== child.getAttribute('aria-hidden'));
+    const layer = open[0];
+    return 1 === open.length && layer !== undefined && holdsOpenLayer(layer);
+}
+function holdsOpenLayer(portal) {
+    const layer = portal.matches(OPEN_LAYER) ? portal : portal.querySelector(OPEN_LAYER);
+    for (let node = layer; null !== node; node = node.parentElement) {
+        const style = node.ownerDocument.defaultView?.getComputedStyle(node) ?? null;
+        if (selfCssHidden(node, style)) {
+            return false;
+        }
+        if (node === portal) {
+            return true;
+        }
+    }
+    return false;
 }
 function selfCssHidden(el, style) {
     if (isHtmlElement(el) && el.hidden) {
@@ -106,6 +137,56 @@ export function isRenderedOutsideAriaHidden(el) {
     }
     return true;
 }
+const BACKFACE_VISIBILITY_HIDDEN = 'hidden';
+function localTransform(style) {
+    if ('undefined' === typeof DOMMatrix) {
+        return null;
+    }
+    try {
+        const transform = style?.transform;
+        return undefined === transform || '' === transform || 'none' === transform
+            ? new DOMMatrix()
+            : new DOMMatrix(transform);
+    }
+    catch {
+        return null;
+    }
+}
+function backFaceTowardViewer(matrix) {
+    return Number.isFinite(matrix.m33) && 0 > matrix.m33;
+}
+function backfaceHidden(el, memo) {
+    const chain = [];
+    let declares = false;
+    for (let current = el; null !== current; current = parentAcrossShadowBoundary(current)) {
+        const style = ownVisibilityInfo(current, memo).style;
+        if (BACKFACE_VISIBILITY_HIDDEN === style?.backfaceVisibility) {
+            declares = true;
+        }
+        chain.push(current);
+    }
+    if (!declares) {
+        return false;
+    }
+    let composed = null;
+    for (let index = chain.length - 1; index >= 0; index -= 1) {
+        const current = chain[index];
+        if (undefined === current) {
+            return false;
+        }
+        const style = ownVisibilityInfo(current, memo).style;
+        const local = localTransform(style);
+        if (null === local) {
+            return false;
+        }
+        composed = null === composed ? local : composed.multiply(local);
+        if (BACKFACE_VISIBILITY_HIDDEN === style?.backfaceVisibility &&
+            backFaceTowardViewer(composed)) {
+            return true;
+        }
+    }
+    return false;
+}
 const CLIPPING_OVERFLOW = new Set(['hidden', 'clip']);
 const SCROLLING_OVERFLOW = new Set(['auto', 'scroll']);
 const NON_CLIPPING_DISPLAY = new Set([
@@ -314,7 +395,9 @@ export function isVisible(el, memo) {
         return cached;
     }
     const info = visibilityInfoMemo(memo);
-    const result = visibleBounds(el, info, undefined, true) !== null && !collapsed(el, info);
+    const result = visibleBounds(el, info, undefined, true) !== null &&
+        !collapsed(el, info) &&
+        !backfaceHidden(el, info);
     if (memo !== undefined) {
         memo.set(el, result);
     }

package/dist/observers/network.js

@@ -228,6 +228,7 @@ export function installNetwork(emit, opts = {}) {
     }
     const owner = {};
     pageSlots()[PAGE_CAPTURE] = owner;
+    const installedAt = performance.now();
     const captureBodies = true === opts.captureBodies;
     const bodyCapture = new AbortController();
     const captureErrorBodies = false !== opts.captureErrorBodies;
@@ -550,7 +551,8 @@ export function installNetwork(emit, opts = {}) {
                         return;
                     }
                     const type = entry.initiatorType || 'other';
-                    if ('fetch' === type || 'xmlhttprequest' === type) {
+                    const patched = 'fetch' === type || 'xmlhttprequest' === type;
+                    if (patched && entry.startTime >= installedAt) {
                         continue;
                     }
                     const rawUrl = entry.name;