Real-world dogfooding surfaced clicks that resolve a valid @ref but still miss:
- Scroll the target into view before computing click coordinates
(scrollIntoViewIfNeeded). Without it, an element below the fold — or revealed
after a scroll/popup — yields off-viewport coordinates and the click lands on
whatever occupies that screen point.
- Fall back to a DOM-dispatched `.click()` when the coordinate path fails (a
persistent floating layer failing the occlusion guard, or coordinates that
won't resolve). The DOM dispatch targets the intended element directly instead
of a screen point, so an overlay or portal can't divert it.
- AGENT_BROWSER_CLICK_MODE: "" (default: scroll + coordinate + DOM fallback),
"coord" (strict coordinate, hard-fail on occlusion), "dom" (always
element.click() — best for autocomplete/menu <li> that close on input blur).
Fallback is limited to left single-clicks (DOM .click() can't express
right/middle/double). Non-left/multi and "coord" mode keep the original error.
Docs: README knob table + skill commands.md gain CLICK_MODE, a click-reliability
note, and a "debug forms/hidden inputs with eval" section (snapshot doesn't show
hidden inputs — the fast path to bugs like a hidden point_choice=none).
6 click/interaction e2e green; full suite 760 passed.
leeguooooo
e7548c3eb5