@reticlehq/browser 2.11.0 → 2.13.0

package/dist/dom/query.js

@@ -1,11 +1,10 @@
-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 { isFrame, isHtmlElement, isInput, isSelect, isTextArea } from './realm.js';
 import { capturedRootOf } from './shadow-registry.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';
+import { declaredTestids } from '../registry/capabilities.js';
 import { identifyComponent } from '../registry/adapters.js';
 import { refs } from './refs.js';
 const TESTID_ATTR = 'data-testid';
@@ -15,6 +14,72 @@ const MAX_PRESENT_TESTIDS = 12;
 const MAX_COMPONENT_CANDIDATES = 2000;
 /** Likely-actionable elements considered when resolving a component anchor without a source stamp. */
 const COMPONENT_CANDIDATE_SELECTOR = `[${SOURCE_ATTR}], [${TESTID_ATTR}], button, a, input, select, textarea, [role]`;
+/**
+ * Every candidate a semantic locator may match: the container ITSELF first, then its descendants.
+ *
+ * The container's own text, role or name was matched by every engine this replaces - a scoped
+ * `{ text: "Saved" }` against `<div id="status">Saved</div>` found #status itself - so dropping
+ * the root here would turn exactly those scoped queries into silent zero-match answers: the worst
+ * failure mode, indistinguishable from the element being absent. `self: true` stays the way to
+ * reach an UNLABELLED root (it skips the predicate entirely); this keeps a root that DOES satisfy
+ * the predicate findable without a second spelling.
+ */
+function elementsUnder(container) {
+    // Embedded roots include ShadowRoots, which are DocumentFragments: they have no attributes or
+    // tag to match on, so only a true Element root joins the candidates.
+    const self = Node.ELEMENT_NODE === container.nodeType ? [container] : [];
+    return [...self, ...Array.from(container.querySelectorAll('*'))];
+}
+/**
+ * Match user-visible prose the way the public query API has always promised: trim and collapse
+ * whitespace, compare canonically equivalent Unicode in NFC, and keep fuzzy text queries
+ * case-insensitive. Attribute identifiers such as testid stay exact and do not pass through here.
+ */
+function normaliseVisibleText(value) {
+    return value.replace(/\s+/g, ' ').trim().normalize('NFC');
+}
+function fuzzyVisibleText(actual, expected) {
+    return normaliseVisibleText(actual)
+        .toLowerCase()
+        .includes(normaliseVisibleText(expected).toLowerCase());
+}
+function exactVisibleText(actual, expected) {
+    return normaliseVisibleText(actual) === normaliseVisibleText(expected);
+}
+function directText(el) {
+    if (isInput(el)) {
+        const type = el.type.toLowerCase();
+        if ('submit' === type || 'button' === type || 'reset' === type)
+            return el.value;
+    }
+    const tag = el.tagName.toLowerCase();
+    if ('script' === tag || 'style' === tag)
+        return '';
+    return Array.from(el.childNodes)
+        .filter((node) => Node.TEXT_NODE === node.nodeType)
+        .map((node) => node.textContent ?? '')
+        .join('');
+}
+/**
+ * Elements whose accessible name comes from author-supplied naming rather than free subtree
+ * content - the set `by: label` addresses.
+ *
+ * Form controls plus anything explicitly named with aria-label/aria-labelledby covers the common
+ * case. `button`, `meter`, `output` and `progress` are included because their names arrive on
+ * attributes (`value`) or from their caption, which is precisely what a label query is looking
+ * for; leaving them out would silently drop buttons from label searches.
+ */
+function semanticNameTarget(el) {
+    if (isInput(el) || isTextArea(el) || isSelect(el))
+        return true;
+    const tag = el.tagName.toLowerCase();
+    return ('button' === tag ||
+        'meter' === tag ||
+        'output' === tag ||
+        'progress' === tag ||
+        el.hasAttribute('aria-label') ||
+        el.hasAttribute('aria-labelledby'));
+}
 /**
  * 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
@@ -84,70 +149,37 @@ 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.
+ * Role + name, matched with the same local accessibility engine used to describe results.
  *
- * 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.
+ * This intentionally makes Reticle's reported role and name the source of truth. If an element is
+ * described as `textbox "Search User"`, the resolver must accept that exact pair, not a different
+ * role or name from a second library.
  */
 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);
+    return elementsUnder(container).filter((el) => getRole(el) === role && (name === undefined || exactVisibleText(getAccessibleName(el), name)));
 }
