@reticlehq/browser 2.7.0 → 2.9.0

package/dist/dom/dom-ignore.js

@@ -1,10 +1,9 @@
 /**
- * Selectors for Reticle's own presenter overlay (cursor, HUD, glow) + the annotator's "flag a bug"
- * UI (`data-reticle-mark`) — never observed/snapshotted. The annotator mounts by DEFAULT with the
- * presenter, so omitting its selector here leaked a phantom `<button>Flag a bug</button>` into every
- * snapshot and streamed its highlight-box mutations/transitions as if the APP had rendered them.
+ * Selectors for Reticle's own presenter overlay (cursor, HUD, glow) + the annotator's
+ * UI (`data-reticle-mark`) - never observed/snapshotted. The annotator mounts by DEFAULT with the
+ * presenter, so omitting its selector here leaked annotation chrome into every snapshot.
  */
-export const RETICLE_OVERLAY = '[data-reticle-overlay],[data-reticle-cursor],[data-reticle-hud],[data-reticle-glow],[data-reticle-mark]';
+export const RETICLE_OVERLAY = '[data-reticle-overlay],[data-reticle-cursor],[data-reticle-hud],[data-reticle-glow],[data-reticle-mark],[data-reticle-blocker]';
 /** Known third-party dev overlays to keep out of snapshots (Agentation, Next dev UI). */
 const DEV_OVERLAYS = '[data-agentation],#__next-build-watcher,nextjs-portal,[data-nextjs-dialog],[data-nextjs-toast]';
 let extraIgnore = '';
