@reticlehq/browser 3.6.0 → 3.8.0

package/dist/dom/chart.js

@@ -46,11 +46,12 @@ export function inspectChart(root) {
     return { examined, findings, canvas };
 }
 export function canvasChartData(canvas, globals) {
-    const chartjs = globals.Chart?.getChart?.(canvas);
+    const libs = globals;
+    const chartjs = libs.Chart?.getChart?.(canvas);
     if (chartjs !== undefined && chartjs !== null) {
         return { library: 'chartjs', data: chartjs.data ?? null };
     }
-    const echart = globals.echarts?.getInstanceByDom?.(canvas);
+    const echart = libs.echarts?.getInstanceByDom?.(canvas);
     if (echart !== undefined && echart !== null) {
         return { library: 'echarts', data: echart.getOption?.() ?? null };
     }

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

@@ -1,8 +1,16 @@
 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 isWordsIgnored(el: Element): boolean;
+export declare const FrameworkErrorDialog: {
+    readonly NEXT: "Next.js error dialog";
+    readonly VITE: "Vite error overlay";
+};
+export declare function dialogCovering(matches: readonly Element[]): string | undefined;
 export declare function appModalOpen(doc: Document): boolean;

package/dist/dom/dom-ignore.js

@@ -1,10 +1,17 @@
-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';
+import { capturedRootOf } from './shadow-registry.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 = '';
 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,14 +21,62 @@ 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],[data-reticle-act-line]';
 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;
 }
+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);
+        if (null !== (root ?? portal).querySelector(NEXT_DIALOG)) {
+            return { name: FrameworkErrorDialog.NEXT, host: portal };
+        }
+    }
+    const light = doc.querySelector(NEXT_DIALOG);
+    return null === light ? undefined : { 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))) {

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

@@ -1,5 +1,6 @@
 import { ElementState, type ElementQuery, type MatchResult, type QueryResult } from '@reticlehq/core';
+export declare function isHiddenNativeOption(el: HTMLElement): boolean;
 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, diagnose?: boolean): MatchResult;
 export declare function elementsMatching(query: ElementQuery): HTMLElement[];
 export declare function runQuery(query: ElementQuery, limit?: number): QueryResult;