@reticlehq/browser 2.2.1 → 2.4.0

package/dist/dom/a11y.js

@@ -1,9 +1,22 @@
 import { ElementState, REDACTED_VALUE } from '@reticlehq/core';
+import { isButton, isHtmlElement, isImage, isInput, isSelect, isTextArea } from './realm.js';
 import { refs } from './refs.js';
 import { inspectChart } from './chart.js';
 import { isSensitiveKey } from '../security/serialization.js';
 import { formatSource, sourceFromDom } from './source.js';
-/** Roles whose accessible name comes from their text content. */
+/**
+ * Roles whose accessible name comes from their text content (ARIA's `nameFrom: author content`).
+ *
+ * `radio`, `checkbox`, `row` and `tooltip` were missing, and the gap is not cosmetic: a segmented
+ * filter written as `<button role="radio">held</button>` — an extremely ordinary design-system
+ * control — reported as a nameless `radio`, so `by: role` + name could not address it at all and an
+ * agent had to fall back to a testid the app has no reason to carry. Measured on a shipments console:
+ * six filters, six nameless radios, none reachable by name.
+ *
+ * `listitem`, `status` and `alert` are NOT in the spec's list. They are kept as a deliberate
+ * over-approximation — a name computed from content is more useful than no name — and removing them
+ * has no measured symptom to justify the risk.
+ */
 const NAME_FROM_CONTENT = new Set([
     'button',
     'link',
@@ -11,9 +24,13 @@ const NAME_FROM_CONTENT = new Set([
     'option',
     'listitem',
     'cell',
+    'checkbox',
     'columnheader',
+    'radio',
+    'row',
     'rowheader',
     'tab',
+    'tooltip',
     'menuitem',
     'menuitemcheckbox',
     'menuitemradio',
@@ -104,12 +121,36 @@ function labelledByText(el) {
     for (const id of ids.split(/\s+/)) {
         const ref = el.ownerDocument.getElementById(id);
         if (ref !== null)
-            parts.push(collapse(ref.textContent ?? ''));
+            parts.push(collapse(textWithoutHidden(ref)));
     }
     const joined = parts.join(' ').trim();
     return joined.length > 0 ? joined : null;
 }
 /** Accessible name via a practical subset of the accname algorithm. */
+/** Accessible name via a practical subset of the accname algorithm. */
+/**
+ * Text content with `aria-hidden` subtrees removed.
+ *
+ * The accessible-name spec excludes them, and — decisively — so does dom-accessibility-api, which is
+ * what `by: role` + name MATCHES against via testing-library. Reading raw `textContent` here made the
+ * name we REPORT differ from the name that can be SELECTED: Material UI renders its required-field
+ * marker as `<span aria-hidden="true"> *</span>`, so a login field was reported as `"Username *"` and
+ * addressable only as `"Username"`. Reporting a name the agent cannot use defeats the purpose of
+ * reporting it at all, so both must come from the same rule.
+ */
+function textWithoutHidden(node) {
+    if (node.nodeType === Node.TEXT_NODE)
+        return node.textContent ?? '';
+    if (node.nodeType !== Node.ELEMENT_NODE)
+        return '';
+    const el = node;
+    if (el.getAttribute('aria-hidden') === 'true')
+        return '';
+    let out = '';
+    for (const child of el.childNodes)
+        out += textWithoutHidden(child);
+    return out;
+}
 export function getAccessibleName(el) {
     const labelled = labelledByText(el);
     if (labelled !== null)
@@ -117,31 +158,29 @@ export function getAccessibleName(el) {
     const ariaLabel = el.getAttribute('aria-label');
     if (ariaLabel !== null && ariaLabel.trim().length > 0)
         return ariaLabel.trim();
-    if (el instanceof HTMLImageElement) {
+    if (isImage(el)) {
         const alt = el.getAttribute('alt');
         if (alt !== null)
             return alt.trim();
     }
-    if (el instanceof HTMLInputElement ||
-        el instanceof HTMLTextAreaElement ||
-        el instanceof HTMLSelectElement) {
+    if (isInput(el) || isTextArea(el) || isSelect(el)) {
         const labels = el.labels;
         if (labels !== null && labels.length > 0) {
             const text = [...labels]
-                .map((l) => collapse(l.textContent ?? ''))
+                .map((l) => collapse(textWithoutHidden(l)))
                 .join(' ')
                 .trim();
             if (text.length > 0)
                 return text;
         }
-        if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+        if (isInput(el) || isTextArea(el)) {
             const placeholder = el.getAttribute('placeholder');
             if (placeholder !== null && placeholder.trim().length > 0)
                 return placeholder.trim();
         }
     }
     if (NAME_FROM_CONTENT.has(getRole(el))) {
-        const text = collapse(el.textContent ?? '');
+        const text = collapse(textWithoutHidden(el));
         if (text.length > 0)
             return text;
     }
@@ -163,14 +202,10 @@ function ariaBool(el, attr) {
 export function getStates(el, visible = isVisible(el)) {
     const states = [ElementState.PRESENT];
     states.push(visible ? ElementState.VISIBLE : ElementState.HIDDEN);
-    const disabledProp = (el instanceof HTMLButtonElement ||
-        el instanceof HTMLInputElement ||
-        el instanceof HTMLSelectElement ||
-        el instanceof HTMLTextAreaElement) &&
-        el.disabled;
+    const disabledProp = (isButton(el) || isInput(el) || isSelect(el) || isTextArea(el)) && el.disabled;
     const disabled = disabledProp || ariaBool(el, 'aria-disabled') === true;
     states.push(disabled ? ElementState.DISABLED : ElementState.ENABLED);
-    const checkedProp = el instanceof HTMLInputElement && (el.type === 'checkbox' || el.type === 'radio') && el.checked;
+    const checkedProp = isInput(el) && (el.type === 'checkbox' || el.type === 'radio') && el.checked;
     if (checkedProp || ariaBool(el, 'aria-checked') === true)
         states.push(ElementState.CHECKED);
     if (ariaBool(el, 'aria-expanded') === true)
@@ -186,9 +221,7 @@ export function getStates(el, visible = isVisible(el)) {
  * flow recorder's fill-value redaction, so recorded flows never persist typed passwords/OTPs/keys.
  */
 export function isSensitiveField(el) {
-    if (!(el instanceof HTMLInputElement) &&
-        !(el instanceof HTMLTextAreaElement) &&
-        !(el instanceof HTMLSelectElement)) {
+    if (!isInput(el) && !isTextArea(el) && !isSelect(el)) {
         return false;
     }
     const autocomplete = el.getAttribute('autocomplete') ?? '';
@@ -199,14 +232,12 @@ export function isSensitiveField(el) {
         el.getAttribute('aria-label') ?? '',
     ];
     const sensitiveAutocomplete = /current-password|new-password|cc-number|cc-csc|one-time-code/i.test(autocomplete);
-    return ((el instanceof HTMLInputElement && el.type.toLowerCase() === 'password') ||
+    return ((isInput(el) && el.type.toLowerCase() === 'password') ||
         sensitiveAutocomplete ||
         identifiers.some(isSensitiveKey));
 }
 export function getValue(el) {
-    if (el instanceof HTMLInputElement ||
-        el instanceof HTMLTextAreaElement ||
-        el instanceof HTMLSelectElement) {
+    if (isInput(el) || isTextArea(el) || isSelect(el)) {
         if (isSensitiveField(el))
             return REDACTED_VALUE;
         return el.value;
@@ -218,7 +249,7 @@ export function getValue(el) {
 function selfHidden(el) {
     if (el.getAttribute('aria-hidden') === 'true')
         return true;
-    if (el instanceof HTMLElement && el.hidden)
+    if (isHtmlElement(el) && el.hidden)
         return true;
     const view = el.ownerDocument.defaultView;
     if (view !== null) {
@@ -296,4 +327,3 @@ export function describe(el, memo) {
     }
     return base;
 }
-//# sourceMappingURL=a11y.js.map

package/dist/dom/auto-anchor.d.ts

@@ -63,4 +63,3 @@ interface SynthesizedAnchor {
  */
 export declare function synthesizeAnchor(input: AnchorInput): SynthesizedAnchor;
 export {};
-//# sourceMappingURL=auto-anchor.d.ts.map

package/dist/dom/auto-anchor.js

@@ -72,4 +72,3 @@ export function synthesizeAnchor(input) {
     // Last resort: position only — addressable but never trusted.
     return { strategy: AnchorStrategy.POSITION, value: `el#${input.nth ?? 0}`, stable: false };
 }
-//# sourceMappingURL=auto-anchor.js.map

package/dist/dom/blind-spots.d.ts

@@ -11,4 +11,3 @@ export declare function classifyCrossOriginFrames(frames: ReadonlyArray<{
 }>): number;
 /** Probe the live document: count iframes whose document is unreachable (cross-origin). */
 export declare function countCrossOriginFrames(): number;
-//# sourceMappingURL=blind-spots.d.ts.map

package/dist/dom/blind-spots.js

@@ -27,4 +27,3 @@ export function countCrossOriginFrames() {
     }
     return classifyCrossOriginFrames(frames);
 }
-//# sourceMappingURL=blind-spots.js.map

package/dist/dom/chart.d.ts

@@ -90,4 +90,3 @@ export declare function canvasChartData(canvas: Element, globals: {
         } | undefined;
     };
 }): CanvasChartData | null;
-//# sourceMappingURL=chart.d.ts.map

package/dist/dom/chart.js

@@ -116,4 +116,3 @@ export function canvasChartData(canvas, globals) {
     }
     return null;
 }
-//# sourceMappingURL=chart.js.map

package/dist/dom/desktop-capture.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Desktop screenshots, asked of the runtime that owns the window.
+ *
+ * A browser tab is captured through CDP. A desktop webview has no CDP endpoint, so the pixels have
+ * to come from the shell — and the shell is the only party that can produce them CORRECTLY.
+ *
+ * Capturing a screen *region* instead was tried and rejected: it photographs the glass, so an app
+ * window sitting behind the editor yields a picture of the editor, saved as a visual baseline that a
+ * later diff would trust. A screenshot tool that can silently return another window's pixels is
+ * worse than one that returns nothing — it manufactures exactly the false green Reticle exists to
+ * eliminate. Electron's `webContents.capturePage()` reads the window's own backing store instead:
+ * correct while occluded, correct while backgrounded, and needing no screen-recording permission.
+ *
+ * Both desktop runtimes can do this, each through its own shell API — `webContents.capturePage()` on
+ * Electron, and on Tauri the platform's own webview snapshot (`WKWebView.takeSnapshot`, WebView2
+ * `CapturePreview`, or WebKitGTK's snapshot). None of them reads the screen, so all stay correct with
+ * the window occluded, hidden, or running headless with nothing on screen at all.
+ *
+ * The app opts in with one line in its main process (`@reticlehq/electron/main`) or one Rust command
+ * (`reticle-tauri`). Absent that, this returns `{ ok: false }` and the tool reports no-provider
+ * rather than guessing.
+ */
+export interface CaptureResult {
+    ok: boolean;
+    /**
+     * Filesystem path of the captured PNG, written by the desktop shell.
+     *
+     * A path, not the image bytes: the SDK's transport sanitizer caps every string at 64KB, so a
+     * base64 PNG came back SILENTLY TRUNCATED and was saved as a "successful" screenshot that no
+     * decoder could read. The daemon and the app always share a machine here (the bridge is loopback),
+     * so handing over a path keeps the image off the event wire entirely.
+     */
+    path?: string;
+    reason?: string;
+}
+export declare function captureDesktopWindow(fullPage?: boolean): Promise<CaptureResult>;

package/dist/dom/desktop-capture.js

@@ -0,0 +1,113 @@
+/**
+ * Desktop screenshots, asked of the runtime that owns the window.
+ *
+ * A browser tab is captured through CDP. A desktop webview has no CDP endpoint, so the pixels have
+ * to come from the shell — and the shell is the only party that can produce them CORRECTLY.
+ *
+ * Capturing a screen *region* instead was tried and rejected: it photographs the glass, so an app
+ * window sitting behind the editor yields a picture of the editor, saved as a visual baseline that a
+ * later diff would trust. A screenshot tool that can silently return another window's pixels is
+ * worse than one that returns nothing — it manufactures exactly the false green Reticle exists to
+ * eliminate. Electron's `webContents.capturePage()` reads the window's own backing store instead:
+ * correct while occluded, correct while backgrounded, and needing no screen-recording permission.
+ *
+ * Both desktop runtimes can do this, each through its own shell API — `webContents.capturePage()` on
+ * Electron, and on Tauri the platform's own webview snapshot (`WKWebView.takeSnapshot`, WebView2
+ * `CapturePreview`, or WebKitGTK's snapshot). None of them reads the screen, so all stay correct with
+ * the window occluded, hidden, or running headless with nothing on screen at all.
+ *
+ * The app opts in with one line in its main process (`@reticlehq/electron/main`) or one Rust command
+ * (`reticle-tauri`). Absent that, this returns `{ ok: false }` and the tool reports no-provider
+ * rather than guessing.
+ */
+import { RETICLE_IPC_GLOBAL, RETICLE_TAURI_CAPTURE_COMMAND, VisualReason } from '@reticlehq/core';
+import { nativeFrame } from '../timers/native-timers.js';
+import { RETICLE_OVERLAY } from './dom-ignore.js';
+/**
+ * What a shell returns when it can photograph the viewport but not the whole scroll height.
+ *
+ * Only WebKitGTK can render a full document offscreen; `capturePage()` and `takeSnapshot` both give
+ * what is composited. Downgrading silently would be the worst option available: the caller asked for
+ * the content below the fold, would get an image without it, and would bank it as a baseline that a
+ * later diff reports as matching. So the shells say so, and the tool reports the reason.
+ */
+const FULL_PAGE_UNSUPPORTED_MARKER = VisualReason.FULL_PAGE_UNSUPPORTED;
+const TAURI_INTERNALS_GLOBAL = '__TAURI_INTERNALS__';
+/**
+ * Tauri's capture path, used when no preload-installed channel exists.
+ *
+ * Electron can install `RETICLE_IPC_GLOBAL` from its preload, which runs before app code. Tauri has
+ * no preload stage at all, so requiring the same global would mean every Tauri app hand-writing a
+ * frontend shim — a setup step that silently yields "no screenshots" when forgotten. Invoking the
+ * command directly removes the JavaScript side entirely: the app registers one Rust command and the
+ * SDK finds it. Absent that command the invoke rejects, and this reports no-provider like any other.
+ */
+function tauriCapture() {
+    const internals = window[TAURI_INTERNALS_GLOBAL];
+    if (typeof internals?.invoke !== 'function')
+        return undefined;
+    const invoke = internals.invoke.bind(internals);
+    return async (fullPage) => {
+        const path = await invoke(RETICLE_TAURI_CAPTURE_COMMAND, { fullPage: fullPage === true });
+        return typeof path === 'string' ? path : null;
+    };
+}
+/**
+ * Take Reticle's own UI out of the shot, then put it back.
+ *
+ * The shell photographs the composited window, so anything Reticle mounted is IN the picture — and
+ * the presenter panel is the worst possible thing to bank into a visual baseline, because it renders
+ * live session state: an event tally, a log tail, a run badge. A baseline captured with it is a
+ * baseline of Reticle's own UI as much as the app's, and the next `reticle_visual_diff` reports a
+ * change that belongs entirely to the observer. That is measuring the instrument.
+ *
+ * Two frames, not one: the first lets the style change apply, the second lets the compositor present
+ * it — capture before that and the shell photographs the pre-hide window anyway. Both are BOUNDED
+ * frames, which is load-bearing rather than defensive: a headless Tauri window is hidden, and a
+ * hidden webview never fires `requestAnimationFrame` at all, so a raw double-rAF here deadlocked
+ * every capture until the command timed out at 8s. Restoration runs in a `finally`, so a capture
+ * that throws still leaves the panel on screen for the human watching.
+ */
+async function withReticleUiHidden(capture) {
+    // The SAME selector the snapshot layer already uses to keep Reticle's own DOM out of what the
+    // agent reads — the presenter panel, the cursor, the glow, and the annotator's "flag a bug"
+    // button. One definition: a root that leaked into snapshots once would otherwise leak into
+    // baselines the second time someone added one.
+    const roots = [...document.querySelectorAll(RETICLE_OVERLAY)];
+    const previous = roots.map((el) => el.style.visibility);
+    // `visibility`, not `display`: it keeps the element's box, so hiding cannot reflow the app
+    // underneath and change the very layout the screenshot is meant to record.
+    for (const el of roots)
+        el.style.visibility = 'hidden';
+    try {
+        if (roots.length > 0) {
+            await nativeFrame();
+            await nativeFrame();
+        }
+        return await capture();
+    }
+    finally {
+        roots.forEach((el, i) => {
+            el.style.visibility = previous[i] ?? '';
+        });
+    }
+}
+export async function captureDesktopWindow(fullPage = false) {
+    const channel = window[RETICLE_IPC_GLOBAL];
+    const capture = typeof channel?.capture === 'function' ? channel.capture : tauriCapture();
+    if (capture === undefined) {
+        return { ok: false, reason: 'no desktop capture helper installed' };
+    }
+    try {
+        const path = await withReticleUiHidden(() => capture(fullPage));
+        return typeof path === 'string' && path.length > 0
+            ? { ok: true, path }
+            : { ok: false, reason: 'capture returned no image' };
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return reason.includes(FULL_PAGE_UNSUPPORTED_MARKER)
+            ? { ok: false, reason: FULL_PAGE_UNSUPPORTED_MARKER }
+            : { ok: false, reason };
+    }
+}

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

@@ -1,3 +1,10 @@
+/**
+ * Selectors for Reticle's own presenter overlay (cursor, HUD, glow) + the annotator's "flag a bug"
+ * UI (`data-reticle-mark`) — never observed/snapshotted. The annotator mounts by DEFAULT with the
+ * presenter, so omitting its selector here leaked a phantom `<button>Flag a bug</button>` into every
+ * snapshot and streamed its highlight-box mutations/transitions as if the APP had rendered them.
+ */
+export declare const RETICLE_OVERLAY = "[data-reticle-overlay],[data-reticle-cursor],[data-reticle-hud],[data-reticle-glow],[data-reticle-mark]";
 /** Let the host app add selectors to exclude from snapshots (e.g. its own dev widgets). */
 export declare function setIgnoreSelectors(selectors: string[]): void;
 /** True if the element is part of Reticle's own presenter overlay. */
@@ -6,4 +13,3 @@ export declare function isReticleOverlay(el: Element): boolean;
 export declare function isReticleUi(node: Element | null): boolean;
 /** True if the element should be excluded from snapshots/queries (Reticle overlay or dev overlay). */
 export declare function isIgnored(el: Element): boolean;
-//# sourceMappingURL=dom-ignore.d.ts.map

package/dist/dom/dom-ignore.js

@@ -4,7 +4,7 @@
  * presenter, so omitting its selector here leaked a phantom `<button>Flag a bug</button>` into every
  * snapshot and streamed its highlight-box mutations/transitions as if the APP had rendered them.
  */
-const RETICLE_OVERLAY = '[data-reticle-overlay],[data-reticle-cursor],[data-reticle-hud],[data-reticle-glow],[data-reticle-mark]';
+export const RETICLE_OVERLAY = '[data-reticle-overlay],[data-reticle-cursor],[data-reticle-hud],[data-reticle-glow],[data-reticle-mark]';
 /** Known third-party dev overlays to keep out of snapshots (Agentation, Next dev UI). */
 const DEV_OVERLAYS = '[data-agentation],#__next-build-watcher,nextjs-portal,[data-nextjs-dialog],[data-nextjs-toast]';
 let extraIgnore = '';
@@ -33,4 +33,3 @@ export function isIgnored(el) {
         : `${RETICLE_OVERLAY},${DEV_OVERLAYS}`;
     return el.closest(sel) !== null;
 }
-//# sourceMappingURL=dom-ignore.js.map

package/dist/dom/occlusion.d.ts

@@ -6,4 +6,3 @@
  * we never false-positive an occlusion. Reticle's own HUD is never treated as an occluder.
  */
 export declare function hitTestOccluder(el: Element, rect: DOMRect): Element | null;
-//# sourceMappingURL=occlusion.d.ts.map

package/dist/dom/occlusion.js

@@ -18,4 +18,3 @@ export function hitTestOccluder(el, rect) {
     const lands = top === el || el.contains(top) || top.contains(el);
     return lands ? null : top;
 }
-//# sourceMappingURL=occlusion.js.map

package/dist/dom/query.d.ts

@@ -16,4 +16,3 @@ export declare function matchQuery(query: ElementQuery, state?: ElementState, li
  * do — silently put the server back to counting survivors and calling that the answer.
  */
 export declare function runQuery(query: ElementQuery, limit?: number): QueryResult;
-//# sourceMappingURL=query.d.ts.map

package/dist/dom/query.js

@@ -1,6 +1,9 @@
 import { queryAllByRole, queryAllByText, queryAllByLabelText, queryAllByPlaceholderText, queryAllByTestId, queryAllByAltText, } from '@testing-library/dom';
 import { DATA_RETICLE_SOURCE_ATTR, ElementState, QueryBy, REDACTED_VALUE, TRANSPORT_LIMITS, } from '@reticlehq/core';
+import { isFrame, isHtmlElement } from './realm.js';
+import { capturedRootOf } from './shadow-registry.js';
 import { describe, getStates, isVisible } from './a11y.js';
+import { isIgnored } from './dom-ignore.js';
 import { isSensitiveKey } from '../security/serialization.js';
 import { getCapabilities } from '../registry/capabilities.js';
 import { identifyComponent } from '../registry/adapters.js';
@@ -22,11 +25,11 @@ function resolveContainer(scope) {
     if (scope === undefined)
         return { container: document.body, scopeMissing: false };
     const byRef = refs.resolve(scope);
-    if (byRef instanceof HTMLElement)
+    if (isHtmlElement(byRef))
         return { container: byRef, scopeMissing: false };
     try {
         const found = document.querySelector(scope);
-        if (found instanceof HTMLElement)
+        if (isHtmlElement(found))
             return { container: found, scopeMissing: false };
     }
     catch {
@@ -138,18 +141,56 @@ function findIn(container, query) {
  * A closed root is deliberately unreachable — `element.shadowRoot` is null by design, and the SDK
  * reports that as a blind spot rather than pretending to see through it.
  */
-function openShadowRootsUnder(root) {
+/**
+ * A same-origin `<iframe>`'s body, or null when the document is unreachable.
+ *
+ * Cross-origin access THROWS in some engines and yields null in others, so both are handled — and
+ * both mean the same thing here: not ours to read. That case is not a silent skip, it is reported
+ * separately as a declared blind spot.
+ */
+function readableFrameBody(frame) {
+    try {
+        return frame.contentDocument?.body ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** How deep to follow frames-inside-frames before giving up. Real consoles nest one, maybe two. */
+const FRAME_DEPTH_MAX = 3;
+/**
+ * Every root beneath the scope that the page can read but `querySelectorAll` will not reach:
+ * open shadow roots, and the documents of SAME-ORIGIN iframes.
+ *
+ * The iframe half was measured missing: a same-origin frame whose text the page could read straight
+ * off `contentDocument` returned zero matches from `query`, and coverage said nothing about it — the
+ * worst combination, an absent-element answer for content that is right there. Cross-origin frames
+ * are a genuinely different case and stay unread; they are declared instead.
+ */
+function embeddedRootsUnder(root) {
     const found = [];
-    const walk = (node) => {
+    const walk = (node, depth) => {
         for (const el of node.querySelectorAll('*')) {
-            const shadow = el.shadowRoot;
+            const shadow = el.shadowRoot ?? capturedRootOf(el);
             if (shadow !== null) {
+                // A ShadowRoot is a DocumentFragment; the Testing-Library queries accept any HTMLElement-like
+                // container, and every call site only reads from it.
                 found.push(shadow);
-                walk(shadow); // nested web components
+                walk(shadow, depth); // nested web components
+                continue;
             }
+            if (depth >= FRAME_DEPTH_MAX)
+                continue;
+            if (!isFrame(el))
+                continue;
+            const body = readableFrameBody(el);
+            if (body === null)
+                continue; // cross-origin — declared, not searched
+            found.push(body);
+            walk(body, depth + 1);
         }
     };
-    walk(root);
+    walk(root, 0);
     return found;
 }
 /**
@@ -185,16 +226,22 @@ function findCandidates(query) {
         for (const el of els) {
             if (seen.has(el))
                 continue; // reachable from both host and root — count once
+            // Reticle's OWN UI is not part of the app under test. `snapshot` has always excluded it; query
+            // did not, so the presenter panel and the annotator answered `by: role` like app controls —
+            // measured on a real merchant dashboard, 7 of the 40 buttons an agent could see were ours
+            // ("Pause", "End", "Minimise the panel", "Export", "Flag a bug for the agent"). Two of those
+            // share a NAME with a real control on that page, so an agent resolving "Export" could drive the
+            // observer instead of the app and then reason about the result. Filtered here, at the one
+            // collection point, so every entry path (by role/text/testid, shadow roots, scoped) is covered.
+            if (isIgnored(el))
+                continue;
             seen.add(el);
             out.push(el);
         }
     };
     collect(findIn(container, query));
-    for (const shadow of openShadowRootsUnder(container)) {
-        // A ShadowRoot is a DocumentFragment; the Testing-Library queries accept any HTMLElement-like
-        // container, and every call site below only reads from it.
-        collect(findIn(shadow, query));
-    }
+    for (const embedded of embeddedRootsUnder(container))
+        collect(findIn(embedded, query));
     return { candidates: out, scopeMissing };
 }
 /** Longest attribute value returned; one enormous href must not blow the response budget. */
@@ -351,6 +398,8 @@ function buildEmptyHint(query) {
     const all = container.querySelectorAll(`[${TESTID_ATTR}]`);
     const present = [];
     for (const el of Array.from(all)) {
+        if (isIgnored(el))
+            continue; // the "what IS here" hint must not advertise Reticle's own UI either
         const id = el.getAttribute(TESTID_ATTR);
         if (id !== null && id.length > 0 && !present.includes(id)) {
             present.push(id);
@@ -388,4 +437,3 @@ export function runQuery(query, limit) {
     }
     return { elements: result.elements, count: result.count, ...scopeFields };
 }
-//# sourceMappingURL=query.js.map

package/dist/dom/realm.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Cross-realm type tests.
+ *
+ * `instanceof` compares against ONE realm's constructor. An element inside a same-origin `<iframe>`
+ * lives in that document's realm, so `frameButton instanceof HTMLElement` — evaluated with the top
+ * window's `HTMLElement` — is FALSE for a perfectly ordinary button.
+ *
+ * That is not theoretical. Once `query` learned to descend into same-origin frames, it returned the
+ * frame's button correctly and `act` then rejected the ref with "is not an HTMLElement": found, and
+ * unusable. A find you cannot act on is worse than a miss, because it reads as a product bug in the
+ * app rather than in the tool.
+ *
+ * These resolve the constructor from the NODE's own document instead, so an element is measured
+ * against its own realm. Same-realm nodes behave exactly as `instanceof` did.
+ */
+export declare const isElement: (n: unknown) => n is Element;
+export declare const isImage: (n: unknown) => n is HTMLImageElement;
+export declare const isHtmlElement: (n: unknown) => n is HTMLElement;
+export declare const isInput: (n: unknown) => n is HTMLInputElement;
+export declare const isTextArea: (n: unknown) => n is HTMLTextAreaElement;
+export declare const isSelect: (n: unknown) => n is HTMLSelectElement;
+export declare const isButton: (n: unknown) => n is HTMLButtonElement;
+export declare const isForm: (n: unknown) => n is HTMLFormElement;
+export declare const isFrame: (n: unknown) => n is HTMLIFrameElement;
+/**
+ * The prototype whose native value setter drives `el` — React and friends install their own accessor
+ * on the instance, so a value write has to go through the prototype's. It must come from the
+ * ELEMENT's realm for the same reason as above.
+ */
+export declare function valuePrototypeOf(el: Element): object | undefined;

package/dist/dom/realm.js

@@ -0,0 +1,58 @@
+/**
+ * Cross-realm type tests.
+ *
+ * `instanceof` compares against ONE realm's constructor. An element inside a same-origin `<iframe>`
+ * lives in that document's realm, so `frameButton instanceof HTMLElement` — evaluated with the top
+ * window's `HTMLElement` — is FALSE for a perfectly ordinary button.
+ *
+ * That is not theoretical. Once `query` learned to descend into same-origin frames, it returned the
+ * frame's button correctly and `act` then rejected the ref with "is not an HTMLElement": found, and
+ * unusable. A find you cannot act on is worse than a miss, because it reads as a product bug in the
+ * app rather than in the tool.
+ *
+ * These resolve the constructor from the NODE's own document instead, so an element is measured
+ * against its own realm. Same-realm nodes behave exactly as `instanceof` did.
+ */
+/** The constructor named `name` in the realm that owns `node`, or undefined if there isn't one. */
+function ctorIn(node, name) {
+    if (node === null || typeof node !== 'object')
+        return undefined;
+    // A Document owns itself; every other node reports an ownerDocument.
+    const doc = node.ownerDocument ?? node;
+    const view = doc.defaultView;
+    if (view === null || view === undefined)
+        return undefined;
+    return view[name];
+}
+/**
+ * `node instanceof <name>`, evaluated in the node's own realm.
+ *
+ * Falls back to the ambient constructor when the node has no view — a detached document, or a jsdom
+ * fragment — so behaviour outside a browser is unchanged.
+ */
+function isIn(node, name, ambient) {
+    const ctor = ctorIn(node, name) ?? ambient;
+    return typeof ctor === 'function' && node instanceof ctor;
+}
+export const isElement = (n) => isIn(n, 'Element', typeof Element === 'undefined' ? undefined : Element);
+export const isImage = (n) => isIn(n, 'HTMLImageElement', typeof HTMLImageElement === 'undefined' ? undefined : HTMLImageElement);
+export const isHtmlElement = (n) => isIn(n, 'HTMLElement', typeof HTMLElement === 'undefined' ? undefined : HTMLElement);
+export const isInput = (n) => isIn(n, 'HTMLInputElement', typeof HTMLInputElement === 'undefined' ? undefined : HTMLInputElement);
+export const isTextArea = (n) => isIn(n, 'HTMLTextAreaElement', typeof HTMLTextAreaElement === 'undefined' ? undefined : HTMLTextAreaElement);
+export const isSelect = (n) => isIn(n, 'HTMLSelectElement', typeof HTMLSelectElement === 'undefined' ? undefined : HTMLSelectElement);
+export const isButton = (n) => isIn(n, 'HTMLButtonElement', typeof HTMLButtonElement === 'undefined' ? undefined : HTMLButtonElement);
+export const isForm = (n) => isIn(n, 'HTMLFormElement', typeof HTMLFormElement === 'undefined' ? undefined : HTMLFormElement);
+export const isFrame = (n) => isIn(n, 'HTMLIFrameElement', typeof HTMLIFrameElement === 'undefined' ? undefined : HTMLIFrameElement);
+/**
+ * The prototype whose native value setter drives `el` — React and friends install their own accessor
+ * on the instance, so a value write has to go through the prototype's. It must come from the
+ * ELEMENT's realm for the same reason as above.
+ */
+export function valuePrototypeOf(el) {
+    const name = isTextArea(el) ? 'HTMLTextAreaElement' : 'HTMLInputElement';
+    const ctor = ctorIn(el, name);
+    if (typeof ctor !== 'function')
+        return undefined;
+    const proto = ctor.prototype;
+    return typeof proto === 'object' && proto !== null ? proto : undefined;
+}

package/dist/dom/refs.d.ts

@@ -35,4 +35,3 @@ export declare class RefRegistry {
 }
 /** Process-wide registry shared by snapshot, query, and the action executor. */
 export declare const refs: RefRegistry;
-//# sourceMappingURL=refs.d.ts.map

package/dist/dom/refs.js

@@ -108,4 +108,3 @@ export class RefRegistry {
 }
 /** Process-wide registry shared by snapshot, query, and the action executor. */
 export const refs = new RefRegistry();
-//# sourceMappingURL=refs.js.map