@reticlehq/browser 2.11.0 → 2.13.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

@@ -142,8 +142,8 @@ function dangerousActionContext(el) {
         form?.getAttribute('action') ?? '',
     ].join(' ');
 }
-function requiresDangerousConfirmation(text) {
-    return isDangerousActionText(text);
+function requiresDangerousConfirmation(text, role) {
+    return isDangerousActionText(text, role);
 }
 /**
  * Which key a `press` is asking for.
@@ -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 ||
@@ -309,11 +325,11 @@ function assertActionAllowed(el, action, args) {
     // Same resolver as the dispatch below, so the destructive-action guard cannot classify a drag
     // by a target the dispatch will not use.
     const dragTarget = action === ActionType.DRAG ? refs.resolve(dragTargetRef(args)) : null;
-    const context = isHtmlElement(dragTarget)
-        ? `${dangerousActionContext(el)} ${dangerousActionContext(dragTarget)}`
-        : dangerousActionContext(el);
+    const sourceDangerous = requiresDangerousConfirmation(dangerousActionContext(el), getRole(el));
+    const targetDangerous = isHtmlElement(dragTarget) &&
+        requiresDangerousConfirmation(dangerousActionContext(dragTarget), getRole(dragTarget));
     if (canTrigger &&
-        requiresDangerousConfirmation(context) &&
+        (sourceDangerous || targetDangerous) &&
         args[DANGEROUS_ACTION_CONFIRM_ARG] !== true) {
         throw new Error(`potentially destructive action blocked; retry with args.${DANGEROUS_ACTION_CONFIRM_ARG}=true`);
     }
@@ -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/connect-options.d.ts

@@ -17,7 +17,11 @@ export interface ReticleConnectOptions {
      * agent scope to the right app even when its dev server boots on an unexpected port. Optional.
      */
     projectId?: string;
-    /** Browser/bridge pairing token. Required when either endpoint is non-localhost. */
+    /**
+     * Browser/bridge pairing token. Required whenever the daemon has one, which is the ordinary case:
+     * it auto-provisions `~/.reticle/pairing-token` on first start and then refuses a hello without it,
+     * including on localhost. Non-localhost additionally needs `allowNonLocalhost`.
+     */
     token?: string;
     /** Explicitly allow Reticle on a non-localhost page or bridge. Requires token. */
     allowNonLocalhost?: boolean;
@@ -35,6 +39,19 @@ export interface ReticleConnectOptions {
      * sensitive keys redacted, per-body capped). Off by default - bodies cost tokens and can carry PII.
      */
     captureNetworkBodies?: boolean;
+    /**
+     * Make Reticle's OWN presenter visible to snapshots and queries. CONTRIBUTORS ONLY.
+     *
+     * The presenter is hidden from every tool by design, for a good reason: an agent that can drive
+     * Reticle's own interface can fabricate its own impact report, and Reticle chrome in a snapshot is
+     * noise in every other app on earth.
+     *
+     * The cost of that rule is that a HUD change is the only kind of change Reticle cannot be used to
+     * check — the panel rendering it is invisible to everything that could look at it. This hatch
+     * exists for exactly that case: the app under test IS Reticle. It reports itself in the app's
+     * capabilities, so a verdict drawn with it open can never be mistaken for an ordinary one.
+     */
+    exposePresenter?: boolean;
     /**
      * The project root, so source paths report repo-relative instead of absolute.
      *

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

@@ -4,6 +4,15 @@
  * presenter, so omitting its selector here leaked annotation chrome into every snapshot.
  */
 export declare const RETICLE_OVERLAY: string;
+/**
+ * Make Reticle's own presenter visible to snapshots and queries. Contributors only.
+ *
+ * Deliberately a function rather than a field on the ignore set, so the one place that decides
+ * "is this ours" also decides "may it be seen", and no caller can half-apply it.
+ */
+export declare function setPresenterVisible(visible: boolean): void;
+/** Whether the hatch is open — reported in the app's capabilities so a verdict is never mistaken. */
+export declare function isPresenterVisible(): boolean;
 /** Let the host app add selectors to exclude from snapshots (e.g. its own dev widgets). */
 export declare function setIgnoreSelectors(selectors: string[]): void;
 /** True if the element is part of Reticle's own presenter overlay. */

package/dist/dom/dom-ignore.js

@@ -7,6 +7,34 @@ export const RETICLE_OVERLAY = '[data-reticle-overlay],[data-reticle-cursor],[da
 /** 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 = '';
+/**
+ * Whether Reticle's OWN UI is visible to snapshots and queries.
+ *
+ * Off, always, unless an app opts in — and the opt-in exists for exactly one situation: the app
+ * under test IS Reticle. A HUD change is otherwise the only kind of change Reticle cannot be used to
+ * check, because the panel that renders it is invisible to every tool that could look at it.
+ *
+ * It stays off by default because the reason for hiding it is sound: an agent that can drive
+ * Reticle's own interface can fabricate its own impact report, and a snapshot full of Reticle chrome
+ * is noise in every other app on earth. This is a hatch for contributors, not a setting.
+ *
+ * Third-party dev overlays stay ignored either way — they are somebody else's furniture and were
+ * never the thing being verified.
+ */
+let presenterVisible = false;
+/**
+ * Make Reticle's own presenter visible to snapshots and queries. Contributors only.
+ *
+ * Deliberately a function rather than a field on the ignore set, so the one place that decides
+ * "is this ours" also decides "may it be seen", and no caller can half-apply it.
+ */
+export function setPresenterVisible(visible) {
+    presenterVisible = visible;
+}
+/** Whether the hatch is open — reported in the app's capabilities so a verdict is never mistaken. */
+export function isPresenterVisible() {
+    return presenterVisible;
+}
 /** Let the host app add selectors to exclude from snapshots (e.g. its own dev widgets). */
 export function setIgnoreSelectors(selectors) {
     extraIgnore = selectors.join(',');
@@ -35,8 +63,9 @@ export function isReticleUi(node) {
 }
 /** True if the element should be excluded from snapshots/queries (Reticle overlay or dev overlay). */
 export function isIgnored(el) {
-    const sel = extraIgnore.length > 0
-        ? `${RETICLE_OVERLAY},${DEV_OVERLAYS},${extraIgnore}`
-        : `${RETICLE_OVERLAY},${DEV_OVERLAYS}`;
+    // With the hatch open, Reticle's own overlay drops out of the ignore set — but the third-party
+    // dev overlays do not. They are somebody else's furniture and were never the thing being verified.
+    const ours = presenterVisible ? '' : RETICLE_OVERLAY;
+    const sel = [ours, DEV_OVERLAYS, extraIgnore].filter((part) => part.length > 0).join(',');
     return el.closest(sel) !== null;
 }