-/**
- * 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 queryByText(container, value) {
+    return elementsUnder(container).filter((el) => fuzzyVisibleText(directText(el), value));
+}
+function queryByLabel(container, value) {
+    return elementsUnder(container).filter((el) => semanticNameTarget(el) && fuzzyVisibleText(getAccessibleName(el), value));
+}
+function queryByPlaceholder(container, value) {
+    return elementsUnder(container).filter((el) => {
+        const placeholder = el.getAttribute('placeholder');
+        return placeholder !== null && fuzzyVisibleText(placeholder, value);
+    });
+}
+function queryByTestId(container, value) {
+    return elementsUnder(container).filter((el) => el.getAttribute(TESTID_ATTR) === value);
+}
+function queryByAlt(container, value) {
+    return elementsUnder(container).filter((el) => {
+        const alt = el.getAttribute('alt');
+        return alt !== null && fuzzyVisibleText(alt, value);
+    });
+}
+/** Run the appropriate local query against ONE root, light DOM or a shadow root. */
 function findIn(container, query) {
     const by = query.by;
     const value = query.value;
@@ -157,18 +189,15 @@ function findIn(container, query) {
             case QueryBy.ROLE:
                 return queryByRoleAndName(container, value, query.name);
             case QueryBy.TEXT:
-                return queryAllByText(container, toNfc(value), { exact: false, ...TEXT_NORMALIZER });
+                return queryByText(container, value);
             case QueryBy.LABEL:
-                return queryAllByLabelText(container, toNfc(value), { exact: false, ...TEXT_NORMALIZER });
+                return queryByLabel(container, value);
             case QueryBy.PLACEHOLDER:
-                return queryAllByPlaceholderText(container, toNfc(value), {
-                    exact: false,
-                    ...TEXT_NORMALIZER,
-                });
+                return queryByPlaceholder(container, value);
             case QueryBy.TESTID:
-                return queryAllByTestId(container, value, { exact: true });
+                return queryByTestId(container, value);
             case QueryBy.ALT:
-                return queryAllByAltText(container, toNfc(value), { exact: false, ...TEXT_NORMALIZER });
+                return queryByAlt(container, value);
             case QueryBy.COMPONENT:
                 // value is the component name;.source (if present) still takes precedence inside.
                 return findByComponent(container, { ...query, component: query.component ?? value });
@@ -193,20 +222,15 @@ function findIn(container, query) {
         return queryByRoleAndName(container, query.role, query.name);
     }
     if (query.text !== undefined)
-        return queryAllByText(container, toNfc(query.text), { exact: false, ...TEXT_NORMALIZER });
-    if (query.label !== undefined) {
-        return queryAllByLabelText(container, toNfc(query.label), { exact: false, ...TEXT_NORMALIZER });
-    }
-    if (query.placeholder !== undefined) {
-        return queryAllByPlaceholderText(container, toNfc(query.placeholder), {
-            exact: false,
-            ...TEXT_NORMALIZER,
-        });
-    }
+        return queryByText(container, query.text);
+    if (query.label !== undefined)
+        return queryByLabel(container, query.label);
+    if (query.placeholder !== undefined)
+        return queryByPlaceholder(container, query.placeholder);
     if (query.testid !== undefined)
-        return queryAllByTestId(container, query.testid, { exact: true });
+        return queryByTestId(container, query.testid);
     if (query.alt !== undefined)
-        return queryAllByAltText(container, toNfc(query.alt), { exact: false, ...TEXT_NORMALIZER });
+        return queryByAlt(container, query.alt);
     return [];
 }
 /**
@@ -247,8 +271,8 @@ function embeddedRootsUnder(root) {
         for (const el of node.querySelectorAll('*')) {
             const shadow = el.shadowRoot ?? capturedRootOf(el);
             if (shadow !== null) {
-                // A ShadowRoot is a DocumentFragment; the Testing-Library queries accept any HTMLElement-like
-                // container, and every call site only reads from it.
+                // A ShadowRoot is a DocumentFragment. The local query helpers only call querySelectorAll on
+                // the container, and every call site only reads from it.
                 found.push(shadow);
                 walk(shadow, depth); // nested web components
                 continue;
@@ -284,9 +308,10 @@ 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
- * snapshot has always pierced open roots; this makes `query` agree with it.
+ * A single querySelectorAll call only walks the root it starts from, so a control inside a web
+ * component returned zero matches 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);
@@ -449,13 +474,7 @@ function buildPresentRegions(query) {
         'tablist',
     ];
     for (const role of CONTAINER_ROLES) {
-        let containers;
-        try {
-            containers = queryAllByRole(container, role, { hidden: true });
-        }
-        catch {
-            continue;
-        }
+        const containers = queryByRoleAndName(container, role, undefined);
         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
@@ -485,6 +504,47 @@ function buildPresentRegions(query) {
     }
     return regions;
 }
+/**
+ * The tightest single element whose SUBTREE text carries `wanted`, when no element's OWN text does.
+ *
+ * `by: text` matches an element's direct text nodes (`directText`), so a label rendered across
+ * several child nodes — `v-html`, an inline `<span>` per word, a highlighted substring — exists on
+ * the page and matches nothing. The two channels disagree by construction: `act_and_wait` reports
+ * `appeared` by concatenating an added subtree, so the string an agent is most likely to copy into
+ * its next predicate is exactly the shape this query cannot find.
+ *
+ * That failure is indistinguishable from the element being absent, which is the expensive half: the
+ * agent reads "no element matched", concludes the app did not render, and reports a bug against
+ * correct code.
+ *
+ * Returns the DEEPEST container rather than the first, because every ancestor up to `<body>` also
+ * contains the string and naming `<body>` is not a locator. The deepest one is the tightest scope
+ * that still holds the whole string, which is the one worth pasting back.
+ */
+function splitTextOwner(container, wanted) {
+    let best;
+    let bestDepth = -1;
+    for (const el of elementsUnder(container)) {
+        if (isIgnored(el))
+            continue; // never point an agent at Reticle's own UI
+        if (!fuzzyVisibleText(el.textContent ?? '', wanted))
+            continue;
+        let depth = 0;
+        for (let parent = el.parentElement; parent !== null; parent = parent.parentElement)
+            depth++;
+        if (depth > bestDepth) {
+            best = el;
+            bestDepth = depth;
+        }
+    }
+    return best;
+}
+/** The text this query searched for, in either spelling, or undefined when it searched by something else. */
+function wantedTextOf(query) {
+    if (query.text !== undefined)
+        return query.text;
+    return QueryBy.TEXT === query.by ? query.value : undefined;
+}
 /** Diagnostic hint for a zero-match query: what testids ARE present in the searched scope. */
 function buildEmptyHint(query) {
     const container = resolveContainer(query.scope).container ?? document.body;
@@ -500,15 +560,26 @@ function buildEmptyHint(query) {
                 break;
         }
     }
-    const registered = getCapabilities().testids;
+    // DECLARED, not observed: see declaredTestids. Every present testid is also an observed one, so
+    // the merged list would make this flag true for any page that has a testid at all.
+    const registered = declaredTestids();
     const knownEmptyState = present.some((id) => registered.includes(id));
     const route = `${location.pathname}${location.search}`;
-    return {
+    const hint = {
         route,
         presentTestids: present,
         presentRegions: buildPresentRegions(query),
         knownEmptyState,
     };
+    // Only for a text search, and only when the string IS here — otherwise this is an ordinary miss
+    // and the extra clause would lengthen every failure to say nothing.
+    const wanted = wantedTextOf(query);
+    if (wanted !== undefined) {
+        const owner = splitTextOwner(container, wanted);
+        if (owner !== undefined)
+            hint.splitText = describe(owner);
+    }
+    return hint;
 }
 /**
  * Resolve a query to descriptors for the `query` MCP tool.

package/dist/dom/refs.d.ts

@@ -63,6 +63,17 @@ export declare class RefRegistry {
     constructor(storage?: () => Storage | undefined);
     /** How many reverse entries are currently retained. Exposed so the bound can be asserted. */
     get size(): number;
+    /**
+     * A hot update just replaced modules in this document: every ref handed out so far was minted
+     * against the DOM the previous version of that code produced.
+     *
+     * Only the boundary is recorded. Nothing is evicted — a hot update is not a navigation, and most
+     * of the page survives one, so refs minted before it very often still resolve. This exists so the
+     * ones that DON'T can say why.
+     */
+    markEdited(): void;
+    /** Was this ref handed out before the last hot update? False while no update has been observed. */
+    mintedBeforeLastEdit(ref: string): boolean;
     /** Get the existing ref for an element, or mint a new one. */
     refFor(el: Element): Ref;
     /**

package/dist/dom/refs.js

@@ -19,6 +19,8 @@ import { TRANSPORT_LIMITS, asRef } from '@reticlehq/core';
 export const MAX_TRACKED_REFS = 10000;
 /** Marks a ref that was too long to echo in full. */
 const REF_ELISION = '…';
+/** Every ref Reticle mints is this letter followed by its sequence number. */
+const REF_PREFIX = 'e';
 /**
  * A ref, made safe to interpolate into an error message.
  *
@@ -105,6 +107,15 @@ export class RefRegistry {
     /** The end of the block currently reserved. Minting past it claims the next one. */
     #reserved = 0;
     #mintsSinceSweep = 0;
+    /**
+     * The highest number handed out before the last hot update was applied, or 0 while none has been.
+     *
+     * A watermark rather than a per-ref stamp: the sequence never restarts within a document, so one
+     * number separates "minted before the code changed" from "minted after it" for every ref at once.
+     * The alternative — an epoch on every map entry — is bookkeeping paid on every mint for an answer
+     * needed only on the rare refusal.
+     */
+    #editedAtSeq = 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
@@ -156,6 +167,24 @@ export class RefRegistry {
         while (this.#fromRef.size > MAX_TRACKED_REFS)
             this.#evictOldest();
     }
+    /**
+     * A hot update just replaced modules in this document: every ref handed out so far was minted
+     * against the DOM the previous version of that code produced.
+     *
+     * Only the boundary is recorded. Nothing is evicted — a hot update is not a navigation, and most
+     * of the page survives one, so refs minted before it very often still resolve. This exists so the
+     * ones that DON'T can say why.
+     */
+    markEdited() {
+        this.#editedAtSeq = this.#seq;
+    }
+    /** Was this ref handed out before the last hot update? False while no update has been observed. */
+    mintedBeforeLastEdit(ref) {
+        if (0 === this.#editedAtSeq || !ref.startsWith(REF_PREFIX))
+            return false;
+        const n = Number(ref.slice(REF_PREFIX.length));
+        return Number.isSafeInteger(n) && n > 0 && n <= this.#editedAtSeq;
+    }
     /** Get the existing ref for an element, or mint a new one. */
     refFor(el) {
         const existing = this.#toRef.get(el);
@@ -173,7 +202,7 @@ export class RefRegistry {
         if (this.#seq >= this.#reserved)
             this.#reserve();
         this.#seq += 1;
-        const ref = asRef(`e${String(this.#seq)}`);
+        const ref = asRef(`${REF_PREFIX}${String(this.#seq)}`);
         this.#toRef.set(el, ref);
         this.#fromRef.set(ref, new WeakRef(el));
         // Keep bounded cheaply on every mint; run the full dead-entry sweep only periodically.

package/dist/dom/snapshot.d.ts

@@ -21,13 +21,50 @@ export interface SnapshotResult {
      * must not receive the entire page as if it were the modal.
      */
     scopeMissing?: boolean;
+    /**
+     * How many MEANINGFUL nodes the lean walk passed over, present only in a lean mode and only when
+     * non-zero. This is what stops an empty `interactive` tree reading as an empty page — the mode is
+     * a role filter, and a production app whose controls carry no roles yields nothing while being
+     * full of things to drive. It shipped untyped: the value was spread into the result and every
+     * consumer had to reach for it without a type, including the tool that builds the note from it.
+     */
+    leanSkipped?: number;
+    /**
+     * Refs of the subtree roots the walk never entered, present ONLY when `truncated`. This is the
+     * cut's own frontier: re-snapshot each with `{ scope: ref, includeRoot: true }` and the union is
+     * the whole tree. Without it `truncated` says only THAT the read stopped, never WHERE, so nobody
+     * could finish it — and a reader who does not finish it must not conclude anything is ABSENT.
+     */
+    unread?: string[];
+    /**
+     * True when the frontier itself did not fit in `MAX_UNREAD_BRANCHES`, so `unread` is a prefix of
+     * the branches that were cut. Completion is then impossible from this read, and the difference
+     * between "impossible" and "not attempted" is the whole point of saying so.
+     */
+    unreadOverflow?: true;
 }
 interface SnapshotOptions {
     scope?: string | undefined;
     mode?: SnapshotMode | undefined;
     maxNodes?: number | undefined;
     maxDepth?: number | undefined;
+    /**
+     * Emit the scope element's OWN line before its descendants. Off by default (a scoped snapshot has
+     * always been the subtree UNDER the scope); the completion re-read needs it, because the branch it
+     * is re-reading is exactly the node the truncated walk stopped before emitting.
+     */
+    includeRoot?: boolean | undefined;
 }
+/**
+ * Cap on how many cut branches one snapshot names.
+ *
+ * A hostile or merely huge DOM can cut thousands of siblings at once (a non-virtualized grid does it
+ * routinely), and a frontier that large is neither affordable to send nor useful to re-read one at a
+ * time. Fifty is well above what a real page's cut produces — the frontier is the branches at the
+ * node cap, not the nodes themselves — and small enough that the list stays a hint rather than a
+ * second snapshot. Past it the read declares `unreadOverflow` instead of quietly sending fewer.
+ */
+export declare const MAX_UNREAD_BRANCHES = 50;
 /** Build the semantic accessibility snapshot of the page or a subtree. */
 export declare function buildSnapshot(options?: SnapshotOptions): SnapshotResult;
 export {};