An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
refactor(page): lift pointer geometry out of trusted-click into its own module
Shahriar74a6a5770ec7
diff --git a/lib/actions/page/hover-element.ts b/lib/actions/page/hover-element.tsindex a146146..dd2196a 100644--- a/lib/actions/page/hover-element.ts+++ b/lib/actions/page/hover-element.ts@@ -1,6 +1,7 @@import { z } from 'zod';import { defineAction } from '../core';import { describeElement, resolveTarget, targetSchema } from './dom';+import { hoverSequence } from './pointer';export const hoverElement = defineAction({name: 'page.hoverElement',@@ -13,20 +14,7 @@ export const hoverElement = defineAction({const el = resolveTarget(target);if (scrollIntoView) el.scrollIntoView({ block: 'center', behavior: 'instant' });const rect = el.getBoundingClientRect();- const clientX = rect.x + rect.width / 2;- const clientY = rect.y + rect.height / 2;- const sequence: Array<['pointer' | 'mouse', string, boolean]> = [- ['pointer', 'pointerover', true],- ['pointer', 'pointerenter', false],- ['pointer', 'pointermove', true],- ['mouse', 'mouseover', true],- ['mouse', 'mouseenter', false],- ['mouse', 'mousemove', true],- ];- for (const [kind, type, bubbles] of sequence) {- const Ctor = kind === 'pointer' ? PointerEvent : MouseEvent;- el.dispatchEvent(new Ctor(type, { clientX, clientY, bubbles, composed: true }));- }+ hoverSequence(el, { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 });return describeElement(el);},});diff --git a/lib/actions/page/pointer.ts b/lib/actions/page/pointer.tsnew file mode 100644index 0000000..09245c5--- /dev/null+++ b/lib/actions/page/pointer.ts@@ -0,0 +1,105 @@+import { z } from 'zod';+import { ActionError } from '../core';+import { cssPath } from './dom';++const APPROACH_OFFSET = 120;++export const APPROACH_STEPS = 4;+const MAX_DRIFT_PX = 6;++export interface Point {+ x: number;+ y: number;+}++export const pointSchema = z.object({+ x: z.number().describe('Pixels from the left edge of the viewport'),+ y: z.number().describe('Pixels from the top edge of the viewport'),+});++function viewport(): { w: number; h: number } {+ return { w: document.documentElement.clientWidth, h: document.documentElement.clientHeight };+}++export function elementPoint(el: HTMLElement): Point {+ const rect = el.getBoundingClientRect();+ const { w, h } = viewport();+ const left = Math.max(rect.left, 0);+ const top = Math.max(rect.top, 0);+ const right = Math.min(rect.right, w);+ const bottom = Math.min(rect.bottom, h);+ if (right <= left || bottom <= top) {+ throw new ActionError(+ 'The element has no visible area inside the viewport — scroll it into view, then retry',+ 'INVALID_TARGET',+ );+ }+ return { x: Math.round((left + right) / 2), y: Math.round((top + bottom) / 2) };+}++export function viewportPoint(point: Point): Point {+ const { w, h } = viewport();+ if (point.x < 0 || point.y < 0 || point.x >= w || point.y >= h) {+ throw new ActionError(+ `The point (${point.x}, ${point.y}) is outside the ${w}×${h} viewport — scroll it into view, then retry`,+ 'INVALID_TARGET',+ );+ }+ return { x: Math.round(point.x), y: Math.round(point.y) };+}++export function approachPoint(to: Point): Point {+ const { w, h } = viewport();+ return {+ x: Math.min(Math.max(to.x - APPROACH_OFFSET, 0), w - 1),+ y: Math.min(Math.max(to.y - APPROACH_OFFSET, 0), h - 1),+ };+}++export function elementAt(point: Point): Element | null {+ return document.elementFromPoint(point.x, point.y);+}++export function assertUncovered(el: HTMLElement, at: Point): void {+ const hit = elementAt(at);+ if (hit === el || el.contains(hit)) return;+ throw new ActionError(+ hit+ ? `${cssPath(hit)} covers (${at.x}, ${at.y}) — dismiss whatever is over the element, then retry`+ : `Nothing is painted at (${at.x}, ${at.y}) — scroll the element into view, then retry`,+ 'INVALID_TARGET',+ );+}++const easeOut = (progress: number) => 1 - (1 - progress) ** 3;++export function pathBetween(from: Point, to: Point, steps: number): Point[] {+ const dx = to.x - from.x;+ const dy = to.y - from.y;+ const span = Math.hypot(dx, dy) || 1;+ const drift = Math.min(MAX_DRIFT_PX, span / 8);+ return Array.from({ length: steps }, (_, index) => {+ const progress = easeOut((index + 1) / steps);+ const wobble = Math.sin(progress * Math.PI) * drift * (index % 2 ? -1 : 1);+ return {+ x: Math.round(from.x + dx * progress - (dy / span) * wobble),+ y: Math.round(from.y + dy * progress + (dx / span) * wobble),+ };+ });+}++const HOVER_SEQUENCE: Array<['pointer' | 'mouse', string, boolean]> = [+ ['pointer', 'pointerover', true],+ ['pointer', 'pointerenter', false],+ ['pointer', 'pointermove', true],+ ['mouse', 'mouseover', true],+ ['mouse', 'mouseenter', false],+ ['mouse', 'mousemove', true],+];++export function hoverSequence(el: Element, at: Point): void {+ for (const [kind, type, bubbles] of HOVER_SEQUENCE) {+ const Ctor = kind === 'pointer' ? PointerEvent : MouseEvent;+ el.dispatchEvent(new Ctor(type, { clientX: at.x, clientY: at.y, bubbles, composed: true }));+ }+}diff --git a/lib/actions/page/trusted-click.ts b/lib/actions/page/trusted-click.tsindex 29f899b..55ea61f 100644--- a/lib/actions/page/trusted-click.ts+++ b/lib/actions/page/trusted-click.ts@@ -1,47 +1,7 @@import { z } from 'zod';import { ActionError, defineAction } from '../core';import { cssPath, describeElement, resolveTarget, submitsOnClick, targetSchema } from './dom';--const APPROACH_OFFSET = 120;--function viewport(): { w: number; h: number } {- return { w: document.documentElement.clientWidth, h: document.documentElement.clientHeight };-}--function clickPoint(el: HTMLElement): { x: number; y: number } {- const rect = el.getBoundingClientRect();- const { w, h } = viewport();- const left = Math.max(rect.left, 0);- const top = Math.max(rect.top, 0);- const right = Math.min(rect.right, w);- const bottom = Math.min(rect.bottom, h);- if (right <= left || bottom <= top) {- throw new ActionError(- 'The element has no visible area inside the viewport — scroll it into view, then retry',- 'INVALID_TARGET',- );- }- return { x: Math.round((left + right) / 2), y: Math.round((top + bottom) / 2) };-}--function viewportPoint(point: { x: number; y: number }): { x: number; y: number } {- const { w, h } = viewport();- if (point.x < 0 || point.y < 0 || point.x >= w || point.y >= h) {- throw new ActionError(- `The point (${point.x}, ${point.y}) is outside the ${w}×${h} viewport — scroll it into view, then retry`,- 'INVALID_TARGET',- );- }- return { x: Math.round(point.x), y: Math.round(point.y) };-}--function approachPoint(to: { x: number; y: number }): { x: number; y: number } {- const { w, h } = viewport();- return {- x: Math.min(Math.max(to.x - APPROACH_OFFSET, 0), w - 1),- y: Math.min(Math.max(to.y - APPROACH_OFFSET, 0), h - 1),- };-}+import { approachPoint, assertUncovered, elementAt, elementPoint, pointSchema, viewportPoint } from './pointer';export const trustedClick = defineAction({name: 'page.trustedClick',@@ -49,11 +9,7 @@ export const trustedClick = defineAction({'Click with a real browser-level mouse event — isTrusted is true, exactly as if the user had clicked. The pointer travels to the target over a short path and dwells before pressing, so widgets that only react after genuine pointer movement (drag handles, hover menus, canvas tools, captcha checkboxes) see the sequence they wait for. Use it when page.clickElement was ignored: pages that check event.isTrusted, and the browser features only a genuine gesture unlocks — native file pickers, fullscreen, clipboard reads, popups, WebAuthn prompts. Give it either a "target" or a raw viewport "point". It attaches Chrome’s debugger for the duration, so the browser shows a “Browsentic is debugging this browser” bar while it runs, it cannot run on a tab that has DevTools open, and it is unavailable on Firefox. page.clickElement stays the default for ordinary clicks.',input: z.object({target: targetSchema.optional().describe('Element to click. Give this or "point", never both.'),- point: z- .object({- x: z.number().describe('Pixels from the left edge of the viewport'),- y: z.number().describe('Pixels from the top edge of the viewport'),- })+ point: pointSchema.optional().describe('Exact viewport coordinates to click, in CSS pixels. Use this when the thing to click has no reachable element — inside a cross-origin iframe or a closed shadow root, as page.findCaptcha reports.',@@ -101,19 +57,12 @@ export const trustedClick = defineAction({const el = target ? resolveTarget(target) : null;if (el && scrollIntoView) el.scrollIntoView({ block: 'center', behavior: 'instant' });- const at = el ? clickPoint(el) : viewportPoint(point!);- const hit = document.elementFromPoint(at.x, at.y);- if (el && !(hit === el || el.contains(hit))) {- throw new ActionError(- hit- ? `${cssPath(hit)} covers the click point — dismiss whatever is over the element, then retry`- : 'Nothing is painted at the click point — scroll the element into view, then retry',- 'INVALID_TARGET',- );- }+ const at = el ? elementPoint(el) : viewportPoint(point!);+ if (el) assertUncovered(el, at);+ const under = elementAt(at);return {- ...(el ? describeElement(el) : { over: hit ? cssPath(hit) : undefined }),+ ...(el ? describeElement(el) : { over: under ? cssPath(under) : undefined }),point: at,from: approachPoint(at),button,