# What Information Is Included in an Ego-Lite Snapshot? A Complete Technical Breakdown

> Discover what an ego-lite snapshot contains. Get a technical breakdown of the structured object, including page content and a stable identifier reference map for reliable DOM node lookup.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: deep-dive
- Published: 2026-07-31

---

**An ego-lite snapshot returns a structured object containing a textual representation of the page (`content`) and a reference map (`refs`) that maps stable identifiers like `@23` to DOM nodes for reliable element lookup.**

When automating browser interactions with the **citrolabs/ego-lite** framework, understanding the exact data structure of an ego-lite snapshot is essential for building reliable agents. According to the source code in [`src/driver/observe.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/observe.ts), every snapshot captures the current page state as a combination of human-readable content and machine-readable reference identifiers. This guide examines the precise fields, configuration options, and implementation details found in the repository.

## The Core Data Structure of an Ego-Lite Snapshot

The `SnapshotRaw` interface defined in [`src/driver/observe.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/observe.ts) specifies that every ego-lite snapshot contains exactly two top-level properties.

### The Content Field

The `content` property provides a **textual representation** of the page's current DOM state. By default, this string includes the full DOM tree text, encompassing both visible text and hidden elements unless specifically filtered through options. This field serves as the primary payload that AI agents process to understand page context and make decisions.

### The Refs Map

The `refs` field contains a `Record<string, unknown>` that maps **snapshot reference identifiers** (such as `@23`) to internal DOM node identifiers. These references enable stable element lookups across page mutations, allowing agents to track specific elements even when the DOM structure changes. The system automatically registers these refs for refresh on subsequent snapshots via the `registerSnapshotForRefRefresh()` callback.

## Snapshot Configuration Options

The `SnapshotOptions` interface provides granular control over how the ego-lite binary generates snapshots.

### Controlling Output Size with maxResultLength

When processing large documents, the `maxResultLength` option truncates the content string to a specified character limit. If the generated content exceeds this length, the `snapshot()` helper automatically slices the result before returning, preventing token overflow in AI contexts.

### Filtering Content with contentOnly

Setting `contentOnly` to `true` restricts the snapshot to visible text only, excluding hidden DOM elements from the textual representation. When `false` or unspecified, the snapshot captures the complete DOM tree text, providing full page context including metadata and hidden elements.

## Accessing Snapshot Data Through Helper Functions

The framework exposes two distinct APIs for retrieving snapshot data, documented in [`src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/format.ts) and implemented in [`src/driver/observe.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/observe.ts).

### Using page.snapshot() for Text-Only Results

The `page.snapshot(options?)` helper returns a `Promise<string>` containing only the textual content. This method calls `snapshotRaw()` internally but strips the refs object, making it the standard choice for AI agents that need to read page state without handling reference mappings.

### Using page.snapshotRaw() for Structured Data

For applications requiring element references, `page.snapshotRaw(options?)` returns a `Promise<SnapshotRaw>` containing both the `content` string and the `refs` object. This method is essential when building interactions that rely on stable element identifiers for later actions.

## Implementation Details and Source Architecture

The snapshot functionality spans multiple files in the **citrolabs/ego-lite** repository:

- **[`src/driver/observe.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/observe.ts)**: Contains the `snapshotRaw()` and `snapshot()` implementations, the `SnapshotOptions` and `SnapshotRaw` interfaces, error handling via `buildEgoError()`, and the ref registration logic.
- **[`src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts)**: Defines the low-level `ego.snapshot()` runtime contract that forwards calls to the ego-lite binary, specifying that results contain `{ content: string, refs: Record<string, any> }`.
- **[`src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/format.ts)**: Registers the public API signatures for `page.snapshot` and `page.snapshotRaw` in the sandboxed script environment.
- **[`src/ref-state.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/ref-state.ts)**: Manages the automatic refreshing of reference identifiers across snapshot calls.

## Practical Code Examples

```javascript
// Retrieve a truncated text snapshot for AI processing
const pageText = await page.snapshot({ maxResultLength: 4000 });
console.log(pageText);

```

```javascript
// Fetch the full structured snapshot with refs for element tracking
const rawSnapshot = await page.snapshotRaw({ contentOnly: true });
console.log('Content:', rawSnapshot.content);
console.log('Available refs:', rawSnapshot.refs);

```

```javascript
// Use a specific ref to create a stable locator
const snapshot = await page.snapshotRaw();
const refId = Object.keys(snapshot.refs)[0]; // e.g., "@23"
const element = await page.locator(`@${refId}`);
await element.click();

```

## Summary

- An ego-lite snapshot consists of `content` (textual page representation) and `refs` (stable element identifiers mapping strings like `@23` to DOM nodes).
- Configure output using `maxResultLength` to limit string size and `contentOnly` to filter hidden elements.
- Use `page.snapshot()` for string-only results or `page.snapshotRaw()` for the full structured object with references.
- Reference identifiers refresh automatically on subsequent snapshots via `registerSnapshotForRefRefresh()`.
- Implementation resides in [`src/driver/observe.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/observe.ts) with runtime support in [`src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts) and API documentation in [`src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/format.ts).

## Frequently Asked Questions

### What is the difference between page.snapshot() and page.snapshotRaw()?

`page.snapshot()` returns a `Promise<string>` containing only the textual content of the page, making it ideal for AI agents that process page text. `page.snapshotRaw()` returns a `Promise<SnapshotRaw>` containing both the content string and the refs object, which is necessary when you need stable element identifiers for later interactions.

### How does the contentOnly option affect snapshot results?

When `contentOnly` is set to `true`, the snapshot includes only visible text content from the DOM, excluding hidden elements and metadata. When `false` or unspecified, the snapshot captures the full DOM tree text including hidden elements, providing a complete page representation.

### What are snapshot refs and how are they used?

Snapshot refs are stable identifiers (like `@23`) mapped to DOM node identifiers in the `refs` object. These references allow agents to track specific elements across page mutations and can be used with locators to perform actions on specific nodes without relying on fragile selectors like XPath or CSS classes.

### Where is the snapshot logic implemented in the ego-lite source code?

The high-level snapshot helpers are implemented in [`src/driver/observe.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/observe.ts), which interfaces with the browser runtime defined in [`src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts). The actual snapshot generation occurs in the ego-lite binary itself, while the JavaScript layer handles options processing, error wrapping via `buildEgoError()`, and ref registration through `registerSnapshotForRefRefresh()`.