# Understanding the Difference Between snapshot and snapshotRaw APIs in ego-browser

> Explore the difference between snapshot and snapshotRaw APIs in ego-browser. Learn how to access formatted or structured data for your applications.

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

---

**The `snapshot()` API returns a formatted, human-readable string containing semantic refs and stable locators, while `snapshotRaw()` returns the underlying structured object `{ content, refs }` for programmatic data access.**

The `ego-browser` package within the [citrolabs/ego-lite](https://github.com/citrolabs/ego-lite) repository provides two distinct helper functions for capturing page state in automated browser environments. Understanding the difference between the `snapshot` and `snapshotRaw` APIs in ego-browser ensures you select the appropriate method for debugging, logging, or feeding context to LLM agents.

## Core API Comparison

Both functions capture the current DOM state, but they differ fundamentally in return type and intended consumption.

### snapshot() – Semantic String Output

The `snapshot()` method returns a `Promise<string>` containing a formatted text representation of the page. According to the source code in [`package/ego-browser/src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/format.ts) (lines 402-410), this function generates a semantic page snapshot with refs (e.g., `@1`, `@2`) and stable locators including CSS selectors and XPath expressions.

**Key characteristics:**
- **Return type:** `Promise<string>`
- **Format:** Human-readable text with inline refs and locators
- **Use case:** Printing to console, logging, or providing context to language models

### snapshotRaw() – Structured Object Output

The `snapshotRaw()` method returns a `Promise<object>` representing the raw JSON response from the Chrome DevTools Protocol (CDP) snapshot RPC. As documented in [`package/ego-browser/src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/format.ts) (lines 416-424), this function returns the structured data without serialization.

**Key characteristics:**
- **Return type:** `Promise<{ content: string, refs: Record<number, any> }>`
- **Format:** Structured object with separate `content` and `refs` properties
- **Use case:** Programmatic DOM inspection, custom ref manipulation, or data transformation pipelines

## Implementation Details in ego-browser Source Code

The architectural relationship between these APIs reveals that `snapshot()` is essentially a convenience wrapper around `snapshotRaw()`.

### Internal Serialization Logic

In [`package/ego-browser/src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/format.ts), the `snapshot()` implementation internally invokes `snapshotRaw()` and then serializes the result into the formatted string that agents expect. This means every call to `snapshot()` triggers the underlying raw capture but adds processing overhead to create the human-readable representation.

### Low-Level CDP Integration

The `snapshotRaw()` function communicates directly with the browser's CDP layer. As noted 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), this method calls the `ego.snapshot` RPC and returns the JSON response unchanged, providing "the text surface most agents want" with full access to the structured `{ content, refs }` shape.

### Module Exports

Both functions are exposed to the agent runtime 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 for import in automation scripts:

```javascript
import { snapshot, snapshotRaw } from 'ego-browser/helpers';

```

## When to Use Each API

Choosing between these methods depends on whether you need consumption-ready text or raw data structures.

### Use snapshot() for Human-Readable Output

Select `snapshot()` when you need immediate visual feedback or text to feed into LLM prompts. The formatted string includes stable locators rendered inline with the content, making it ideal for debugging sessions or generating human-readable reports.

```javascript
// Generate a printable snapshot for debugging
const pageSnapshot = await page.snapshot();
console.log('Current page state:\n', pageSnapshot);

```

### Use snapshotRaw() for Programmatic Processing

Select `snapshotRaw()` when you need to inspect individual DOM references, count available elements, or transform the content before further processing. The structured object allows direct access to the `refs` mapping, which correlates numeric IDs (`@1`, `@2`) to specific DOM node information.

```javascript
// Access raw structure for custom processing
const raw = await page.snapshotRaw();
console.log('Content length:', raw.content.length);
console.log('Available refs:', Object.keys(raw.refs));

```

## Complete Code Examples

### Basic Logging with snapshot()

```javascript
import { snapshot } from 'ego-browser/helpers';

async function debugPage(page) {
  // Returns a formatted string ready for console or logs
  const snap = await page.snapshot();
  console.log(snap);
  // Output includes: "@1 [button] Click me" with CSS/XPath locators
}

```

### Data Extraction with snapshotRaw()

```javascript
import { snapshotRaw } from 'ego-browser/helpers';

async function extractRefs(page) {
  // Returns { content: string, refs: Record<number, any> }
  const raw = await page.snapshotRaw();
  
  // Programmatically inspect specific refs
  const refIds = Object.keys(raw.refs);
  const firstRef = raw.refs[1];
  
  return {
    textLength: raw.content.length,
    elementCount: refIds.length,
    firstElement: firstRef
  };
}

```

## Summary

- **`snapshot()`** returns a `Promise<string>` containing formatted, human-readable page content with semantic refs and stable locators, ideal for debugging and LLM prompts.
- **`snapshotRaw()`** returns a `Promise<object>` with the raw structured snapshot `{ content, refs }`, providing programmatic access to DOM node mappings for custom processing.
- **Implementation:** `snapshot()` internally calls `snapshotRaw()` located in [`package/ego-browser/src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/format.ts) and serializes the result, while `snapshotRaw()` invokes the CDP `ego.snapshot` RPC 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).
- **Exports:** Both functions are available through [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) for use in automation scripts.

## Frequently Asked Questions

### Does snapshot() call snapshotRaw() internally?

Yes. According to the source code in [`package/ego-browser/src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/format.ts) (lines 402-410), the `snapshot()` method calls `snapshotRaw()` and then serializes the structured result into the formatted string output. This means `snapshot()` always incurs the processing cost of `snapshotRaw()` plus additional string formatting overhead.

### Can I access individual DOM refs using snapshot()?

No. The `snapshot()` API returns a flat string where refs (e.g., `@1`, `@2`) are embedded as text markers. To access the structured mapping of numeric IDs to DOM node objects, you must use `snapshotRaw()`, which returns the `refs` property as a `Record<number, any>`.

### Which API should I use for LLM-based automation?

Use `snapshot()`. The formatted string output includes semantic context and stable locators (CSS/XPath) in a human-readable format that language models can interpret effectively. The `snapshotRaw()` object structure is designed for programmatic consumption rather than LLM text prompts.

### Where are these snapshot functions exported from?

Both functions are re-exported from [`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 in the agent scripting environment. The actual implementations reside in [`package/ego-browser/src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/format.ts), with the underlying CDP integration located in [`package/ego-browser/src/driver/observe.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/observe.ts).