@reticlehq/browser 3.8.2 → 3.10.0

package/dist/commands/commands.js

@@ -1,7 +1,7 @@
-import { ComponentStateReason, ElementQuerySchema, INSPECT_IN_VIEWPORT_FIELD, INSPECT_REVEAL_ARG, ReticleCommand, SnapshotMode, TRANSPORT_LIMITS, selectPath, capDepth, } from '@reticlehq/core';
+import { ANIMATION_TARGET_ARG, ComponentStateReason, ElementQuerySchema, INSPECT_IN_VIEWPORT_FIELD, INSPECT_REVEAL_ARG, MatchArg, ReticleCommand, SnapshotMode, SESSION_REF, 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';
+import { embeddedRootsUnder, matchQuery, runQuery } from '../dom/query.js';
 import { executeAction, executeSequence } from '../actions/actions.js';
 import { describe } from '../dom/a11y.js';
 import { documentHasSourceStamps, sourceFor, formatSource } from '../dom/addressing/source.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);
@@ -173,23 +173,98 @@ function readState(ref, store, path, depth) {
     }
     return result;
 }
-function listAnimations() {
+function animationName(animation) {
+    const fields = animation;
+    const name = str(fields.animationName);
+    if (name !== undefined && name.length > 0) {
+        return name;
+    }
+    const transition = str(fields.transitionProperty);
+    return transition !== undefined && transition.length > 0 ? transition : undefined;
+}
+function resolveAnimationTarget(target) {
+    if (target === undefined) {
+        return undefined;
+    }
+    const byRef = refs.resolve(target);
+    if (byRef !== null) {
+        const ref = refs.refFor(byRef);
+        return {
+            report: { target, matched: true, refs: [ref], count: 1 },
+            matches: (animationTarget) => animationTarget !== null && refs.refFor(animationTarget) === ref,
+        };
+    }
+    if (SESSION_REF.test(target)) {
+        return {
+            report: { target, matched: false, refs: [], count: 0 },
+            matches: () => false,
+        };
+    }
+    let elements;
+    try {
+        const roots = [document];
+        const container = document.body ?? document.documentElement;
+        if (container !== null) {
+            roots.push(...embeddedRootsUnder(container));
+        }
+        const seen = new Set();
+        elements = [];
+        for (const root of roots) {
+            for (const el of root.querySelectorAll(target)) {
+                if (seen.has(el)) {
+                    continue;
+                }
+                seen.add(el);
+                elements.push(el);
+            }
+        }
+    }
+    catch {
+        return {
+            report: { target, matched: false, refs: [], count: 0, invalid: true },
+            matches: () => false,
+        };
+    }
+    const allRefs = new Set(elements.map((el) => refs.refFor(el)));
+    const refsInReport = Array.from(allRefs).slice(0, TRANSPORT_LIMITS.MAX_COLLECTION_ITEMS);
+    return {
+        report: {
+            target,
+            matched: elements.length > 0,
+            refs: refsInReport,
+            count: elements.length,
+            ...(allRefs.size > refsInReport.length ? { truncated: true } : {}),
+        },
+        matches: (animationTarget) => animationTarget !== null && allRefs.has(refs.refFor(animationTarget)),
+    };
+}
+function listAnimations(args = {}) {
     const doc = document;
+    const targetFilter = resolveAnimationTarget(str(args[ANIMATION_TARGET_ARG]));
     if (typeof doc.getAnimations !== 'function') {
-        return { animations: [] };
+        return {
+            animations: [],
+            ...(targetFilter === undefined ? {} : { target: targetFilter.report }),
+        };
     }
     const animations = doc.getAnimations().map((a) => {
         const effect = a.effect;
         const timing = effect?.getTiming();
         const target = effect?.target ?? null;
+        const name = animationName(a);
         return {
+            ...(name === undefined ? {} : { name }),
             playState: a.playState,
             currentTime: a.currentTime,
             duration: timing?.duration,
             target: null === target ? null : describe(target),
+            ...(targetFilter === undefined ? {} : { targetMatches: targetFilter.matches(target) }),
         };
     });
-    return { animations };
+    return {
+        animations,
+        ...(targetFilter === undefined ? {} : { target: targetFilter.report }),
+    };
 }
 export function resolveNavigationUrl(rawUrl, baseUrl) {
     if (0 === rawUrl.length || rawUrl.length > TRANSPORT_LIMITS.MAX_URL_LENGTH) {
@@ -211,12 +286,13 @@ export function createCommandRegistry() {
         includeRoot: true === args['includeRoot'],
         ids: true === args['ids'],
         audit: true === args['audit'],
+        charts: true === args['charts'],
     }));
     reg.set(ReticleCommand.QUERY, (args) => {
         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']));
@@ -229,7 +305,7 @@ export function createCommandRegistry() {
         return result;
     });
     reg.set(ReticleCommand.INSPECT, (args) => inspect(str(args['ref']) ?? '', true === args[INSPECT_REVEAL_ARG]));
-    reg.set(ReticleCommand.ANIMATIONS, () => listAnimations());
+    reg.set(ReticleCommand.ANIMATIONS, (args) => listAnimations(args));
     reg.set(ReticleCommand.CLOCK, (args) => {
         if (true === args['reset']) {
             resetClock();

package/dist/connect-options.d.ts

@@ -1,4 +1,4 @@
-import { HelloInstrumentation, type HelloEnv, type HelloScope, type RedactionConfig } from '@reticlehq/core';
+import { HelloInstrumentation, HudVisibility, type HelloEnv, type HelloScope, type RedactionConfig } from '@reticlehq/core';
 export interface ReticleConnectOptions {
     url?: string;
     session?: string;
@@ -37,3 +37,13 @@ export declare function helloMode(options: Pick<ReticleConnectOptions, 'env' | '
 };
 export declare function shouldBlockProduction(nodeEnv: string | undefined, allowInProduction: boolean): boolean;
 export declare function leaseToken(options: ReticleConnectOptions, current: string | undefined): string | undefined;
+export declare function oneOf<T extends Record<string, string>>(values: T, raw: unknown): T[keyof T] | undefined;
+export declare function reticleParamsFromSearch(search: string): {
+    session?: string;
+    projectId?: string;
+    hud?: HudVisibility;
+};
+export declare function hudWithoutPanel(hud: HudVisibility | undefined): {
+    remember?: HudVisibility;
+    placed: HudVisibility[];
+};

package/dist/connect-options.js

@@ -1,4 +1,4 @@
-import { HelloInstrumentation, } from '@reticlehq/core';
+import { HelloInstrumentation, HudVisibility, RETICLE_URL_PARAM, } from '@reticlehq/core';
 export function helloMode(options) {
     return {
         ...(options.env === undefined ? {} : { env: options.env }),
@@ -16,3 +16,29 @@ export function leaseToken(options, current) {
     }
     return token;
 }
+export function oneOf(values, raw) {
+    return Object.values(values).includes(raw) ? raw : undefined;
+}
+export function reticleParamsFromSearch(search) {
+    const params = new URLSearchParams(search);
+    const out = {};
+    const session = params.get(RETICLE_URL_PARAM.SESSION);
+    const projectId = params.get(RETICLE_URL_PARAM.PROJECT);
+    const hud = oneOf(HudVisibility, params.get(RETICLE_URL_PARAM.HUD));
+    if (session !== null && session.length > 0) {
+        out.session = session;
+    }
+    if (projectId !== null && projectId.length > 0) {
+        out.projectId = projectId;
+    }
+    if (hud !== undefined) {
+        out.hud = hud;
+    }
+    return out;
+}
+export function hudWithoutPanel(hud) {
+    if (hud === undefined) {
+        return { placed: [] };
+    }
+    return { remember: hud, placed: HudVisibility.SHOWN === hud ? [] : [hud] };
+}

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,11 +1,11 @@
 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';
 import { isSensitiveKey } from '../security/serialization.js';
 import { formatSource, sourceFromDom } from './addressing/source.js';
-import { HTML_DETAILS_OPEN_ATTRIBUTE, HTML_DETAILS_TAG, HTML_SUMMARY_TAG, isVisible, } from './visibility.js';
+import { HTML_DETAILS_OPEN_ATTRIBUTE, HTML_DETAILS_TAG, HTML_SUMMARY_TAG, isNonRendered, isVisible, } from './visibility.js';
 const NAME_FROM_CONTENT = new Set([
     'button',
     'link',
@@ -30,6 +30,7 @@ const NAME_FROM_CONTENT = new Set([
     'alert',
 ]);
 const INPUT_TEXT_TYPES = new Set(['text', 'email', 'tel', 'url', 'password', '']);
+const INPUT_BUTTON_TYPES = new Set(['submit', 'button', 'reset', 'file', 'image']);
 function inputRole(input) {
     const type = input.type.toLowerCase();
     if ('search' === type) {
@@ -50,7 +51,7 @@ function inputRole(input) {
     if ('number' === type) {
         return 'spinbutton';
     }
-    if ('submit' === type || 'button' === type || 'reset' === type) {
+    if (INPUT_BUTTON_TYPES.has(type)) {
         return 'button';
     }
     return 'textbox';
@@ -182,7 +183,7 @@ function textWithoutHidden(node) {
         return '';
     }
     const el = node;
-    if ('true' === el.getAttribute('aria-hidden')) {
+    if ('true' === el.getAttribute('aria-hidden') || isNonRendered(el)) {
         return '';
     }
     if (isImage(el)) {
@@ -360,14 +361,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 +381,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/chart-geometry.d.ts

@@ -0,0 +1,7 @@
+export declare const CHART_SHAPE_CAP = 120;
+export interface ChartReading {
+    label: string;
+    shapes: string[];
+    cut?: number;
+}
+export declare function readCharts(root: Element): ChartReading[];

package/dist/dom/chart-geometry.js

@@ -0,0 +1,39 @@
+export const CHART_SHAPE_CAP = 120;
+const MIN_CHART_WIDTH = 120;
+const MIN_CHART_HEIGHT = 60;
+const SHAPE_TAGS = ['rect', 'circle', 'ellipse', 'line', 'polyline', 'polygon', 'path'];
+const NOT_DRAWN = 'defs, clipPath, mask, pattern, marker, symbol';
+const pct = (v, of) => {
+    const n = Math.round((v / of) * 1000) / 10;
+    return Object.is(n, -0) ? '0' : String(n);
+};
+export function readCharts(root) {
+    const out = [];
+    const svgs = Array.from(root.querySelectorAll('svg')).filter((s) => null === s.parentElement?.closest('svg'));
+    for (const svg of svgs) {
+        const frame = svg.getBoundingClientRect();
+        if (frame.width < MIN_CHART_WIDTH || frame.height < MIN_CHART_HEIGHT) {
+            continue;
+        }
+        const marks = Array.from(svg.querySelectorAll(SHAPE_TAGS.join(','))).filter((el) => null === el.closest(NOT_DRAWN));
+        const shapes = [];
+        for (const el of marks) {
+            const b = el.getBoundingClientRect();
+            if (0 === b.width && 0 === b.height) {
+                continue;
+            }
+            const x = pct(b.left - frame.left, frame.width);
+            const y = pct(b.top - frame.top, frame.height);
+            shapes.push(`${el.tagName.toLowerCase()} ${x} ${y} ${pct(b.width, frame.width)} ${pct(b.height, frame.height)}`);
+        }
+        if (0 === shapes.length) {
+            continue;
+        }
+        const label = svg.getAttribute('aria-label') ?? `chart ${String(out.length + 1)}`;
+        const kept = shapes.slice(0, CHART_SHAPE_CAP);
+        out.push(shapes.length > CHART_SHAPE_CAP
+            ? { label, shapes: kept, cut: shapes.length - CHART_SHAPE_CAP }
+            : { label, shapes: kept });
+    }
+    return out;
+}

package/dist/dom/occlusion.js

@@ -13,6 +13,10 @@ export function hitTestOccluder(el, rect) {
     const doc = el.ownerDocument;
     if (typeof doc.elementFromPoint !== 'function')
         return null;
+    const passThrough = pointerPassesThrough(el, rect);
+    if (passThrough !== undefined) {
+        return passThrough;
+    }
     const withStack = doc;
     const isOursButNotTheTarget = (candidate) => isReticleUi(candidate) &&
         candidate !== el &&
@@ -41,3 +45,20 @@ export function hitTestOccluder(el, rect) {
     }
     return worstCount >= BLOCKED_MAJORITY ? worst : null;
 }
+function pointerPassesThrough(el, rect) {
+    const view = el.ownerDocument.defaultView;
+    if (null === view || 'none' !== view.getComputedStyle(el).pointerEvents) {
+        return undefined;
+    }
+    const top = el.ownerDocument.elementFromPoint(rect.left + rect.width / 2, rect.top + rect.height / 2);
+    if (null === top || el.contains(top) || isReticleUi(top)) {
+        return null;
+    }
+    const labels = 'labels' in el ? el.labels : null;
+    for (const label of labels ?? []) {
+        if (label === top || label.contains(top)) {
+            return null;
+        }
+    }
+    return top;
+}

package/dist/dom/query-finders.d.ts

@@ -1,6 +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 ownWords(el: Element): string;
 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

@@ -1,7 +1,7 @@
 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 { isNonRendered, 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';
@@ -12,10 +12,6 @@ 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();
@@ -67,15 +63,22 @@ function findByComponentName(container, component) {
     }
     return out;
 }
+export function ownWords(el) {
+    return (el.textContent ?? '').replace(/\s+/g, ' ').trim();
+}
 function findByComponent(container, query) {
+    const words = query.text === undefined ? undefined : query.text.replace(/\s+/g, ' ').trim();
+    const role = query.role;
+    const keep = (els) => els.filter((el) => (words === undefined || ownWords(el) === words) &&
+        (role === undefined || matchesRole(getRole(el), role)));
     if (query.source !== undefined) {
-        const bySource = findBySource(container, query.source);
+        const bySource = keep(findBySource(container, query.source));
         if (bySource.length > 0) {
             return bySource;
         }
     }
     if (query.component !== undefined && query.component.length > 0) {
-        return findByComponentName(container, query.component);
+        return keep(findByComponentName(container, query.component));
     }
     return [];
 }

package/dist/dom/query.d.ts

@@ -1,5 +1,9 @@
-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 function embeddedRootsUnder(root: HTMLElement): HTMLElement[];
 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;