# Snapshot vs snapshotRaw in ego-browser: Key Differences and When to Use Each

> Understand the difference between page.snapshot and page.snapshotRaw in ego-browser. Learn when to use the human-readable string or the structured object for your needs.

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

---

**`page.snapshot()` returns a semantic, human-readable `string` ideal for logging and LLM prompts, while `page.snapshotRaw()` returns a structured `object` containing `{ content, refs }` for programmatic DOM manipulation and custom processing.**

The `ego-browser` package within the citrolabs/ego-lite repository provides two distinct methods for capturing page state during browser automation. Understanding the difference between `snapshot` and `snapshotRaw` is essential for building efficient agents, debugging interactions, and optimizing data extraction pipelines.

## Return Types and Data Structures

### snapshot(): Human-Readable String Output

According to the API documentation in [`package/ego-browser/src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/format.ts) (lines 402-410), `page.snapshot()` returns a `Promise<string>` containing formatted text with **refs** (`@N`) and **stable locators** (CSS, XPath, etc.). This serialization creates a semantic representation ready for immediate printing, logging, or consumption by language models.

The string format includes visual representations of the page structure that humans can easily interpret, making it the preferred choice for debugging and agent observation.

### snapshotRaw(): Structured Object for Programmatic Access

In contrast, `page.snapshotRaw()`—defined at lines 416-424 of the same file—returns `Promise<object>` with the exact shape `{ content: string, refs: Record<number, any> }`. The `content` field holds the page's text surface, while `refs` maps numeric IDs to DOM node references.

This raw structure enables precise element targeting without re-querying the browser, allowing agents to reuse specific references or transform content programmatically before further processing.

## Implementation Details in the Source Code

The architectural distinction originates in how each method handles the Chrome DevTools Protocol (CDP) response. As implemented in [`package/ego-browser/src/driver/observe.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/observe.ts) (lines 68-73), `snapshotRaw` calls the underlying CDP snapshot RPC (`ego.snapshot`) and returns the JSON response unchanged, providing "the text surface most agents want."

Internally, `snapshot()` calls `snapshotRaw()` and applies serialization logic to convert the structured object into a formatted string, applying the same defaults that agents normally expect during automation workflows.

Both functions are exposed through [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) (lines 84-85), making them available as top-level helpers in the agent scripting environment.

## Practical Usage Examples

Use `snapshot()` when you need printable output for debugging or LLM consumption:

```javascript
// Example 1 – Getting a printable snapshot (most common)
const snap = await page.snapshot();           // → string
console.log('Page snapshot:\n', snap);

```

Use `snapshotRaw()` when you need to inspect the DOM structure programmatically:

```javascript
// Example 2 – Getting the raw snapshot object for custom processing
const raw = await page.snapshotRaw();         // → { content: string, refs: Record<number, any> }
console.log('Raw content length:', raw.content.length);
console.log('Available refs:', Object.keys(raw.refs));

```

## When to Use Each Method

**Choose `page.snapshot()` when:**
- You need a quick, printable view for debugging or logging
- Feeding context to language models that expect readable text
- Generating human-friendly reports of page state

**Choose `page.snapshotRaw()` when:**
- You need programmatic access to individual DOM references
- Reusing specific refs across multiple operations without re-fetching
- Transforming or filtering content before serialization
- Building custom agents that manage their own formatting logic

## Summary

- `snapshot()` returns a formatted `string` via `Promise<string>`, while `snapshotRaw()` returns a structured `object` via `Promise<object>` with shape `{ content, refs }`
- Both methods are defined in [`package/ego-browser/src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/format.ts) and exported through [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts)
- `snapshot()` internally calls `snapshotRaw()` and serializes the result, while `snapshotRaw()` returns the raw CDP response from `ego.snapshot`
- Use `snapshot()` for human-readable logging and LLM prompts; use `snapshotRaw()` for DOM manipulation and custom data processing pipelines

## Frequently Asked Questions

### Can I convert the output of snapshotRaw() to the same string format as snapshot()?

Yes, since `snapshot()` internally calls `snapshotRaw()` and applies serialization logic defined in [`package/ego-browser/src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/format.ts), you can replicate this transformation by formatting the `{ content, refs }` object yourself. However, using `snapshot()` directly is more efficient for obtaining the string representation without manual conversion overhead.

### Does snapshotRaw() provide better performance than snapshot()?

Technically, `snapshotRaw()` performs slightly less work since it skips the serialization step, but both methods execute the same underlying CDP snapshot RPC (`ego.snapshot`). The performance difference is negligible for most use cases, though `snapshotRaw()` avoids string conversion overhead when processing thousands of snapshots in high-frequency automation scenarios.

### What are "refs" in the context of ego-browser snapshots?

Refs are numeric identifiers (e.g., `@1`, `@2`) that map to specific DOM nodes in the page. The `refs` object in `snapshotRaw()` output contains these mappings to actual DOM elements, allowing agents to reference elements precisely using stable locators like CSS selectors or XPath expressions without re-querying the DOM or refreshing the page.

### Are both methods available in the ego-browser helpers module?

Yes, both `snapshot` and `snapshotRaw` are exported from [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) at lines 84-85, making them available as top-level helpers in the agent runtime environment alongside other browser automation utilities provided by the citrolabs/ego-lite framework.