> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simular.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AccessibilityNode

> A node in a machine's accessibility tree.

A node in a machine's accessibility tree. Thin binding for
`simulang_rs::Node` (macOS `AXUIElement` / Windows UIA element /
Linux AT-SPI accessible / Android uiautomator snapshot node).

Obtain via \[`Machine.focusedRoot`], \[`Machine.systemRoot`],
\[`Machine.nodeAtPoint`], \[`Instance.root`], \[`Window.node`],
or via tree-walking methods on another node / `Instance` / `Window`
(`children`, `find`, `scoredSearch`). Desktop nodes are live handles
whose properties re-resolve from the platform accessibility framework
on each access; Android nodes are part of a parsed snapshot whose
actions resolve back to the live screen.

## Constructor

```typescript
AccessibilityNode(): AccessibilityNode
```

### Returns

`AccessibilityNode`

## Properties

<ResponseField name={"automationId"} type={"string"} required>
  Stable element identifier that the inspected application's own source
  code assigned to this element (e.g. for its UI tests), or the empty
  string when the application didn't set one — most elements don't have
  it.

  Each platform reads its native concept: UIA `AutomationId` on Windows,
  `AXIdentifier` on macOS, AT-SPI `Accessible.AccessibleId` on Linux,
  and the view `resource-id` on Android.
</ResponseField>

<ResponseField name={"className"} type={"string"} required>
  Platform class name (Windows UIA `ClassName` / macOS subrole /
  Android widget class).
</ResponseField>

<ResponseField name={"description"} type={"string"} required>
  Short description (`AXDescription` / UIA `Name`-adjacent fields).
</ResponseField>

<ResponseField name={"helpText"} type={"string"} required>
  Help text / tooltip.
</ResponseField>

<ResponseField name={"isEnabled"} type={"boolean"} required>
  Whether the node accepts user input.
</ResponseField>

<ResponseField name={"isVisible"} type={"null | boolean"} required>
  Whether the platform reports the node as visible, or `null` when the
  visibility attribute cannot be read.

  On Windows this maps to UIA `!IsOffscreen`; on Linux to the AT-SPI
  `Visible` + `Showing` states. On macOS it reads the non-standard
  `AXVisible` attribute — a Chromium-specific extension that native
  apps don't expose (→ `null`). Note Chromium's accessibility-tree
  visibility is compositor-driven, not pixel-driven: many
  web-content nodes (including links) report `AXVisible = false`
  even when rendered, so filtering a browser window on
  `isVisible === true` can silently drop most of the page.
</ResponseField>

<ResponseField name={"localizedControlType"} type={"string"} required>
  Localized control type string.
</ResponseField>

<ResponseField name={"name"} type={"string"} required>
  Accessible name (title / label).
</ResponseField>

