Touché (Touch): reading the accessibility tree

Touché is the structural reading organ: it returns the elements of an interface (role, label, position) as the system exposes them through accessibility, redacted of sensitive content. The tool descriptions speak of the "macOS accessibility tree". Both tools are read-only and are not subject to the Mains ceiling.

Tool	Role	Level
touche_tree	Bounded, redacted tree of a window	read
touche_probe	Element located under a point on the screen	read

Prerequisite: the system Accessibility permission must be granted to the process responsible for Daimon. Without it, both tools return accessibility_permission_denied. daimon_doctor checks this permission without ever opening a dialog.

Common errors

Code	Meaning
accessibility_permission_denied	The Accessibility permission is missing
excluded	The target belongs to an application protected by your exclusions
snapshot_failed	Reading the tree failed

touche_tree

Returns the accessibility tree, depth-bounded and redacted.

Parameter	Type	Default	Required	Role
max_depth	integer	4	no	Maximum depth of the traversal from the root
root	object {x, y}	root of the foreground window	no	Point designating the root of the subtree
roles	list of strings	no filter	no	Filter by role; empty or omitted, no filter
prune_empty	boolean	true	no	Prunes empty or uninteresting nodes
summary	boolean	false	no	Returns a compact text summary rather than the node tree
window	object {pid, bundle, title}	foreground window	no	Window target; each field is optional

Level: read.

Example call

{ "max_depth": 3, "roles": ["AXButton"], "summary": false, "window": { "bundle": "com.apple.finder" } }

Returns: the redacted node tree, or {summary} (a string) when summary is true, or a contract error (see above).

Pitfalls

• A high depth on a rich application produces a very large response: prefer summary, roles or a targeted root.
• Role values are those of the system accessibility; read them first from a full tree rather than guessing them.
• An empty or silent tree (custom-drawn applications) is not an error: use vue_find then.
• Provide the role and label obtained this way to the Mains tools so that Daimon can check reversibility.

touche_probe

Returns the single accessibility element located under a point on the screen, redacted.

Parameter	Type	Default	Required	Role
x	integer	none	yes	X coordinate of the screen point
y	integer	none	yes	Y coordinate of the screen point

Level: read.

Example call: { "x": 640, "y": 420 }

Returns: the single redacted node, or a contract error (see above).

Pitfalls: x and y are points of the global desktop, the same unit as that of main_click.