atomic_interact
Perform browser interactions (click, type, drag) as a single atomic operation, preventing race conditions from DOM re-renders.
Instructions
THE PRIMARY INTERACTION TOOL. Combines element location and action into a single, uninterruptible browser engine tick. This eliminates Virtual DOM detachment race conditions that plague multi-step locate→act patterns. Uses direct CDP Input.dispatch* commands — not high-level Puppeteer abstractions.
ACTIONS: • click — Click an element. Uses spatial validation to verify the target is not occluded. • dblclick — Double-click an element (useful for canvas items or file explorers). • type — Focus an element and type text into it. Automatically clears existing content first. • clear — Clear an input element. • hover — Move the mouse to an element's center to trigger hover states. • key — Press a keyboard key (e.g., "Enter", "Escape", "Tab", "ArrowDown"). • scroll — Scroll the page (direction: "up", "down", "top", "bottom"). • drag_and_drop — Drag an element or coordinate to another element or coordinate.
LOCATOR STRATEGIES: • backendNodeId (number) — The most reliable. Obtained from get_semantic_surface output (the [id: NNN] tag on each node). • coordinate ([x, y]) — Raw pixel coordinates. Use for Canvas/WebGL or when backendNodeId is unavailable.
IMPORTANT: Always prefer backendNodeId from get_semantic_surface over CSS selectors or coordinates. backendNodeIds are assigned by the browser engine and survive React/Vue re-renders.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Key name to press (required for action="key", e.g., "Enter", "Escape", "Tab") | |
| text | No | Text to type (required for action="type") | |
| force | No | If true, bypass spatial occlusion validation and force interaction at the element center (default: false). | |
| action | Yes | The interaction action to perform | |
| amount | No | Scroll amount in pixels (default: viewport height) | |
| offset | No | Relative [dx, dy] offset from the element center in pixels. Use when center is clipped or covered. | |
| waitFor | No | TEMPORAL AWARENESS. After the action and settle time, wait for this condition to be met before returning. Eliminates the need for separate polling calls to check if your action had the expected effect. Examples: • After clicking "Submit": waitFor: { type: "text", value: "Success" } • After clicking a nav link: waitFor: { type: "url", value: "/dashboard" } • After triggering a modal: waitFor: { type: "selector", value: ".modal-dialog" } • After dismissing a toast: waitFor: { type: "selector_hidden", value: ".toast" } • After form submit: waitFor: { type: "network_idle" } | |
| direction | No | Scroll direction (required for action="scroll") | |
| timeoutMs | No | Max time in ms to wait for the element to become interactable (default: 2000) | |
| clearFirst | No | For "type": clear the input field first (default: true) | |
| coordinate | No | Raw [x, y] pixel coordinates. Use for Canvas or as fallback. | |
| frameIndex | No | Target frame index (optional, defaults to automatic detection if backendNodeId is used). | |
| returnDelta | No | If true, immediately computes and returns a unified delta of what changed (DOM changes, network traffic, console logs) directly in the feedback. | |
| settleTimeMs | No | Delay in ms after the interaction completes before capturing the delta and screenshots (default: 250ms). | |
| backendNodeId | No | The backend DOM node ID from get_semantic_surface (the [id: NNN] tag). Preferred locator. | |
| waitForTimeout | No | Max time in ms to wait for the waitFor condition (default: 5000). Only used when waitFor is specified. | |
| dragToCoordinate | No | Raw [x, y] pixel coordinates to drag to (required for action="drag_and_drop" if dragToBackendNodeId is not provided). | |
| dragToBackendNodeId | No | The backend DOM node ID to drag to (required for action="drag_and_drop" if dragToCoordinate is not provided). |