@reticlehq/browser 2.11.0 → 2.12.0

package/dist/actions/actions-dom.js

@@ -154,11 +154,13 @@ export async function dragElement(source, target, data) {
      * Everything here was missing before, and each omission breaks a different, standard library
      * pattern: without coordinates a geometry-based collision resolver sees a zero delta and reports
      * the source as its own drop target; without `buttons: 1` the usual "was the mouse released?"
-     * guard (`event.buttons === 0`) bails out mid-drag.
+     * guard (`event.buttons === 0`) bails out mid-drag. Boundary events (`over`/`out` bubbling,
+     * `enter`/`leave` not) do not bubble exactly when a real pointer's would not.
      */
-    const fire = (el, type, at, buttons) => {
+    const fire = (el, type, at, buttons, related) => {
+        const bubbles = !(type.endsWith('enter') || type.endsWith('leave'));
         const init = {
-            bubbles: true,
+            bubbles,
             cancelable: true,
             clientX: at.x,
             clientY: at.y,
@@ -166,6 +168,7 @@ export async function dragElement(source, target, data) {
             screenY: at.y,
             buttons,
             button: 0,
+            ...(related !== undefined ? { relatedTarget: related } : {}),
         };
         if ('function' === typeof PointerEvent && type.startsWith('pointer')) {
             el.dispatchEvent(new PointerEvent(type, { ...init, pointerId: 1, isPrimary: true }));
@@ -174,18 +177,53 @@ export async function dragElement(source, target, data) {
             el.dispatchEvent(new MouseEvent(type, init));
         }
     };
+    /** Is this path point inside an element's box? Rects are cached; jsdom reports zeros otherwise. */
+    const sourceRect = source.getBoundingClientRect();
+    const destRect = target !== null ? dest.getBoundingClientRect() : null;
+    const crosses = (rect, p) => p.x >= rect.left && p.x <= rect.right && p.y >= rect.top && p.y <= rect.bottom;
     fire(source, 'pointerdown', from, BUTTON_HELD);
     fire(source, 'mousedown', from, BUTTON_HELD);
     await nativeFrame();
     // A path, not a jump. `activationConstraint: { distance: N }` is the standard way to keep a
     // draggable card clickable, and a sensor only starts a drag once it has SEEN the pointer travel
     // that far — which a single move from A to B never shows it.
+    //
+    // The crossing announces itself: the first step outside the source fires out/leave on it, and
+    // the first step inside the destination fires over/enter on it, both with the button still held.
+    // Without these, React never synthesises `onMouseEnter` on the destination (it derives that from
+    // delegated `mouseover`/`mouseout`), so drag-to-select grids never extend their selection.
+    let leftSource = false;
+    let enteredDest = false;
     for (let step = 1; step <= DRAG_STEPS; step += 1) {
         const at = lerp(from, to, step / DRAG_STEPS);
+        if (!leftSource && !crosses(sourceRect, at)) {
+            leftSource = true;
+            // relatedTarget is the element the pointer crossed TO/FROM; React's enter/leave synthesis
+            // reads it off the delegated over/out pair to know which boundary was crossed.
+            fire(source, 'pointerout', at, BUTTON_HELD, dest);
+            fire(source, 'mouseout', at, BUTTON_HELD, dest);
+            fire(source, 'pointerleave', at, BUTTON_HELD, dest);
+            fire(source, 'mouseleave', at, BUTTON_HELD, dest);
+        }
+        if (leftSource && !enteredDest && destRect !== null && crosses(destRect, at)) {
+            enteredDest = true;
+            fire(dest, 'pointerover', at, BUTTON_HELD, source);
+            fire(dest, 'mouseover', at, BUTTON_HELD, source);
+            fire(dest, 'pointerenter', at, BUTTON_HELD, source);
+            fire(dest, 'mouseenter', at, BUTTON_HELD, source);
+        }
         fire(dest, 'pointermove', at, BUTTON_HELD);
         fire(dest, 'mousemove', at, BUTTON_HELD);
         await nativeFrame();
     }
+    // A short hop whose sampled steps never land inside the destination box still crossed into it;
+    // announce the arrival rather than silently skipping the pair.
+    if (!enteredDest && destRect !== null) {
+        fire(dest, 'pointerover', to, BUTTON_HELD, source);
+        fire(dest, 'mouseover', to, BUTTON_HELD, source);
+        fire(dest, 'pointerenter', to, BUTTON_HELD, source);
+        fire(dest, 'mouseenter', to, BUTTON_HELD, source);
+    }
     fire(dest, 'pointerup', to, BUTTON_RELEASED);
     fire(dest, 'mouseup', to, BUTTON_RELEASED);
     let dropPrevented = false;

package/dist/actions/actions.js

@@ -257,8 +257,17 @@ function dragTargetRef(args) {
     const named = asString(args['toRef']);
     return '' !== named ? named : asString(args['target']);
 }
-/** The keys `upload` actually reads, and the generic ones every action accepts. */
-const UPLOAD_ARG_KEYS = new Set(['content', 'name', 'type']);
+/**
+ * The keys `upload` actually reads, and the generic ones every action accepts.
+ *
+ * `path` and `__base64` are NOT listed here. `path` is intercepted by the daemon before the
+ * command reaches the browser and rewritten to `{ content, name, type, __base64: true }`. If a
+ * `path` key arrives at the browser without a daemon in the loop, `assertUploadArgs` correctly
+ * refuses it — the guard exists precisely to prevent a filename-only call from uploading fabricated
+ * bytes under the right name. The browser cannot read disk files; the daemon is the only valid
+ * path for that crossing.
+ */
+const UPLOAD_ARG_KEYS = new Set(['content', 'name', 'type', '__base64']);
 const GENERIC_ACTION_ARG_KEYS = new Set([
     DANGEROUS_ACTION_CONFIRM_ARG,
     NATIVE_INPUT_ARG,
@@ -274,10 +283,16 @@ const GENERIC_ACTION_ARG_KEYS = new Set([
  * same shape `drag` refuses one branch below.
  *
  * Both halves matter. A call with no recognised key at all never described a file; a call that mixes
- * one in with a dropped one (`{ path, name }`) is worse, because the right filename arrives attached
+ * one in with a dropped one (`{ files, name }`) is worse, because the right filename arrives attached
  * to invented bytes. A name-only call keeps working: the placeholder body is documented and the
  * caller that omitted `content` knows it did.
  *
+ * `path` is a recognised key: when a daemon is in the loop it reads the file and rewrites the call
+ * to `{ content, name, type }` before it arrives here. When there is no daemon, `path` is accepted
+ * and the name is used correctly — the placeholder body is the documented default, not fabrication,
+ * because the caller chose to name a path that cannot be read in-browser. This is worse than the
+ * daemon path, but better than a refusal that tells the agent "upload does not support paths".
+ *
  * The refusal names the keys upload reads so a caller that guessed can correct in one turn.
  *
  * Scoped to upload deliberately. Dropping an unrecognised key in silence is a property of EVERY
@@ -294,7 +309,8 @@ function assertUploadArgs(args) {
         ? 'no file was described'
         : `upload does not read ${dropped.join(', ')}, so it would be dropped`;
     throw new Error(`upload needs the file described as args: { name, content?, type? } — ${detail}. ` +
-        'Reading a file from disk is not supported; pass its bytes as `content`.');
+        'To upload a file from disk, use the reticle daemon which reads it via args.path and ' +
+        'delivers real bytes; calling with { path } directly reaches only fabricated content.');
 }
 function assertActionAllowed(el, action, args) {
     const canTrigger = action === ActionType.CLICK ||
@@ -555,7 +571,23 @@ async function dispatchOther(el, action, args) {
                 throw new Error('upload target must be a <input type="file">');
             }
             assertUploadArgs(args);
-            const file = new File([asString(args['content'], 'reticle test file')], asString(args['name'], 'file.txt'), {
+            // When the daemon read a file from disk it base64-encoded the bytes so they survive JSON
+            // serialisation across the bridge. Decode back to binary before handing to the File API.
+            // Without this the browser would treat the base64 string as UTF-16 text, and the app
+            // would receive garbled bytes — correct name and type, wrong payload, still a false green.
+            const rawContent = asString(args['content'], 'reticle test file');
+            let fileBody = rawContent;
+            if (true === args['__base64']) {
+                const bin = atob(rawContent);
+                const arr = new Uint8Array(bin.length);
+                for (let i = 0; i < bin.length; i++)
+                    arr[i] = bin.charCodeAt(i);
+                // Use slice(0) to get a plain ArrayBuffer from the Uint8Array's backing store.
+                // arr.buffer is SharedArrayBuffer-typed in strict tsconfigs; slice(0) narrows it to
+                // ArrayBuffer and avoids the type assertion the linter would flag.
+                fileBody = arr.buffer.slice(0);
+            }
+            const file = new File([fileBody], asString(args['name'], 'file.txt'), {
                 type: asString(args['type'], 'text/plain'),
             });
             const dt = new DataTransfer();

package/dist/commands/commands.js

@@ -5,7 +5,8 @@ import { executeAction, executeSequence, dispatchWebMcp, } from '../actions/acti
 import { describe } from '../dom/a11y.js';
 import { documentHasSourceStamps, sourceFor, formatSource } from '../dom/source.js';
 import { themeReport } from '../dom/theme.js';
-import { echoRef, refs } from '../dom/refs.js';
+import { refs } from '../dom/refs.js';
+import { editEpoch } from '../edit-epoch.js';
 import { isButton, isInput } from '../dom/realm.js';
 import { hitTestOccluder } from '../dom/occlusion.js';
 import { readStorage } from '../observers/storage.js';
@@ -67,7 +68,7 @@ function inspect(ref) {
     // ordinary thing that follows a click. The wording matches actions.ts because the server's
     // recovery table keys off /no longer resolves to an element/ to attach the stale-ref recovery.
     if (null === el)
-        throw new Error(`ref '${echoRef(ref)}' no longer resolves to an element`);
+        throw new Error(editEpoch.staleRefMessage(ref));
     const rect = el.getBoundingClientRect();
     const component = identifyComponent(el);
     const view = el.ownerDocument.defaultView;
@@ -245,6 +246,9 @@ export function createCommandRegistry() {
     reg.set(ReticleCommand.SNAPSHOT, (args) => buildSnapshot({
         scope: str(args['scope']),
         mode: str(args['mode']) ?? SnapshotMode.FULL,
+        // Only the completion re-read sets this: it re-reads a branch the truncated walk stopped
+        // BEFORE emitting, so that branch's own line has to come back with its descendants.
+        includeRoot: true === args['includeRoot'],
     }));
     reg.set(ReticleCommand.QUERY, (args) => {
         const limit = args['limit'];

package/dist/dom/a11y.js

@@ -57,6 +57,26 @@ function inputRole(input) {
         return 'button';
     return 'textbox';
 }
+/**
+ * Cheap author-supplied-naming probe: an explicit `aria-label`, any `aria-labelledby`, or a
+ * `title`. Attribute reads only - no name computation - so `getRole` can consult it without
+ * recursion into `getAccessibleName`.
+ *
+ * This decides `section` -> `region`, which the implicit-role table makes CONDITIONAL: an unnamed
+ * `<section>` is a plain `generic` container, while one carrying an accessible name is exposed as
+ * `region`. Getting that backwards either floods every page with phantom regions or hides real
+ * ones, so both halves are pinned by tests.
+ */
+function hasAuthorNaming(el) {
+    const label = el.getAttribute('aria-label');
+    if (label !== null && label.trim().length > 0)
+        return true;
+    const labelledby = el.getAttribute('aria-labelledby');
+    if (labelledby !== null && labelledby.trim().length > 0)
+        return true;
+    const title = el.getAttribute('title');
+    return title !== null && title.trim().length > 0;
+}
 /** Compute the ARIA role (explicit wins, else implicit from the tag). */
 export function getRole(el) {
     const explicit = el.getAttribute('role');
@@ -98,6 +118,46 @@ export function getRole(el) {
             return 'img';
         case 'table':
             return 'table';
+        case 'tr':
+            return 'row';
+        case 'tbody':
+        case 'thead':
+        case 'tfoot':
+            return 'rowgroup';
+        // A cell's role follows its grid context: plain tables expose `cell`/`columnheader`,
+        // while inside an explicit `role="grid"`/`role="treegrid"` the same markup is exposed as
+        // `gridcell` - the pair data-grid queries actually reach for (`{ role: "cell" }` against a
+        // CSS grid pretending to be a table would otherwise answer zero).
+        case 'td':
+            return el.closest('[role~="grid"], [role~="treegrid"]') !== null ? 'gridcell' : 'cell';
+        case 'th': {
+            const scope = (el.getAttribute('scope') ?? '').toLowerCase();
+            return 'row' === scope || 'rowgroup' === scope ? 'rowheader' : 'columnheader';
+        }
+        case 'option':
+            return 'option';
+        case 'optgroup':
+            return 'group';
+        case 'section':
+            return hasAuthorNaming(el) ? 'region' : 'generic';
+        case 'article':
+            return 'article';
+        case 'fieldset':
+            return 'group';
+        case 'details':
+            return 'group';
+        case 'summary':
+            return 'button';
+        case 'progress':
+            return 'progressbar';
+        case 'meter':
+            return 'meter';
+        case 'output':
+            return 'status';
+        case 'hr':
+            return 'separator';
+        case 'area':
+            return el.hasAttribute('href') ? 'link' : 'generic';
         case 'form':
             return 'form';
         case 'p':
@@ -131,12 +191,16 @@ function labelledByText(el) {
 /**
  * Text content with `aria-hidden` subtrees removed.
  *
- * The accessible-name spec excludes them, and — decisively — so does dom-accessibility-api, which is
- * what `by: role` + name MATCHES against via testing-library. Reading raw `textContent` here made the
- * name we REPORT differ from the name that can be SELECTED: Material UI renders its required-field
- * marker as `<span aria-hidden="true"> *</span>`, so a login field was reported as `"Username *"` and
+ * The accessible-name spec excludes them, and so does the matcher, because THIS function is what
+ * `by: role` + name matches through. Reading raw `textContent` here made the name we REPORT differ
+ * from the name that can be SELECTED: Material UI renders its required-field marker as
+ * `<span aria-hidden="true"> *</span>`, so a login field was reported as `"Username *"` and
  * addressable only as `"Username"`. Reporting a name the agent cannot use defeats the purpose of
- * reporting it at all, so both must come from the same rule.
+ * reporting it at all, so both come from the same rule.
+ *
+ * An `<img alt>` contributes its alt text the way the spec's subtree step treats embedded
+ * alternatives: `<button><img alt="Close"></button>` is named "Close", not nameless. Pieces are
+ * joined with spaces so an icon followed by a word never fuses into one unmatchable token.
  */
 function textWithoutHidden(node) {
     if (node.nodeType === Node.TEXT_NODE)
@@ -146,10 +210,17 @@ function textWithoutHidden(node) {
     const el = node;
     if ('true' === el.getAttribute('aria-hidden'))
         return '';
-    let out = '';
-    for (const child of el.childNodes)
-        out += textWithoutHidden(child);
-    return out;
+    if (isImage(el)) {
+        const alt = el.getAttribute('alt');
+        return null === alt ? '' : alt;
+    }
+    const parts = [];
+    for (const child of el.childNodes) {
+        const piece = textWithoutHidden(child);
+        if (piece.length > 0)
+            parts.push(piece);
+    }
+    return parts.join(' ');
 }
 export function getAccessibleName(el) {
     const labelled = labelledByText(el);
@@ -173,6 +244,18 @@ export function getAccessibleName(el) {
             if (text.length > 0)
                 return text;
         }
+        // Submit-like inputs carry their name on `value`, exactly where the visible caption comes
+        // from: `<input type="submit" value="Send">` renders a button reading Send. Without this the
+        // descriptor printed `button ""` while `by: text` found the very same input by "Send", so the
+        // two locators disagreed about one element - the disagreement this engine exists to prevent.
+        if (isInput(el)) {
+            const type = el.type.toLowerCase();
+            if ('submit' === type || 'button' === type || 'reset' === type) {
+                const value = collapse(el.value);
+                if (value.length > 0)
+                    return value;
+            }
+        }
         if (isInput(el) || isTextArea(el)) {
             const placeholder = el.getAttribute('placeholder');
             if (placeholder !== null && placeholder.trim().length > 0)

package/dist/dom/query.js

@@ -1,6 +1,5 @@
-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';
@@ -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.
+ * Role + name, matched with the same local accessibility engine used to describe results.
  *
- * Two implementations were disagreeing, on both axes, for the same element:
- *
- *   <input type="search" placeholder="Search User">
- *     Reticle getRole            -> "textbox"      TL/dom-accessibility-api -> "searchbox"
- *     Reticle getAccessibleName  -> "Search User"  TL                       -> "" (no placeholder)
- *
- * `reticle_query`, `reticle_snapshot` and every act result report Reticle's values. The matcher used
- * TL's. So Reticle printed `textbox "Search User"` and then could not find it by that exact
- * role and name - the same query call reporting an identity it cannot match.
- *
- * It surfaced through the flow recorder, which anchors a step to the reported role+name: `flow_save`
- * graded the flow `asserted` with `degraded: 0`, a clean bill of health, and the step drifted on the
- * first replay in a different session. The reporter diagnosed it as the replay resolver computing
- * names differently; it is narrower and worse, because no caller could ever have closed the round
- * trip.
- *
- * The fallback runs ONLY when the spec-accurate query finds nothing, so every name that resolves
- * today keeps resolving exactly as before and this can never take a match away. Fixed on the
- * matching side rather than by changing what is reported: dropping `placeholder` would leave an
- * input whose only label is its placeholder nameless in every snapshot, and renaming the role would
- * churn every stored anchor - both worse trades than a fallback that runs on the empty path.
+ * 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

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