@reticlehq/browser 2.5.0 → 2.6.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

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) {

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;
 }
@@ -152,12 +153,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 +199,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 +210,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
@@ -323,8 +369,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 +381,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 +411,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

@@ -173,6 +173,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 +193,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 });

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/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.6.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.6.0"
   },
   "devDependencies": {
     "@tanstack/query-core": "^5.101.4",