@reticlehq/browser 2.4.0 → 2.6.0

package/dist/commands/commands.js

@@ -5,7 +5,7 @@ import { executeAction, executeSequence, dispatchWebMcp, } from '../actions/acti
 import { describe } from '../dom/a11y.js';
 import { sourceFor, formatSource } from '../dom/source.js';
 import { themeReport } from '../dom/theme.js';
-import { refs } from '../dom/refs.js';
+import { echoRef, refs } from '../dom/refs.js';
 import { isButton, isInput } from '../dom/realm.js';
 import { hitTestOccluder } from '../dom/occlusion.js';
 import { readStorage } from '../observers/storage.js';
@@ -19,16 +19,16 @@ import { scrollContainer } from '../actions/scroll.js';
 /** Query param appended on a hard reload to bypass the browser cache. */
 export const RELOAD_CACHE_BUST_PARAM = '_reticle_reload';
 function str(value) {
-    return typeof value === 'string' ? value : undefined;
+    return 'string' === typeof value ? value : undefined;
 }
 function num(value) {
-    return typeof value === 'number' ? value : undefined;
+    return 'number' === typeof value ? value : undefined;
 }
 function record(value) {
-    return typeof value === 'object' && value !== null ? value : {};
+    return 'object' === typeof value && value !== null ? value : {};
 }
 function sourceLocation(value) {
-    if (typeof value !== 'object' || value === null)
+    if (typeof value !== 'object' || null === value)
         return undefined;
     const obj = value;
     if (typeof obj['file'] !== 'string' || typeof obj['line'] !== 'number')
@@ -49,15 +49,20 @@ function queryFromArgs(args) {
         component: str(args['component']),
         scope: str(args['scope']),
         attrs: Array.isArray(args['attrs'])
-            ? args['attrs'].filter((a) => typeof a === 'string')
+            ? args['attrs'].filter((a) => 'string' === typeof a)
             : undefined,
         source: sourceLocation(args['source']),
     };
 }
 function inspect(ref) {
     const el = refs.resolve(ref);
-    if (el === null)
-        return { error: `ref '${ref}' no longer resolves` };
+    // THROW, exactly as executeAction does. Returning an error payload made it a SUCCESSFUL command
+    // result, which the server then handed to reticle_inspect's outputSchema (ref/role/name/states/
+    // visible all required) — so the MCP layer answered -32602 Output validation error for the most
+    // ordinary thing that follows a click. The wording matches actions.ts because the server's
+    // recovery table keys off /no longer resolves to an element/ to attach the stale-ref recovery.
+    if (null === el)
+        throw new Error(`ref '${echoRef(ref)}' no longer resolves to an element`);
     const rect = el.getBoundingClientRect();
     const component = identifyComponent(el);
     const view = el.ownerDocument.defaultView;
@@ -104,7 +109,7 @@ function isOccluded(el, rect) {
 }
 /** Narrowing guard: an adapter returned a ComponentStateResult (has a boolean `ok`). */
 function isComponentStateResult(value) {
-    return (typeof value === 'object' && value !== null && 'ok' in value && typeof value.ok === 'boolean');
+    return ('object' === typeof value && value !== null && 'ok' in value && 'boolean' === typeof value.ok);
 }
 const COMPONENT_UNAVAILABLE = {
     ok: false,
@@ -158,7 +163,7 @@ function readState(ref, store, path, depth) {
         result.truncation = truncation;
     if (ref !== undefined && ref.length > 0) {
         const el = refs.resolve(ref);
-        if (el === null) {
+        if (null === el) {
             result.component = COMPONENT_UNAVAILABLE;
         }
         else {
@@ -168,6 +173,19 @@ function readState(ref, store, path, depth) {
     }
     return result;
 }
+/**
+ * Every animation, and WHICH element it drives.
+ *
+ * Reported from the field: a page with nine concurrent animations returned nine indistinguishable
+ * `{playState, currentTime, duration}` rows. `a.effect` was read only for `getTiming()`, never for
+ * its `target` — so the tool advertised "targets/timing" and shipped timing alone. A list you cannot
+ * index is not a list, and the question this tool exists to answer is "is THAT thing still
+ * animating".
+ *
+ * `describe()` is reused rather than inventing a target shape: it is what `reticle_query` returns,
+ * so the descriptor carries a `ref` the agent can pass straight to `reticle_act` — a target you
+ * cannot act on would be half an answer.
+ */
 function listAnimations() {
     const doc = document;
     if (typeof doc.getAnimations !== 'function')
@@ -175,20 +193,25 @@ function listAnimations() {
     const animations = doc.getAnimations().map((a) => {
         const effect = a.effect;
         const timing = effect?.getTiming();
+        // A KeyframeEffect's target is legitimately nullable, and only KeyframeEffect has one at all.
+        // `null` is reported explicitly: omitting the key would make "this animation has no element"
+        // indistinguishable from the bug above, which is the distinction the fix exists to draw.
+        const target = effect?.target ?? null;
         return {
             playState: a.playState,
             currentTime: a.currentTime,
             duration: timing?.duration,
+            target: null === target ? null : describe(target),
         };
     });
     return { animations };
 }
 export function resolveNavigationUrl(rawUrl, baseUrl) {
-    if (rawUrl.length === 0 || rawUrl.length > TRANSPORT_LIMITS.MAX_URL_LENGTH)
+    if (0 === rawUrl.length || rawUrl.length > TRANSPORT_LIMITS.MAX_URL_LENGTH)
         return null;
     try {
         const url = new URL(rawUrl, baseUrl);
-        return url.protocol === 'http:' || url.protocol === 'https:' ? url.toString() : null;
+        return 'http:' === url.protocol || 'https:' === url.protocol ? url.toString() : null;
     }
     catch {
         return null;
@@ -203,14 +226,14 @@ export function createCommandRegistry() {
     }));
     reg.set(ReticleCommand.QUERY, (args) => {
         const limit = args['limit'];
-        return runQuery(queryFromArgs(args), typeof limit === 'number' ? limit : undefined);
+        return runQuery(queryFromArgs(args), 'number' === typeof limit ? limit : undefined);
     });
     reg.set(ReticleCommand.MATCH, (args) => matchQuery(ElementQuerySchema.parse(record(args['query'])), str(args['state'])));
     reg.set(ReticleCommand.ACT, (args) => {
         const action = str(args['action']) ?? '';
         if (action === ActionType.WEBMCP) {
             const inner = record(args['args']);
-            return dispatchWebMcp(str(inner['tool']) ?? '', record(inner['params']), inner[DANGEROUS_ACTION_CONFIRM_ARG] === true);
+            return dispatchWebMcp(str(inner['tool']) ?? '', record(inner['params']), true === inner[DANGEROUS_ACTION_CONFIRM_ARG]);
         }
         return executeAction(str(args['ref']) ?? '', action, record(args['args']));
     });
@@ -218,14 +241,14 @@ export function createCommandRegistry() {
     reg.set(ReticleCommand.INSPECT, (args) => inspect(str(args['ref']) ?? ''));
     reg.set(ReticleCommand.ANIMATIONS, () => listAnimations());
     reg.set(ReticleCommand.CLOCK, (args) => {
-        if (args['reset'] === true) {
+        if (true === args['reset']) {
             resetClock();
         }
         else {
-            if (args['freeze'] === true)
+            if (true === args['freeze'])
                 freezeClock();
             const adv = args['advanceMs'];
-            if (typeof adv === 'number')
+            if ('number' === typeof adv)
                 advanceClock(adv);
         }
         return { frozen: isClockFrozen() };
@@ -233,24 +256,24 @@ 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.CAPTURE, (args) => captureDesktopWindow(true === args['fullPage']));
     reg.set(ReticleCommand.SCROLL, (args) => {
         const dy = args['dy'];
         const fraction = args['fraction'];
-        return scrollContainer(str(args['ref']), typeof dy === 'number' ? dy : undefined, typeof fraction === 'number' ? fraction : undefined);
+        return scrollContainer(str(args['ref']), 'number' === typeof dy ? dy : undefined, 'number' === typeof fraction ? fraction : undefined);
     });
     reg.set(ReticleCommand.NAVIGATE, (args) => {
         const rawUrl = str(args['url']);
-        if (rawUrl === undefined || rawUrl.length === 0)
+        if (rawUrl === undefined || 0 === rawUrl.length)
             return { ok: false, reason: 'url required' };
         const url = resolveNavigationUrl(rawUrl, window.location.href);
-        if (url === null)
+        if (null === url)
             return { ok: false, reason: 'only http(s) navigation is allowed' };
         window.location.assign(url);
         return { ok: true, url };
     });
     reg.set(ReticleCommand.REFRESH, (args) => {
-        if (args['hard'] === true) {
+        if (true === args['hard']) {
             // Hard reload: navigate to self with a cache-busting param then replace history.
             const url = new URL(window.location.href);
             url.searchParams.set(RELOAD_CACHE_BUST_PARAM, String(Date.now()));

package/dist/connect-options.d.ts

@@ -45,6 +45,12 @@ export interface ReticleConnectOptions {
      * and the TypeScript cast that needed shipped into a `.jsx` file and broke the build.
      */
     root?: string;
+    /**
+     * The SDK's own package version, so a version-skewed pair against the daemon can name itself
+     * rather than surfacing as a bare `-32000`. Build plugins supply it automatically; pass it here
+     * only for a hand-wired connect that has no plugin.
+     */
+    sdkVersion?: string;
     /** Presenter mode: glow border, animated cursor, click/hover effects, narration HUD. */
     present?: boolean;
     /** Per-action pacing (ms) in presenter mode so a human can follow. Default 450. */

package/dist/dom/a11y.js

@@ -45,15 +45,15 @@ function inputRole(input) {
     const type = input.type.toLowerCase();
     if (INPUT_TEXT_TYPES.has(type))
         return 'textbox';
-    if (type === 'checkbox')
+    if ('checkbox' === type)
         return 'checkbox';
-    if (type === 'radio')
+    if ('radio' === type)
         return 'radio';
-    if (type === 'range')
+    if ('range' === type)
         return 'slider';
-    if (type === 'number')
+    if ('number' === type)
         return 'spinbutton';
-    if (type === 'submit' || type === 'button' || type === 'reset')
+    if ('submit' === type || 'button' === type || 'reset' === type)
         return 'button';
     return 'textbox';
 }
@@ -115,7 +115,7 @@ function collapse(text) {
 }
 function labelledByText(el) {
     const ids = el.getAttribute('aria-labelledby');
-    if (ids === null)
+    if (null === ids)
         return null;
     const parts = [];
     for (const id of ids.split(/\s+/)) {
@@ -144,7 +144,7 @@ function textWithoutHidden(node) {
     if (node.nodeType !== Node.ELEMENT_NODE)
         return '';
     const el = node;
-    if (el.getAttribute('aria-hidden') === 'true')
+    if ('true' === el.getAttribute('aria-hidden'))
         return '';
     let out = '';
     for (const child of el.childNodes)
@@ -191,9 +191,9 @@ export function getAccessibleName(el) {
 }
 function ariaBool(el, attr) {
     const value = el.getAttribute(attr);
-    if (value === null)
+    if (null === value)
         return undefined;
-    return value === 'true';
+    return 'true' === value;
 }
 /**
  * The set of states relevant to assertions. `visible` is an O(depth) forced-style walk; callers that
@@ -203,12 +203,12 @@ export function getStates(el, visible = isVisible(el)) {
     const states = [ElementState.PRESENT];
     states.push(visible ? ElementState.VISIBLE : ElementState.HIDDEN);
     const disabledProp = (isButton(el) || isInput(el) || isSelect(el) || isTextArea(el)) && el.disabled;
-    const disabled = disabledProp || ariaBool(el, 'aria-disabled') === true;
+    const disabled = disabledProp || true === ariaBool(el, 'aria-disabled');
     states.push(disabled ? ElementState.DISABLED : ElementState.ENABLED);
-    const checkedProp = isInput(el) && (el.type === 'checkbox' || el.type === 'radio') && el.checked;
-    if (checkedProp || ariaBool(el, 'aria-checked') === true)
+    const checkedProp = isInput(el) && ('checkbox' === el.type || 'radio' === el.type) && el.checked;
+    if (checkedProp || true === ariaBool(el, 'aria-checked'))
         states.push(ElementState.CHECKED);
-    if (ariaBool(el, 'aria-expanded') === true)
+    if (true === ariaBool(el, 'aria-expanded'))
         states.push(ElementState.EXPANDED);
     if (el.ownerDocument.activeElement === el)
         states.push(ElementState.FOCUSED);
@@ -232,7 +232,7 @@ 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 ((isInput(el) && el.type.toLowerCase() === 'password') ||
+    return ((isInput(el) && 'password' === el.type.toLowerCase()) ||
         sensitiveAutocomplete ||
         identifiers.some(isSensitiveKey));
 }
@@ -247,19 +247,19 @@ export function getValue(el) {
 }
 /** Whether the element's OWN box hides it — one forced-style resolution, no ancestor walk. */
 function selfHidden(el) {
-    if (el.getAttribute('aria-hidden') === 'true')
+    if ('true' === el.getAttribute('aria-hidden'))
         return true;
     if (isHtmlElement(el) && el.hidden)
         return true;
     const view = el.ownerDocument.defaultView;
     if (view !== null) {
         const style = view.getComputedStyle(el);
-        if (style.display === 'none' ||
-            style.visibility === 'hidden' ||
-            style.visibility === 'collapse') {
+        if ('none' === style.display ||
+            'hidden' === style.visibility ||
+            'collapse' === style.visibility) {
             return true;
         }
-        if (Number.parseFloat(style.opacity || '1') === 0)
+        if (0 === Number.parseFloat(style.opacity || '1'))
             return true;
     }
     return false;
@@ -282,7 +282,7 @@ export function isVisible(el, memo) {
     // Each cached boolean already folds in that node's own aria-hidden/[hidden]/display/visibility/opacity,
     // so inherited visibility composes by AND up the chain and a sibling short-circuits at the first
     // cached ancestor.
-    const result = !selfHidden(el) && (parent === null || isVisible(parent, memo));
+    const result = !selfHidden(el) && (null === parent || isVisible(parent, memo));
     if (memo !== undefined)
         memo.set(el, result);
     return result;

package/dist/dom/auto-anchor.js

@@ -32,7 +32,7 @@ export const AnchorStrategy = {
     POSITION: 'position',
 };
 function nonEmpty(s) {
-    return typeof s === 'string' && s.length > 0;
+    return 'string' === typeof s && s.length > 0;
 }
 /** Source as a compact `file:line` suffix; basename only to stay terse and path-independent. */
 function sourceTag(source) {

package/dist/dom/blind-spots.js

@@ -10,7 +10,7 @@ export function classifyCrossOriginFrames(frames) {
 }
 /** Probe the live document: count iframes whose document is unreachable (cross-origin). */
 export function countCrossOriginFrames() {
-    if (typeof document === 'undefined')
+    if ('undefined' === typeof document)
         return 0;
     const frames = [];
     for (const frame of document.querySelectorAll('iframe')) {

package/dist/dom/chart.js

@@ -54,12 +54,12 @@ export function hasNonFiniteCoordinate(value) {
 /** True when the geometry encloses no area — no coordinates, or every coordinate pair identical. */
 export function isDegenerate(value) {
     const nums = geometryNumbers(value).filter((n) => Number.isFinite(n));
-    if (nums.length === 0)
+    if (0 === nums.length)
         return true;
     // A polyline of one repeated point draws nothing. Compare pairs, not raw numbers, so a legitimately
     // flat line (varying x, constant y) is NOT flagged — that is a real chart of constant data.
-    const xs = nums.filter((_, i) => i % 2 === 0);
-    const ys = nums.filter((_, i) => i % 2 === 1);
+    const xs = nums.filter((_, i) => 0 === i % 2);
+    const ys = nums.filter((_, i) => 1 === i % 2);
     const allSame = (arr) => arr.every((v) => v === arr[0]);
     return xs.length > 1 && allSame(xs) && allSame(ys);
 }
@@ -74,14 +74,14 @@ export function inspectChart(root) {
         for (const el of Array.from(root.querySelectorAll(tag))) {
             for (const attr of GEOMETRY_ATTRS) {
                 const value = el.getAttribute(attr);
-                if (value === null)
+                if (null === value)
                     continue;
                 examined += 1;
                 const sample = value.length > SAMPLE_MAX ? `${value.slice(0, SAMPLE_MAX)}…` : value;
                 if (hasNonFiniteCoordinate(value)) {
                     findings.push({ kind: 'non-finite-coordinates', tag, attr, sample });
                 }
-                else if (value.trim().length === 0) {
+                else if (0 === value.trim().length) {
                     findings.push({ kind: 'empty-geometry', tag, attr, sample });
                 }
                 else if (isDegenerate(value)) {

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

@@ -20,7 +20,7 @@
  * (`reticle-tauri`). Absent that, this returns `{ ok: false }` and the tool reports no-provider
  * rather than guessing.
  */
-export interface CaptureResult {
+interface CaptureResult {
     ok: boolean;
     /**
      * Filesystem path of the captured PNG, written by the desktop shell.
@@ -34,3 +34,4 @@ export interface CaptureResult {
     reason?: string;
 }
 export declare function captureDesktopWindow(fullPage?: boolean): Promise<CaptureResult>;
+export {};

package/dist/dom/desktop-capture.js

@@ -48,8 +48,8 @@ function tauriCapture() {
         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;
+        const path = await invoke(RETICLE_TAURI_CAPTURE_COMMAND, { fullPage: true === fullPage });
+        return 'string' === typeof path ? path : null;
     };
 }
 /**
@@ -94,13 +94,13 @@ async function withReticleUiHidden(capture) {
 }
 export async function captureDesktopWindow(fullPage = false) {
     const channel = window[RETICLE_IPC_GLOBAL];
-    const capture = typeof channel?.capture === 'function' ? channel.capture : tauriCapture();
+    const capture = 'function' === typeof channel?.capture ? 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
+        return 'string' === typeof path && path.length > 0
             ? { ok: true, path }
             : { ok: false, reason: 'capture returned no image' };
     }

package/dist/dom/occlusion.js

@@ -7,13 +7,13 @@ import { isReticleUi } from './dom-ignore.js';
  * we never false-positive an occlusion. Reticle's own HUD is never treated as an occluder.
  */
 export function hitTestOccluder(el, rect) {
-    if (rect.width === 0 || rect.height === 0)
+    if (0 === rect.width || 0 === rect.height)
         return null;
     const doc = el.ownerDocument;
     if (typeof doc.elementFromPoint !== 'function')
         return null;
     const top = doc.elementFromPoint(rect.left + rect.width / 2, rect.top + rect.height / 2);
-    if (top === null || isReticleUi(top))
+    if (null === top || isReticleUi(top))
         return null;
     const lands = top === el || el.contains(top) || top.contains(el);
     return lands ? null : top;

package/dist/dom/query.js

@@ -2,7 +2,7 @@ import { queryAllByRole, queryAllByText, queryAllByLabelText, queryAllByPlacehol
 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 { getAccessibleName, getRole, describe, getStates, isVisible } from './a11y.js';
 import { isIgnored } from './dom-ignore.js';
 import { isSensitiveKey } from '../security/serialization.js';
 import { getCapabilities } from '../registry/capabilities.js';
@@ -83,6 +83,41 @@ function findByComponent(container, query) {
     }
     return [];
 }
+/**
+ * Role + name, matched the way Reticle REPORTS them — not only the way Testing Library computes them.
+ *
+ * Two implementations were disagreeing, on both axes, for the same element:
+ *
+ *   <input type="search" placeholder="Search User">
+ *     Reticle getRole            -> "textbox"      TL/dom-accessibility-api -> "searchbox"
+ *     Reticle getAccessibleName  -> "Search User"  TL                       -> "" (no placeholder)
+ *
+ * `reticle_query`, `reticle_snapshot` and every act result report Reticle's values. The matcher used
+ * TL's. So Reticle printed `textbox "Search User"` and then could not find it by that exact
+ * role and name — the same query call reporting an identity it cannot match.
+ *
+ * It surfaced through the flow recorder, which anchors a step to the reported role+name: `flow_save`
+ * graded the flow `asserted` with `degraded: 0`, a clean bill of health, and the step drifted on the
+ * first replay in a different session. The reporter diagnosed it as the replay resolver computing
+ * names differently; it is narrower and worse, because no caller could ever have closed the round
+ * trip.
+ *
+ * The fallback runs ONLY when the spec-accurate query finds nothing, so every name that resolves
+ * today keeps resolving exactly as before and this can never take a match away. Fixed on the
+ * matching side rather than by changing what is reported: dropping `placeholder` would leave an
+ * input whose only label is its placeholder nameless in every snapshot, and renaming the role would
+ * churn every stored anchor — both worse trades than a fallback that runs on the empty path.
+ */
+function queryByRoleAndName(container, role, name) {
+    if (name === undefined)
+        return queryAllByRole(container, role, { hidden: true });
+    const spec = queryAllByRole(container, role, { hidden: true, name });
+    if (spec.length > 0)
+        return spec;
+    const wanted = name.trim();
+    // Reticle's own role AND name: the pair actually printed to the caller.
+    return [...container.querySelectorAll('*')].filter((el) => getRole(el) === role && getAccessibleName(el).trim() === wanted);
+}
 /** Run the appropriate Testing-Library query against ONE root (light DOM or a shadow root). */
 function findIn(container, query) {
     const by = query.by;
@@ -91,7 +126,7 @@ function findIn(container, query) {
     if (by !== undefined && value !== undefined) {
         switch (by) {
             case QueryBy.ROLE:
-                return queryAllByRole(container, value, query.name !== undefined ? { hidden: true, name: query.name } : { hidden: true });
+                return queryByRoleAndName(container, value, query.name);
             case QueryBy.TEXT:
                 return queryAllByText(container, value, { exact: false });
             case QueryBy.LABEL:
@@ -106,7 +141,13 @@ function findIn(container, query) {
                 // value is the component name;.source (if present) still takes precedence inside.
                 return findByComponent(container, { ...query, component: query.component ?? value });
             default:
-                return [];
+                // THROW, never `return []`. An unsupported strategy answering "no matches" is
+                // indistinguishable from the element genuinely being absent, so `by:'css'` — the first thing
+                // anyone arriving from Playwright reaches for — reported a page with a <body> as empty. The
+                // server now rejects unknown strategies at the schema; this is the same guarantee for every
+                // other path in (replay, reticle_run, an internal caller), because a false negative invented
+                // by the tool is the exact failure this product exists to prevent.
+                throw new Error(`unsupported query strategy '${String(by)}' — use one of: ${Object.values(QueryBy).join(', ')}`);
         }
     }
     // Auto-anchor (component / source) — checked before the role/text fields so a query carrying
@@ -114,12 +155,10 @@ function findIn(container, query) {
     if (query.component !== undefined || query.source !== undefined) {
         return findByComponent(container, query);
     }
-    // Structured form (role+name, or any single field).
+    // Structured form (role+name, or any single field). Same round-trip guarantee as the by+value
+    // spelling above — the two forms must not disagree about what is findable.
     if (query.role !== undefined) {
-        const options = query.name !== undefined
-            ? { hidden: true, name: query.name }
-            : { hidden: true };
-        return queryAllByRole(container, query.role, options);
+        return queryByRoleAndName(container, query.role, query.name);
     }
     if (query.text !== undefined)
         return queryAllByText(container, query.text, { exact: false });
@@ -184,7 +223,7 @@ function embeddedRootsUnder(root) {
             if (!isFrame(el))
                 continue;
             const body = readableFrameBody(el);
-            if (body === null)
+            if (null === body)
                 continue; // cross-origin — declared, not searched
             found.push(body);
             walk(body, depth + 1);
@@ -218,7 +257,7 @@ function findCandidates(query) {
     const { container, scopeMissing } = resolveContainer(query.scope);
     // A given-but-missing scope searches NOTHING — never the whole page. The empty result plus the
     // scopeMissing flag is what keeps "gone scope" distinct from "absent element".
-    if (container === null)
+    if (null === container)
         return { candidates: [], scopeMissing: true };
     const seen = new Set();
     const out = [];
@@ -259,7 +298,7 @@ function projectAttrs(el, keys) {
     const out = {};
     for (const key of keys.slice(0, ATTR_KEYS_MAX)) {
         const raw = el.getAttribute(key);
-        if (raw === null)
+        if (null === raw)
             continue;
         out[key] = isSensitiveKey(key) ? REDACTED_VALUE : raw.slice(0, ATTR_VALUE_MAX);
     }
@@ -286,16 +325,15 @@ const MAX_DESCRIBED = TRANSPORT_LIMITS.MAX_COLLECTION_ITEMS;
  * "how many?" stay exact while the answer stays affordable.
  */
 export function matchQuery(query, state, limit = MAX_DESCRIBED) {
-    let elements;
-    let scopeMissing = false;
-    try {
-        const found = findCandidates(query);
-        elements = found.candidates;
-        scopeMissing = found.scopeMissing;
-    }
-    catch {
-        elements = [];
-    }
+    // NO blanket try/catch here. It used to turn ANY exception during candidate-finding into
+    // `elements = []`, which is the same lie as the `default` arm above: a query that could not run
+    // reported that the element is not on the page. The one failure it was plausibly guarding —
+    // a scope selector that matches nothing — is already handled explicitly and distinctly, as
+    // `scopeMissing`, so what remained was a net that could only convert real faults into false
+    // negatives.
+    const found = findCandidates(query);
+    const elements = found.candidates;
+    const scopeMissing = found.scopeMissing;
     // One visibility cache for the whole (synchronous) query pass. isVisible is an O(depth) forced-style
     // walk; the state filter runs it over EVERY candidate (the count must be exact) — on a match-heavy
     // page (e.g. a 3k-row grid) that is tens of thousands of getComputedStyle calls on the host's main
@@ -306,7 +344,7 @@ export function matchQuery(query, state, limit = MAX_DESCRIBED) {
     const described = filtered.slice(0, Math.max(0, Math.min(limit, MAX_DESCRIBED)));
     const descriptors = described.map((el) => {
         const base = describe(el, visMemo);
-        if (attrs === undefined || attrs.length === 0)
+        if (attrs === undefined || 0 === attrs.length)
             return base;
         const projected = projectAttrs(el, attrs);
         return projected === undefined ? base : { ...base, attrs: projected };
@@ -316,13 +354,18 @@ export function matchQuery(query, state, limit = MAX_DESCRIBED) {
         count: filtered.length,
         elements: descriptors,
         ...(scopeMissing ? { scopeMissing: true } : {}),
+        // On a MISS, carry the same diagnosis `runQuery` has always returned. MATCH is the command every
+        // PREDICATE uses, so without this a failed assertion was a dead end ("no element matched") while
+        // the identical failure through reticle_query listed the testids that ARE present. Computed only
+        // when there is nothing to report, so the hot path pays nothing.
+        ...(0 === filtered.length ? { hint: buildEmptyHint(query) } : {}),
     };
 }
 /** Resolve `aria-labelledby` (one or more element IDs) to the referenced elements' text — a bare ID is
  * not a human-readable name. Undefined when unset or nothing resolves. */
 function resolveLabelledBy(el) {
     const ids = el.getAttribute('aria-labelledby');
-    if (ids === null)
+    if (null === ids)
         return undefined;
     const text = ids
         .split(/\s+/)
@@ -426,8 +469,8 @@ function buildEmptyHint(query) {
  */
 export function runQuery(query, limit) {
     const result = matchQuery(query, undefined, limit);
-    const scopeFields = result.scopeMissing === true ? { scopeMissing: true } : {};
-    if (result.elements.length === 0) {
+    const scopeFields = true === result.scopeMissing ? { scopeMissing: true } : {};
+    if (0 === result.elements.length) {
         return {
             elements: result.elements,
             count: result.count,