@reticlehq/browser 2.8.0 → 2.9.0

package/NOTICE

@@ -3,3 +3,10 @@ Copyright 2026 Reticle Labs
 
 This product includes software developed at Reticle Labs.
 Licensed under the Apache License, Version 2.0.
+
+---
+
+Heroicons (presenter HUD)
+Copyright (c) Tailwind Labs, Inc.
+Licensed under the MIT License.
+https://github.com/tailwindlabs/heroicons

package/dist/actions/actions-dom.js

@@ -1,6 +1,7 @@
 import { refs } from '../dom/refs.js';
 import { hitTestOccluder } from '../dom/occlusion.js';
 import { nativeFrame } from '../timers/native-timers.js';
+import { asSyntheticInput } from './synthetic-input.js';
 export const NO_GEOMETRY = {
     occluded: false,
     occludedBy: null,
@@ -16,7 +17,7 @@ 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 }));
+    asSyntheticInput(() => el.dispatchEvent(new MouseEvent('mousedown', { bubbles: true, cancelable: true })));
     if (el.tabIndex >= 0 && 'function' === typeof el.focus)
         el.focus();
     // The gap that makes hold-to-confirm driveable. Everything between down and up used to be
@@ -34,8 +35,11 @@ export async function fireClickSequence(el, hold) {
         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 }));
+    asSyntheticInput(() => el.dispatchEvent(new MouseEvent('mouseup', { bubbles: true, cancelable: true })));
+    // Marked as ours so the annotator's capture-phase listener lets it through. Only the CHECK branch
+    // used to do this, so the ordinary click action — which is this function — was swallowed whole in
+    // annotate mode while still reporting `dispatched: true`.
+    const notPrevented = asSyntheticInput(() => el.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true })));
     return { prevented: !notPrevented, heldMs };
 }
 /** A box has layout we can reason about (jsdom returns an all-zero box — nothing to hit-test). */
