@reticlehq/browser 2.13.1 → 2.14.0

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

@@ -4,12 +4,6 @@ interface ClickGeometry {
     scrolledIntoView: boolean;
 }
 export declare const NO_GEOMETRY: ClickGeometry;
-/**
- * Full click as a real user produces it: pointerdown -> mousedown -> focus -> pointerup -> mouseup
- * -> click. A bare `click` event skips pointer- and focus-gated handlers. Returns the click event's
- * `defaultPrevented` so the probe is unchanged. Focus only moves for focusable targets (tabIndex>=0),
- * so a plain <div> click still reports focusMoved=null.
- */
 export declare function fireClickSequence(el: HTMLElement, hold?: {
     ms: number;
     sleep: (ms: number) => Promise<void>;
@@ -18,22 +12,8 @@ export declare function fireClickSequence(el: HTMLElement, hold?: {
     prevented: boolean;
     heldMs: number;
 }>;
-/**
- * Click-like geometry honesty: scroll an off-viewport target into view, then hit-test the click
- * point. Synthetic dispatch always reaches the target regardless — this is purely so the agent
- * learns when the target is off-screen or visually blocked instead of getting a false "it worked".
- */
 export declare function clickGeometry(el: HTMLElement): ClickGeometry;
 export declare function firePointer(el: Element, type: string, relatedTarget?: EventTarget | null): void;
-/** Enter/leave pointer events are non-bubbling per spec; keep them so to avoid double-firing. */
 export declare function firePointerNonBubbling(el: Element, type: string, relatedTarget?: EventTarget | null): void;
-/**
- * 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

@@ -7,12 +7,6 @@ export const NO_GEOMETRY = {
     occludedBy: null,
     scrolledIntoView: false,
 };
-/**
- * Full click as a real user produces it: pointerdown -> mousedown -> focus -> pointerup -> mouseup
- * -> click. A bare `click` event skips pointer- and focus-gated handlers. Returns the click event's
- * `defaultPrevented` so the probe is unchanged. Focus only moves for focusable targets (tabIndex>=0),
- * so a plain <div> click still reports focusMoved=null.
- */
 export async function fireClickSequence(el, hold) {
     const doc = el.ownerDocument;
     const from = doc.activeElement ?? doc.body;
@@ -20,14 +14,6 @@ export async function fireClickSequence(el, hold) {
     asSyntheticInput(() => el.dispatchEvent(new MouseEvent('mousedown', { bubbles: true, cancelable: true })));
     if (el.tabIndex >= 0 && 'function' === typeof el.focus)
         el.focus();
-    // The gap that makes hold-to-confirm driveable. Everything between down and up used to be
-    // synchronous, so a control whose contract is "the button is down for N ms" could not be
-    // expressed at all — the reported case cancelled its own confirm on the mouseup that arrived 7ms
-    // later. `drag` already splits the pair across a gap; this is that shape with a timer.
-    //
-    // The ACHIEVED hold is measured and returned rather than echoed back: `holdMs: 1200` against a
-    // 1200ms animation is a race by construction, and a caller needs to tell "held 1200" from
-    // "held 1204". A backgrounded tab throttles timers, so this can legitimately overshoot by a lot.
     let heldMs = 0;
     if (hold !== undefined && hold.ms > 0) {
         const startedAt = hold.now();
@@ -36,17 +22,12 @@ export async function fireClickSequence(el, hold) {
     }
     firePointer(el, 'pointerup', from);
     asSyntheticInput(() => el.dispatchEvent(new MouseEvent('mouseup', { bubbles: true, cancelable: true })));
-    // Marked as ours so the annotator's capture-phase listener lets it through. Only the CHECK branch
-    // used to do this, so the ordinary click action — which is this function — was swallowed whole in
-    // annotate mode while still reporting `dispatched: true`.
     const notPrevented = asSyntheticInput(() => el.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true })));
     return { prevented: !notPrevented, heldMs };
 }
-/** A box has layout we can reason about (jsdom returns an all-zero box — nothing to hit-test). */
 function isMeasurable(rect) {
     return rect.width > 0 || rect.height > 0;
 }
-/** The center of `rect` falls outside the visible viewport. */
 function isOffViewport(el, rect) {
     const win = el.ownerDocument.defaultView;
     if (null === win)
@@ -55,18 +36,12 @@ function isOffViewport(el, rect) {
     const cy = rect.top + rect.height / 2;
     return cx < 0 || cy < 0 || cx > win.innerWidth || cy > win.innerHeight;
 }
-/** Hit-test the center: occluded iff the top NON-Reticle element is a foreign subtree (not target/ancestor/descendant). */
 function hitTest(el, rect) {
     const top = hitTestOccluder(el, rect);
     return null === top
         ? { occluded: false, occludedBy: null }
         : { occluded: true, occludedBy: refs.refFor(top) };
 }
-/**
- * Click-like geometry honesty: scroll an off-viewport target into view, then hit-test the click
- * point. Synthetic dispatch always reaches the target regardless — this is purely so the agent
- * learns when the target is off-screen or visually blocked instead of getting a false "it worked".
- */
 export function clickGeometry(el) {
     if (typeof el.getBoundingClientRect !== 'function')
         return NO_GEOMETRY;
@@ -91,7 +66,6 @@ export function firePointer(el, type, relatedTarget = null) {
         }
     });
 }
-/** Enter/leave pointer events are non-bubbling per spec; keep them so to avoid double-firing. */
 export function firePointerNonBubbling(el, type, relatedTarget = null) {
     asSyntheticInput(() => {
         if ('function' === typeof PointerEvent) {
@@ -106,7 +80,6 @@ function makeDataTransfer(data) {
     if (typeof DataTransfer !== 'function')
         return null;
     const dt = new DataTransfer();
-    // data: { mime, value } or [{ mime, value }, …]
     const entries = Array.isArray(data) ? data : data !== undefined ? [data] : [];
     for (const entry of entries) {
         if ('object' === typeof entry && entry !== null) {
@@ -117,46 +90,20 @@ 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 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. 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, related) => {
         const bubbles = !(type.endsWith('enter') || type.endsWith('leave'));
         const init = {
@@ -177,29 +124,18 @@ 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);
@@ -216,8 +152,6 @@ export async function dragElement(source, target, data) {
         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);

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

@@ -0,0 +1,10 @@
+export declare function pressKey(args: Record<string, unknown>): string;
+export declare function pressModifiers(args: Record<string, unknown>): {
+    metaKey: boolean;
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    altKey: boolean;
+};
+export declare function pressCode(args: Record<string, unknown>, key: string): string;
+export declare function focusedOrDocument(): HTMLElement;
+export declare function isReflessDocumentPress(ref: string, action: string, args: Record<string, unknown>): boolean;

package/dist/actions/actions-press.js

@@ -0,0 +1,77 @@
+import { ActionType, isGlobalPress, pressKeyFromArgs } from '@reticlehq/core';
+import { isHtmlElement } from '../dom/realm.js';
+function asString(value, fallback = '') {
+    return 'string' === typeof value ? value : fallback;
+}
+export function pressKey(args) {
+    return pressKeyFromArgs(args);
+}
+export function pressModifiers(args) {
+    const raw = args['modifiers'];
+    const names = Array.isArray(raw) ? raw.map((m) => asString(m).toLowerCase()) : [];
+    const has = (...aliases) => aliases.some((a) => names.includes(a));
+    return {
+        metaKey: has('meta', 'cmd', 'command', 'super', 'win'),
+        ctrlKey: has('control', 'ctrl'),
+        shiftKey: has('shift'),
+        altKey: has('alt', 'option', 'opt'),
+    };
+}
+export function pressCode(args, key) {
+    const explicit = args['code'];
+    if ('string' === typeof explicit && 0 < explicit.length)
+        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 '';
+    }
+    return /^[A-Z][A-Za-z0-9]*$/.test(key) && KNOWN_NAMED_KEYS.has(key) ? key : '';
+}
+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',
+]);
+const NO_DOCUMENT_TO_PRESS = 'no document to press into';
+export function focusedOrDocument() {
+    const active = document.activeElement;
+    if (isHtmlElement(active) && document.body !== active)
+        return active;
+    if (isHtmlElement(document.body))
+        return document.body;
+    const root = document.documentElement;
+    if (isHtmlElement(root))
+        return root;
+    throw new Error(NO_DOCUMENT_TO_PRESS);
+}
+export function isReflessDocumentPress(ref, action, args) {
+    return 0 === ref.length && isGlobalPress(args) && ActionType.PRESS === action;
+}

package/dist/actions/actions.d.ts

@@ -1,94 +1,30 @@
 import { SettleReason } from '@reticlehq/core';
-/**
- * Best-effort evidence of whether/why an action landed, so the agent can separate
- * "my action missed" vs "app didn't react" vs "tool didn't dispatch". All probes are
- * cheap and best-effort (see docs/usage.md).
- */
 interface ActionEffect {
-    /** We reached dispatch (no throw before it). Typed `true`: if we never dispatch we throw. */
     dispatched: true;
-    /** Ref resolved to a still-connected element at read time. */
     targetMatched: boolean;
-    /** a11y isVisible(el) at the start of the action. */
     visible: boolean;
-    /** Not disabled / aria-disabled at the start of the action. */
     enabled: boolean;
-    /** The primary cancelable event's dispatchEvent returned false (handler called preventDefault). */
     defaultPrevented: boolean;
-    /** "<prevRef>-><newRef>" if document.activeElement changed, else null. body counts as null. */
     focusMoved: string | null;
-    /** fill/type/clear only: input value before !== after; else false. */
     valueChanged: boolean;
-    /** Mutation records counted by a short-lived MutationObserver (one microtask + rAF window). */
     domMutatedWithin: number;
-    /**
-     * Text the action put on the page, truncated. OMITTED when it added none.
-     *
-     * `domMutatedWithin` says the click did SOMETHING; it cannot say the app rejected you. A login
-     * that fails returns ok/settled/mutated and reads exactly like one that succeeded, so an agent
-     * moves on and asserts against a page it misread. The observer already receives these records
-     * and was keeping only `.length` — the message was being thrown away, not gathered.
-     *
-     * Deliberately NOT a verdict: this is what appeared, not what it means. Absence means no text
-     * was added, which is why a silent class toggle omits the key rather than reporting "".
-     */
     appeared?: string;
-    /**
-     * Click-like only: the center hit-tested to a foreign element (an overlay is on top). Synthetic
-     * dispatch STILL delivered the event to the target, but a real user could not click it — treat
-     * the target as visually blocked. `false` when not click-like or not hit-testable (no layout).
-     */
     occluded: boolean;
-    /** Ref of the element actually on top at the click point when `occluded`, else null. */
     occludedBy: string | null;
-    /** Click-like only: the target was off-viewport, so it was scrolled into view before dispatch. */
     scrolledIntoView: boolean;
-    /**
-     * How long the pointer was ACTUALLY held down, for a click with `args.holdMs`. Absent otherwise.
-     *
-     * Measured, not echoed. `holdMs: 1200` against a 1200ms animation is a race by construction, so a
-     * caller needs to tell "held 1200" from "held 1204" — and a backgrounded tab throttles timers, so
-     * the achieved hold can legitimately be much longer than the one requested.
-     */
     heldMs?: number;
-    /**
-     * check/uncheck only: the control ALREADY read as the requested state, so NOTHING was dispatched.
-     * OMITTED otherwise (the uninformative default).
-     *
-     * Not clicking is right — clicking an already-checked box would uncheck it. But the branch that
-     * skips the click reads the DOM PROPERTY, and that is not evidence about what the APPLICATION
-     * holds. They come apart exactly when it matters: a default-checked input the app has not
-     * committed, a property written earlier by something else, a control read mid-render. Then `check`
-     * no-ops, the framework never hears, and every later read agrees because every later read is also
-     * reading the DOM — reported from the field as a form whose flag was unset in the database while
-     * Reticle confirmed it checked.
-     *
-     * So this is a caveat, not a failure: the requested state is what the DOM shows, and Reticle did
-     * not put it there. Assert the app's own state (a signal, a request, a derived control) rather than
-     * the box.
-     */
     alreadyAtValue?: true;
 }
 interface ActionResult {
     ok: true;
     ref: string;
     action: string;
-    /** We reached dispatch without throwing. Mirror of effect.dispatched for top-level reads. */
     dispatched: boolean;
-    /** A real animation frame fired within the settle budget (false = fallback timer fired). */
     settled: boolean;
-    /** Why settle did not complete on a real frame: SettleReason.TIMEOUT when the budget fallback fired, else null. */
     settleReason: SettleReason | null;
     effect: ActionEffect;
-    /** data-testid of the resolved element, when present — lets the server compile a ref-stable replay step. */
     testid?: string;
-    /**
-     * Auto-anchor fallback (attached ONLY when there is no testid): the element's nearest component
-     * name + source location, so the server can compile a stable `component` anchor instead of a
-     * degraded role one — addressing the element across replays with zero hand-added testids.
-     */
     component?: string;
-    /** Role + accessible name — the anchor that identifies an INSTANCE, not a JSX site. */
     role?: string;
     name?: string;
     source?: {
@@ -96,28 +32,10 @@ interface ActionResult {
         line: number;
         column?: number;
     };
-    /** Best-effort caveat the agent should heed (e.g. synthetic hover may not fire enter/leave). */
     warning?: string;
 }
-/**
- * Dispatch the action's events. Returns `defaultPrevented` of the primary cancelable event
- * (false for actions whose primary event is non-cancelable or unobservable). Drag/hover-hold
- * await internally; the probe wrapper builds the result once they resolve.
- */
-/**
- * The longest a single action may hold the pointer down, in milliseconds.
- *
- * An unbounded `holdMs` is a tool call that never returns, which is the failure the transport layer
- * is shaped around. 30s is far above any real hold-to-confirm (the reported case was 1.2s) and far
- * below a hang.
- */
 export declare const MAX_HOLD_MS = 30000;
-/**
- * Execute a single action against a ref and probe for best-effort evidence of effect.
- * Always async: the MutationObserver read needs a microtask + rAF after dispatch.
- */
 export declare function executeAction(ref: string, action: string, args?: Record<string, unknown>): Promise<ActionResult>;
-/** Best-effort WebMCP passthrough: call a navigator.modelContext tool if the site exposes one. */
 export declare function dispatchWebMcp(tool: string, params: Record<string, unknown>, confirmDangerous?: boolean): Promise<unknown>;
 export interface ActionStep {
     ref: string;
@@ -127,15 +45,9 @@ export interface ActionStep {
 interface SequenceStepResult {
     ref: string;
     action: string;
-    /** per-step dispatch/settle outcome (see ActionResult). */
     dispatched: boolean;
     settled: boolean;
     settleReason: SettleReason | null;
-    /**
-     * The SAME anchors a single act reports. Reporting only the testid meant a testid-less app
-     * compiled every sub-step to a volatile ref, so the saved flow carried the degraded sentinel and
-     * every replay drifted.
-     */
     testid?: string;
     component?: string;
     role?: string;
@@ -145,7 +57,6 @@ interface SequenceStepResult {
         line: number;
         column?: number;
     };
-    /** best-effort caveat for this step (e.g. synthetic hover may not fire enter/leave). */
     warning?: string;
 }
 export declare function executeSequence(steps: ActionStep[]): Promise<{