> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vercel-labs/agent-browser/llms.txt
> Use this file to discover all available pages before exploring further.

# Snapshot Functions

> Functions for generating enhanced accessibility snapshots with element refs

# Snapshot Functions

The snapshot module provides functions for generating accessibility tree snapshots with embedded element refs for deterministic element selection.

## Core Functions

### getEnhancedSnapshot()

Generate an enhanced accessibility snapshot with element refs.

```typescript theme={null}
import { getEnhancedSnapshot } from '@agentic-labs/browser';
import { chromium } from 'playwright-core';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://example.com');

const snapshot = await getEnhancedSnapshot(page, {
  interactive: true,
  cursor: true,
  maxDepth: 5,
  compact: true,
  selector: '#main-content'
});

console.log(snapshot.tree);
console.log(snapshot.refs);
```

<ParamField path="page" type="Page">
  Playwright Page instance
</ParamField>

<ParamField path="options" type="SnapshotOptions">
  Snapshot configuration options

  <ParamField path="interactive" type="boolean">
    Only include interactive elements (buttons, links, inputs, etc.)
  </ParamField>

  <ParamField path="cursor" type="boolean">
    Include cursor-interactive elements (cursor:pointer, onclick, tabindex)
  </ParamField>

  <ParamField path="maxDepth" type="number">
    Maximum depth of tree to include (0 = root only)
  </ParamField>

  <ParamField path="compact" type="boolean">
    Remove structural elements without meaningful content
  </ParamField>

  <ParamField path="selector" type="string">
    CSS selector to scope the snapshot to a specific element
  </ParamField>
</ParamField>

<ResponseField name="return" type="EnhancedSnapshot">
  <ResponseField name="tree" type="string">
    Accessibility tree as formatted text with refs
  </ResponseField>

  <ResponseField name="refs" type="RefMap">
    Map of element refs (e1, e2, etc.) to locator data
  </ResponseField>
</ResponseField>

**Example Output:**

```
- heading "Example Domain" [ref=e1] [level=1]
- paragraph: This domain is for use in illustrative examples
- link "More information..." [ref=e2]
- button "Submit" [ref=e3]
- textbox "Email" [ref=e4]
# Cursor-interactive elements:
- clickable "Login" [ref=e5] [cursor:pointer]
```

### parseRef()

Parse a ref from a command argument. Supports multiple ref formats.

```typescript theme={null}
import { parseRef } from '@agentic-labs/browser';

const ref1 = parseRef('@e1');      // 'e1'
const ref2 = parseRef('ref=e2');   // 'e2'
const ref3 = parseRef('e3');       // 'e3'
const ref4 = parseRef('#button');  // null (not a ref)
```

<ParamField path="arg" type="string">
  Ref argument string (e.g., '@e1', 'ref=e1', or 'e1')
</ParamField>

<ResponseField name="return" type="string | null">
  Parsed ref ID (e.g., 'e1') or null if not a valid ref format
</ResponseField>

**Supported Formats:**

* `@e1` - At-prefixed ref
* `ref=e1` - Ref with equals
* `e1` - Direct ref (pattern: /^e\d+\$/)

### getSnapshotStats()

Get statistics about a snapshot.

```typescript theme={null}
import { getSnapshotStats } from '@agentic-labs/browser';

const snapshot = await getEnhancedSnapshot(page);
const stats = getSnapshotStats(snapshot.tree, snapshot.refs);

console.log(stats);
// {
//   lines: 42,
//   chars: 1234,
//   tokens: 309,
//   refs: 15,
//   interactive: 12
// }
```

<ParamField path="tree" type="string">
  Snapshot tree text
</ParamField>

<ParamField path="refs" type="RefMap">
  Snapshot refs map
</ParamField>

