@reticlehq/browser 2.8.0 → 2.10.0

package/dist/dom/query.js

@@ -1,8 +1,8 @@
-import { queryAllByRole, queryAllByText, queryAllByLabelText, queryAllByPlaceholderText, queryAllByTestId, queryAllByAltText, } from '@testing-library/dom';
+import { queryAllByRole, queryAllByText, queryAllByLabelText, queryAllByPlaceholderText, queryAllByTestId, queryAllByAltText, getDefaultNormalizer, } 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 { getAccessibleName, getRole, describe, getStates, isVisible } from './a11y.js';
+import { getAccessibleName, getRole, describe, getStates, isInViewport, isVisible, } from './a11y.js';
 import { isIgnored } from './dom-ignore.js';
 import { isSensitiveKey } from '../security/serialization.js';
 import { getCapabilities } from '../registry/capabilities.js';
@@ -17,7 +17,7 @@ const MAX_COMPONENT_CANDIDATES = 2000;
 const COMPONENT_CANDIDATE_SELECTOR = `[${SOURCE_ATTR}], [${TESTID_ATTR}], button, a, input, select, textarea, [role]`;
 /**
  * Resolve a scope to its container. A container of `null` means a scope was GIVEN but resolved to
- * nothing (unmounted, or a selector that matches no element) — the caller must NOT fall back to the
+ * nothing (unmounted, or a selector that matches no element) - the caller must NOT fall back to the
  * whole page, or a scoped query silently widens into a phantom match. `scope === undefined` (no scope)
  * legitimately searches the body.
  */
