Touchpoint

Only call this when the element shows actions=[...] in snapshot()
output AND click() either failed silently or is not the right verb.
Use the exact action name shown in the snapshot — do not guess.
Example: an element showing actions=[expand, collapse] can be acted
on with action(element_id, "expand").

Args:
    element_id: The element ID.
    action_name: Exact action name from the snapshot actions=[...] list.

Element-scoped actions (click, set_value, select_text, etc.) bring
their window to focus automatically — you rarely need this.  Use it
when you need to type_text or press_key in a window without first
clicking an element in it (e.g. sending a keyboard shortcut to a
window you haven't interacted with yet in this task).

Args:
    window_id: The window ID to activate (from windows()).

Pass ``element_id`` to click via the element's native
accessibility action (most reliable).  Pass ``x`` and ``y``
to click directly at screen coordinates instead — useful
when clicking by ID triggers an unintended action (e.g.
opens a dropdown instead of focusing a text entry).
Every element shows its position as @(x,y) in listings.
Coordinate clicks always report OK even if nothing was hit —
verify the result with a screenshot or find().

Args:
    element_id: The element ID to click.
    x: Screen X coordinate (use with y instead of element_id).
    y: Screen Y coordinate (use with x instead of element_id).
    button: "left" (default) or "right".
    double_click: If true, perform a double-click instead.
        Cannot be combined with button="right".

Use windows() to find the window ID first.

Args:
    window_id: The window ID to close.

Args:
    probe: If true (default), initialise optional providers and perform
        discovery. Pass false for a side-effect-free state snapshot.

Matches against element names (button labels, link text, field
labels), NOT body text or prose content inside articles or
documents.

Returns element IDs that you can use with click, set_value, etc.
Use the FULL visible text for best results (e.g. "Send Message"
not just "Send").

Args:
    query: Text to search for (e.g. "Send Message", "Submit", "Search").
    app: Scope to this application (e.g. "Firefox", "Slack").
    window_id: Scope to this window.
    role: Only match this role (e.g. "button", "text_field", "link").
    states: Only match elements with ALL these states (e.g. ["enabled", "visible"]).
    max_results: Maximum matches to return.
    fields: Which fields to search -- ["name"], ["name", "value"], or ["name", "value", "description"].
    source: "full" (default, merged native+web), "cdp_ax" (CDP accessibility tree only), "native" (platform only), or "dom" (live DOM). "ax" remains as a compatibility alias for "cdp_ax".

Args:
    element_id: The element ID to focus.

Use windows() to find the window ID first.

Args:
    window_id: The window ID.
    fullscreen: True to enter fullscreen (default), False to exit.

Returns a fresh snapshot with current states, value, supported
actions, and description.  Use this to inspect an element
before calling the ``action()`` tool — the actions list shows
exactly which raw action names are available.

Args:
    element_id: The element ID (from find/elements results).

Use windows() to find the window ID first.
To restore a minimized window, use activate_window().

Args:
    window_id: The window ID to minimize.

Use this before scroll() to scroll within a specific area.

Args:
    element_id: The element ID to move the cursor to.
    x: Screen X coordinate (use with y instead of element_id).
    y: Screen Y coordinate (use with x instead of element_id).

Use windows() to find the window ID first.

Args:
    window_id: The window ID to move.
    x: New horizontal position of the top-left corner.
    y: New vertical position of the top-left corner.

Single key: "enter", "tab", "escape", "f5", "backspace".
Combination: ["ctrl", "s"], ["ctrl", "shift", "p"], ["alt", "f4"].

Args:
    keys: A single key name, or a list of keys for a combination
          (all held together, then released in reverse order).
    repeat: Number of times to press (default 1).

Some backends expose aggregate descendant text for containers.
Pass a container ID from snapshot() to read an entire section,
article, dialog, or document body when the backend supports it.

Workflow: snapshot() to find the right container, read_text(id)
to read its full contents.

Args:
    element_id: The element or container ID to read text from.

Use windows() to find the window ID first.

Args:
    window_id: The window ID to resize.
    width: New width in pixels.
    height: New height in pixels.

With no arguments, captures the full desktop.  Specify one
parameter to crop to a specific target.

Args:
    app: Crop to this application's window.
    window_id: Crop to this specific window.
    element_id: Crop to this element's bounding box.
    padding: Extra pixels around the crop region.
    monitor: Capture only this monitor (0-indexed).

With ``element_id``, moves the cursor to that element's position
first, then scrolls — useful for scrolling inside a specific list,
panel, or container.  Without it, scrolls at the current cursor
position.

Args:
    direction: One of "up", "down", "left", "right".
    amount: Number of scroll ticks (default 3).
    element_id: Optional element to scroll at.  When given, cursor
        is moved to the element's center first.

Finds the text within the element and applies a native text
selection over that range.  Works on editable fields and document
bodies on all backends.  On web content (CDP) and Windows (UIA)
also works on read-only containers such as articles and sections.
Useful for formatting, copying, or replacing specific text.

Args:
    element_id: The element ID containing the text.
    text: The exact substring to select.
    occurrence: Which occurrence to select (1 = first, 2 = second, etc.).

Args:
    element_id: The element ID (a slider, spin button, etc.).
    value: The numeric value to set.

Calls the platform's native value-setting API.  Behaviour depends
on the target widget:
  * Text fields / text areas: writes the text.
  * Combo boxes / dropdowns / <select>: picks the option whose
    label or value matches *value*.  Prefer this over clicking
    the dropdown and then clicking a popup item — picking by name
    is one atomic call and avoids popup-click failures on some
    toolkits.
  * Other editable widgets: whatever their value interface accepts.

Args:
    element_id: The element ID (a text field, combo box, etc.).
    value: The text or option label to set.
    replace: If true, clear the field first and replace all content.
             If false (default), insert at the current cursor position.

The primary orient tool in no-vision mode.  In vision mode, use it
as a structural complement to screenshot() — cheaper than a
screenshot and gives element IDs directly.  Default behaviour: pick
the currently active window, walk its accessibility tree, prune
anonymous structural wrappers, preserve semantic containers (dialogs,
menus, lists, etc.), and emit an indented text view with one line per
interactive element.

Args:
    app: Snapshot the given app's active window (or first window).
        Case-insensitive.
    window_id: Snapshot a specific window by ID.
    element_id: Start the tree walk from a specific element instead
        of the window root.  Use to dig into a container whose
        children were not visible in a previous (truncated) snapshot.
        To read the text content of a container, use read_text()
        rather than snapshot().
    all_elements: If true, include every named element — not just
        interactive + container roles.  Use when the default
        filter is hiding something.
    max_depth: Maximum tree depth to walk.  Defaults to the
        configured value (typically 20).  Decrease for a faster
        overview of a large window.

Simulates keyboard input.  Focus a text field first with
click() or focus(), then type into it.

Special characters:
  \n = Enter (line break),  \t = Tab (next field),
  \b = Backspace (delete previous character).

Args:
    text: The text to type.
    raw: If true, type literal backslashes without converting
        ``\n``, ``\t``, or ``\b`` escape sequences.

Polls until matching elements are found (or gone) or timeout.
Use after actions that trigger UI changes.

Args:
    element: Text to search for.  Pass a single string (e.g.
        "Submit") or a list of strings (e.g. ["Success", "Error"])
        for multi-query mode.  With mode="any", returns as soon
        as any query matches.  With mode="all", waits until every
        query has matched.
    app: Scope to this application.
    window_id: Scope to this window.
    role: Only match this role.
    states: Only match elements with ALL these states.
    fields: Which fields to search (default: ["name"]).
    mode: "any" (return when any query matches) or "all"
        (wait for all queries to match).  Only meaningful when
        element is a list.
    timeout: Maximum seconds to wait (default 10).
    source: "full" (default), "cdp_ax", "native", or "dom".
        "ax" remains as a compatibility alias for "cdp_ax".
    max_results: Maximum elements to return (default 5).
    wait_for_new: If true, ignore elements already present -- wait for NEW ones.
    gone: If true, wait for matching elements to DISAPPEAR instead.

Polls the application list until the app is found (or gone).
Use after launching or closing an application.

Args:
    app: Application name to wait for (e.g. "Firefox", "Slack").
    timeout: Maximum seconds to wait (default 10).
    gone: If true, wait for the app to DISAPPEAR instead.

Polls the window list until a window with a matching title is
found (or gone).  Use after actions that open or close windows.
When found, auto-activates the window so subsequent type_text
and press_key target it.

Args:
    title: Window title to search for (substring match).
    app: Only look for windows in this application.
    timeout: Maximum seconds to wait (default 10).
    gone: If true, wait for the window to DISAPPEAR instead.

Returns window IDs, titles, sizes, and app names.
Use window IDs to scope find/elements queries or activate_window.