@reticlehq/browser 2.5.0 → 2.7.0

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

@@ -10,7 +10,14 @@ export declare const NO_GEOMETRY: ClickGeometry;
  * `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): boolean;
+export declare function fireClickSequence(el: HTMLElement, hold?: {
+    ms: number;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+}): Promise<{
+    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
@@ -23,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

@@ -12,17 +12,31 @@ export const NO_GEOMETRY = {
  * `defaultPrevented` so the probe is unchanged. Focus only moves for focusable targets (tabIndex>=0),
  * so a plain <div> click still reports focusMoved=null.
  */
-export function fireClickSequence(el) {
+export async function fireClickSequence(el, hold) {
     const doc = el.ownerDocument;
     const from = doc.activeElement ?? doc.body;
     firePointer(el, 'pointerdown', from);
     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();
+        await hold.sleep(hold.ms);
+        heldMs = hold.now() - startedAt;
+    }
     firePointer(el, 'pointerup', from);
     el.dispatchEvent(new MouseEvent('mouseup', { bubbles: true, cancelable: true }));
     const notPrevented = el.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true }));
-    return !notPrevented;
+    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) {
@@ -95,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');
-    await nativeFrame();
-    fire(dest, 'pointermove');
-    fire(dest, 'mousemove');
+    fire(source, 'pointerdown', from, BUTTON_HELD);
+    fire(source, 'mousedown', from, BUTTON_HELD);
     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.d.ts

@@ -21,6 +21,18 @@ interface ActionEffect {
     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
@@ -31,6 +43,14 @@ interface ActionEffect {
     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;
 }
 interface ActionResult {
     ok: true;
@@ -62,6 +82,19 @@ interface ActionResult {
     /** 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.

package/dist/actions/actions.js

@@ -5,6 +5,7 @@ import { getAccessibleName, getRole, isVisible, getStates } from '../dom/a11y.js
 import { elementHasHoverHandlers, identifyComponent } from '../registry/adapters.js';
 import { isForm, isHtmlElement, isInput, isSelect, isTextArea } from '../dom/realm.js';
 import { nativeSetTimeout, settle } from '../timers/native-timers.js';
+import { AppearedText } from './appeared-text.js';
 function asString(value, fallback = '') {
     return 'string' === typeof value ? value : fallback;
 }
@@ -111,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);
@@ -152,12 +252,38 @@ function activeRef(el) {
  * (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 const MAX_HOLD_MS = 30_000;
+/** A hold the caller asked for, bounded and sanitised. Non-numbers and negatives mean "no hold". */
+function clampHold(raw) {
+    if ('number' !== typeof raw || !Number.isFinite(raw) || raw <= 0)
+        return 0;
+    return Math.min(raw, MAX_HOLD_MS);
+}
+/**
+ * Click is the only action that can hold the pointer down, so it is the only one that reports a
+ * duration. Everything else routes through the switch below unchanged and holds for zero.
+ */
 async function dispatchFor(el, action, args) {
+    if (ActionType.CLICK === action) {
+        // Full pointer/mouse sequence (not a bare click) so pointer- and focus-gated handlers fire the
+        // way they do for a real user.
+        //
+        // `args.holdMs` keeps the pointer down in between, which is the only way to drive a
+        // hold-to-confirm control. Capped: an unbounded hold is a tool call that never returns.
+        const hold = clampHold(args['holdMs']);
+        return await fireClickSequence(el, 0 === hold ? undefined : { ms: hold, sleep, now: () => Date.now() });
+    }
+    return { prevented: await dispatchOther(el, action, args), heldMs: 0 };
+}
+async function dispatchOther(el, action, args) {
     switch (action) {
-        case ActionType.CLICK:
-            // Full pointer/mouse sequence (not a bare click) so pointer- and focus-gated handlers fire
-            // the way they do for a real user. Returns the click event's defaultPrevented.
-            return fireClickSequence(el);
         case ActionType.DBLCLICK:
             return !el.dispatchEvent(new MouseEvent('dblclick', { bubbles: true, cancelable: true }));
         case ActionType.HOVER: {
@@ -172,8 +298,9 @@ async function dispatchFor(el, action, args) {
             el.dispatchEvent(new MouseEvent('mouseenter', { relatedTarget: from }));
             firePointer(el, 'pointermove', from);
             const moved = el.dispatchEvent(new MouseEvent('mousemove', { bubbles: true, cancelable: true }));
-            // hover-dwell: keep "hovering" for holdMs so timer-gated reveals can mount.
-            const holdMs = 'number' === typeof args['holdMs'] ? args['holdMs'] : 0;
+            // hover-dwell: keep "hovering" for holdMs so timer-gated reveals can mount. Same cap as
+            // click — this arg was previously unbounded here, which is the same never-returns hazard.
+            const holdMs = clampHold(args['holdMs']);
             if (holdMs > 0)
                 await sleep(holdMs);
             return !moved;
@@ -182,13 +309,31 @@ async function dispatchFor(el, action, args) {
             el.focus();
             el.dispatchEvent(new FocusEvent('focusin', { bubbles: true }));
             return false; // FocusEvents are not cancelable.
-        case ActionType.BLUR:
-            // Fire a bubbling focusout so React 19's delegated root listener runs onBlur
-            // (commit-on-blur). el.blur alone only works if the element was truly focused.
+        case ActionType.BLUR: {
+            // React 19 listens for `focusout` at the ROOT, so a commit-on-blur handler needs a BUBBLING
+            // event to reach it — and `el.blur()` is a no-op on an element that was never focused, which
+            // is why the synthetic pair exists at all.
+            //
+            // But on a FOCUSED element `el.blur()` already dispatches `blur` and a bubbling `focusout`
+            // natively. Dispatching them again meant React ran `onBlur` TWICE, and Reticle reported the
+            // resulting double write as a `duplicate-request` contradiction — a defect we invented and
+            // handed to a human as real. Reported from the field on React 19 + Vite with a single
+            // `onBlur={() => mutate(...)}`, one render site and no StrictMode.
+            //
+            // So synthesize ONLY when nothing native will fire. Read before the call, because `blur()` is
+            // what changes it — and read off the element's own ROOT: `document.activeElement` reports the
+            // shadow HOST for an element inside a shadow root, so an element that genuinely was focused
+            // would read as unfocused and take the double-dispatch path this exists to prevent. Both
+            // Document and ShadowRoot expose `activeElement`, so one expression covers both.
+            const root = el.getRootNode();
+            const wasFocused = root.activeElement === el;
             el.blur();
-            el.dispatchEvent(new FocusEvent('blur'));
-            el.dispatchEvent(new FocusEvent('focusout', { bubbles: true }));
+            if (!wasFocused) {
+                el.dispatchEvent(new FocusEvent('blur'));
+                el.dispatchEvent(new FocusEvent('focusout', { bubbles: true }));
+            }
             return false;
+        }
         case ActionType.FILL:
             if (isInput(el) || isTextArea(el)) {
                 // A MISSING value is a malformed call, not a request to empty the field. `asString` defaults
@@ -258,13 +403,39 @@ async function dispatchFor(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)
@@ -273,9 +444,10 @@ async function dispatchFor(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:
@@ -296,11 +468,21 @@ async function dispatchFor(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}'`);
@@ -323,8 +505,10 @@ export async function executeAction(ref, action, args = {}) {
     // mutation observer (scroll/hit-test never mutate the DOM, but keep the probe window clean).
     const geometry = CLICK_LIKE.has(action) ? clickGeometry(el) : NO_GEOMETRY;
     let mutated = 0;
+    const said = new AppearedText();
     const obs = new MutationObserver((records) => {
         mutated += records.length;
+        said.collect(records);
     });
     obs.observe(el.ownerDocument.documentElement, {
         subtree: true,
@@ -333,10 +517,14 @@ export async function executeAction(ref, action, args = {}) {
         characterData: true,
     });
     let defaultPrevented = false;
+    /** How long the pointer was actually held down. Zero for every action that cannot hold. */
+    let heldMs = 0;
     let settled = false;
     let settleReason = null;
     try {
-        defaultPrevented = await dispatchFor(el, action, args);
+        const outcome = await dispatchFor(el, action, args);
+        defaultPrevented = outcome.prevented;
+        heldMs = outcome.heldMs;
     }
     finally {
         // bounded settle — microtask + one BOUNDED frame so React's commit (and the resulting DOM
@@ -359,9 +547,15 @@ export async function executeAction(ref, action, args = {}) {
         focusMoved: prevFocus !== nextFocus ? `${prevFocus ?? 'null'}->${nextFocus ?? 'null'}` : null,
         valueChanged: isFillLike(action) ? valueBefore !== valueAfter : false,
         domMutatedWithin: mutated,
+        // Omitted rather than "" when nothing was said — an empty string reads as "it said nothing
+        // meaningful", where absence says "it added no text at all". Those are different findings.
+        ...said.effect(valueAfter),
         occluded: geometry.occluded,
         occludedBy: geometry.occludedBy,
         scrolledIntoView: geometry.scrolledIntoView,
+        // Omitted when there was no hold: an absent key says "this action does not hold", where a 0
+        // would read as "it held for no time", which is a different and misleading claim.
+        ...(heldMs > 0 ? { heldMs } : {}),
     };
     // Honesty caveats: a visually-occluded click is reported even though synthetic dispatch landed;
     // else synthetic hover may not fire framework enter/leave handlers (no native hit-test).

package/dist/actions/appeared-text.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Gathers the text an action put on the page, from mutation records the observer already receives.
+ *
+ * `domMutatedWithin` counts records and throws their content away, so a failed login reports
+ * `ok / settled / mutated` and reads exactly like a successful one. The message the app rendered
+ * was passing through this callback the whole time.
+ *
+ * Deliberately reports what appeared, never what it means: no error/success classification, no
+ * guessing which fragment matters. Truncated, because a route change can add a whole page.
+ */
+export declare class AppearedText {
+    #private;
+    collect(records: readonly MutationRecord[]): void;
+    /**
+     * `{ appeared }` when the APP added text, `{}` otherwise — an absent key means it added none.
+     *
+     * `wrote` is the value the action itself just set, and is excluded: a textarea carries its value
+     * in a child text node, so a controlled one re-rendering after the write mutates characterData
+     * with the caller's own string. Handing that back is noise wearing the name of evidence, and
+     * `valueChanged` already reports that the write landed. Exact-match only, so an app that quotes
+     * your input inside a sentence of its own ("No results for zzz") is still reported — that is
+     * the app talking.
+     */
+    effect(wrote?: string): {
+        appeared?: string;
+    };
+}

package/dist/actions/appeared-text.js

@@ -0,0 +1,92 @@
+import { isIgnored } from '../dom/dom-ignore.js';
+/** Cap on the reported text. Enough for an error message, far short of a re-rendered page. */
+const APPEARED_MAX = 200;
+/** Separator between distinct fragments that appeared in the same window. */
+const JOIN = ' | ';
+const TEXT_NODE = 3;
+/** Any letter, in any script — Latin, Cyrillic, CJK, Arabic. */
+const HAS_LETTER = /\p{L}/u;
+/**
+ * A fragment with no letters at all is not the app saying something.
+ *
+ * The Hostile fixture mutates a counter every 16ms, and clicking a button on that page reported
+ * `appeared: "409"` — the ticker, not the action's effect. A count-up animation is exactly what
+ * emits a bare number into the settle window, and a bare number carries no message a reader can
+ * act on. Deliberately conservative: it drops only fragments with NO letters, so "status 500",
+ * "3 items deleted" and "Could not save" all survive. An app whose only feedback is a naked
+ * numeral loses it here — the snapshot still shows it, and that is the cheaper mistake.
+ */
+function saysSomething(text) {
+    return HAS_LETTER.test(text);
+}
+/**
+ * Gathers the text an action put on the page, from mutation records the observer already receives.
+ *
+ * `domMutatedWithin` counts records and throws their content away, so a failed login reports
+ * `ok / settled / mutated` and reads exactly like a successful one. The message the app rendered
+ * was passing through this callback the whole time.
+ *
+ * Deliberately reports what appeared, never what it means: no error/success classification, no
+ * guessing which fragment matters. Truncated, because a route change can add a whole page.
+ */
+export class AppearedText {
+    #seen = new Set();
+    #length = 0;
+    collect(records) {
+        for (const record of records) {
+            if (this.#full())
+                return;
+            if ('characterData' === record.type) {
+                // The NEW value; oldValue is not requested, so this is what the reader now sees.
+                this.#add(record.target.textContent, record.target.parentElement);
+                continue;
+            }
+            for (const node of record.addedNodes) {
+                if (this.#full())
+                    return;
+                const owner = TEXT_NODE === node.nodeType ? node.parentElement : elementOf(node);
+                this.#add(node.textContent, owner);
+            }
+        }
+    }
+    /**
+     * `{ appeared }` when the APP added text, `{}` otherwise — an absent key means it added none.
+     *
+     * `wrote` is the value the action itself just set, and is excluded: a textarea carries its value
+     * in a child text node, so a controlled one re-rendering after the write mutates characterData
+     * with the caller's own string. Handing that back is noise wearing the name of evidence, and
+     * `valueChanged` already reports that the write landed. Exact-match only, so an app that quotes
+     * your input inside a sentence of its own ("No results for zzz") is still reported — that is
+     * the app talking.
+     */
+    effect(wrote) {
+        const said = [...this.#seen].filter((text) => text !== wrote);
+        if (0 === said.length)
+            return {};
+        const joined = said.join(JOIN);
+        return {
+            appeared: joined.length > APPEARED_MAX ? `${joined.slice(0, APPEARED_MAX)}…` : joined,
+        };
+    }
+    #full() {
+        return this.#length > APPEARED_MAX;
+    }
+    #add(raw, owner) {
+        // Reticle's own overlay mutates constantly (the "live" panel); reporting it as the app's
+        // response would be worse than reporting nothing.
+        if (null !== owner && isIgnored(owner))
+            return;
+        const text = (raw ?? '').replace(/\s+/g, ' ').trim();
+        if (0 === text.length)
+            return;
+        if (!saysSomething(text))
+            return;
+        if (this.#seen.has(text))
+            return;
+        this.#seen.add(text);
+        this.#length += text.length + JOIN.length;
+    }
+}
+function elementOf(node) {
+    return node instanceof Element ? node : node.parentElement;
+}

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,
@@ -173,6 +178,19 @@ function readState(ref, store, path, depth) {
     }
     return result;
 }
+/**
+ * Every animation, and WHICH element it drives.
+ *
+ * Reported from the field: a page with nine concurrent animations returned nine indistinguishable
+ * `{playState, currentTime, duration}` rows. `a.effect` was read only for `getTiming()`, never for
+ * its `target` — so the tool advertised "targets/timing" and shipped timing alone. A list you cannot
+ * index is not a list, and the question this tool exists to answer is "is THAT thing still
+ * animating".
+ *
+ * `describe()` is reused rather than inventing a target shape: it is what `reticle_query` returns,
+ * so the descriptor carries a `ref` the agent can pass straight to `reticle_act` — a target you
+ * cannot act on would be half an answer.
+ */
 function listAnimations() {
     const doc = document;
     if (typeof doc.getAnimations !== 'function')
@@ -180,10 +198,15 @@ function listAnimations() {
     const animations = doc.getAnimations().map((a) => {
         const effect = a.effect;
         const timing = effect?.getTiming();
+        // A KeyframeEffect's target is legitimately nullable, and only KeyframeEffect has one at all.
+        // `null` is reported explicitly: omitting the key would make "this animation has no element"
+        // indistinguishable from the bug above, which is the distinction the fix exists to draw.
+        const target = effect?.target ?? null;
         return {
             playState: a.playState,
             currentTime: a.currentTime,
             duration: timing?.duration,
+            target: null === target ? null : describe(target),
         };
     });
     return { animations };

package/dist/dom/query.js

@@ -2,7 +2,7 @@ import { queryAllByRole, queryAllByText, queryAllByLabelText, queryAllByPlacehol
 import { DATA_RETICLE_SOURCE_ATTR, ElementState, QueryBy, REDACTED_VALUE, TRANSPORT_LIMITS, } from '@reticlehq/core';
 import { isFrame, isHtmlElement } from './realm.js';
 import { capturedRootOf } from './shadow-registry.js';
-import { describe, getStates, isVisible } from './a11y.js';
+import { getAccessibleName, getRole, describe, getStates, isVisible } from './a11y.js';
 import { isIgnored } from './dom-ignore.js';
 import { isSensitiveKey } from '../security/serialization.js';
 import { getCapabilities } from '../registry/capabilities.js';
@@ -83,6 +83,41 @@ function findByComponent(container, query) {
     }
     return [];
 }
+/**
+ * Role + name, matched the way Reticle REPORTS them — not only the way Testing Library computes them.
+ *
+ * Two implementations were disagreeing, on both axes, for the same element:
+ *
+ *   <input type="search" placeholder="Search User">
+ *     Reticle getRole            -> "textbox"      TL/dom-accessibility-api -> "searchbox"
+ *     Reticle getAccessibleName  -> "Search User"  TL                       -> "" (no placeholder)
+ *
+ * `reticle_query`, `reticle_snapshot` and every act result report Reticle's values. The matcher used
+ * TL's. So Reticle printed `textbox "Search User"` and then could not find it by that exact
+ * role and name — the same query call reporting an identity it cannot match.
+ *
+ * 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.
+ */
+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);
+}
 /** Run the appropriate Testing-Library query against ONE root (light DOM or a shadow root). */
 function findIn(container, query) {
     const by = query.by;
@@ -91,7 +126,7 @@ function findIn(container, query) {
     if (by !== undefined && value !== undefined) {
         switch (by) {
             case QueryBy.ROLE:
-                return queryAllByRole(container, value, query.name !== undefined ? { hidden: true, name: query.name } : { hidden: true });
+                return queryByRoleAndName(container, value, query.name);
             case QueryBy.TEXT:
                 return queryAllByText(container, value, { exact: false });
             case QueryBy.LABEL:
@@ -120,12 +155,10 @@ function findIn(container, query) {
     if (query.component !== undefined || query.source !== undefined) {
         return findByComponent(container, query);
     }
-    // Structured form (role+name, or any single field).
+    // Structured form (role+name, or any single field). Same round-trip guarantee as the by+value
+    // spelling above — the two forms must not disagree about what is findable.
     if (query.role !== undefined) {
-        const options = query.name !== undefined
-            ? { hidden: true, name: query.name }
-            : { hidden: true };
-        return queryAllByRole(container, query.role, options);
+        return queryByRoleAndName(container, query.role, query.name);
     }
     if (query.text !== undefined)
         return queryAllByText(container, query.text, { exact: false });
@@ -226,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/dom/snapshot.js

@@ -20,6 +20,24 @@ const INTERACTIVE = new Set([
     'option',
 ]);
 const SKIP_TAGS = new Set(['script', 'style', 'noscript', 'template', 'head', 'meta', 'link']);
+/** Roles whose whole purpose is announcing a change; both imply an implicit aria-live. */
+const ANNOUNCE_ROLES = new Set(['alert', 'status']);
+/**
+ * Is this element the app SAYING something changed?
+ *
+ * INTERACTIVE mode keeps only actionable elements, which silently drops the one node that explains
+ * why an action did nothing — the error the app just rendered. An agent told to prefer the cheaper
+ * mode was structurally blind to the failure it had caused: the click reports settled with a DOM
+ * mutation, and the lean snapshot shows the same controls as before. Live regions exist precisely
+ * to announce state changes to a consumer that cannot see the screen, which is exactly the agent,
+ * so they are the principled exception — and a bounded one, since a page has very few.
+ */
+function announces(el, role) {
+    if (ANNOUNCE_ROLES.has(role))
+        return true;
+    const live = el.getAttribute('aria-live');
+    return live !== null && 'off' !== live;
+}
 /** Cap on inlined text content so a verbose node can't blow up the snapshot. */
 const TEXT_MAX = 80;
 /**
@@ -116,7 +134,7 @@ function pierceChildren(parent) {
     }
     return out;
 }
-function walk(parent, depth, ctx) {
+function walk(parent, depth, ctx, inLive = false) {
     if (depth > ctx.maxDepth)
         return;
     for (const child of pierceChildren(parent)) {
@@ -135,9 +153,12 @@ function walk(parent, depth, ctx) {
         const role = getRole(child);
         const name = getAccessibleName(child);
         const interactive = INTERACTIVE.has(role);
+        // Announcements are exempt from leanness, and so is everything inside one: a live region whose
+        // message sits in a child element would otherwise be included as a contentless `- generic`.
+        const announce = inLive || announces(child, role);
+        const lean = ctx.mode === SnapshotMode.INTERACTIVE && !announce;
         // A generic, unnamed container's own text content — only consulted outside INTERACTIVE mode,
         // so the actionable-only view stays lean while FULL/meaningful views see content regressions.
-        const lean = ctx.mode === SnapshotMode.INTERACTIVE;
         const text = !lean && 'generic' === role && 0 === name.length ? directText(child) : '';
         // Layout signature for grid/flex containers — makes CLS/layout regressions visible.
         const layout = lean ? '' : layoutSignature(style);
@@ -148,10 +169,10 @@ function walk(parent, depth, ctx) {
             ctx.lines.push(text.length > 0 && 0 === name.length && 0 === layout.length
                 ? formatTextLine(depth, text)
                 : formatLine(child, depth, role, name, layout));
-            walk(child, depth + 1, ctx);
+            walk(child, depth + 1, ctx, announce);
         }
         else {
-            walk(child, depth, ctx);
+            walk(child, depth, ctx, announce);
         }
     }
 }

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/dist/timers/clock.js

@@ -109,6 +109,14 @@ export function resetClock() {
     //
     // So keep a translation map and a clear-shim for exactly as long as re-armed work is outstanding.
     // Nothing is dropped, and the app's handles keep working.
+    // Bound to `window`, not called off `natives`. A timer native invoked with any other receiver
+    // throws `TypeError: Illegal invocation` in a real browser — and `natives.setTimeout(...)` passes
+    // `natives`. jsdom does not enforce the receiver, so every unit test here passed while the browser
+    // threw on the one path that matters: re-arming work the app queued during the freeze. The early
+    // return above means it only fires when something IS pending, which is exactly when this function
+    // has a job to do. Caught by `bench/harness/clock-timetravel.mjs` driving real Chromium.
+    const nativeSetTimeout = natives.setTimeout.bind(window);
+    const nativeSetInterval = natives.setInterval.bind(window);
     const reArmed = new Map();
     const done = (virtualId) => {
         reArmed.delete(virtualId);
@@ -117,10 +125,10 @@ export function resetClock() {
     };
     for (const task of pending) {
         if (task.interval !== undefined) {
-            reArmed.set(task.id, natives.setInterval(task.cb, task.interval));
+            reArmed.set(task.id, nativeSetInterval(task.cb, task.interval));
         }
         else {
-            reArmed.set(task.id, natives.setTimeout(() => {
+            reArmed.set(task.id, nativeSetTimeout(() => {
                 done(task.id);
                 task.cb();
             }, Math.max(0, task.time - resumeFrom)));
@@ -130,15 +138,20 @@ export function resetClock() {
 }
 /** Route a clear() for a re-armed virtual id to its real native id; everything else passes through. */
 function installTranslatingClears(reArmed, natives, done) {
-    const translate = (rawClear) => ((id) => {
-        const nativeId = reArmed.get(id);
-        if (nativeId === undefined) {
-            rawClear(id);
-            return;
-        }
-        rawClear(nativeId);
-        done(id);
-    });
+    // `.bind(window)` for the same reason as the re-arm above: a bare `rawClear(id)` reaches the DOM
+    // with the wrong receiver and throws `Illegal invocation` in a real browser.
+    const translate = (rawClear) => {
+        const clear = rawClear.bind(window);
+        return ((id) => {
+            const nativeId = reArmed.get(id);
+            if (nativeId === undefined) {
+                clear(id);
+                return;
+            }
+            clear(nativeId);
+            done(id);
+        });
+    };
     window.clearTimeout = translate(natives.clearTimeout);
     window.clearInterval = translate(natives.clearInterval);
 }

package/dist/transport/transport.d.ts

@@ -36,7 +36,30 @@ interface TransportDeps {
      * unsubscribe; injected so a test can drive visibility without a real document.
      */
     onVisible?: (handler: () => void) => () => void;
+    /**
+     * Schedule an internal retry (default: `nativeSetTimeout`). Injected for the same reason `now` and
+     * `onVisible` are — the default is bound to the real timer at module load so a frozen app clock
+     * cannot deadlock the SDK, which also means no fake clock can observe what was scheduled.
+     */
+    schedule?: (fn: () => void, ms: number) => void;
 }
+/**
+ * The ceiling on reconnect backoff.
+ *
+ * A flat 1s retry with no growth and no cap meant a tab left open against a stopped daemon made
+ * ~600 failed WebSocket opens in ten minutes — CPU, and a devtools console full of
+ * ERR_CONNECTION_REFUSED. Backing off is only safe BECAUSE this transport also reconnects on
+ * focus/visibility, so a human returning to the tab retries immediately rather than waiting out
+ * the delay; the backoff resets on that path for the same reason.
+ */
+export declare const RECONNECT_MAX_DELAY_MS = 30000;
+/**
+ * The next reconnect delay: double, then clamp. Pure, and exported so the POLICY is testable —
+ * the scheduling itself runs on `nativeSetTimeout`, which is bound to the real timer at module load
+ * (deliberately, so a frozen `reticle_clock` cannot deadlock the SDK) and therefore cannot be driven
+ * by a fake clock.
+ */
+export declare function nextReconnectDelay(previous: number): number;
 /** Offline queue cap. Exported so tests overflow the real bound instead of a mirrored copy of it. */
 export declare const MAX_QUEUE = 500;
 /** WebSocket client to the bridge. Reconnects across reloads; buffers events while down. */

package/dist/transport/transport.js

@@ -1,4 +1,4 @@
-import { CommandMessageSchema, EventType, MessageKind, SESSION_LIFECYCLE, } from '@reticlehq/core';
+import { CHURN_TYPES, CommandMessageSchema, EventType, MessageKind, SESSION_LIFECYCLE, } from '@reticlehq/core';
 import { nativeSetTimeout, nativeNow } from '../timers/native-timers.js';
 import { nativeWarn } from '../timers/native-console.js';
 import { safeStringify } from '../security/serialization.js';
@@ -13,7 +13,27 @@ function subscribeDocumentVisible(handler) {
     document.addEventListener('visibilitychange', listener);
     return () => document.removeEventListener('visibilitychange', listener);
 }
+/** The first retry after a drop. Kept short: the common outage is a daemon restarting. */
 const RECONNECT_DELAY_MS = 1000;
+/**
+ * The ceiling on reconnect backoff.
+ *
+ * A flat 1s retry with no growth and no cap meant a tab left open against a stopped daemon made
+ * ~600 failed WebSocket opens in ten minutes — CPU, and a devtools console full of
+ * ERR_CONNECTION_REFUSED. Backing off is only safe BECAUSE this transport also reconnects on
+ * focus/visibility, so a human returning to the tab retries immediately rather than waiting out
+ * the delay; the backoff resets on that path for the same reason.
+ */
+export const RECONNECT_MAX_DELAY_MS = 30_000;
+/**
+ * The next reconnect delay: double, then clamp. Pure, and exported so the POLICY is testable —
+ * the scheduling itself runs on `nativeSetTimeout`, which is bound to the real timer at module load
+ * (deliberately, so a frozen `reticle_clock` cannot deadlock the SDK) and therefore cannot be driven
+ * by a fake clock.
+ */
+export function nextReconnectDelay(previous) {
+    return Math.min(previous * 2, RECONNECT_MAX_DELAY_MS);
+}
 /** Offline queue cap. Exported so tests overflow the real bound instead of a mirrored copy of it. */
 export const MAX_QUEUE = 500;
 /**
@@ -29,10 +49,14 @@ const UNREACHABLE_WARN_AFTER = 3;
 /** WebSocket client to the bridge. Reconnects across reloads; buffers events while down. */
 export class Transport {
     #ws;
-    #queue = [];
+    #churnQueue = [];
+    #signalQueue = [];
+    #insertOrder = 0;
     #closed = false;
     /** When the current continuous outage began (nativeNow), or undefined while connected. */
     #disconnectedSince;
+    /** Current reconnect delay; grows on each failure, resets on a successful open or on focus. */
+    #reconnectDelay = RECONNECT_DELAY_MS;
     /** Whether onConnectionLost has already fired for the current outage (fire-once). */
     #lost = false;
     /** True once the socket has opened at least once — gates the "unreachable" first-connect warning. */
@@ -72,7 +96,14 @@ export class Transport {
      * exists (connected or mid-connect), so we never open a duplicate racing the scheduled retry.
      */
     #onVisible() {
-        if (this.#closed || this.#ws !== undefined)
+        if (this.#closed)
+            return;
+        // A human just came back to the tab, which is the strongest signal the outage may be over — and
+        // it is what makes a 30s ceiling safe. Reset the backoff BEFORE the mid-connect early return: if
+        // a socket is already in flight and then fails, that retry should be prompt too, rather than
+        // inheriting a delay earned while nobody was watching.
+        this.#reconnectDelay = RECONNECT_DELAY_MS;
+        if (this.#ws !== undefined)
             return;
         this.#open();
     }
@@ -90,8 +121,7 @@ export class Transport {
             // note the outage and schedule the normal retry.
             this.#noteOutage();
             this.#noteInitialFailure();
-            if (!this.#closed)
-                nativeSetTimeout(() => this.#reopen(), RECONNECT_DELAY_MS);
+            this.#scheduleReopen();
             return;
         }
         this.#ws = ws;
@@ -99,17 +129,21 @@ export class Transport {
             this.#disconnectedSince = undefined; // healthy again — reset the loss timer
             this.#lost = false;
             this.#everConnected = true; // a real connection happened ⇒ never warn "unreachable"
+            this.#reconnectDelay = RECONNECT_DELAY_MS; // recovered — the next drop starts prompt again
             // HELLO is SDK-owned schema data. Preserve its pairing token; the generic sanitizer
             // intentionally redacts fields named "token" from app-controlled payloads.
             const greeting = this.#deps.hello();
             this.#sessionId ??= greeting.sessionId;
             ws.send(JSON.stringify(greeting));
-            // Declare any gap BEFORE replaying the backlog. The queue evicts its OLDEST entries, so the
-            // hole always precedes everything that survived it.
+            // Declare any gap BEFORE replaying the backlog, stamped with the OLDEST event the queue
+            // dropped — see #sendRaw. The two queues are drained back into one stream in insertion order,
+            // so what the bridge receives is the order the page produced, minus the holes.
             this.#sendGapMarker(ws, greeting.sessionId);
-            for (const msg of this.#queue)
+            const replay = [...this.#churnQueue, ...this.#signalQueue].sort((a, b) => a.order - b.order);
+            for (const msg of replay)
                 ws.send(msg.text);
-            this.#queue = [];
+            this.#churnQueue = [];
+            this.#signalQueue = [];
             this.#deps.onConnected?.();
         };
         ws.onmessage = (event) => {
@@ -131,8 +165,7 @@ export class Transport {
             }
             this.#noteOutage();
             this.#noteInitialFailure();
-            if (!this.#closed)
-                nativeSetTimeout(() => this.#reopen(), RECONNECT_DELAY_MS);
+            this.#scheduleReopen();
         };
         ws.onerror = () => {
             ws.close();
@@ -142,6 +175,20 @@ export class Transport {
      * A scheduled reconnect — skipped if the SDK was torn down, or if a foreground-triggered reconnect
      * already opened a socket (guard against the throttled timer racing #onVisible into a duplicate).
      */
+    /**
+     * Schedule the next retry and grow the delay. Nothing is scheduled once the SDK is torn down.
+     *
+     * The delay grows AFTER scheduling, so the first retry of any outage is prompt (a daemon
+     * restarting must not cost 30 seconds) and only a persistent outage backs off.
+     */
+    #scheduleReopen() {
+        if (this.#closed)
+            return;
+        const delay = this.#reconnectDelay;
+        this.#reconnectDelay = nextReconnectDelay(delay);
+        const schedule = this.#deps.schedule ?? nativeSetTimeout;
+        schedule(() => this.#reopen(), delay);
+    }
     #reopen() {
         if (this.#closed || this.#ws !== undefined)
             return;
@@ -241,6 +288,7 @@ export class Transport {
         this.#sendRaw(safeStringify({ kind: MessageKind.EVENT, event }), {
             seq: event.seq,
             t: event.t,
+            type: event.type,
         });
     }
     /**
@@ -262,19 +310,31 @@ export class Transport {
             this.#ws.send(text);
             return;
         }
-        if (this.#queue.length >= MAX_QUEUE) {
-            // Full offline queue: drop the OLDEST and keep the newest (ring), so after reconnect the agent
-            // replays RECENT activity instead of 500 stale events with the latest lost. Remember what went
-            // so the loss can be declared on reconnect — an unmarked hole reads as "the app did nothing".
-            // Only an evicted EVENT counts: a dropped COMMAND_RESULT is a reply the agent already gave up
-            // waiting for, not a hole in what the app was observed to do.
-            const evicted = this.#queue.shift();
+        if (this.#churnQueue.length + this.#signalQueue.length >= MAX_QUEUE) {
+            // Prefer sacrificing churn (high-volume, low-signal) over signal events. Falls back to signal
+            // FIFO only when the churn queue is empty — the buffer is bounded either way.
+            const evicted = this.#churnQueue.length > 0 ? this.#churnQueue.shift() : this.#signalQueue.shift();
             if (evicted?.event !== undefined) {
                 this.#dropped += 1;
-                this.#gap = evicted.event;
+                // Keep the EARLIEST drop, not the latest. Under plain FIFO the two were the same thing, so
+                // "latest evicted" was a precise boundary: everything before it was gone. Churn-first
+                // eviction breaks that — a churn event newer than a surviving signal event can be the one
+                // sacrificed, and stamping the marker with it would claim a hole that swallows events the
+                // agent is about to receive. The oldest drop is the honest floor: the hole starts no later
+                // than here. A truncation marker may over-state its reach; it must never under-state it.
+                const previous = this.#gap;
+                if (previous === undefined || evicted.event.t < previous.t)
+                    this.#gap = evicted.event;
             }
         }
-        this.#queue.push({ text, event });
+        const isChurn = event !== undefined && CHURN_TYPES.has(event.type);
+        const order = this.#insertOrder++;
+        if (isChurn) {
+            this.#churnQueue.push({ text, event, order });
+        }
+        else {
+            this.#signalQueue.push({ text, event, order });
+        }
     }
     /**
      * Tell the bridge the offline queue swallowed events, then consider the gap declared.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/browser",
-  "version": "2.5.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.5.0"
+    "@reticlehq/core": "2.7.0"
   },
   "devDependencies": {
     "@tanstack/query-core": "^5.101.4",