Cursor Crane
Overview

Element Selectors

const buttons = root.queryElements('Button[title="Save"]');

Start with a copied selector#

In most cases, select the target in Element Menu Mode, open the Copy submenu, and choose Copy Selector. Paste that into your script, then simplify it.

Simplifying matters because Cursor Crane generates a selector precise enough to identify the element right now, and interface titles, list contents, and web text all change. Run it once, then remove unstable parts until only useful distinguishing conditions remain.

This selector is very specific:

Window[title="Project Alpha"] Group Button[title="Run"]

If the project name changes often and the Run button in its group is already distinctive, simplify to:

Group Button[title="Run"]

Common patterns#

Goal Pattern Example
Find by element type Button, TextField, List Button
Find by title [title="..."] Button[title="Save"]
Find by identifier #id Button#save-button
Find by accessibility role [role="AX..."] [role="AXWebArea"]
Find by state :enabled, :focused TextField:focused
Find any element * *[visible=true]

Supported kinds#

Built-in Kind names are Application, Unknown, Popover, Group, Button, TextField, Cell, Image, Toolbar, ScrollArea, OverflowedWebContent, List, Link, and Draggable.

A Kind is Cursor Crane's internal classification and does not necessarily map to one accessibility role. In the type position, a token matches either the Kind or the accessibility role, and roles may be written with or without the AX prefix, so Button matches AXButton.

Not every element has one of those Kinds. Use any raw accessibility role in the type position, or omit the type and filter by role:

WebArea
AXWebArea
[role="AXWebArea"]

Use * for an explicit wildcard, as in *[role="AXWebArea"]. When you are unsure which Kind or role applies, start from a copied selector.

Express hierarchy#

A space means "anywhere inside", > means "directly inside", and a comma means "match either":

Window Button
Window > Button
Button[title="Save"], Button[title="Cancel"]
  • Window Button finds buttons at any depth inside a window.
  • Window > Button finds only direct child buttons.
  • The last line finds both Save and Cancel.

Filter by text and attributes#

Attribute conditions support exact, starts-with, ends-with, and contains matching, so you can target an element whose title is only partly stable.

Next#

Powered by Docsbook