@reticlehq/browser 2.6.0 → 2.7.0

package/dist/actions/actions-dom.d.ts

@@ -30,6 +30,10 @@ export declare function firePointerNonBubbling(el: Element, type: string, relate
 /**
  * Pointer-based drag (dnd-kit / react-beautiful-dnd) + best-effort HTML5 DnD. Async: yields a
  * frame between phases so React commits state between steps (fixes stale-closure handlers).
+ *
+ * Dispatches along a PATH with real client coordinates and a held button. Without those a
+ * geometry-based library resolves the drop target as the source, so the action reports success over
+ * an app that did not change — a false green produced by the tool rather than caught by it.
  */
 export declare function dragElement(source: HTMLElement, target: HTMLElement | null, data: unknown): Promise<boolean>;
 export {};

package/dist/actions/actions-dom.js

@@ -109,28 +109,77 @@ function makeDataTransfer(data) {
     }
     return dt;
 }
+/** `buttons` bitmask for the primary button: 1 while held, 0 once released. */
+const BUTTON_HELD = 1;
+const BUTTON_RELEASED = 0;
+/**
+ * How many intermediate moves a drag emits.
+ *
+ * Enough to cross any realistic `activationConstraint: { distance: N }` while a sensor is watching,
+ * and few enough that a drag stays a handful of frames rather than an animation.
+ */
+const DRAG_STEPS = 5;
+/** The centre of an element in client coordinates — what a real pointer would be over. */
+function centreOf(el) {
+    const box = el.getBoundingClientRect();
+    return { x: box.left + box.width / 2, y: box.top + box.height / 2 };
+}
+/** A point `t` of the way from `a` to `b`, rounded — pointer coordinates are integers in practice. */
+function lerp(a, b, t) {
+    return { x: Math.round(a.x + (b.x - a.x) * t), y: Math.round(a.y + (b.y - a.y) * t) };
+}
 /**
  * Pointer-based drag (dnd-kit / react-beautiful-dnd) + best-effort HTML5 DnD. Async: yields a
  * frame between phases so React commits state between steps (fixes stale-closure handlers).
+ *
+ * Dispatches along a PATH with real client coordinates and a held button. Without those a
+ * geometry-based library resolves the drop target as the source, so the action reports success over
+ * an app that did not change — a false green produced by the tool rather than caught by it.
  */
 export async function dragElement(source, target, data) {
     const dest = target ?? source;
-    const fire = (el, type) => {
+    const from = centreOf(source);
+    const to = centreOf(dest);
+    /**
+     * Dispatch ONE pointer/mouse pair with real coordinates and button state.
+     *
+     * 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.
+     */
+    const fire = (el, type, at, buttons) => {
+        const init = {
+            bubbles: true,
+            cancelable: true,
+            clientX: at.x,
+            clientY: at.y,
+            screenX: at.x,
+            screenY: at.y,
+            buttons,
+            button: 0,
+        };
         if ('function' === typeof PointerEvent && type.startsWith('pointer')) {
-            el.dispatchEvent(new PointerEvent(type, { bubbles: true, cancelable: true }));
+            el.dispatchEvent(new PointerEvent(type, { ...init, pointerId: 1, isPrimary: true }));
         }
         else {
-            el.dispatchEvent(new MouseEvent(type, { bubbles: true, cancelable: true }));
+            el.dispatchEvent(new MouseEvent(type, init));
         }
     };
-    fire(source, 'pointerdown');
-    fire(source, 'mousedown');
+    fire(source, 'pointerdown', from, BUTTON_HELD);
+    fire(source, 'mousedown', from, BUTTON_HELD);
     await nativeFrame();
-    fire(dest, 'pointermove');
-    fire(dest, 'mousemove');
-    await nativeFrame();
-    fire(dest, 'pointerup');
-    fire(dest, 'mouseup');
+    // 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.
+    for (let step = 1; step <= DRAG_STEPS; step += 1) {
+        const at = lerp(from, to, step / DRAG_STEPS);
+        fire(dest, 'pointermove', at, BUTTON_HELD);
+        fire(dest, 'mousemove', at, BUTTON_HELD);
+        await nativeFrame();
+    }
+    fire(dest, 'pointerup', to, BUTTON_RELEASED);
+    fire(dest, 'mouseup', to, BUTTON_RELEASED);
     let dropPrevented = false;
     if ('function' === typeof DragEvent) {
         const dataTransfer = makeDataTransfer(data);

package/dist/actions/actions.js

@@ -112,13 +112,112 @@ function dangerousActionContext(el) {
 function requiresDangerousConfirmation(text) {
     return isDangerousActionText(text);
 }
+/**
+ * Which key a `press` is asking for.
+ *
+ * `text` FIRST, because that is what the tool description documents ("{ text } for type/press") and
+ * therefore what agents send. The implementation read only `args['key']` and defaulted to `'Enter'`,
+ * so the documented call — `press` with `{ text: 'Escape' }` — silently dispatched **Enter** and
+ * reported success. Two field reports blamed "synthetic events not reaching the app"; the events
+ * arrived perfectly and said the wrong thing.
+ *
+ * Enter is the worst possible substitute to pick by accident: on a focused field inside a form it
+ * SUBMITS it, so a request to dismiss a dialog could file the form behind it. `key` still works —
+ * it is what anyone reading the source would have sent — and the default only applies when neither
+ * was named.
+ */
+function pressKey(args) {
+    const text = args['text'];
+    if ('string' === typeof text && text.length > 0)
+        return text;
+    return asString(args['key'], 'Enter');
+}
+/**
+ * The PHYSICAL key identity — `event.code` — derived from the logical key.
+ *
+ * A real browser always sends both, and a meaningful class of library reads only `code`, because it
+ * is the layout-independent one: dnd-kit's KeyboardSensor matches its activation and arrow keys on
+ * it, and so does react-aria. We sent `key` alone, so those handlers simply never matched — the
+ * event fired, the listener ran, the guard failed, and the action reported dispatched over an app
+ * that did nothing. Reported from the field as a keyboard drag that could be neither started nor
+ * steered.
+ *
+ * An explicit `code` always wins: a caller driving a non-US layout knows something this derivation
+ * cannot. And an unrecognised multi-character key yields `''` rather than a guess — a wrong `code`
+ * is worse than none, because a handler will act on it.
+ */
+function pressCode(args, key) {
+    const explicit = args['code'];
+    if ('string' === typeof explicit && explicit.length > 0)
+        return explicit;
+    if (' ' === key)
+        return 'Space';
+    if (1 === key.length) {
+        if (/[a-z]/i.test(key))
+            return `Key${key.toUpperCase()}`;
+        if (/[0-9]/.test(key))
+            return `Digit${key}`;
+        return '';
+    }
+    // Named keys — 'Enter', 'Escape', 'Tab', 'ArrowDown' — already ARE their own code.
+    return /^[A-Z][A-Za-z0-9]*$/.test(key) && KNOWN_NAMED_KEYS.has(key) ? key : '';
+}
+/**
+ * Named keys whose `code` equals their `key`. An allow-list rather than a shape test: `Zzz` looks
+ * exactly like `Tab` to a regex, and inventing `code: "Zzz"` would be a confident fabrication.
+ */
+const KNOWN_NAMED_KEYS = new Set([
+    'Enter',
+    'Escape',
+    'Tab',
+    'Backspace',
+    'Delete',
+    'Home',
+    'End',
+    'PageUp',
+    'PageDown',
+    'ArrowUp',
+    'ArrowDown',
+    'ArrowLeft',
+    'ArrowRight',
+    'Insert',
+    'F1',
+    'F2',
+    'F3',
+    'F4',
+    'F5',
+    'F6',
+    'F7',
+    'F8',
+    'F9',
+    'F10',
+    'F11',
+    'F12',
+]);
+/**
+ * The drop target a `drag` names, under either spelling.
+ *
+ * `toRef` is what the source has always read and it appears NOWHERE in the tool description an
+ * agent sees — the `args` sentence names `value`, `text`, `native`, `holdMs` and `confirmDangerous`
+ * and omits the one argument without which this action cannot do its job. So agents guess, and
+ * `target` is the guess they make. Accepting it costs nothing and removes a whole class of
+ * silently-target-less drags; the description now documents `toRef` as well.
+ */
+function dragTargetRef(args) {
+    const named = asString(args['toRef']);
+    return '' !== named ? named : asString(args['target']);
+}
 function assertActionAllowed(el, action, args) {
     const canTrigger = action === ActionType.CLICK ||
         action === ActionType.DBLCLICK ||
         action === ActionType.DRAG ||
         action === ActionType.SUBMIT ||
-        (action === ActionType.PRESS && 'Enter' === asString(args['key'], 'Enter'));
-    const dragTarget = action === ActionType.DRAG ? refs.resolve(asString(args['toRef'])) : null;
+        // Read through the SAME resolver as the dispatch below. Reading a different argument here meant
+        // the destructive-action guard classified the call by a key nobody had asked for.
+        (action === ActionType.PRESS && 'Enter' === pressKey(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);
@@ -304,13 +403,39 @@ async function dispatchOther(el, action, args) {
             }
             throw new Error(`cannot select on a <${el.tagName.toLowerCase()}>`);
         case ActionType.CHECK:
-        case ActionType.UNCHECK:
-            if (isInput(el)) {
-                el.checked = action === ActionType.CHECK;
-                el.dispatchEvent(new Event('change', { bubbles: true }));
+        case ActionType.UNCHECK: {
+            if (!isInput(el))
+                throw new Error(`cannot (un)check a <${el.tagName.toLowerCase()}>`);
+            // Same rule as the readonly/disabled refusal on fill: if a real user could not do it, forcing
+            // it is not a test, it is damage — and a green over it is a false one.
+            if (!enabledOf(el)) {
+                throw new Error(`cannot ${action} a disabled control — a real user could not, so neither will Reticle`);
+            }
+            const wanted = action === ActionType.CHECK;
+            // Already there: report success and touch nothing. `check` means "end up checked", not
+            // "toggle", so clicking here would flip it OFF and hand the app an event no user produced.
+            if (el.checked === wanted)
                 return false;
+            // `click()`, never `el.checked = …`. Assigning the property flips the pixel and tells no
+            // framework: React binds a checkbox's onChange to the CLICK event, and its value tracker
+            // dedups the change it would otherwise synthesise from a direct assignment — so a controlled
+            // `checked={state}` box never heard from us while the action reported success. `click()` is
+            // the one DOM call that runs the element's ACTIVATION BEHAVIOUR (the native toggle) as well
+            // as firing the event; `dispatchEvent` does not.
+            let prevented = false;
+            // On window, so it runs after every listener on the element itself whenever they were added.
+            const probe = (e) => {
+                prevented = e.defaultPrevented;
+            };
+            window.addEventListener('click', probe, { once: true, capture: false });
+            try {
+                el.click();
+            }
+            finally {
+                window.removeEventListener('click', probe, false);
             }
-            throw new Error(`cannot (un)check a <${el.tagName.toLowerCase()}>`);
+            return prevented;
+        }
         case ActionType.SUBMIT: {
             const form = isForm(el) ? el : el.closest('form');
             if (null === form)
@@ -319,9 +444,10 @@ async function dispatchOther(el, action, args) {
             return false; // requestSubmit returns void; the internal submit event is unobservable.
         }
         case ActionType.PRESS: {
-            const key = asString(args['key'], 'Enter');
-            const down = el.dispatchEvent(new KeyboardEvent('keydown', { key, bubbles: true, cancelable: true }));
-            el.dispatchEvent(new KeyboardEvent('keyup', { key, bubbles: true }));
+            const key = pressKey(args);
+            const code = pressCode(args, key);
+            const down = el.dispatchEvent(new KeyboardEvent('keydown', { key, code, bubbles: true, cancelable: true }));
+            el.dispatchEvent(new KeyboardEvent('keyup', { key, code, bubbles: true }));
             return !down;
         }
         case ActionType.SCROLL_INTO_VIEW:
@@ -342,11 +468,21 @@ async function dispatchOther(el, action, args) {
             return !inputOk;
         }
         case ActionType.DRAG: {
-            const toRef = asString(args['toRef']);
+            const toRef = dragTargetRef(args);
             // asString falls back to '' (never undefined), so the old `!== undefined` was always true and
-            // handed '' to refs.resolve. A drag with no target ref is a free drag — resolve nothing.
-            const resolved = toRef !== '' ? refs.resolve(toRef) : null;
-            return await dragElement(el, isHtmlElement(resolved) ? resolved : null, args['data']);
+            // handed '' to refs.resolve. A drag with NO target named is a free drag — resolve nothing.
+            if ('' === toRef)
+                return await dragElement(el, null, args['data']);
+            // A target WAS named and did not resolve. That is a malformed call, not a free drag: dragging
+            // nowhere and reporting `ok: true` is a false green, and it is the one this action produced
+            // in the field — the drop target argument is undocumented, the agent guessed a name, the guess
+            // read as "no target", and the drag landed nowhere while every effect field looked healthy.
+            const resolved = refs.resolve(toRef);
+            if (!isHtmlElement(resolved)) {
+                throw new Error(`drag target '${echoRef(toRef)}' did not resolve to an element — pass a ref from ` +
+                    'reticle_snapshot or reticle_query as args.toRef (alias: args.target)');
+            }
+            return await dragElement(el, resolved, args['data']);
         }
         default:
             throw new Error(`unknown action '${action}'`);

package/dist/commands/commands.js

@@ -48,6 +48,11 @@ function queryFromArgs(args) {
         alt: str(args['alt']),
         component: str(args['component']),
         scope: str(args['scope']),
+        // The THIRD allowlist a query input has to appear in — tool schema, server forward, and here.
+        // `self` was in the first two and missing from this one, so a live call returned zero matches on
+        // an element that was plainly on the page, with no error to explain it. Same shape as the
+        // `attrs` drop below it.
+        self: true === args['self'] ? true : undefined,
         attrs: Array.isArray(args['attrs'])
             ? args['attrs'].filter((a) => 'string' === typeof a)
             : undefined,

package/dist/dom/query.js

@@ -259,6 +259,16 @@ function findCandidates(query) {
     // 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
+    // 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) {
+        if (query.scope === undefined)
+            return { candidates: [], scopeMissing };
+        return { candidates: isIgnored(container) ? [] : [container], scopeMissing };
+    }
     const seen = new Set();
     const out = [];
     const collect = (els) => {

package/dist/observers/network.js

@@ -449,6 +449,10 @@ export function installNetwork(emit, opts = {}) {
                     });
                 });
             }
+            // `override` is required, not decorative: this shadows WebSocket.prototype.send, and without
+            // the keyword a rename or signature drift in the base class would silently turn this from an
+            // override into a NEW method — the observer would stop intercepting and report no WebSocket
+            // traffic at all, which reads as "the app sends none". Caught by noImplicitOverride.
             send(data) {
                 if (this.#isBridge) {
                     super.send(data);

package/dist/reticle.js

@@ -160,7 +160,7 @@ export class Reticle {
         // Dev-only backstop: refuse to activate in a production build (SSR healthcheck, prod bundle opened
         // on localhost). `process` may not exist in a raw browser, so read NODE_ENV off globalThis.
         const proc = globalThis.process;
-        const nodeEnv = proc?.env?.NODE_ENV;
+        const nodeEnv = proc?.env?.['NODE_ENV'];
         if (shouldBlockProduction(nodeEnv, true === options.allowInProduction)) {
             globalThis.console.warn('[Reticle] disabled in production (NODE_ENV=production). Gate the import behind ' +
                 'import.meta.env.DEV, or pass allowInProduction:true to override.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/browser",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "Reticle browser SDK — installs observers, builds semantic snapshots, executes actions, talks to the bridge.",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,7 +14,7 @@
   },
   "dependencies": {
     "@testing-library/dom": "^10.4.1",
-    "@reticlehq/core": "2.6.0"
+    "@reticlehq/core": "2.7.0"
   },
   "devDependencies": {
     "@tanstack/query-core": "^5.101.4",