@reticlehq/browser 3.5.0 → 3.7.0

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/addressing/refs.js

@@ -1,4 +1,5 @@
 import { TRANSPORT_LIMITS, asRef } from '@reticlehq/core';
+import { ReticleStorageKey } from '../../storage-keys.js';
 export const MAX_TRACKED_REFS = 10000;
 const REF_ELISION = '…';
 const REF_PREFIX = 'e';
@@ -7,7 +8,7 @@ export function echoRef(ref) {
     return max >= ref.length ? ref : `${ref.slice(0, max)}${REF_ELISION}`;
 }
 const SWEEP_EVERY_MINTS = 1000;
-const REF_BASE_KEY = '__reticle_ref_base';
+const REF_BASE_KEY = ReticleStorageKey.REF_BASE;
 export const REF_BLOCK = 100;
 function readBase(store) {
     try {

package/dist/dom/addressing/testid-attr.d.ts

@@ -0,0 +1,4 @@
+export declare function getTestIdAttr(): string;
+export declare function testIdSelector(): string;
+export declare function readTestId(el: Element): string | null;
+export declare function setTestIdAttr(name: string | undefined): void;

package/dist/dom/addressing/testid-attr.js

@@ -0,0 +1,14 @@
+import { DEFAULT_TESTID_ATTR, TESTID_ATTR_PATTERN } from '@reticlehq/core';
+let testIdAttr = DEFAULT_TESTID_ATTR;
+export function getTestIdAttr() {
+    return testIdAttr;
+}
+export function testIdSelector() {
+    return `[${testIdAttr}]`;
+}
+export function readTestId(el) {
+    return el.getAttribute(testIdAttr);
+}
+export function setTestIdAttr(name) {
+    testIdAttr = undefined !== name && TESTID_ATTR_PATTERN.test(name) ? name : DEFAULT_TESTID_ATTR;
+}

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,4 +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

@@ -1,4 +1,4 @@
-import { DATA_RETICLE_SOURCE_ATTR, ElementState, QueryBy, REDACTED_VALUE, TRANSPORT_LIMITS, } from '@reticlehq/core';
+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';
@@ -7,11 +7,11 @@ 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';
-const TESTID_ATTR = 'data-testid';
+import { getTestIdAttr, readTestId, testIdSelector } from './addressing/testid-attr.js';
 const SOURCE_ATTR = DATA_RETICLE_SOURCE_ATTR;
 const MAX_PRESENT_TESTIDS = 12;
 const MAX_COMPONENT_CANDIDATES = 2000;
-const COMPONENT_CANDIDATE_SELECTOR = `[${SOURCE_ATTR}], [${TESTID_ATTR}], button, a, input, select, textarea, [role]`;
+const componentCandidateSelector = () => `[${SOURCE_ATTR}], ${testIdSelector()}, button, a, input, select, textarea, [role]`;
 function elementsUnder(container) {
     const self = Node.ELEMENT_NODE === container.nodeType ? [container] : [];
     return [...self, ...Array.from(container.querySelectorAll('*'))];
@@ -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;
@@ -94,7 +111,7 @@ function findBySource(container, source) {
 function findByComponentName(container, component) {
     const out = [];
     let scanned = 0;
-    for (const el of Array.from(container.querySelectorAll(COMPONENT_CANDIDATE_SELECTOR))) {
+    for (const el of Array.from(container.querySelectorAll(componentCandidateSelector()))) {
         if (scanned >= MAX_COMPONENT_CANDIDATES)
             break;
         scanned += 1;
@@ -115,14 +132,33 @@ function findByComponent(container, query) {
     }
     return [];
 }
+function matchesRole(actual, queried) {
+    if (actual === queried)
+        return true;
+    if ('textbox' === queried && 'searchbox' === actual)
+        return true;
+    return false;
+}
 function queryByRoleAndName(container, role, name) {
-    return elementsUnder(container).filter((el) => getRole(el) === role && (name === undefined || exactVisibleText(getAccessibleName(el), 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) => {
@@ -131,7 +167,7 @@ function queryByPlaceholder(container, value) {
     });
 }
 function queryByTestId(container, value) {
-    return elementsUnder(container).filter((el) => el.getAttribute(TESTID_ATTR) === value);
+    return elementsUnder(container).filter((el) => readTestId(el) === value);
 }
 function queryByAlt(container, value) {
     return elementsUnder(container).filter((el) => {
@@ -147,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:
@@ -169,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)
@@ -221,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 };
@@ -261,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;
@@ -329,7 +368,7 @@ function buildPresentRegions(query) {
                 continue;
             const name = el.getAttribute('aria-label') ??
                 resolveLabelledBy(el) ??
-                el.getAttribute('data-testid') ??
+                readTestId(el) ??
                 undefined;
             const children = el.querySelectorAll('[role]');
             const sample = [];
@@ -338,7 +377,7 @@ function buildPresentRegions(query) {
                     break;
                 const childRole = child.getAttribute('role');
                 const childName = child.getAttribute('aria-label') ??
-                    child.getAttribute('data-testid') ??
+                    readTestId(child) ??
                     child.textContent?.trim().slice(0, 40) ??
                     '';
                 if (childRole !== null && childName.length > 0) {
@@ -355,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)
@@ -374,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;
@@ -381,7 +446,7 @@ function wantedTextOf(query) {
 }
 const MAX_NAME_NEAR_MISSES = 5;
 function nameNearMisses(container, query) {
-    const role = QueryBy.ROLE === query.by ? query.value : undefined;
+    const role = QueryBy.ROLE === query.by ? query.value : query.role;
     const wanted = query.name;
     if (role === undefined || wanted === undefined || 0 === wanted.length)
         return [];
@@ -405,15 +470,28 @@ function nameNearMisses(container, query) {
     }
     return out;
 }
+function testidFoundUnder(container, query) {
+    if (QueryBy.TESTID !== query.by || undefined === query.value)
+        return undefined;
+    const configured = getTestIdAttr();
+    for (const attr of [DEFAULT_TESTID_ATTR, ...ALTERNATIVE_TESTID_ATTRS]) {
+        if (attr === configured)
+            continue;
+        const found = elementsUnder(container).some((el) => el.getAttribute(attr) === query.value && !isIgnored(el));
+        if (found)
+            return attr;
+    }
+    return undefined;
+}
 function buildEmptyHint(query) {
     const container = resolveContainer(query.scope).container ?? document.body;
-    const all = container.querySelectorAll(`[${TESTID_ATTR}]`);
+    const all = container.querySelectorAll(testIdSelector());
     const present = [];
     const seen = new Set();
     for (const el of Array.from(all)) {
         if (isIgnored(el))
             continue;
-        const id = el.getAttribute(TESTID_ATTR);
+        const id = readTestId(el);
         if (null === id || 0 === id.length || seen.has(id))
             continue;
         seen.add(id);
@@ -432,17 +510,28 @@ 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)
         hint.nameNearMiss = near;
+    const elsewhere = testidFoundUnder(container, query);
+    if (elsewhere !== undefined)
+        hint.testidFoundUnder = elsewhere;
     return hint;
 }
+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/snapshot.js

@@ -1,6 +1,6 @@
 import { ElementState, SnapshotMode } from '@reticlehq/core';
 import { capturedRootOf } from './shadow-registry.js';
-import { isFrame } from './realm.js';
+import { isElement, isFrame } from './realm.js';
 import { getAccessibleName, getRole, getStates, getValue, isVisible } from './a11y.js';
 import { refs } from './addressing/refs.js';
 import { isIgnored, isReticleOverlay } from './dom-ignore.js';
@@ -8,6 +8,7 @@ const INTERACTIVE = new Set([
     'button',
     'link',
     'textbox',
+    'searchbox',
     'checkbox',
     'radio',
     'combobox',
@@ -29,13 +30,44 @@ function announces(el, role) {
 }
 const TEXT_MAX = 80;
 function directText(el) {
-    let out = '';
+    const parts = readingParts(el);
+    const collapsed = (parts.own ? parts.text : '').replace(/\s+/g, ' ').trim();
+    return collapsed.length > TEXT_MAX ? `${collapsed.slice(0, TEXT_MAX)}…` : collapsed;
+}
+function readingParts(el) {
+    let text = '';
+    let own = false;
     for (const node of el.childNodes) {
-        if (3 === node.nodeType)
-            out += node.textContent ?? '';
+        if (3 === node.nodeType) {
+            text += node.textContent ?? '';
+            own ||= 0 < (node.textContent ?? '').trim().length;
+        }
+        else if (isElement(node) && foldsIntoParent(node)) {
+            const inner = readingParts(node);
+            text += inner.text;
+            own ||= inner.own;
+        }
+        else if (isElement(node) && isInlineIn(node) && INTERACTIVE.has(getRole(node))) {
+            text += getAccessibleName(node);
+        }
     }
-    const collapsed = out.replace(/\s+/g, ' ').trim();
-    return collapsed.length > TEXT_MAX ? `${collapsed.slice(0, TEXT_MAX)}…` : collapsed;
+    return { text, own };
+}
+function isInlineIn(el) {
+    const view = el.ownerDocument.defaultView;
+    const parent = el.parentElement;
+    if (null === view || null === parent)
+        return false;
+    const around = view.getComputedStyle(parent).display;
+    if (around.includes('flex') || around.includes('grid'))
+        return false;
+    return 'inline' === view.getComputedStyle(el).display;
+}
+function foldsIntoParent(el) {
+    if (skipEarly(el) || !isInlineIn(el))
+        return false;
+    const role = getRole(el);
+    return !INTERACTIVE.has(role) && !announces(el, role) && 0 === getAccessibleName(el).length;
 }
 export const MAX_UNREAD_BRANCHES = 50;
 function hiddenByMarkup(el) {
@@ -82,6 +114,7 @@ function layoutSignature(style) {
     }
     return '';
 }
+const overlayStamped = (el) => el.hasAttribute('data-aria-hidden') && 'true' === el.getAttribute('aria-hidden');
 function recordUnread(branches, ctx) {
     for (const branch of branches) {
         if (ctx.unread.length >= MAX_UNREAD_BRANCHES) {
@@ -108,7 +141,11 @@ function pierceChildren(parent) {
     return out;
 }
 function visit(child, depth, ctx, inLive) {
-    if (skipEarly(child)) {
+    const stampedOnly = true === ctx.throughOverlay &&
+        overlayStamped(child) &&
+        !isIgnored(child) &&
+        !(child instanceof HTMLElement && child.hidden);
+    if (!stampedOnly && skipEarly(child)) {
         if (hiddenByMarkup(child))
             ctx.hiddenSkipped += 1;
         return;
@@ -119,6 +156,10 @@ function visit(child, depth, ctx, inLive) {
         ctx.hiddenSkipped += 1;
         return;
     }
+    if (style !== null && 'inline' === style.display && !inLive && foldsIntoParent(child)) {
+        walk(child, depth, ctx, inLive);
+        return;
+    }
     const role = getRole(child);
     const name = getAccessibleName(child);
     const interactive = INTERACTIVE.has(role);
@@ -173,6 +214,7 @@ function collectDialogs(root) {
     }
     return names;
 }
+const MODAL_SELECTOR = '[role="dialog"], [role="alertdialog"], dialog[open], [aria-modal="true"]';
 function overlayHidingPage(root) {
     if (root !== document.body)
         return undefined;
@@ -241,6 +283,13 @@ export function buildSnapshot(options = {}) {
         visit(root, 0, ctx, false);
     else
         walk(root, 0, ctx);
+    if (0 === ctx.nodes && root === document.body) {
+        ctx.throughOverlay = true;
+        for (const child of Array.from(root.children))
+            if (overlayStamped(child) && null !== child.querySelector(MODAL_SELECTOR))
+                visit(child, 0, ctx, false);
+        ctx.throughOverlay = false;
+    }
     return {
         tree: ctx.lines.join('\n'),
         status,