<ResponseField name={"overallDescription"} type={"string"} required>
  Synthetic, query-friendly description used by `scoredSearch` (combines
  the node's role, label, value, and a small amount of ancestor context).
</ResponseField>

<ResponseField name={"role"} type={"AriaRole"} required>
  Cross-platform ARIA role.
</ResponseField>

<ResponseField name={"url"} type={"null | string"} required>
  Hyperlink target of this node, or `null` when the node is not a link,
  the link has no target, or the platform backend does not expose the
  target through the accessibility API. The string is the raw URL as
  reported by the platform (no parsing or normalisation).
</ResponseField>

<ResponseField name={"value"} type={"string"} required>
  Current text value (textbox content, slider value as string, …).
</ResponseField>

## Methods

### activate()

```typescript
activate(): void
```

Invoke / click the element (button, link, menu item).

### ancestors()

```typescript
ancestors(): AccessibilityNode[]
```

Parent chain for this node, nearest parent first, excluding this node.
Stops when a node has no parent; parent lookup failures throw.

#### Returns

`AccessibilityNode[]`

### boundingBox()

```typescript
boundingBox(): BoundingBox
```

Live bounding box of the element on the global desktop, in the canonical
coordinate space (OS-native units; see \[`Machine`]).
`right` and `bottom` are exclusive (Playwright / DOM convention).

#### Returns

`BoundingBox`

### children()

```typescript
children(): AccessibilityNode[]
```

Direct child nodes. Throws when the subtree has been torn down or
the children attribute is unreadable. (Tree walks — `snapshot`,
`scoredSearch`, `childrenCollapsed` — treat such failures as "no
children" instead, so one torn-down subtree cannot abort a whole
walk.)

#### Returns

`AccessibilityNode[]`

### childrenCollapsed()

```typescript
childrenCollapsed(): AccessibilityNode[]
```

Direct children with collapsible structural wrappers hoisted out:
a child that is a collapsible structural wrapper is skipped and its own
(recursively collapsed) children take its place, preserving sibling
order. This is the single-level counterpart of the structural hoisting
applied by tree walks, for callers that drive their own walks.

An error from this node's `children()` is propagated; errors from a
collapsible wrapper's own `children()` are treated as "no children"
(the walkers' convention), so one torn-down wrapper cannot abort the
whole read.

#### Returns

`AccessibilityNode[]`

### expandCollapse()

```typescript
expandCollapse(): void
```

Expand or collapse a dropdown or tree item.

### focus()

```typescript
focus(): void
```

Move keyboard focus to this element (brings its window to the
foreground as a side effect on most platforms).

### isAncestorOf()

```typescript
isAncestorOf(other: AccessibilityNode): boolean
```

Whether this node is a strict ancestor of `other`.

#### Parameters

<ResponseField name={"other"} type={"AccessibilityNode"} required />

#### Returns

`boolean`

### isChildOf()

```typescript
isChildOf(other: AccessibilityNode): boolean
```

Whether this node is a direct child of `other`.

#### Parameters

<ResponseField name={"other"} type={"AccessibilityNode"} required />

#### Returns

`boolean`

### isDescendantOf()

```typescript
isDescendantOf(other: AccessibilityNode): boolean
```

Whether this node is a strict descendant of `other`.

#### Parameters

<ResponseField name={"other"} type={"AccessibilityNode"} required />

#### Returns

`boolean`

### isParentOf()

```typescript
isParentOf(other: AccessibilityNode): boolean
```

Whether this node is the direct parent of `other`.

#### Parameters

<ResponseField name={"other"} type={"AccessibilityNode"} required />

#### Returns

`boolean`

### lowestCommonAncestor()

```typescript
lowestCommonAncestor(other: AccessibilityNode): null | [AccessibilityNode, number]
```

Lowest shared ancestor for this node and `other`, plus that ancestor's
level from the reached parentless node (`parentless = 0`, its children
`= 1`). Returns `null` when both chains resolve and no shared ancestor
exists; lookup failures throw.

#### Parameters

<ResponseField name={"other"} type={"AccessibilityNode"} required />

#### Returns

`null | [AccessibilityNode, number]`

### parent()

```typescript
parent(): null | AccessibilityNode
```

Direct parent node, or `null` if this node has no parent. Parent lookup
failures throw.

#### Returns

`null | AccessibilityNode`

### scoredSearch()

```typescript
scoredSearch(order: TraversalOrder, maxNodes: number, collapseStructural: boolean, query: string, threshold: number): AccessibilityNode[]
```

Search this subtree by *concept text*, using bag-of-words
paired-Jaccard scoring against each node's `overallDescription`
(`simulang_rs::AXNodeSynthetic::summary_with_context`).

Returns every node whose score equals the maximum found and exceeds
`threshold` — same semantics as `simulang_rs::scored_search` with
`BowJaccard::score(...).primary` as the scorer and a permissive
filter.

* `order`               – `TraversalOrder.DepthFirst` or
  `TraversalOrder.BreadthFirst`
* `max_nodes`           – upper bound on nodes visited (uses `.take()`
  over the walk)
* `collapse_structural` – hoist empty structural wrappers out of the
  walk before scoring
* `query`               – natural-language concept Jaccard-compared
  against each node's `overallDescription`
* `threshold`           – minimum score to keep a node

#### Parameters

<ResponseField name={"order"} type={"TraversalOrder"} required />

<ResponseField name={"maxNodes"} type={"number"} required />

<ResponseField name={"collapseStructural"} type={"boolean"} required />

<ResponseField name={"query"} type={"string"} required />

<ResponseField name={"threshold"} type={"number"} required />

#### Returns

`AccessibilityNode[]`

### scrollIntoView()

```typescript
scrollIntoView(): void
```

Scroll the element into view.

### select()

```typescript
select(): void
```

Select a tab, radio button, or list item.

### setValue()

```typescript
setValue(value: string): void
```

Set the text value of the element (textbox, combobox, …).

#### Parameters

<ResponseField name={"value"} type={"string"} required />

### showMenu()

```typescript
showMenu(): void
```

Open the element's context menu — the semantic equivalent of a
right-click, without synthesizing pointer input, so it works on
background / obscured windows (Windows `ShowContextMenu`, macOS
`AXShowMenu`, Linux AT-SPI show-menu, Android long-press).

The opened menu itself typically appears as the topmost / focused
window even when the target window stays in the background — a user
watching the desktop sees a menu pop up without having done
anything.

Throws when the element does not support opening a menu this way;
callers can fall back to a coordinate right-click at the element's
`boundingBox()` center.

### snapshot()

```typescript
snapshot(): string
```

Render this node's accessibility subtree as an indented
Playwright-style aria snapshot string.

One line per node, two spaces of indentation per depth level, in
pre-order DFS. Roles are emitted raw (`AXWindow` on macOS,
`UIA.ControlType.*` on Windows), with title and value appended when
non-empty.

#### Returns

`string`

### supportedActions()

```typescript
supportedActions(): string[]
```

Human-readable names of the actions this node currently supports
(e.g. `"activate"`, `"toggle"`, `"scroll_into_view"`).

#### Returns

`string[]`

### toggle()

```typescript
toggle(): void
```

Toggle a checkbox or switch.