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

# AccessibilitySnapshot

> A materialized accessibility snapshot: one pre-order walk of a subtree, stored flat so every node is addressable by a stable index (its "ref").

Construct with \[`AccessibilitySnapshot.fromNode`] (e.g. from
\[`Machine.focusedRoot`]) or \[`AccessibilitySnapshot.fromWindow`]. Render it
as
LLM-facing text with \[`AccessibilitySnapshot.toStringWith`], resolve
indices back to live nodes with \[`AccessibilitySnapshot.node`], and act
on elements by index via the action methods.

Indices are frozen at capture time and cover **every** node of the walk
(including collapsible wrappers), so the same snapshot can be printed
with different \[`SnapshotPrintOptions`] without renumbering. A
consequence: rendering with `collapseStructural` produces
non-contiguous `[ref=N]` values, because skipped wrappers keep their
index.

## Constructor

```typescript
AccessibilitySnapshot(): AccessibilitySnapshot
```

### Returns

`AccessibilitySnapshot`

## Properties

<ResponseField name={"nodeCount"} type={"number"} required>
  Number of captured nodes. Alias for \[`AccessibilitySnapshot.len`].
</ResponseField>

## Methods

### activate()

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

Invoke / press the element at `index`.

#### Parameters

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

### boundingBox()

```typescript
boundingBox(index: number): BoundingBox
```

Live bounding box of the element at `index` — for example for a
coordinate-click fallback when a semantic action fails.

#### Parameters

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

#### Returns

`BoundingBox`

### click()

```typescript
click(index: number): void
```

Click the element at `index`, dispatching to the platform action that
matches its current role:

* button / link / menuitem / img → `activate`
* tab / radio / option → `select`
* combobox / treeitem → `expandCollapse`
* checkbox / switch → `toggle`
* anything else → `activate`

On error, callers can fall back to a coordinate click at the centre
of \[`AccessibilitySnapshot.boundingBox`].

#### Parameters

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

### clickablePoint()

```typescript
clickablePoint(index: number, allowDescendants?: null | boolean): [number, number]
```

A screen point where a pointer click actually lands on the element at
`index`, as `[x, y]` in the canonical global-desktop space. Verified
by hit-testing; throws (saying why) when the element has no such
point, instead of guessing a center that would click something else.
See \[`AccessibilityNode.clickablePoint`] for the per-platform
behavior and the `allowDescendants` semantics.

#### Parameters

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

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

#### Returns

`[number, number]`

### expandCollapse()

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

Expand or collapse the element at `index`.

#### Parameters

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

### focusElement()

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

Alias for \[`AccessibilitySnapshot.setFocus`].

#### Parameters

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

### fromNode()

```typescript
fromNode(node: AccessibilityNode): AccessibilitySnapshot
```

Construct a snapshot of the subtree rooted at `node`.

This is a full pre-order walk with no structural collapse and no
property reads. Filtering and formatting are deferred to
\[`AccessibilitySnapshot.toStringWith`] so one capture can serve
several renderings.

#### Parameters

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

#### Returns

`AccessibilitySnapshot`

### fromWindow()

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

Construct a snapshot of `window`'s accessibility subtree.

#### Parameters

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

#### Returns

`AccessibilitySnapshot`

### getBounds()

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

Alias for \[`AccessibilitySnapshot.boundingBox`].

#### Parameters

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

#### Returns

`BoundingBox`

### isEmpty()

```typescript
isEmpty(): boolean
```

`true` if the snapshot holds no nodes.

#### Returns

`boolean`

### len()

```typescript
len(): number
```

Number of captured nodes.

#### Returns

`number`

### node()

```typescript
node(index: number): AccessibilityNode
```

Live node handle for a ref index.

An out-of-range index is an error, not an expected miss: refs come
from this snapshot's own rendered output, so an unknown index means
the caller mixed up snapshots (or hallucinated a ref).

#### Parameters

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

#### Returns

`AccessibilityNode`

### print()

```typescript
print(options?: null | SnapshotPrintOptions): string
```

Alias for \[`AccessibilitySnapshot.toStringWith`].

#### Parameters

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

#### Returns

`string`

### scrollIntoView()

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

Scroll the element at `index` into view.

#### Parameters

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

### select()

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

Select the tab / radio / list item at `index`.

#### Parameters

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

### setFocus()

```typescript
setFocus(index: number): void
```

Focus the element at `index` (may also bring its window to the
foreground).

#### Parameters

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

### setValue()

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

Set the text value of the element at `index`.

#### Parameters

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

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

### showMenu()

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

Open the context menu of the element at `index` — 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 centre of
\[`AccessibilitySnapshot.boundingBox`].

#### Parameters

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

### toggle()

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

Toggle the checkbox / switch at `index`.

#### Parameters

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

### toStringWith()

```typescript
toStringWith(options?: null | SnapshotPrintOptions): string
```

Render the snapshot as indented, Playwright-style lines with
`[ref=N]` markers:

```text
- window "Untitled - Notepad" [ref=0]
  - textbox "Text editor" #editor [ref=2]: "hello"
  - button "Save" [ref=5]
```

One line per rendered node: two spaces of indentation per depth
level, the cross-platform ARIA role, the name (escaped and truncated
per `maxChars`), a `#automation-id` marker when the platform reports
one, the ref index, and a `: "value"` suffix for value-bearing roles.
Filtering is controlled by \[`SnapshotPrintOptions`]; returns
`"(empty)"` when every node is filtered out.

Properties are read from the live elements on every call, so the text
reflects current UI state while ref numbering stays frozen.

#### Parameters

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

#### Returns

`string`