> ## 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.

# AccessibilityTree

> Accessibility tree bound to a window (or, on macOS, an application).

Accessibility tree bound to a window (or, on macOS, an application).
Provides snapshot, search, and ref-based actions.

## Constructor

```typescript
AccessibilityTree(): AccessibilityTree
```

### Returns

`AccessibilityTree`

## Properties

<ResponseField name={"windowTitle"} type={"string"} required>
  Get the window title (empty when it cannot be resolved).

  For an application-scoped tree (macOS `fromInstance`) this is the
  title of the application's first window.
</ResponseField>

## Methods

### activate()

```typescript
activate(refId: number): void
```

Invoke/click an element (button, link, menuitem).

#### Parameters

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

### clearRefs()

```typescript
clearRefs(): void
```

Clear all stored element refs.

### expandCollapse()

```typescript
expandCollapse(refId: number): void
```

Expand or collapse a dropdown or tree item.

#### Parameters

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

### find()

```typescript
find(order: TraversalOrder, role?: null | AriaRole, name?: null | string, visibleOnly?: null | boolean, maxResults?: null | number, collapseStructural?: null | boolean): AccessibilityNodeJs[]
```

Search the tree using the chosen traversal order.

* `order` – `TraversalOrder.DepthFirst` or `TraversalOrder.BreadthFirst`
* `role`  – keep nodes whose ARIA role equals this value
  (e.g. `AriaRole.Button`, `AriaRole.TabList`,
  `AriaRole.MenuBar`). Cross-platform ARIA roles, not
  the platform-native `UIA.ControlType.*` / `AX*` /
  `AT-SPI.Role.*` vocabulary.
* `name`  – keep nodes whose title or description contains this
  string
* `visible_only` – skip invisible nodes (default `false`)
* `max_results`  – stop after this many matches (uses `.take()`)
* `collapse_structural` – hoist empty structural wrappers (for example `Pane`
  / `Group` / `Custom` / `Document` on Windows, `AXGroup` /
  `AXGenericGroup` / `AXUnknown` on macOS, AT-SPI `Panel` /
  `Filler` / `Section` on Linux) out of the walk so role searches
  do not hit unnamed containers (default `false`)

Clears existing refs; returned nodes carry `refId` values usable
with action methods (`activate`, `setValue`, …).

#### Parameters

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

<ResponseField name={"role"} type={"null | AriaRole"} />

<ResponseField name={"name"} type={"null | string"} />

<ResponseField name={"visibleOnly"} type={"null | boolean"} />

<ResponseField name={"maxResults"} type={"null | number"} />

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

#### Returns

`AccessibilityNodeJs[]`

### findByDescription()

```typescript
findByDescription(description: string): AccessibilityNodeJs[]
```

Find every node whose `overallDescription`
(`AXNodeSynthetic::summary_with_context`) is **exactly** equal to
`description`, walked in pre-order depth-first.

Clears existing refs; returned nodes carry `refId` values usable
with the action methods (`activate`, `setValue`, …).

#### Parameters

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

#### Returns

`AccessibilityNodeJs[]`

### focusElement()

```typescript
focusElement(refId: number): void
```

Focus an element (brings window to foreground).

#### Parameters

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

### fromInstance()

```typescript
fromInstance(instance: Instance): AccessibilityTree
```

Create an accessibility tree bound to a running application instance
(from \[`Machine.foregroundApp`], \[`App.open`], …). The instance
carries its machine, so the tree targets whatever machine — local
desktop or Android — the instance came from.

The target is resolved **once** at construction time — subsequent
snapshots keep targeting it even if the user switches away.

Scope differs by platform (historical behavior): for a local
instance on macOS the tree covers the whole application (every
window plus the app menu bar); everywhere else it covers the
instance's first visible top-level window (Android: the app's first
live task). Use \[`AccessibilityTree.fromWindow`] for guaranteed
window scoping.

#### Parameters

<ResponseField name={"instance"} type={"Instance"} required />

#### Returns

`AccessibilityTree`

### fromWindow()

```typescript
fromWindow(window: Window): AccessibilityTree
```

Create an accessibility tree scoped to a single window.

Unlike \[`AccessibilityTree.fromInstance`] — which on macOS scopes to
the whole application (every window plus the app menu bar) — this
scopes to exactly the given window's subtree on every
platform. Use it to measure "is this element unique within this
window", or to snapshot / act on one window of a multi-window app.

The window handle stores a persistent identity, so each snapshot
re-resolves fresh data for that same window; the handle can go stale
if the window is destroyed and recreated.

#### Parameters

<ResponseField name={"window"} type={"Window"} required />

#### Returns

`AccessibilityTree`

### getBounds()

```typescript
getBounds(refId: number): BoundingBox
```

Get the live bounding box of an element.

#### Parameters

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

#### Returns

`BoundingBox`

### getSupportedActions()

```typescript
getSupportedActions(refId: number): string[]
```

Get the list of supported actions for an element.

#### Parameters

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

#### Returns

`string[]`

### scrollIntoView()

```typescript
scrollIntoView(refId: number): void
```

Scroll an element into view.

#### Parameters

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

### select()

```typescript
select(refId: number): void
```

Select a tab, radio button, or list item.

#### Parameters

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

### setValue()

```typescript
setValue(refId: number, value: string): void
```

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

#### Parameters

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

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

### showMenu()

```typescript
showMenu(refId: number): void
```

Open an 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 center of
\[`AccessibilityTree.getBounds`].

#### Parameters

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

### snapshot()

```typescript
snapshot(visibleOnly?: null | boolean): AccessibilityNodeJs
```

Take a snapshot of the tree.

Re-resolves the root so each call sees current data. On Windows the
resolve issues a single `BuildUpdatedCache` IPC; the recursive walk
over children and properties then stays entirely in-process, \~40×
faster than walking a live root.

`visible_only` (default `false`) controls whether nodes whose
non-standard `AXVisible` attribute reads `false` are dropped from
the result.

`AXVisible` is a Chromium-specific extension; native macOS apps
don't expose it, so the filter only matters for browser windows.
Chrome reports many web-content nodes (including `AXLink`) as
`AXVisible=false` because its accessibility-tree visibility is
compositor-driven, not pixel-driven — setting `visible_only=true`
on a Chrome window will silently drop most of the page including
links.

#### Parameters

<ResponseField name={"visibleOnly"} type={"null | boolean"} />

#### Returns

`AccessibilityNodeJs`

### toggle()

```typescript
toggle(refId: number): void
```

Toggle a checkbox or switch.

#### Parameters

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