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

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, 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 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 and implemented in 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: Contains the snapshotRaw() and snapshot() implementations, the SnapshotOptions and SnapshotRaw interfaces, error handling via buildEgoError(), and the ref registration logic.
• 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: Registers the public API signatures for page.snapshot and page.snapshotRaw in the sandboxed script environment.
• src/ref-state.ts: Manages the automatic refreshing of reference identifiers across snapshot calls.

Practical Code Examples

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

// 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);

// 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 with runtime support in src/browser-runtime.ts and API documentation in 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, which interfaces with the browser runtime defined in 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().

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}