@@ -33,12 +33,12 @@ function resolveContainer(scope) {
             return { container: found, scopeMissing: false };
     }
     catch {
-        // invalid selector — treat as a missing scope, never a whole-page search
+        // invalid selector - treat as a missing scope, never a whole-page search
     }
     return { container: null, scopeMissing: true };
 }
 /**
- * Resolve an element by its SOURCE location — the precise, granular auto-anchor. The babel plugin
+ * Resolve an element by its SOURCE location - the precise, granular auto-anchor. The babel plugin
  * stamps `data-reticle-source="file:line:column"` on host elements, so a line-level starts-with match
  * pins the exact JSX element with a single fast attribute selector (no fiber walk). Column is
  * ignored so a small column drift doesn't unbind the anchor.
@@ -55,7 +55,7 @@ function findBySource(container, source) {
 /**
  * Resolve by component display name when no source stamp is available: scan a bounded set of
  * likely-actionable elements and keep those whose NEAREST enclosing component (via the registered
- * framework adapter) matches. Coarser than source (one component renders many hosts) — used as a
+ * framework adapter) matches. Coarser than source (one component renders many hosts) - used as a
  * fallback / for frameworks without a source plugin.
  */
 function findByComponentName(container, component) {
@@ -84,7 +84,7 @@ function findByComponent(container, query) {
     return [];
 }
 /**
- * Role + name, matched the way Reticle REPORTS them — not only the way Testing Library computes them.
+ * 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:
  *
@@ -94,7 +94,7 @@ function findByComponent(container, query) {
  *
  * `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.
+ * 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
@@ -106,7 +106,7 @@ function findByComponent(container, query) {
  * 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.
+ * churn every stored anchor - both worse trades than a fallback that runs on the empty path.
  */
 function queryByRoleAndName(container, role, name) {
     if (name === undefined)
@@ -118,6 +118,35 @@ function queryByRoleAndName(container, role, name) {
     // 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);
 }
+/**
+ * The same text, written two legal ways, did not match itself.
+ *
+ * Unicode lets `café` be one code point (`é`) or two (`e` + a combining acute). They render
+ * identically, they are canonically equivalent, and JavaScript string comparison says they differ —
+ * so a query typed one way against a DOM holding the other found nothing. That is a false RED: the
+ * agent asserts text that is visibly on screen, is told it is absent, and reports a working app as
+ * broken.
+ *
+ * It cannot happen in English, which is why it survived here. It is ordinary in French, Vietnamese
+ * and Korean, and the decomposed form is what macOS filesystems, several IMEs and some databases
+ * hand back.
+ *
+ * Normalising both sides can only ADD matches: normalisation is idempotent and
+ * canonical-equivalence-preserving, so two strings equal before are equal after and nothing that
+ * matched can stop matching. That property is why this is safe to apply to the matching core.
+ *
+ * Applied only to queries over USER-VISIBLE text. A testid is an attribute the developer typed on
+ * both sides and a component name is an identifier; normalising those would change what an exact
+ * match means, for no case anyone has.
+ */
+const toNfc = (value) => value.normalize('NFC');
+/**
+ * Testing Library's own normaliser — whitespace trimming and collapsing — with NFC on top.
+ *
+ * Composed rather than replaced: writing a normaliser from scratch here would silently drop their
+ * whitespace handling, which every existing match depends on.
+ */
+const TEXT_NORMALIZER = { normalizer: (text) => toNfc(getDefaultNormalizer()(text)) };
 /** Run the appropriate Testing-Library query against ONE root (light DOM or a shadow root). */
 function findIn(container, query) {
     const by = query.by;
@@ -128,62 +157,68 @@ function findIn(container, query) {
             case QueryBy.ROLE:
                 return queryByRoleAndName(container, value, query.name);
             case QueryBy.TEXT:
-                return queryAllByText(container, value, { exact: false });
+                return queryAllByText(container, toNfc(value), { exact: false, ...TEXT_NORMALIZER });
             case QueryBy.LABEL:
-                return queryAllByLabelText(container, value, { exact: false });
+                return queryAllByLabelText(container, toNfc(value), { exact: false, ...TEXT_NORMALIZER });
             case QueryBy.PLACEHOLDER:
-                return queryAllByPlaceholderText(container, value, { exact: false });
+                return queryAllByPlaceholderText(container, toNfc(value), {
+                    exact: false,
+                    ...TEXT_NORMALIZER,
+                });
             case QueryBy.TESTID:
                 return queryAllByTestId(container, value, { exact: true });
             case QueryBy.ALT:
-                return queryAllByAltText(container, value, { exact: false });
+                return queryAllByAltText(container, toNfc(value), { exact: false, ...TEXT_NORMALIZER });
             case QueryBy.COMPONENT:
                 // value is the component name;.source (if present) still takes precedence inside.
                 return findByComponent(container, { ...query, component: query.component ?? value });
             default:
                 // 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
+                // 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(', ')}`);
+                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
+    // Auto-anchor (component / source) - checked before the role/text fields so a query carrying
     // both a component anchor and an incidental role resolves by the more durable anchor.
     if (query.component !== undefined || query.source !== undefined) {
         return findByComponent(container, query);
     }
     // 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.
+    // spelling above - the two forms must not disagree about what is findable.
     if (query.role !== undefined) {
         return queryByRoleAndName(container, query.role, query.name);
     }
     if (query.text !== undefined)
-        return queryAllByText(container, query.text, { exact: false });
+        return queryAllByText(container, toNfc(query.text), { exact: false, ...TEXT_NORMALIZER });
     if (query.label !== undefined) {
-        return queryAllByLabelText(container, query.label, { exact: false });
+        return queryAllByLabelText(container, toNfc(query.label), { exact: false, ...TEXT_NORMALIZER });
     }
     if (query.placeholder !== undefined) {
-        return queryAllByPlaceholderText(container, query.placeholder, { exact: false });
+        return queryAllByPlaceholderText(container, toNfc(query.placeholder), {
+            exact: false,
+            ...TEXT_NORMALIZER,
+        });
     }
     if (query.testid !== undefined)
         return queryAllByTestId(container, query.testid, { exact: true });
     if (query.alt !== undefined)
-        return queryAllByAltText(container, query.alt, { exact: false });
+        return queryAllByAltText(container, toNfc(query.alt), { exact: false, ...TEXT_NORMALIZER });
     return [];
 }
 /**
  * Every open shadow root at or beneath `root`, in document order.
  *
- * A closed root is deliberately unreachable — `element.shadowRoot` is null by design, and the SDK
+ * 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.
  */
 /**
  * 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
+ * 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.
  */
@@ -202,7 +237,7 @@ const FRAME_DEPTH_MAX = 3;
  * 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
+ * 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.
  */
@@ -224,7 +259,7 @@ function embeddedRootsUnder(root) {
                 continue;
             const body = readableFrameBody(el);
             if (null === body)
-                continue; // cross-origin — declared, not searched
+                continue; // cross-origin - declared, not searched
             found.push(body);
             walk(body, depth + 1);
         }
@@ -234,13 +269,13 @@ function embeddedRootsUnder(root) {
 }
 /**
  * NOTE ON COST. The walk above is a `querySelectorAll('*')` over the container, and `reticle_query` is
- * a hot-path tool, so every query on every app pays it — including the overwhelming majority that hold
+ * a hot-path tool, so every query on every app pays it - including the overwhelming majority that hold
  * no web components.
  *
  * A cache invalidated by a MutationObserver was written and then REMOVED, because it is not sound:
  * `attachShadow` on an element that is already in the document mutates only the shadow tree, which an
  * observer watching documentElement's subtree never sees. The cached "no shadow roots here" would
- * persist and the content would be silently missed — a false negative indistinguishable from a genuinely
+ * persist and the content would be silently missed - a false negative indistinguishable from a genuinely
  * absent element, which is the exact bug the piercing was added to fix.
  *
  * Correctness wins until there is a measurement saying the walk actually matters. The allocation is
@@ -250,18 +285,18 @@ function embeddedRootsUnder(root) {
  * Run the query against the light DOM AND every open shadow root beneath the scope.
  *
  * Testing Library only walks the light DOM, so a control inside a web component returned zero matches
- * on a completely healthy page — a miss indistinguishable from a genuinely absent element. The
+ * on a completely healthy page - a miss indistinguishable from a genuinely absent element. The
  * snapshot has always pierced open roots; this makes `query` agree with it.
  */
 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
+    // 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 (null === container)
         return { candidates: [], scopeMissing: true };
     // `self: true` asks for the container ITSELF, which every other path excludes by construction.
     // A layout element with no role, name, testid or own text is unreachable by any semantic locator,
-    // and it is routinely the element carrying the handler — "click the empty space in this row" is a
+    // and it is routinely the element carrying the handler - "click the empty space in this row" is a
     // real user action that was simply not expressible. Requires a scope: without one there is no root
     // to return, and answering `document.body` would be a wrong answer wearing the shape of one.
     if (true === query.self) {
@@ -274,11 +309,11 @@ function findCandidates(query) {
     const collect = (els) => {
         for (const el of els) {
             if (seen.has(el))
-                continue; // reachable from both host and root — count once
+                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 —
+            // 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
+            // ("Pause", "End", "Chat", "Export"). 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.
@@ -295,14 +330,14 @@ function findCandidates(query) {
 }
 /** Longest attribute value returned; one enormous href must not blow the response budget. */
 export const ATTR_VALUE_MAX = 512;
-/** Most attributes projected per element — a guard against a caller asking for everything. */
+/** Most attributes projected per element - a guard against a caller asking for everything. */
 const ATTR_KEYS_MAX = 12;
 /**
  * Read the requested attributes off an element.
  *
  * Absent attributes are OMITTED rather than returned empty, so "not present" and "present but blank"
  * stay distinguishable. Credential-bearing names are redacted with the same rule the network and
- * storage paths use — a projection API must not become an exfiltration path.
+ * storage paths use - a projection API must not become an exfiltration path.
  */
 function projectAttrs(el, keys) {
     const out = {};
@@ -315,6 +350,11 @@ function projectAttrs(el, keys) {
     return Object.keys(out).length > 0 ? out : undefined;
 }
 function inState(el, state, memo) {
+    // inViewport is computed on demand rather than listed in getStates, so it stays assertable without
+    // adding a state to every element in every snapshot (it would bloat the wire and churn every
+    // describe). The predicate path is the only consumer that needs it. (#398)
+    if (ElementState.IN_VIEWPORT === state)
+        return isInViewport(el, memo);
     return getStates(el, isVisible(el, memo)).includes(state);
 }
 /**
@@ -322,7 +362,7 @@ function inState(el, state, memo) {
  *
  * describe() is the expensive part of a query: it resolves the accessible name and forces a style
  * computation for every ancestor to decide visibility. Describing every match on a page with
- * thousands of them freezes the main thread for seconds — and then the wire discards all but the
+ * thousands of them freezes the main thread for seconds - and then the wire discards all but the
  * first `MAX_COLLECTION_ITEMS` anyway, so the work past that point was never observable by anyone.
  * Matching one to the other means the cost of a broad query is bounded by the transport rather than
  * by the size of the page.
@@ -337,15 +377,15 @@ const MAX_DESCRIBED = TRANSPORT_LIMITS.MAX_COLLECTION_ITEMS;
 export function matchQuery(query, state, limit = MAX_DESCRIBED) {
     // 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
+    // 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
+    // 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
     // thread. The memo makes each element's ancestors resolve once, then short-circuit for every sibling.
     const visMemo = new Map();
@@ -371,7 +411,7 @@ export function matchQuery(query, state, limit = MAX_DESCRIBED) {
         ...(0 === filtered.length ? { hint: buildEmptyHint(query) } : {}),
     };
 }
-/** Resolve `aria-labelledby` (one or more element IDs) to the referenced elements' text — a bare ID is
+/** 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');
@@ -384,7 +424,7 @@ function resolveLabelledBy(el) {
         .join(' ');
     return text.length > 0 ? text : undefined;
 }
-/** Structural clusters of the page — the successor to the raw testid list in zero-match hints. */
+/** Structural clusters of the page - the successor to the raw testid list in zero-match hints. */
 function buildPresentRegions(query) {
     // For the diagnostic hint we WANT the page's orientation even when the scope is gone, so fall back
     // to the body here (the match path above already reported scopeMissing, so this can't mask it).
@@ -418,7 +458,7 @@ function buildPresentRegions(query) {
         }
         for (const el of containers) {
             const name = el.getAttribute('aria-label') ??
-                resolveLabelledBy(el) ?? // aria-labelledby is an element ID — resolve it to the referenced TEXT
+                resolveLabelledBy(el) ?? // aria-labelledby is an element ID - resolve it to the referenced TEXT
                 el.getAttribute('data-testid') ??
                 undefined;
             const children = el.querySelectorAll('[role]');
@@ -474,8 +514,8 @@ function buildEmptyHint(query) {
  * Resolve a query to descriptors for the `query` MCP tool.
  *
  * `count` is carried through deliberately: the server reports match totals from it rather than from
- * the array, because the array is capped in transit. Dropping it here — which this function used to
- * do — silently put the server back to counting survivors and calling that the answer.
+ * the array, because the array is capped in transit. Dropping it here - which this function used to
+ * do - silently put the server back to counting survivors and calling that the answer.
  */
 export function runQuery(query, limit) {
     const result = matchQuery(query, undefined, limit);

package/dist/dom/snapshot.d.ts

@@ -4,6 +4,11 @@ interface SnapshotStatus {
     title: string;
     /** Open dialogs, OMITTED when there are none — absence means "no dialog is up". */
     visibleDialogs?: string[];
+    /**
+     * Present ONLY when a whole-page snapshot came back near-empty because an open overlay
+     * aria-hidden the rest of the page (#397). Absence means the page is not hidden behind an overlay.
+     */
+    overlayHidingPage?: string;
 }
 export interface SnapshotResult {
     tree: string;

package/dist/dom/snapshot.js

@@ -194,12 +194,46 @@ function collectDialogs(root) {
  * case, so the field was almost pure repetition; a reader learns nothing from its presence and
  * everything from it.
  */
+/**
+ * A focus-trap modal (Radix and friends) marks every sibling of the portal root aria-hidden. The
+ * snapshot walk correctly skips aria-hidden subtrees, so a whole-page snapshot can return only the
+ * overlay's own nodes and nothing else -- indistinguishable from "this page is empty". If the
+ * overlay's cleanup is stuck (common on a throttled tab), every later action then dispatches with no
+ * effect because the overlay genuinely captures pointer events. Say so instead of returning a
+ * near-empty tree with no explanation. (#397)
+ */
+function overlayHidingPage(root) {
+    // Only meaningful for a whole-page snapshot; a scoped snapshot is the subtree the caller chose.
+    if (root !== document.body)
+        return undefined;
+    const dialogs = document.body.querySelectorAll('[role="dialog"], dialog[open], [aria-modal="true"]');
+    let modal;
+    for (const d of dialogs) {
+        if (isVisible(d)) {
+            modal = d;
+            break;
+        }
+    }
+    if (modal === undefined)
+        return undefined;
+    const modalEl = modal;
+    const outside = Array.from(document.body.children).filter((c) => !c.contains(modalEl));
+    if (0 === outside.length)
+        return undefined;
+    if (!outside.every((c) => 'true' === c.getAttribute('aria-hidden')))
+        return undefined;
+    return ('the rest of the page is aria-hidden behind an open overlay (a focus-trap modal), so this ' +
+        'snapshot shows only the overlay. If it will not close its cleanup may be stuck on a throttled ' +
+        'tab: dismiss the overlay, or snapshot with { scope } inside it.');
+}
 function buildStatus(root) {
     const visibleDialogs = collectDialogs(root);
+    const overlay = overlayHidingPage(root);
     return {
         route: `${location.pathname}${location.search}${location.hash}`,
         title: document.title,
         ...(visibleDialogs.length > 0 ? { visibleDialogs } : {}),
+        ...(overlay !== undefined ? { overlayHidingPage: overlay } : {}),
     };
 }
 /** Build the semantic accessibility snapshot of the page or a subtree. */

package/dist/dom/source.d.ts

@@ -29,6 +29,20 @@ export declare function parseSourceAttr(value: string | null): SourceLocation |
 export declare function sourceFromDom(el: Element): SourceLocation | undefined;
 /** Best source for the element: the framework adapter's, else the nearest babel-stamped attribute. */
 export declare function sourceFor(el: Element, adapterSource: SourceLocation | undefined): SourceLocation | undefined;
+/**
+ * Does ANY element in this document carry a source stamp?
+ *
+ * The difference between "this element has no stamp" and "the stamping loader is not running at
+ * all" — two answers that look identical from a single missing `source` field, and that call for
+ * completely different next actions. The first is ordinary: not every element sits under a stamped
+ * host. The second means "fix at file:line", the single most-cited reason to reach for Reticle over
+ * a generic DOM tool, is silently unavailable for the whole session — and it has been discovered by
+ * reading the adapter's source rather than from anything Reticle said.
+ *
+ * One `querySelector`, which stops at the first hit, so this is cheap enough to answer on a
+ * single-element path like inspect. It is only consulted when a source is already missing.
+ */
+export declare function documentHasSourceStamps(doc: Document): boolean;
 /**
  * `file:line` — the form an agent can act on directly.
  *

package/dist/dom/source.js

@@ -46,6 +46,22 @@ export function sourceFor(el, adapterSource) {
         return { file: adapterSource.file, line: adapterSource.line };
     return sourceFromDom(el);
 }
+/**
+ * Does ANY element in this document carry a source stamp?
+ *
+ * The difference between "this element has no stamp" and "the stamping loader is not running at
+ * all" — two answers that look identical from a single missing `source` field, and that call for
+ * completely different next actions. The first is ordinary: not every element sits under a stamped
+ * host. The second means "fix at file:line", the single most-cited reason to reach for Reticle over
+ * a generic DOM tool, is silently unavailable for the whole session — and it has been discovered by
+ * reading the adapter's source rather than from anything Reticle said.
+ *
+ * One `querySelector`, which stops at the first hit, so this is cheap enough to answer on a
+ * single-element path like inspect. It is only consulted when a source is already missing.
+ */
+export function documentHasSourceStamps(doc) {
+    return doc.querySelector(`[${SOURCE_ATTR}]`) !== null;
+}
 /**
  * `file:line` — the form an agent can act on directly.
  *

package/dist/observers/install-all.js

@@ -18,7 +18,7 @@ import { installFocus } from './focus.js';
 import { installBlindSpots } from './blind-spots.js';
 import { installDownload } from './download.js';
 import { installNetwork } from './network.js';
-import { installIpc, ipcNetOverrides } from './ipc.js';
+import { installIpc, ipcNetOverrides, isReticleOwnIpc } from './ipc.js';
 import { installPerf } from './perf.js';
 import { installRoute } from './route.js';
 import { installConsole } from './console.js';
@@ -43,6 +43,9 @@ export function installAllObservers(emit, options) {
         guard(emit, SdkSite.NETWORK_OBSERVER, () => installNetwork(emit, {
             captureBodies: options.captureBodies,
             reinterpret: ipcNetOverrides,
+            // The SDK's own Tauri screenshot is a fetch like any other — skip it, or the observer
+            // reports its own captures as the app's writes.
+            ignore: isReticleOwnIpc,
         })),
         // Desktop backends are reached over IPC, not HTTP — inert on a plain web page.
         guard(emit, SdkSite.IPC_OBSERVER, () => installIpc(emit, { captureBodies: options.captureBodies })),

package/dist/observers/ipc.d.ts

@@ -5,6 +5,22 @@ import type { Emit, Teardown } from './types.js';
  * already holds, so IPC knowledge stays in this file.
  */
 export declare function ipcNetOverrides(url: string, header: (name: string) => string | null): Record<string, unknown> | undefined;
+/**
+ * Is this fetch Reticle's OWN desktop call rather than the app's?
+ *
+ * Tauri has no preload stage, so `reticle_screenshot` reaches the shell the only way it can: an
+ * `invoke` — and an invoke IS a fetch to the `ipc://` protocol, straight through the patch the
+ * network observer installed. So the observer recorded its own screenshots as app IPC calls, and
+ * because `IPC` counts as a mutating method, three concurrent captures inside one action window came
+ * back to the agent as `duplicate-request`: "the same write fired 3 times", against an app that had
+ * never made the call. Accusing a correct app of a double submit is the most damaging thing a
+ * verification tool can do, and here the tool was the one submitting.
+ *
+ * Electron never had this problem — its preload captures through the UNPATCHED invoke for exactly
+ * this reason — and the bridge's own WebSocket is skipped on the same principle (`isBridgeSocket`).
+ * The capture command is the SDK's whole Tauri-side surface, so matching it is the whole rule.
+ */
+export declare function isReticleOwnIpc(url: string): boolean;
 /**
  * Subscribe to the Electron preload shim, if this app installed it. Inert on Tauri (whose calls the
  * network observer handles) and on a plain web page.

package/dist/observers/ipc.js

@@ -1,4 +1,4 @@
-import { BlindSpotKind, EventType, IPC_URL_SCHEME, IpcStatus, NetInitiator, RETICLE_IPC_GLOBAL, } from '@reticlehq/core';
+import { BlindSpotKind, EventType, IPC_URL_SCHEME, IpcStatus, NetInitiator, RETICLE_IPC_GLOBAL, RETICLE_TAURI_CAPTURE_COMMAND, } from '@reticlehq/core';
 import { observeSafely } from './types.js';
 /**
  * How Tauri v2 reports a command's verdict. The transport answers HTTP 200 whether the Rust command
@@ -48,6 +48,24 @@ export function ipcNetOverrides(url, header) {
         statusText: ok ? IPC_STATUS_TEXT.OK : IPC_STATUS_TEXT.ERROR,
     };
 }
+/**
+ * Is this fetch Reticle's OWN desktop call rather than the app's?
+ *
+ * Tauri has no preload stage, so `reticle_screenshot` reaches the shell the only way it can: an
+ * `invoke` — and an invoke IS a fetch to the `ipc://` protocol, straight through the patch the
+ * network observer installed. So the observer recorded its own screenshots as app IPC calls, and
+ * because `IPC` counts as a mutating method, three concurrent captures inside one action window came
+ * back to the agent as `duplicate-request`: "the same write fired 3 times", against an app that had
+ * never made the call. Accusing a correct app of a double submit is the most damaging thing a
+ * verification tool can do, and here the tool was the one submitting.
+ *
+ * Electron never had this problem — its preload captures through the UNPATCHED invoke for exactly
+ * this reason — and the bridge's own WebSocket is skipped on the same principle (`isBridgeSocket`).
+ * The capture command is the SDK's whole Tauri-side surface, so matching it is the whole rule.
+ */
+export function isReticleOwnIpc(url) {
+    return TAURI_IPC_URL.exec(url)?.[1] === RETICLE_TAURI_CAPTURE_COMMAND;
+}
 /**
  * Is this page an Electron renderer? Read off the user agent, which Electron stamps and which is
  * available whether or not the preload ran — the whole point is to recognise a renderer that has

package/dist/observers/network.d.ts

@@ -16,6 +16,14 @@ interface NetworkOptions {
     captureBodies?: boolean;
     /** Optional hook that reinterprets a completed request — see NetResponseReinterpreter. */
     reinterpret?: NetResponseReinterpreter;
+    /**
+     * Requests Reticle itself makes, which must never reach the app's evidence.
+     *
+     * Same seam and same reason as `reinterpret`: this observer knows nothing about desktop IPC, and
+     * the SDK's own Tauri screenshot travels as an ordinary fetch through this very patch. Passed in
+     * rather than imported, so the knowledge stays in the IPC observer.
+     */
+    ignore?: (url: string) => boolean;
 }
 /** Pure: the first real app-code frame in a stack string, capped. Exported for unit testing. */
 export declare function firstAppFrame(stack: string | undefined): string | undefined;

package/dist/observers/network.js

@@ -61,6 +61,22 @@ function projectRequestBody(body, captureBodies) {
     const { body: out, truncated } = projectBody(text, contentType);
     return truncated ? { requestBody: out, requestBodyTruncated: true } : { requestBody: out };
 }
+/**
+ * Did this response succeed? A REDIRECT DID.
+ *
+ * The one rule both transports must share. `Response.ok` is true only for 200-299, so reading it
+ * straight through stamped every 3xx as a failed request, while the XHR path computed the same field
+ * itself and called the identical status a success. Downstream, `ok` is authoritative when present —
+ * so a POST-redirect-GET login, the first flow anyone verifies in an app with auth, produced a
+ * `ui-advanced-request-failed` contradiction citing its own success path, and the agent had to
+ * overrule the verdict by hand. A verdict that gets manually overruled is not deciding anything.
+ *
+ * 3xx is normal successful navigation. An opaque (no-cors) response reports status 0 and is correctly
+ * excluded here, exactly as `Response.ok` excluded it.
+ */
+function statusIsOk(status) {
+    return status >= 200 && status < 400;
+}
 /**
  * Response metadata that needs no body capture: HTTP status text, content-type, and byte size (from
  * content-length when the server sent it). Lets an agent tell an HTML error page served as 200 from
@@ -219,10 +235,15 @@ export function installNetwork(emit, opts = {}) {
     let seq = 0;
     const nextId = () => `n${++seq}`;
     window.fetch = async (input, init) => {
+        const rawUrl = urlOf(input);
+        // Reticle's own call: pass it straight through, observed by nobody. Emitting even the PENDING
+        // half would be wrong twice over — it lands in the agent's network evidence, and `settle` would
+        // wait on the SDK's own screenshot as if the app had a request in flight.
+        if (true === opts.ignore?.(rawUrl))
+            return callFetch(input, init);
         const id = nextId();
         const start = performance.now();
         const method = methodOf(input, init);
-        const rawUrl = urlOf(input);
         const url = redactUrl(rawUrl);
         const initiatorStack = initiatorFrame();
         const initiatorFields = initiatorStack === undefined ? {} : { initiatorStack };
@@ -241,7 +262,7 @@ export function installNetwork(emit, opts = {}) {
                     method,
                     url,
                     status: res.status,
-                    ok: res.ok,
+                    ok: statusIsOk(res.status),
                     durationMs: Math.round(headersAt - start),
                     initiator: 'fetch',
                     ...initiatorFields,
@@ -384,7 +405,7 @@ export function installNetwork(emit, opts = {}) {
                         method: cur.method,
                         url: cur.url,
                         status: this.status,
-                        ok: this.status >= 200 && this.status < 400,
+                        ok: statusIsOk(this.status),
                         durationMs: Math.round(performance.now() - cur.start),
                         initiator: 'xhr',
                         ...(cur.initiatorStack === undefined ? {} : { initiatorStack: cur.initiatorStack }),

package/dist/observers/state.js

@@ -1,4 +1,4 @@
-import { EventType, REDACTED_VALUE } from '@reticlehq/core';
+import { BlindSpotKind, EventType, REDACTED_VALUE } from '@reticlehq/core';
 import { subscribableStores, onStoreRegistered, } from '../registry/stores.js';
 import { isSensitiveKey, sanitizeForTransport } from '../security/serialization.js';
 function isRecord(value) {
@@ -68,9 +68,28 @@ export function installStoreState(emit) {
     // Stores already registered...
     for (const entry of subscribableStores())
         watch(entry);
+    /**
+     * Declare an unwatched state channel — and clear it the moment one is watched.
+     *
+     * With nothing subscribed, every act reports `stateDiffs: []`, which reads as "the app changed no
+     * state" when the truth is "nobody was looking". Emitted as a BLIND_SPOT so it travels the path
+     * that already exists for everything the layer cannot see: bounding, never impeaching, so no
+     * verdict turns UNKNOWN over it.
+     */
+    if (0 === active.size) {
+        emit(EventType.BLIND_SPOT, { kind: BlindSpotKind.UNWATCHED_STATE, count: 1 });
+    }
     //...and any registered LATER. The SDK installs observers during connect, but apps call
     // registerStore after that, so without this the common case subscribes to nothing.
-    const offRegistered = onStoreRegistered(watch);
+    const offRegistered = onStoreRegistered((entry) => {
+        const wasDark = 0 === active.size;
+        watch(entry);
+        // The channel just lit up. A blind spot that is never withdrawn is a permanent lie, and this one
+        // is withdrawn in the ordinary case: apps register their stores AFTER connect() installs us.
+        if (wasDark && active.size > 0) {
+            emit(EventType.BLIND_SPOT, { kind: BlindSpotKind.UNWATCHED_STATE, count: 0 });
+        }
+    });
     return () => {
         offRegistered();
         for (const unsubscribe of active.values()) {