@@ -16,15 +15,23 @@ export function setIgnoreSelectors(selectors) {
 export function isReticleOverlay(el) {
     return el.closest(RETICLE_OVERLAY) !== null;
 }
-/** Walk ancestors: true iff any element in the chain carries a data-reticle* attribute (Reticle's own UI). */
+/**
+ * True iff the element is part of Reticle's OWN UI - the presenter overlay, the HUD, the synthetic
+ * cursor, the glow, or the annotator's marks - or lives inside one of them.
+ *
+ * The rule used to be "any ancestor carries a data-reticle* attribute", which is wrong twice over.
+ * `data-reticle-mark-active` sits on <html> while annotate mode is live, so the whole document
+ * answered yes; and `data-reticle-source` is stamped by the Vite/Babel plugins on every element the
+ * APP renders, so in an instrumented app - which is the only kind there is - most of the page
+ * answered yes too. Those attributes describe page content; they do not make it ours.
+ *
+ * Two things read this and both failed silently. `pageElementAt` (annotator) skipped every stamped
+ * element and anchored the note to the outermost unstamped ancestor, i.e. the app shell instead of
+ * the control under the cursor. `occlusion.ts` reads a yes as "nothing to report", so occlusion
+ * detection - a bug class Reticle advertises catching - came back clean wherever the stamp reached.
+ */
 export function isReticleUi(node) {
-    for (let n = node; n !== null; n = n.parentElement) {
-        for (const attr of Array.from(n.attributes)) {
-            if (attr.name.startsWith('data-reticle'))
-                return true;
-        }
-    }
-    return false;
+    return node !== null && node.closest(RETICLE_OVERLAY) !== null;
 }
 /** True if the element should be excluded from snapshots/queries (Reticle overlay or dev overlay). */
 export function isIgnored(el) {

package/dist/dom/query.d.ts

@@ -12,7 +12,7 @@ export declare function matchQuery(query: ElementQuery, state?: ElementState, li
  * 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 declare function runQuery(query: ElementQuery, limit?: number): QueryResult;

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/refs.d.ts

@@ -31,8 +31,36 @@ export declare const MAX_TRACKED_REFS = 10000;
  * the message.
  */
 export declare function echoRef(ref: string): string;
+/**
+ * How many numbers a document claims at once.
+ *
+ * The reservation is a synchronous storage write, so it cannot happen per mint — mints are frequent
+ * (every meaningful DOM addition, every transitionend, every scroll reveal). One write per this many
+ * mints is free.
+ *
+ * Sized to keep refs SHORT, and the first attempt at that reasoned about the wrong axis. It bounded
+ * how many navigations it took to reach seven digits and concluded "a hundred" — but the cost is not
+ * paid at seven digits, it is paid at every digit, on every ref, in every snapshot and every error
+ * message, on every turn. At 10,000 the SECOND document already mints five-digit refs.
+ *
+ * Measured on one unchanged three-element page across a session: 61 tokens on the first document,
+ * 64 after a reload, 65 later — +6.5% for the same page, entirely in ref width. The benchmark saw the
+ * same thing as a ~4% rise in average observation cost, which is what a benchmark is for.
+ *
+ * So the block is small. A document claims another one when it outmints this, which costs one more
+ * storage write and is exactly proportional: a page with thousands of elements has a long snapshot
+ * anyway, and a small page — the common case, and the one an agent drives repeatedly — keeps
+ * three-digit refs across dozens of navigations.
+ */
+export declare const REF_BLOCK = 100;
 export declare class RefRegistry {
     #private;
+    /**
+     * Storage is injected rather than read from the global for the same reason the clock is: it is an
+     * ambient dependency that decides behaviour, and the cross-document property is untestable if the
+     * only way to get a second document is to actually navigate.
+     */
+    constructor(storage?: () => Storage | undefined);
     /** How many reverse entries are currently retained. Exposed so the bound can be asserted. */
     get size(): number;
     /** Get the existing ref for an element, or mint a new one. */

package/dist/dom/refs.js

@@ -44,11 +44,96 @@ export function echoRef(ref) {
  * over-cap mint, and the expensive dead-entry sweep runs once per this many mints (amortized O(1)).
  */
 const SWEEP_EVERY_MINTS = 1000;
+/**
+ * Where a document records the ref numbers it has claimed, so the next one starts past them.
+ *
+ * Refs are per-DOCUMENT: a reload or a cross-page link tears this module down and the next document
+ * used to start minting from `e1` again. So `e7` from page A was a valid, resolvable, DIFFERENT
+ * element on page B — nothing refused, the wrong element was acted on, and the result came back `ok`.
+ * The SPA case was always safe (WeakRef liveness + isConnected); this was the other half, and the
+ * more dangerous one, because it produced a false green instead of an error.
+ *
+ * Deliberately NOT a change to the ref grammar. Stamping refs `e7@3` would have worked too, but every
+ * agent passes refs back verbatim and every saved flow on disk already holds bare ones, so it buys a
+ * wire-format migration for a property the sequence itself can carry. A number that never restarts
+ * means a stale ref simply misses the map, and the refusal that already exists — already worded for
+ * exactly this case — fires unchanged.
+ *
+ * Namespaced like the session key it sits beside; `sessionStorage` is the right scope for the same
+ * reason session continuity uses it (survives reloads and same-tab navigations, not shared with
+ * another tab, which is a different session with its own registry anyway).
+ */
+const REF_BASE_KEY = '__reticle_ref_base';
+/**
+ * How many numbers a document claims at once.
+ *
+ * The reservation is a synchronous storage write, so it cannot happen per mint — mints are frequent
+ * (every meaningful DOM addition, every transitionend, every scroll reveal). One write per this many
+ * mints is free.
+ *
+ * Sized to keep refs SHORT, and the first attempt at that reasoned about the wrong axis. It bounded
+ * how many navigations it took to reach seven digits and concluded "a hundred" — but the cost is not
+ * paid at seven digits, it is paid at every digit, on every ref, in every snapshot and every error
+ * message, on every turn. At 10,000 the SECOND document already mints five-digit refs.
+ *
+ * Measured on one unchanged three-element page across a session: 61 tokens on the first document,
+ * 64 after a reload, 65 later — +6.5% for the same page, entirely in ref width. The benchmark saw the
+ * same thing as a ~4% rise in average observation cost, which is what a benchmark is for.
+ *
+ * So the block is small. A document claims another one when it outmints this, which costs one more
+ * storage write and is exactly proportional: a page with thousands of elements has a long snapshot
+ * anyway, and a small page — the common case, and the one an agent drives repeatedly — keeps
+ * three-digit refs across dozens of navigations.
+ */
+export const REF_BLOCK = 100;
+/** The reserved-block high-water mark, or 0 when storage is unavailable or its value is junk. */
+function readBase(store) {
+    try {
+        const raw = store?.getItem(REF_BASE_KEY);
+        const value = null === raw || undefined === raw ? Number.NaN : Number(raw);
+        return Number.isSafeInteger(value) && value > 0 ? value : 0;
+    }
+    catch {
+        return 0; // a sandboxed iframe throws on access; a session must still start
+    }
+}
 export class RefRegistry {
     #toRef = new WeakMap();
     #fromRef = new Map();
+    #storage;
     #seq = 0;
+    /** The end of the block currently reserved. Minting past it claims the next one. */
+    #reserved = 0;
     #mintsSinceSweep = 0;
+    /**
+     * Storage is injected rather than read from the global for the same reason the clock is: it is an
+     * ambient dependency that decides behaviour, and the cross-document property is untestable if the
+     * only way to get a second document is to actually navigate.
+     */
+    constructor(storage = () => globalThis.sessionStorage) {
+        this.#storage = storage;
+    }
+    /** Read the tab's high-water mark and claim the next block, BEFORE any of it is handed out. */
+    #reserve() {
+        let store;
+        try {
+            store = this.#storage();
+        }
+        catch {
+            store = undefined; // hostile storage: no cross-document guarantee, but the session still starts
+        }
+        const base = Math.max(readBase(store), this.#seq);
+        this.#reserved = base + REF_BLOCK;
+        try {
+            store?.setItem(REF_BASE_KEY, String(this.#reserved));
+        }
+        catch {
+            /* same: never block a mint on storage */
+        }
+        // Claimed on the FIRST mint, not at unload — a page that crashes, is killed, or navigates away
+        // without firing unload has still permanently spent its numbers.
+        this.#seq = base;
+    }
     /** How many reverse entries are currently retained. Exposed so the bound can be asserted. */
     get size() {
         return this.#fromRef.size;
@@ -85,6 +170,8 @@ export class RefRegistry {
             this.#fromRef.set(existing, weak ?? new WeakRef(el));
             return existing;
         }
+        if (this.#seq >= this.#reserved)
+            this.#reserve();
         this.#seq += 1;
         const ref = asRef(`e${String(this.#seq)}`);
         this.#toRef.set(el, ref);

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.
  *