@@ -78,21 +82,25 @@ export function clickGeometry(el) {
     return { ...hitTest(el, rect), scrolledIntoView };
 }
 export function firePointer(el, type, relatedTarget = null) {
-    if ('function' === typeof PointerEvent) {
-        el.dispatchEvent(new PointerEvent(type, { bubbles: true, cancelable: true, relatedTarget }));
-    }
-    else {
-        el.dispatchEvent(new MouseEvent(type, { bubbles: true, cancelable: true, relatedTarget }));
-    }
+    asSyntheticInput(() => {
+        if ('function' === typeof PointerEvent) {
+            el.dispatchEvent(new PointerEvent(type, { bubbles: true, cancelable: true, relatedTarget }));
+        }
+        else {
+            el.dispatchEvent(new MouseEvent(type, { bubbles: true, cancelable: true, relatedTarget }));
+        }
+    });
 }
 /** Enter/leave pointer events are non-bubbling per spec; keep them so to avoid double-firing. */
 export function firePointerNonBubbling(el, type, relatedTarget = null) {
-    if ('function' === typeof PointerEvent) {
-        el.dispatchEvent(new PointerEvent(type, { bubbles: false, cancelable: true, relatedTarget }));
-    }
-    else {
-        el.dispatchEvent(new MouseEvent(type, { bubbles: false, cancelable: true, relatedTarget }));
-    }
+    asSyntheticInput(() => {
+        if ('function' === typeof PointerEvent) {
+            el.dispatchEvent(new PointerEvent(type, { bubbles: false, cancelable: true, relatedTarget }));
+        }
+        else {
+            el.dispatchEvent(new MouseEvent(type, { bubbles: false, cancelable: true, relatedTarget }));
+        }
+    });
 }
 function makeDataTransfer(data) {
     if (typeof DataTransfer !== 'function')

package/dist/actions/actions.d.ts

@@ -51,6 +51,23 @@ interface ActionEffect {
      * the achieved hold can legitimately be much longer than the one requested.
      */
     heldMs?: number;
+    /**
+     * check/uncheck only: the control ALREADY read as the requested state, so NOTHING was dispatched.
+     * OMITTED otherwise (the uninformative default).
+     *
+     * Not clicking is right — clicking an already-checked box would uncheck it. But the branch that
+     * skips the click reads the DOM PROPERTY, and that is not evidence about what the APPLICATION
+     * holds. They come apart exactly when it matters: a default-checked input the app has not
+     * committed, a property written earlier by something else, a control read mid-render. Then `check`
+     * no-ops, the framework never hears, and every later read agrees because every later read is also
+     * reading the DOM — reported from the field as a form whose flag was unset in the database while
+     * Reticle confirmed it checked.
+     *
+     * So this is a caveat, not a failure: the requested state is what the DOM shows, and Reticle did
+     * not put it there. Assert the app's own state (a signal, a request, a derived control) rather than
+     * the box.
+     */
+    alreadyAtValue?: true;
 }
 interface ActionResult {
     ok: true;

package/dist/actions/actions.js

@@ -1,4 +1,5 @@
-import { ActionType, ActionWarning, DANGEROUS_ACTION_CONFIRM_ARG, ElementState, isDangerousActionText, SettleReason, } from '@reticlehq/core';
+import { ActionType, ActionWarning, DANGEROUS_ACTION_CONFIRM_ARG, ElementState, isDangerousActionText, NATIVE_INPUT_ARG, SettleReason, } from '@reticlehq/core';
+import { asSyntheticInput } from './synthetic-input.js';
 import { echoRef, refs } from '../dom/refs.js';
 import { assertEditable, assertNotRichText, setNativeValue } from './value-input.js';
 import { getAccessibleName, getRole, isVisible, getStates } from '../dom/a11y.js';
@@ -95,7 +96,40 @@ const FILL_LIKE = new Set([
 ]);
 const isFillLike = (action) => FILL_LIKE.has(action);
 /** Actions that resolve to a point and so benefit from off-viewport scroll + occlusion hit-test. */
-const CLICK_LIKE = new Set([ActionType.CLICK, ActionType.DBLCLICK]);
+const CLICK_LIKE = new Set([
+    ActionType.CLICK,
+    ActionType.DBLCLICK,
+    // check/uncheck activate through a real click, so they need everything a click needs: the point
+    // geometry, the off-viewport scroll, the occlusion hit-test, and the component/source attribution.
+    // Their absence here is why a `check` came back with no `component` while a `click` on the same
+    // element carried one — the tell the field report noticed and could not explain.
+    ActionType.CHECK,
+    ActionType.UNCHECK,
+]);
+/**
+ * A check/uncheck whose requested state the element already reads as, so nothing will be dispatched.
+ *
+ * ONE predicate, read twice — the dispatch branch decides not to click, the effect reports that it
+ * did not. Two copies of this rule could disagree, and a disagreement here is precisely the false
+ * green: an act that reports it drove a control it never touched.
+ */
+function alreadyAtCheckedState(el, action) {
+    if (action !== ActionType.CHECK && action !== ActionType.UNCHECK)
+        return false;
+    return isInput(el) && el.checked === (action === ActionType.CHECK);
+}
+/**
+ * What the destructive-action guard classifies: the ELEMENT, and nothing rendered around it.
+ *
+ * This used to end with `form?.textContent`, so the whole enclosing form's rendered text decided the
+ * verdict for every control inside it — a settings form with per-row "Remove" buttons made its own
+ * Save button read as destructive, intermittently, depending on whether the rows had rendered yet.
+ * The field report's workaround was `confirmDangerous: true` on every click, which deletes the guard
+ * outright: a guard that fires on everything is a guard that gets switched off.
+ *
+ * The form's `action` stays — that is a URL this element submits to, i.e. a property of what this
+ * click DOES, not of what happens to be on screen beside it.
+ */
 function dangerousActionContext(el) {
     const form = el.closest('form');
     return [
@@ -106,7 +140,6 @@ function dangerousActionContext(el) {
         el.getAttribute('aria-label') ?? '',
         el.getAttribute('href') ?? '',
         form?.getAttribute('action') ?? '',
-        form?.textContent ?? '',
     ].join(' ');
 }
 function requiresDangerousConfirmation(text) {
@@ -132,6 +165,23 @@ function pressKey(args) {
         return text;
     return asString(args['key'], 'Enter');
 }
+/**
+ * Modifier flags for a `press`, from `args.modifiers`: an array of Meta / Control / Shift / Alt
+ * (case-insensitive, with the usual aliases). Without them a Cmd+K / Ctrl+Shift shortcut receives a
+ * keydown with every modifier false, so the app's own `event.metaKey` check never matches and
+ * nothing observable happens -- a false negative Reticle reports as no error. (#393)
+ */
+function pressModifiers(args) {
+    const raw = args['modifiers'];
+    const names = Array.isArray(raw) ? raw.map((m) => asString(m).toLowerCase()) : [];
+    const has = (...aliases) => aliases.some((a) => names.includes(a));
+    return {
+        metaKey: has('meta', 'cmd', 'command', 'super', 'win'),
+        ctrlKey: has('control', 'ctrl'),
+        shiftKey: has('shift'),
+        altKey: has('alt', 'option', 'opt'),
+    };
+}
 /**
  * The PHYSICAL key identity — `event.code` — derived from the logical key.
  *
@@ -207,9 +257,50 @@ function dragTargetRef(args) {
     const named = asString(args['toRef']);
     return '' !== named ? named : asString(args['target']);
 }
+/** The keys `upload` actually reads, and the generic ones every action accepts. */
+const UPLOAD_ARG_KEYS = new Set(['content', 'name', 'type']);
+const GENERIC_ACTION_ARG_KEYS = new Set([
+    DANGEROUS_ACTION_CONFIRM_ARG,
+    NATIVE_INPUT_ARG,
+    'holdMs',
+]);
+/**
+ * An `upload` must have been told what to upload.
+ *
+ * The branch below defaults every field, so a call whose keys were all unrecognised — the field
+ * report sent `args.files` — manufactured a 17-byte `file.txt` reading "reticle test file", uploaded
+ * THAT, and returned ok:true. The server answered 200, the UI refreshed, and every signal the agent
+ * could read said its PDF had been processed. That is a manufactured green on the write path, the
+ * same shape `drag` refuses one branch below.
+ *
+ * Both halves matter. A call with no recognised key at all never described a file; a call that mixes
+ * one in with a dropped one (`{ path, name }`) is worse, because the right filename arrives attached
+ * to invented bytes. A name-only call keeps working: the placeholder body is documented and the
+ * caller that omitted `content` knows it did.
+ *
+ * The refusal names the keys upload reads so a caller that guessed can correct in one turn.
+ *
+ * Scoped to upload deliberately. Dropping an unrecognised key in silence is a property of EVERY
+ * action — `args` is `z.record(z.unknown())` at the wire boundary — but upload is the one where the
+ * dropped key is replaced with fabricated content. Refusing unknown keys everywhere needs a
+ * per-action arg schema in core and is a larger change than this release should carry.
+ */
+function assertUploadArgs(args) {
+    const keys = Object.keys(args);
+    const dropped = keys.filter((k) => !UPLOAD_ARG_KEYS.has(k) && !GENERIC_ACTION_ARG_KEYS.has(k));
+    if (0 === dropped.length && keys.some((k) => UPLOAD_ARG_KEYS.has(k)))
+        return;
+    const detail = 0 === dropped.length
+        ? 'no file was described'
+        : `upload does not read ${dropped.join(', ')}, so it would be dropped`;
+    throw new Error(`upload needs the file described as args: { name, content?, type? } — ${detail}. ` +
+        'Reading a file from disk is not supported; pass its bytes as `content`.');
+}
 function assertActionAllowed(el, action, args) {
     const canTrigger = action === ActionType.CLICK ||
         action === ActionType.DBLCLICK ||
+        action === ActionType.CHECK ||
+        action === ActionType.UNCHECK ||
         action === ActionType.DRAG ||
         action === ActionType.SUBMIT ||
         // Read through the SAME resolver as the dispatch below. Reading a different argument here meant
@@ -285,7 +376,7 @@ async function dispatchFor(el, action, args) {
 async function dispatchOther(el, action, args) {
     switch (action) {
         case ActionType.DBLCLICK:
-            return !el.dispatchEvent(new MouseEvent('dblclick', { bubbles: true, cancelable: true }));
+            return !asSyntheticInput(() => el.dispatchEvent(new MouseEvent('dblclick', { bubbles: true, cancelable: true })));
         case ActionType.HOVER: {
             const doc = el.ownerDocument;
             // Best-effort "previous" node for relatedTarget so React's enter/leave synthesis has a "from".
@@ -411,30 +502,33 @@ async function dispatchOther(el, action, args) {
             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);
+            // A radio is deselected by selecting another radio, never on its own. Refusing is the same
+            // rule as the disabled control above: a state no user could reach must not be forced.
+            if ('radio' === el.type && action === ActionType.UNCHECK) {
+                throw new Error('cannot uncheck a radio button — a real user could not; select another radio in the group');
             }
-            return prevented;
+            // Already there: touch nothing. `check` means "end up checked", not "toggle", so clicking here
+            // would flip it OFF, and SETTING it would hand the app an `input`/`change` no user produced —
+            // enough to make an app that autosaves, logs or POSTs on change act on a no-op. Reported as
+            // `effect.alreadyAtValue` — the same predicate, read again by executeAction — because "nothing
+            // was dispatched" is not the same claim as "the app holds this value". See ActionEffect.
+            if (alreadyAtCheckedState(el, action))
+                return false;
+            // A real 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.
+            //
+            // Dispatched rather than `el.click()` so cancellation is read off the event object itself. The
+            // old probe listened on `window`, which never runs when a handler calls `stopPropagation()`, so
+            // a cancelled activation was reported as a successful one. Activation behaviour runs either way
+            // — a synthetic click toggles the box, which `adversarial.check.test.ts` pins, because the
+            // comment this replaces asserted the opposite and was wrong.
+            const event = new MouseEvent('click', { bubbles: true, cancelable: true, composed: true });
+            // Marked as ours so the annotator's capture-phase listener lets it through: in annotate mode
+            // it cancels clicks to place a mark, which would otherwise swallow every action we dispatch.
+            const notPrevented = asSyntheticInput(() => el.dispatchEvent(event));
+            return !notPrevented || event.defaultPrevented;
         }
         case ActionType.SUBMIT: {
             const form = isForm(el) ? el : el.closest('form');
@@ -446,8 +540,11 @@ async function dispatchOther(el, action, args) {
         case ActionType.PRESS: {
             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 }));
+            const mods = pressModifiers(args);
+            // Marked as ours like the click sequence: the annotator leaves annotate mode on Escape, so an
+            // agent pressing Escape would otherwise switch off a mode the person turned on.
+            const down = asSyntheticInput(() => el.dispatchEvent(new KeyboardEvent('keydown', { key, code, bubbles: true, cancelable: true, ...mods })));
+            asSyntheticInput(() => el.dispatchEvent(new KeyboardEvent('keyup', { key, code, bubbles: true, ...mods })));
             return !down;
         }
         case ActionType.SCROLL_INTO_VIEW:
@@ -457,6 +554,7 @@ async function dispatchOther(el, action, args) {
             if (!isInput(el) || el.type !== 'file') {
                 throw new Error('upload target must be a <input type="file">');
             }
+            assertUploadArgs(args);
             const file = new File([asString(args['content'], 'reticle test file')], asString(args['name'], 'file.txt'), {
                 type: asString(args['type'], 'text/plain'),
             });
@@ -504,6 +602,8 @@ export async function executeAction(ref, action, args = {}) {
     // Click-like: scroll an off-viewport target in + hit-test the click point BEFORE installing the
     // 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;
+    // Read BEFORE dispatch, from the same predicate the dispatch branch uses.
+    const alreadyAtValue = alreadyAtCheckedState(el, action);
     let mutated = 0;
     const said = new AppearedText();
     const obs = new MutationObserver((records) => {
@@ -556,6 +656,9 @@ export async function executeAction(ref, action, args = {}) {
         // 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 } : {}),
+        // Omitted unless it applies: an absent key means the action actually drove the control (or is
+        // not a check at all), which is the only reading that must not be ambiguous.
+        ...(alreadyAtValue ? { alreadyAtValue: true } : {}),
     };
     // 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/synthetic-input.d.ts

@@ -0,0 +1,9 @@
+/** True while a Reticle-dispatched input event is being delivered. */
+export declare function isSyntheticInput(): boolean;
+/**
+ * Run `dispatch` marked as Reticle's own.
+ *
+ * `finally` rather than a trailing decrement: a listener that throws must not leave the flag stuck
+ * on, which would silently disable annotation for the rest of the page's life.
+ */
+export declare function asSyntheticInput<T>(dispatch: () => T): T;

package/dist/actions/synthetic-input.js

@@ -0,0 +1,40 @@
+/**
+ * Is the input event currently being dispatched one that RETICLE made?
+ *
+ * The annotator listens for clicks in the capture phase and cancels them, because a click in
+ * annotate mode is a request to place a mark rather than a request to press a button. That is right
+ * for a person and wrong for the agent: `reticle_act` dispatches its clicks into the same document,
+ * so with the HUD expanded every agent click was swallowed while the action still reported
+ * `dispatched: true`. Measured on this repo's own fixture — the same click that produced
+ * `POST /api/login -> 200` with annotate off produced no network at all with it on.
+ *
+ * `isTrusted` looks like the answer and is not usable: it is false for everything `dispatchEvent`
+ * creates, which is also how every test in this package drives the annotator, so gating on it would
+ * make annotation untestable and would still not distinguish Reticle's clicks from the page's own
+ * synthetic ones.
+ *
+ * So Reticle marks its own. Dispatch is synchronous, so a plain depth counter held across the call
+ * is exact: any listener running inside it — capture phase included — is running because of us.
+ * Nested actions are counted rather than flagged, so an inner action finishing does not clear the
+ * mark for the outer one still in flight.
+ */
+let depth = 0;
+/** True while a Reticle-dispatched input event is being delivered. */
+export function isSyntheticInput() {
+    return depth > 0;
+}
+/**
+ * Run `dispatch` marked as Reticle's own.
+ *
+ * `finally` rather than a trailing decrement: a listener that throws must not leave the flag stuck
+ * on, which would silently disable annotation for the rest of the page's life.
+ */
+export function asSyntheticInput(dispatch) {
+    depth += 1;
+    try {
+        return dispatch();
+    }
+    finally {
+        depth -= 1;
+    }
+}

package/dist/commands/commands.js

@@ -3,7 +3,7 @@ import { buildSnapshot } from '../dom/snapshot.js';
 import { matchQuery, runQuery } from '../dom/query.js';
 import { executeAction, executeSequence, dispatchWebMcp, } from '../actions/actions.js';
 import { describe } from '../dom/a11y.js';
-import { sourceFor, formatSource } from '../dom/source.js';
+import { documentHasSourceStamps, sourceFor, formatSource } from '../dom/source.js';
 import { themeReport } from '../dom/theme.js';
 import { echoRef, refs } from '../dom/refs.js';
 import { isButton, isInput } from '../dom/realm.js';
@@ -91,6 +91,15 @@ function inspect(ref) {
     // stamped host. `act` already did this; inspect did not, so the two tools disagreed about the same
     // ref and inspect — the tool you reach for to ask where something lives — was the one saying null.
     const source = formatSource(sourceFor(el, component?.source));
+    // Say WHY the source is missing rather than omitting the field and leaving the caller to guess.
+    // No stamp anywhere in the document is decisive: the loader is not running, so no element will
+    // have one this session, and the fix is a build-config change rather than anything about this
+    // element. Only computed when `source` is already absent, so the ordinary path pays nothing.
+    const sourceUnavailable = source !== undefined
+        ? undefined
+        : documentHasSourceStamps(el.ownerDocument)
+            ? 'This element has no source stamp. Others on the page do, so the stamping loader is running — the nearest stamped ancestor is out of range, or this element is rendered outside instrumented code.'
+            : 'No element in this document carries a source stamp, so the stamping loader is not running: an older adapter, a bundler whose hook never ran, or a build the plugin was dropped from. Add @reticlehq/vite-plugin (or @reticlehq/babel-plugin) to the dev build and restart the dev server to get `file:line` back.';
     const scroll = {
         scrollTop: el.scrollTop,
         scrollHeight: el.scrollHeight,
@@ -100,6 +109,7 @@ function inspect(ref) {
     return {
         ...describe(el),
         ...(source !== undefined ? { source } : {}),
+        ...(sourceUnavailable !== undefined ? { sourceUnavailable } : {}),
         tag: el.tagName.toLowerCase(),
         href: el.getAttribute('href') ?? undefined,
         formAction: isButton(el) || isInput(el) ? (el.form?.getAttribute('action') ?? undefined) : undefined,

package/dist/connect-options.d.ts

@@ -2,7 +2,7 @@ import type { RedactionConfig } from '@reticlehq/core';
 /**
  * What `reticle.connect()` accepts.
  *
- * Split out of reticle.ts when that file crossed the 600-line cap — the same move `session-info.ts`
+ * Split out of reticle.ts when that file crossed the 600-line cap - the same move `session-info.ts`
  * made for the server's Session. A pure description of the SDK's public entry contract has no reason
  * to live inside the class that happens to consume it, and separating them keeps the surface every
  * integrating app actually reads reviewable on its own.
@@ -32,7 +32,7 @@ export interface ReticleConnectOptions {
     overlay?: boolean;
     /**
      * Capture request/response bodies on net.request events (dev-only; text-like content only,
-     * sensitive keys redacted, per-body capped). Off by default — bodies cost tokens and can carry PII.
+     * sensitive keys redacted, per-body capped). Off by default - bodies cost tokens and can carry PII.
      */
     captureNetworkBodies?: boolean;
     /**
@@ -41,7 +41,7 @@ export interface ReticleConnectOptions {
      * React's `_debugSource.fileName` is absolute; the babel stamp is repo-relative. Build plugins that
      * can `define` a global set it themselves; frameworks that cannot (Next passes it through env,
      * Astro through its own config) hand it here instead. Taking it as a connect OPTION is what keeps
-     * the generated app-side code plain JavaScript — the previous shape made the caller assign a global,
+     * the generated app-side code plain JavaScript - the previous shape made the caller assign a global,
      * and the TypeScript cast that needed shipped into a `.jsx` file and broke the build.
      */
     root?: string;
@@ -66,13 +66,13 @@ export interface ReticleConnectOptions {
     logMax?: number;
     /**
      * Mount the floating human-recorder toolbar (Record/Stop/Annotate).
-     * Default off — purely additive, dev-only.
+     * Default off - purely additive, dev-only.
      */
     recorder?: boolean;
     /**
-     * Mount the "Flag a bug" annotator: the human clicks an element that looks wrong, types what's
-     * wrong, and Reticle emits a HUMAN_MARK the agent drains via reticle_review. Defaults to ON with the
-     * presenter (it's the human's side of the look→act→assert loop); pass `annotate: false` to suppress.
+     * Mount the page annotator: expanding the HUD enters click-to-annotate mode, and Reticle emits
+     * a HUMAN_MARK the agent drains via reticle_review. Defaults to ON with the presenter; pass
+     * `annotate: false` to suppress.
      */
     annotate?: boolean;
     /** Live-control: overridable ended-border fade delay (native timer). Default 4000. */
@@ -91,13 +91,13 @@ export interface ReticleConnectOptions {
      * });
      * ```
      *
-     * Additive only — there is no way to replace the built-in rule, because a config that could would
+     * Additive only - there is no way to replace the built-in rule, because a config that could would
      * eventually ship an app that leaks. `keys` strings match a key name exactly (case-insensitively);
      * a RegExp is tested against it. `allow` exempts a key from the DEFAULT rule and loses to `keys`.
      *
      * Literal `keys` strings also cross the bridge, so the daemon redacts them on the driven path,
      * where request bodies are captured raw from the network stack and never pass through this SDK.
-     * RegExp entries and `allow` do NOT cross — see docs/usage.md ("Extending the redaction rules") for why, and what that means.
+     * RegExp entries and `allow` do NOT cross - see docs/usage.md ("Extending the redaction rules") for why, and what that means.
      */
     redact?: RedactionConfig;
 }

package/dist/dom/a11y.d.ts

@@ -23,6 +23,15 @@ export declare function getValue(el: Element): string | undefined;
  * static for the pass's duration — the cache MUST be a per-call Map, never module-level (that would go
  * stale the instant the app mutates, the same trap the shadow-root note in query.ts documents).
  */
+/**
+ * True when the element is inside the viewport right now: visible AND its bounding box intersects
+ * the window. This is what makes a scroll assertable (#398) — content below the fold of a scrolling
+ * container is `visible`/`present` before any scroll, so only a viewport-intersection check can tell
+ * "scrolled into view" from "was always in the DOM". Uses getBoundingClientRect (viewport-relative,
+ * already accounts for scroll position), not an IntersectionObserver, so it stays synchronous inside
+ * the predicate pass.
+ */
+export declare function isInViewport(el: Element, memo?: Map<Element, boolean>): boolean;
 export declare function isVisible(el: Element, memo?: Map<Element, boolean>): boolean;
 /** Build the compact descriptor surfaced to the agent. `memo` (optional) shares the per-call
  * visibility cache with the query's state filter so ancestors aren't re-walked per element. */

package/dist/dom/a11y.js

@@ -272,6 +272,25 @@ function selfHidden(el) {
  * static for the pass's duration — the cache MUST be a per-call Map, never module-level (that would go
  * stale the instant the app mutates, the same trap the shadow-root note in query.ts documents).
  */
+/**
+ * True when the element is inside the viewport right now: visible AND its bounding box intersects
+ * the window. This is what makes a scroll assertable (#398) — content below the fold of a scrolling
+ * container is `visible`/`present` before any scroll, so only a viewport-intersection check can tell
+ * "scrolled into view" from "was always in the DOM". Uses getBoundingClientRect (viewport-relative,
+ * already accounts for scroll position), not an IntersectionObserver, so it stays synchronous inside
+ * the predicate pass.
+ */
+export function isInViewport(el, memo) {
+    if (!isVisible(el, memo))
+        return false;
+    const view = el.ownerDocument.defaultView;
+    if (null === view)
+        return false;
+    const r = el.getBoundingClientRect();
+    if (r.width <= 0 || r.height <= 0)
+        return false;
+    return r.bottom > 0 && r.right > 0 && r.top < view.innerHeight && r.left < view.innerWidth;
+}
 export function isVisible(el, memo) {
     if (!el.isConnected)
         return false;

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

@@ -1,15 +1,28 @@
 /**
- * Selectors for Reticle's own presenter overlay (cursor, HUD, glow) + the annotator's "flag a bug"
- * UI (`data-reticle-mark`) — never observed/snapshotted. The annotator mounts by DEFAULT with the
- * presenter, so omitting its selector here leaked a phantom `<button>Flag a bug</button>` into every
- * snapshot and streamed its highlight-box mutations/transitions as if the APP had rendered them.
+ * Selectors for Reticle's own presenter overlay (cursor, HUD, glow) + the annotator's
+ * UI (`data-reticle-mark`) - never observed/snapshotted. The annotator mounts by DEFAULT with the
+ * presenter, so omitting its selector here leaked annotation chrome into every snapshot.
  */
-export declare const RETICLE_OVERLAY = "[data-reticle-overlay],[data-reticle-cursor],[data-reticle-hud],[data-reticle-glow],[data-reticle-mark]";
+export declare const RETICLE_OVERLAY: string;
 /** Let the host app add selectors to exclude from snapshots (e.g. its own dev widgets). */
 export declare function setIgnoreSelectors(selectors: string[]): void;
 /** True if the element is part of Reticle's own presenter overlay. */
 export declare function isReticleOverlay(el: Element): boolean;
-/** Walk ancestors: true iff any element in the chain carries a data-reticle* attribute (Reticle's own UI). */
+/**
+ * True iff the element is part of Reticle's OWN UI - the presenter overlay, the HUD, the synthetic
+ * cursor, the glow, or the annotator's marks - or lives inside one of them.
+ *
+ * The rule used to be "any ancestor carries a data-reticle* attribute", which is wrong twice over.
+ * `data-reticle-mark-active` sits on <html> while annotate mode is live, so the whole document
+ * answered yes; and `data-reticle-source` is stamped by the Vite/Babel plugins on every element the
+ * APP renders, so in an instrumented app - which is the only kind there is - most of the page
+ * answered yes too. Those attributes describe page content; they do not make it ours.
+ *
+ * Two things read this and both failed silently. `pageElementAt` (annotator) skipped every stamped
+ * element and anchored the note to the outermost unstamped ancestor, i.e. the app shell instead of
+ * the control under the cursor. `occlusion.ts` reads a yes as "nothing to report", so occlusion
+ * detection - a bug class Reticle advertises catching - came back clean wherever the stamp reached.
+ */
 export declare function isReticleUi(node: Element | null): boolean;
 /** True if the element should be excluded from snapshots/queries (Reticle overlay or dev overlay). */
 export declare function isIgnored(el: Element): boolean;

package/dist/dom/dom-ignore.js

@@ -1,10 +1,9 @@
 /**
- * Selectors for Reticle's own presenter overlay (cursor, HUD, glow) + the annotator's "flag a bug"
- * UI (`data-reticle-mark`) — never observed/snapshotted. The annotator mounts by DEFAULT with the
- * presenter, so omitting its selector here leaked a phantom `<button>Flag a bug</button>` into every
- * snapshot and streamed its highlight-box mutations/transitions as if the APP had rendered them.
+ * Selectors for Reticle's own presenter overlay (cursor, HUD, glow) + the annotator's
+ * UI (`data-reticle-mark`) - never observed/snapshotted. The annotator mounts by DEFAULT with the
+ * presenter, so omitting its selector here leaked annotation chrome into every snapshot.
  */
-export const RETICLE_OVERLAY = '[data-reticle-overlay],[data-reticle-cursor],[data-reticle-hud],[data-reticle-glow],[data-reticle-mark]';
+export const RETICLE_OVERLAY = '[data-reticle-overlay],[data-reticle-cursor],[data-reticle-hud],[data-reticle-glow],[data-reticle-mark],[data-reticle-blocker]';
 /** Known third-party dev overlays to keep out of snapshots (Agentation, Next dev UI). */
 const DEV_OVERLAYS = '[data-agentation],#__next-build-watcher,nextjs-portal,[data-nextjs-dialog],[data-nextjs-toast]';
 let extraIgnore = '';
@@ -16,15 +15,23 @@ export function setIgnoreSelectors(selectors) {
 export function isReticleOverlay(el) {
     return el.closest(RETICLE_OVERLAY) !== null;
 }
-/** Walk ancestors: true iff any element in the chain carries a data-reticle* attribute (Reticle's own UI). */
+/**
+ * True iff the element is part of Reticle's OWN UI - the presenter overlay, the HUD, the synthetic
+ * cursor, the glow, or the annotator's marks - or lives inside one of them.
+ *
+ * The rule used to be "any ancestor carries a data-reticle* attribute", which is wrong twice over.
+ * `data-reticle-mark-active` sits on <html> while annotate mode is live, so the whole document
+ * answered yes; and `data-reticle-source` is stamped by the Vite/Babel plugins on every element the
+ * APP renders, so in an instrumented app - which is the only kind there is - most of the page
+ * answered yes too. Those attributes describe page content; they do not make it ours.
+ *
+ * Two things read this and both failed silently. `pageElementAt` (annotator) skipped every stamped
+ * element and anchored the note to the outermost unstamped ancestor, i.e. the app shell instead of
+ * the control under the cursor. `occlusion.ts` reads a yes as "nothing to report", so occlusion
+ * detection - a bug class Reticle advertises catching - came back clean wherever the stamp reached.
+ */
 export function isReticleUi(node) {
-    for (let n = node; n !== null; n = n.parentElement) {
-        for (const attr of Array.from(n.attributes)) {
-            if (attr.name.startsWith('data-reticle'))
-                return true;
-        }
-    }
-    return false;
+    return node !== null && node.closest(RETICLE_OVERLAY) !== null;
 }
 /** True if the element should be excluded from snapshots/queries (Reticle overlay or dev overlay). */
 export function isIgnored(el) {

package/dist/dom/query.d.ts

@@ -12,7 +12,7 @@ export declare function matchQuery(query: ElementQuery, state?: ElementState, li
  * Resolve a query to descriptors for the `query` MCP tool.
  *
  * `count` is carried through deliberately: the server reports match totals from it rather than from
- * the array, because the array is capped in transit. Dropping it here — which this function used to
- * do — silently put the server back to counting survivors and calling that the answer.
+ * the array, because the array is capped in transit. Dropping it here - which this function used to
+ * do - silently put the server back to counting survivors and calling that the answer.
  */
 export declare function runQuery(query: ElementQuery, limit?: number): QueryResult;