Capture a PNG screenshot of the primary display (when displayId is null/undefined) or a specific display id (0..2147483647).

Run OCR (Tesseract) on a display and return recognized text plus classified UI elements.

List connected displays with id, bounds, scale factor, rotation, and primary flag.

List all visible top-level OS windows. Returns one WindowInfo per window with hwnd (platform-specific integer handle), pid (owning process id), title, rect (x/y/width/height), and isVisible. The hwnd can be passed to da_window_focus to bring the window to the foreground. Linux requires wmctrl on PATH; macOS uses osascript; Windows uses PowerShell + Win32 EnumWindows.

Bring a top-level OS window to the foreground so subsequent da_click / da_type / da_key land on it. Resolves the window either by hwnd (exact match) or by a case-insensitive substring of its title (optionally narrowed by pid). bringToTop: true (default) also calls SetWindowPos(HWND_TOP) on Windows so the window is at the top of the Z-order. Returns { hwnd, pid, title, foreground } where foreground: false indicates the OS refused the foreground change (e.g. another process holds the foreground lock on Windows). Throws NOT_FOUND when no visible window matches. Linux requires wmctrl on PATH; macOS uses osascript; Windows uses PowerShell + Win32 SetForegroundWindow.

Block until a window with a matching title appears in da_window_list, or timeoutMs (default 5000, max 60000) elapses. Match strategies: "substring" (default, case-insensitive), "exact", or "regex" (full match). Polls every intervalMs (default 200, min 50, max 5000). Throws NOT_FOUND on timeout — use this after da_launch to wait for a newly-spawned app to finish painting before clicking inside it.

Return the current cursor position as { x, y } in screen coordinates.

Move the cursor to absolute (x, y) screen coordinates.

Click a mouse button (defaults to "left", count 1). When x/y are given, the cursor is moved first.

Click the on-screen element whose text label matches text. Uses OCR + UI-element classification to locate the text, then clicks the center of its bounding box. Set fuzzy: true for case-insensitive matching with whitespace normalization. Returns the clicked coordinates, the matched bbox, and the recognized text. Throws NOT_FOUND when no element matches.

Locate the on-screen element whose text label matches text (OCR + UI-element classification). Returns the bounding box, the center coordinates, the recognized text, and the OCR confidence — but does NOT click. Set fuzzy: true for case-insensitive matching with whitespace normalization. Throws NOT_FOUND when no element matches. Use this when you need to decide an action (click vs. drag vs. type-into) based on element position; use da_click_text when you already know the action is "click the center".

Block until text appears on screen (OCR + UI-element classification), or timeoutMs (default 5000, max 60000) elapses. Match strategy is identical to da_click_text / da_find_text — substring by default, set fuzzy: true for case-insensitive + whitespace-normalized matching. Polls every intervalMs (default 200, min 50, max 5000). Throws NOT_FOUND on timeout. Use this after a click / key / dialog-open to confirm the new state is painted before continuing.

Block until a pixel-level predicate holds on the next screenshot, or timeoutMs (default 10000, max 60000) elapses. Predicates: {kind:"color", rgb:[r,g,b], tolerance?, minCount} (counts matching pixels, succeeds when count >= minCount); {kind:"diff", baseline:"", threshold, tolerance?} (succeeds when >= threshold fraction of pixels differ from the baseline PNG). Optional region clips the check to a rectangle. Polls every intervalMs (default 200). Throws NOT_FOUND on timeout. Use this to verify visual state after an action (e.g. "wait until 200+ red pixels appear on the canvas").

Double-click the left mouse button. Moves to (x, y) first when provided.

Drag from (x1, y1) to (x2, y2). Button defaults to "left"; non-left buttons are accepted in the schema but currently ignored.

Draw a multi-point path with the mouse by tracing through points with the given button held. Useful for freeform shapes, signatures, circles (as N points on the circumference), etc. modifiers are held pressed for the duration of the trace (e.g. ["shift"] for constrained-drawing in Paint). Strict modifier pairing is enforced even on errors.

Scroll the wheel at the current (or given) cursor position by (dx, dy) pixel deltas. Positive dy = down, positive dx = right.

Type a string at the current keyboard focus. Empty string is a no-op. Optional per-char delay (ms).

Press a key by name, optionally with modifiers (e.g. {"key":"c","modifiers":["ctrl"]} for Ctrl+C). holdMs > 0 issues a press-hold-release.

Launch a program by name or absolute path. argv[0] is required. cwd, env, timeoutMs, and detached are optional.