@reticlehq/browser 2.2.1 → 2.3.0

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

@@ -26,4 +26,3 @@ export declare function firePointerNonBubbling(el: Element, type: string, relate
  */
 export declare function dragElement(source: HTMLElement, target: HTMLElement | null, data: unknown): Promise<boolean>;
 export {};
-//# sourceMappingURL=actions-dom.d.ts.map

package/dist/actions/actions-dom.js

@@ -133,4 +133,3 @@ export async function dragElement(source, target, data) {
     }
     return dropPrevented;
 }
-//# sourceMappingURL=actions-dom.js.map

package/dist/actions/actions.d.ts

@@ -51,6 +51,9 @@ interface ActionResult {
      * degraded role one — addressing the element across replays with zero hand-added testids.
      */
     component?: string;
+    /** Role + accessible name — the anchor that identifies an INSTANCE, not a JSX site. */
+    role?: string;
+    name?: string;
     source?: {
         file: string;
         line: number;
@@ -89,4 +92,3 @@ export declare function executeSequence(steps: ActionStep[]): Promise<{
     steps: SequenceStepResult[];
 }>;
 export {};
-//# sourceMappingURL=actions.d.ts.map

package/dist/actions/actions.js

@@ -1,26 +1,10 @@
 import { ActionType, ActionWarning, DANGEROUS_ACTION_CONFIRM_ARG, ElementState, isDangerousActionText, SettleReason, } from '@reticlehq/core';
 import { refs } from '../dom/refs.js';
-import { getAccessibleName, isVisible, getStates } from '../dom/a11y.js';
+import { assertEditable, assertNotRichText, setNativeValue } from './value-input.js';
+import { getAccessibleName, getRole, isVisible, getStates } from '../dom/a11y.js';
 import { elementHasHoverHandlers, identifyComponent } from '../registry/adapters.js';
-import { captureValueSetter } from '../patching/capture-method.js';
+import { isForm, isHtmlElement, isInput, isSelect, isTextArea } from '../dom/realm.js';
 import { nativeSetTimeout, settle } from '../timers/native-timers.js';
-/**
- * Set a value on a controlled input the way React expects (native setter + input event).
- * Returns the `input` event's dispatchEvent result (defaultPrevented of the primary event).
- */
-function setNativeValue(el, value) {
-    const proto = el instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
-    const setter = captureValueSetter(proto);
-    if (setter !== undefined) {
-        setter.call(el, value);
-    }
-    else {
-        el.value = value;
-    }
-    const notPrevented = el.dispatchEvent(new Event('input', { bubbles: true, cancelable: true }));
-    el.dispatchEvent(new Event('change', { bubbles: true }));
-    return !notPrevented;
-}
 function asString(value, fallback = '') {
     return typeof value === 'string' ? value : fallback;
 }
@@ -28,7 +12,7 @@ function requireElement(ref) {
     const el = refs.resolve(ref);
     if (el === null)
         throw new Error(`ref '${ref}' no longer resolves to an element`);
-    if (!(el instanceof HTMLElement))
+    if (!isHtmlElement(el))
         throw new Error(`ref '${ref}' is not an HTMLElement`);
     return el;
 }
@@ -55,6 +39,12 @@ function anchorOf(el) {
         out.component = component;
     if (info?.source !== undefined)
         out.source = info.source;
+    const role = getRole(el);
+    const name = getAccessibleName(el);
+    if (role.length > 0 && name.length > 0) {
+        out.role = role;
+        out.name = name;
+    }
     return out;
 }
 const result = (ref, action, effect, settled, settleReason, anchor, warning) => {
@@ -77,6 +67,10 @@ const result = (ref, action, effect, settled, settleReason, anchor, warning) =>
         base.component = anchor.component;
     if (anchor.source !== undefined)
         base.source = anchor.source;
+    if (anchor.role !== undefined)
+        base.role = anchor.role;
+    if (anchor.name !== undefined)
+        base.name = anchor.name;
     if (warning !== undefined)
         base.warning = warning;
     return base;
@@ -116,7 +110,7 @@ function assertActionAllowed(el, action, args) {
         action === ActionType.SUBMIT ||
         (action === ActionType.PRESS && asString(args['key'], 'Enter') === 'Enter');
     const dragTarget = action === ActionType.DRAG ? refs.resolve(asString(args['toRef'])) : null;
-    const context = dragTarget instanceof HTMLElement
+    const context = isHtmlElement(dragTarget)
         ? `${dangerousActionContext(el)} ${dangerousActionContext(dragTarget)}`
         : dangerousActionContext(el);
     if (canTrigger &&
@@ -133,9 +127,7 @@ function enabledOf(el) {
 }
 /** Current value for inputs/textareas/selects, else undefined. */
 function valueOf(el) {
-    if (el instanceof HTMLInputElement ||
-        el instanceof HTMLTextAreaElement ||
-        el instanceof HTMLSelectElement) {
+    if (isInput(el) || isTextArea(el) || isSelect(el)) {
         return el.value;
     }
     return undefined;
@@ -190,41 +182,69 @@ async function dispatchFor(el, action, args) {
             el.dispatchEvent(new FocusEvent('focusout', { bubbles: true }));
             return false;
         case ActionType.FILL:
-            if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+            if (isInput(el) || isTextArea(el)) {
+                // A MISSING value is a malformed call, not a request to empty the field. `asString` defaults
+                // to '', which made such a fill indistinguishable from `clear`: it wiped what was there,
+                // dispatched a real input event so React committed the empty string to state, and reported
+                // ok:true with nothing flagged. The value is nested (`args:{value}`) at the tool boundary, so
+                // passing it at the top level lands here — measured on bench-app's login form, where
+                // "admin@reticle.dev" was destroyed by a fill that reported success. An explicit '' still
+                // clears, because that is someone asking for it.
+                if (typeof args['value'] !== 'string') {
+                    throw new Error("fill requires a string `value` — pass it nested, as args: { value: '…' }. " +
+                        'To empty a field on purpose use the `clear` action, or fill with an explicit "".');
+                }
+                assertEditable(el, 'fill');
                 el.focus(); // focus first so a later blur commits (onBlur editors)
-                return setNativeValue(el, asString(args['value']));
+                return setNativeValue(el, args['value']);
             }
+            assertNotRichText(el, 'fill');
             throw new Error(`cannot fill a <${el.tagName.toLowerCase()}>`);
         case ActionType.TYPE:
-            if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+            if (isInput(el) || isTextArea(el)) {
+                // Same family as the valueless FILL: a missing `text` appended '' and reported ok:true, so an
+                // agent believed it had typed into a field nothing was written to.
+                if (typeof args['text'] !== 'string') {
+                    throw new Error("type requires a string `text` — pass it nested, as args: { text: '…' }.");
+                }
+                assertEditable(el, 'type');
                 el.focus();
-                return setNativeValue(el, el.value + asString(args['text']));
+                return setNativeValue(el, el.value + args['text']);
             }
+            assertNotRichText(el, 'type into');
             throw new Error(`cannot type into a <${el.tagName.toLowerCase()}>`);
         case ActionType.CLEAR:
-            if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) {
+            if (isInput(el) || isTextArea(el)) {
                 return setNativeValue(el, '');
             }
             // Consistent with TYPE/SELECT/CHECK: clearing a non-field is not a silent success. Throwing
             // surfaces the mismatch instead of reporting ok:true for an action that did nothing.
             throw new Error(`cannot clear a <${el.tagName.toLowerCase()}>`);
         case ActionType.SELECT:
-            if (el instanceof HTMLSelectElement) {
-                el.value = asString(args['value']);
+            if (isSelect(el)) {
+                // A MISSING value assigned '' to the <select>. No option carries that, so the browser sets
+                // selectedIndex to -1 — deselecting everything — from a call that was simply malformed.
+                // (Selecting a value that no option carries is a different case and is deliberately NOT
+                // refused: `actions.effect.test.ts` pins it as a detectable no-op, where the reported
+                // valueChanged delta is what tells the agent the option never took.)
+                if (typeof args['value'] !== 'string') {
+                    throw new Error("select requires a string `value` — pass it nested, as args: { value: '…' }.");
+                }
+                el.value = args['value'];
                 el.dispatchEvent(new Event('change', { bubbles: true }));
                 return false; // change is not cancelable.
             }
             throw new Error(`cannot select on a <${el.tagName.toLowerCase()}>`);
         case ActionType.CHECK:
         case ActionType.UNCHECK:
-            if (el instanceof HTMLInputElement) {
+            if (isInput(el)) {
                 el.checked = action === ActionType.CHECK;
                 el.dispatchEvent(new Event('change', { bubbles: true }));
                 return false;
             }
             throw new Error(`cannot (un)check a <${el.tagName.toLowerCase()}>`);
         case ActionType.SUBMIT: {
-            const form = el instanceof HTMLFormElement ? el : el.closest('form');
+            const form = isForm(el) ? el : el.closest('form');
             if (form === null)
                 throw new Error('no form to submit');
             form.requestSubmit();
@@ -240,7 +260,7 @@ async function dispatchFor(el, action, args) {
             el.scrollIntoView();
             return false;
         case ActionType.UPLOAD: {
-            if (!(el instanceof HTMLInputElement) || el.type !== 'file') {
+            if (!isInput(el) || el.type !== 'file') {
                 throw new Error('upload target must be a <input type="file">');
             }
             const file = new File([asString(args['content'], 'reticle test file')], asString(args['name'], 'file.txt'), {
@@ -258,7 +278,7 @@ async function dispatchFor(el, action, args) {
             // asString falls back to '' (never undefined), so the old `!== undefined` was always true and
             // handed '' to refs.resolve. A drag with no target ref is a free drag — resolve nothing.
             const resolved = toRef !== '' ? refs.resolve(toRef) : null;
-            return await dragElement(el, resolved instanceof HTMLElement ? resolved : null, args['data']);
+            return await dragElement(el, isHtmlElement(resolved) ? resolved : null, args['data']);
         }
         default:
             throw new Error(`unknown action '${action}'`);
@@ -363,4 +383,3 @@ export async function executeSequence(steps) {
     }
     return { ok: true, count: steps.length, effects, steps: stepResults };
 }
-//# sourceMappingURL=actions.js.map

package/dist/actions/scroll.d.ts

@@ -16,4 +16,3 @@ interface ScrollResult {
  */
 export declare function scrollContainer(ref: string | undefined, dy: number | undefined, fraction?: number): ScrollResult;
 export {};
-//# sourceMappingURL=scroll.d.ts.map

package/dist/actions/scroll.js

@@ -41,4 +41,3 @@ export function scrollContainer(ref, dy, fraction) {
         atEnd: after + target.clientHeight >= target.scrollHeight - 1,
     };
 }
-//# sourceMappingURL=scroll.js.map

package/dist/actions/value-input.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Writing a value into a field, and the two preconditions that make it honest.
+ *
+ * Lifted out of actions.ts when that file hit the 600-line cap. It is a cohesive unit: every export
+ * here exists so that a value write either lands as a real user's edit would, or is refused with a
+ * reason — never forced through while reporting success.
+ */
+/**
+ * Set a value on a controlled input the way React expects (native setter + input event).
+ * Returns the `input` event's dispatchEvent result (defaultPrevented of the primary event).
+ */
+export declare function setNativeValue(el: HTMLInputElement | HTMLTextAreaElement, value: string): boolean;
+/**
+ * Refuse to write to a field a person could not edit.
+ *
+ * `readonly` and `disabled` block USER input, not scripted assignment, so the prototype value setter
+ * writes straight through both. Measured: filling a readonly input reported `ok:true` and
+ * `valueChanged:true` with nothing in the effect block marking it read-only. That leaves the app in a
+ * state no user could reach, and every conclusion drawn from what follows is about software nobody
+ * can operate — the same reason the click path reports `occluded`, and the same choice Playwright
+ * makes when it refuses to fill a non-editable element.
+ */
+/**
+ * A rich-text target is UNSUPPORTED, not a mistake by the caller.
+ *
+ * Every rich-text editor (TipTap, Quill, ProseMirror, Slate, Lexical) is `[contenteditable]`, and
+ * these actions handle only input/textarea. `cannot fill a <div>` reads as "you picked the wrong
+ * element" and sends the reader hunting for a better selector that does not exist. Support is not
+ * faked: assigning textContent would update the DOM while the editor's own model kept the old value,
+ * so the tool would report success for content the app will never submit.
+ */
+export declare function assertNotRichText(el: HTMLElement, action: string): void;
+export declare function assertEditable(el: HTMLInputElement | HTMLTextAreaElement, action: string): void;

package/dist/actions/value-input.js

@@ -0,0 +1,63 @@
+import { captureValueSetter } from '../patching/capture-method.js';
+import { valuePrototypeOf } from '../dom/realm.js';
+/**
+ * Writing a value into a field, and the two preconditions that make it honest.
+ *
+ * Lifted out of actions.ts when that file hit the 600-line cap. It is a cohesive unit: every export
+ * here exists so that a value write either lands as a real user's edit would, or is refused with a
+ * reason — never forced through while reporting success.
+ */
+/**
+ * Set a value on a controlled input the way React expects (native setter + input event).
+ * Returns the `input` event's dispatchEvent result (defaultPrevented of the primary event).
+ */
+export function setNativeValue(el, value) {
+    // Realm-aware: a controlled input inside a same-origin frame has its own prototype.
+    const proto = valuePrototypeOf(el);
+    const setter = proto === undefined ? undefined : captureValueSetter(proto);
+    if (setter !== undefined) {
+        setter.call(el, value);
+    }
+    else {
+        el.value = value;
+    }
+    const notPrevented = el.dispatchEvent(new Event('input', { bubbles: true, cancelable: true }));
+    el.dispatchEvent(new Event('change', { bubbles: true }));
+    return !notPrevented;
+}
+/**
+ * Refuse to write to a field a person could not edit.
+ *
+ * `readonly` and `disabled` block USER input, not scripted assignment, so the prototype value setter
+ * writes straight through both. Measured: filling a readonly input reported `ok:true` and
+ * `valueChanged:true` with nothing in the effect block marking it read-only. That leaves the app in a
+ * state no user could reach, and every conclusion drawn from what follows is about software nobody
+ * can operate — the same reason the click path reports `occluded`, and the same choice Playwright
+ * makes when it refuses to fill a non-editable element.
+ */
+/**
+ * A rich-text target is UNSUPPORTED, not a mistake by the caller.
+ *
+ * Every rich-text editor (TipTap, Quill, ProseMirror, Slate, Lexical) is `[contenteditable]`, and
+ * these actions handle only input/textarea. `cannot fill a <div>` reads as "you picked the wrong
+ * element" and sends the reader hunting for a better selector that does not exist. Support is not
+ * faked: assigning textContent would update the DOM while the editor's own model kept the old value,
+ * so the tool would report success for content the app will never submit.
+ */
+export function assertNotRichText(el, action) {
+    // The ATTRIBUTE, not `isContentEditable`: jsdom does not implement the property, so a test would
+    // pass against a guard that never fires in the environment the unit suite runs in.
+    const flag = el.getAttribute('contenteditable');
+    if (el.isContentEditable || (flag !== null && flag !== 'false')) {
+        throw new Error(`cannot ${action} a contenteditable element — rich-text editors keep their own document model, ` +
+            'so writing to the DOM here would look right and submit the old content. This surface is not supported yet.');
+    }
+}
+export function assertEditable(el, action) {
+    if (el.disabled) {
+        throw new Error(`cannot ${action} a disabled <${el.tagName.toLowerCase()}> — a user could not edit it, so forcing the value would put the app in a state nobody can reach`);
+    }
+    if (el.readOnly) {
+        throw new Error(`cannot ${action} a readonly <${el.tagName.toLowerCase()}> — a user could not edit it, so forcing the value would put the app in a state nobody can reach`);
+    }
+}

package/dist/commands/commands.d.ts

@@ -4,4 +4,3 @@ export declare const RELOAD_CACHE_BUST_PARAM = "_reticle_reload";
 export declare function resolveNavigationUrl(rawUrl: string, baseUrl: string): string | null;
 /** Map browser command names to handlers. Used by the transport on each COMMAND. */
 export declare function createCommandRegistry(): Map<string, CommandHandler>;
-//# sourceMappingURL=commands.d.ts.map

package/dist/commands/commands.js

@@ -5,8 +5,10 @@ import { executeAction, executeSequence, dispatchWebMcp, } from '../actions/acti
 import { describe } from '../dom/a11y.js';
 import { themeReport } from '../dom/theme.js';
 import { refs } from '../dom/refs.js';
+import { isButton, isInput } from '../dom/realm.js';
 import { hitTestOccluder } from '../dom/occlusion.js';
 import { readStorage } from '../observers/storage.js';
+import { captureDesktopWindow } from '../dom/desktop-capture.js';
 import { identifyComponent, readComponentState } from '../registry/adapters.js';
 import { readStoresWithTruncation, readStoresRaw, storeNames } from '../registry/stores.js';
 import { sanitizeWithReport } from '../security/serialization.js';
@@ -24,6 +26,14 @@ function num(value) {
 function record(value) {
     return typeof value === 'object' && value !== null ? value : {};
 }
+function sourceLocation(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const obj = value;
+    if (typeof obj['file'] !== 'string' || typeof obj['line'] !== 'number')
+        return undefined;
+    return { file: obj['file'], line: obj['line'], column: num(obj['column']) };
+}
 function queryFromArgs(args) {
     return {
         by: str(args['by']),
@@ -35,10 +45,12 @@ function queryFromArgs(args) {
         placeholder: str(args['placeholder']),
         testid: str(args['testid']),
         alt: str(args['alt']),
+        component: str(args['component']),
         scope: str(args['scope']),
         attrs: Array.isArray(args['attrs'])
             ? args['attrs'].filter((a) => typeof a === 'string')
             : undefined,
+        source: sourceLocation(args['source']),
     };
 }
 function inspect(ref) {
@@ -66,12 +78,8 @@ function inspect(ref) {
         ...describe(el),
         tag: el.tagName.toLowerCase(),
         href: el.getAttribute('href') ?? undefined,
-        formAction: el instanceof HTMLButtonElement || el instanceof HTMLInputElement
-            ? (el.form?.getAttribute('action') ?? undefined)
-            : undefined,
-        formText: el instanceof HTMLButtonElement || el instanceof HTMLInputElement
-            ? (el.form?.textContent ?? undefined)
-            : undefined,
+        formAction: isButton(el) || isInput(el) ? (el.form?.getAttribute('action') ?? undefined) : undefined,
+        formText: isButton(el) || isInput(el) ? (el.form?.textContent ?? undefined) : undefined,
         box: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
         // True when another element sits over this one's center point — the click would hit the overlay,
         // not this control (a z-index/overlay bug the DOM tree cannot show).
@@ -213,6 +221,7 @@ export function createCommandRegistry() {
     reg.set(ReticleCommand.STATE_READ, (args) => readState(str(args['ref']), str(args['store']), str(args['path']), num(args['depth'])));
     reg.set(ReticleCommand.STORAGE_READ, (args) => readStorage(str(args['area'])));
     reg.set(ReticleCommand.CAPABILITIES, () => getCapabilities());
+    reg.set(ReticleCommand.CAPTURE, (args) => captureDesktopWindow(args['fullPage'] === true));
     reg.set(ReticleCommand.SCROLL, (args) => {
         const dy = args['dy'];
         const fraction = args['fraction'];
@@ -242,4 +251,3 @@ export function createCommandRegistry() {
     });
     return reg;
 }
-//# sourceMappingURL=commands.js.map

package/dist/dom/a11y.d.ts

@@ -1,7 +1,6 @@
 import { ElementState, type ElementDescriptor } from '@reticlehq/core';
 /** Compute the ARIA role (explicit wins, else implicit from the tag). */
 export declare function getRole(el: Element): string;
-/** Accessible name via a practical subset of the accname algorithm. */
 export declare function getAccessibleName(el: Element): string;
 /**
  * The set of states relevant to assertions. `visible` is an O(depth) forced-style walk; callers that
@@ -28,4 +27,3 @@ export declare function isVisible(el: Element, memo?: Map<Element, boolean>): bo
 /** Build the compact descriptor surfaced to the agent. `memo` (optional) shares the per-call
  * visibility cache with the query's state filter so ancestors aren't re-walked per element. */
 export declare function describe(el: Element, memo?: Map<Element, boolean>): ElementDescriptor;
-//# sourceMappingURL=a11y.d.ts.map

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>;