<ResponseField name="return" type="object">
  <ResponseField name="lines" type="number">Number of lines in tree</ResponseField>
  <ResponseField name="chars" type="number">Number of characters</ResponseField>
  <ResponseField name="tokens" type="number">Estimated token count (chars / 4)</ResponseField>
  <ResponseField name="refs" type="number">Total number of refs</ResponseField>
  <ResponseField name="interactive" type="number">Number of interactive element refs</ResponseField>
</ResponseField>

### resetRefs()

Reset the ref counter. Called automatically at the start of each snapshot.

```typescript theme={null}
import { resetRefs } from '@agentic-labs/browser';

resetRefs(); // Reset counter to 0
```

## Types & Interfaces

### EnhancedSnapshot

The result of `getEnhancedSnapshot()`.

```typescript theme={null}
interface EnhancedSnapshot {
  tree: string;      // Accessibility tree as formatted text
  refs: RefMap;      // Map of refs to element data
}
```

### RefMap

Map of element refs to their locator data.

```typescript theme={null}
interface RefMap {
  [ref: string]: {
    selector: string;  // Playwright selector (e.g., "getByRole('button', { name: 'Submit', exact: true })")
    role: string;      // ARIA role (e.g., 'button', 'link', 'textbox')
    name: string;      // Accessible name
    nth?: number;      // Index for disambiguation when multiple elements have same role+name
  };
}
```

**Example:**

```typescript theme={null}
{
  'e1': {
    selector: "getByRole('heading', { name: 'Example Domain', exact: true })",
    role: 'heading',
    name: 'Example Domain'
  },
  'e2': {
    selector: "getByRole('link', { name: 'More information...', exact: true })",
    role: 'link',
    name: 'More information...'
  },
  'e3': {
    selector: "getByRole('button', { name: 'Submit', exact: true })",
    role: 'button',
    name: 'Submit',
    nth: 0  // First of multiple 'Submit' buttons
  }
}
```

### SnapshotOptions

Configuration options for `getEnhancedSnapshot()`.

```typescript theme={null}
interface SnapshotOptions {
  /** Only include interactive elements (buttons, links, inputs, etc.) */
  interactive?: boolean;
  
  /** Include cursor-interactive elements (cursor:pointer, onclick, tabindex) */
  cursor?: boolean;
  
  /** Maximum depth of tree to include (0 = root only) */
  maxDepth?: number;
  
  /** Remove structural elements without meaningful content */
  compact?: boolean;
  
  /** CSS selector to scope the snapshot */
  selector?: string;
}
```

## Interactive Roles

Elements with these ARIA roles are considered interactive and receive refs:

* `button`
* `link`
* `textbox`
* `checkbox`
* `radio`
* `combobox`
* `listbox`
* `menuitem`, `menuitemcheckbox`, `menuitemradio`
* `option`
* `searchbox`
* `slider`
* `spinbutton`
* `switch`
* `tab`
* `treeitem`

## Content Roles

Elements with these roles get refs for text extraction:

* `heading`
* `cell`, `gridcell`, `columnheader`, `rowheader`
* `listitem`
* `article`
* `region`
* `main`
* `navigation`

## Cursor-Interactive Elements

When `cursor: true` is enabled, the snapshot includes elements with:

* `cursor: pointer` CSS property
* `onclick` attribute or handler
* `tabindex` attribute (except `-1`)

These elements get pseudo-roles:

* `clickable` - Has cursor:pointer or onclick
* `focusable` - Has tabindex

The selector for cursor-interactive elements is a CSS selector, not a role-based selector.

## Usage with BrowserManager

The `BrowserManager` class provides a convenient wrapper:

```typescript theme={null}
import { BrowserManager } from '@agentic-labs/browser';

const manager = new BrowserManager();
await manager.launch();

const page = manager.getPage();
await page.goto('https://example.com');

// Get snapshot via manager (caches refs internally)
const snapshot = await manager.getSnapshot({ interactive: true });

// Click element by ref
const locator = manager.getLocatorFromRef('@e3');
if (locator) {
  await locator.click();
}

// Or use getLocator which supports both refs and selectors
await manager.getLocator('@e3').click();
```