# What Is the Difference Between `snapshot` and `snapshotRaw` in Ego‑Lite

> Understand the difference between snapshot and snapshotRaw in ego-lite. Learn how snapshotRaw provides detailed page data while snapshot offers plain text for easier agent integration.

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

---

**`snapshotRaw` returns a structured object containing the page content, reference mappings, and runtime metadata, whereas `snapshot` returns a plain string containing only the page text by wrapping `snapshotRaw` with agent-friendly defaults.**

The Ego‑Lite browser automation framework (citrolabs/ego-lite) provides two distinct APIs for capturing DOM state. Understanding the difference between `snapshot` and `snapshotRaw` ensures you select the appropriate method for your agent’s interaction model—whether you need full programmatic access to page references or just the readable text content.

## Understanding `snapshotRaw`: The Full Payload

`snapshotRaw` is the low-level interface that communicates directly with the browser runtime. According to the source code in [`package/ego-browser/src/driver/observe.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/observe.ts) (lines 49–63), this function invokes `browserEgo().snapshot` and returns the complete, unmodified payload.

The returned object includes:

- **`content`**: The text representation of the page
- **`refs`**: An array of snapshot references used for element resolution
- **Additional metadata** supplied by the browser runtime

Use `snapshotRaw` when you need to inspect the automatically generated reference map, reuse `refs` for later element targeting, or process the raw data programmatically. This function is also re-exported in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) (lines 85–86) for external module consumption.

## Understanding `snapshot`: The Text-Only Wrapper

`snapshot` is a high-level convenience method designed for standard agent workflows. 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 73–80), it acts as a thin wrapper around `snapshotRaw`.

The function applies three default options—`scope: "full_page"`, `includeActionMarks: true`, and `includeStableLocator: true`—then extracts and returns only the `content` property from the result. The inline documentation (lines 68–70) explicitly notes that agents requiring the structured `{ content, refs }` object should call `snapshotRaw` directly instead.

## Implementation Comparison

| Function | Implementation Location | Return Type | Key Difference |
|----------|------------------------|-------------|----------------|
| **`snapshotRaw`** | [`observe.ts`](https://github.com/citrolabs/ego-lite/blob/main/observe.ts#L49-L63) | Structured object (`{ content, refs, ... }`) | Returns the exact payload from `browserEgo().snapshot` |
| **`snapshot`** | [`observe.ts`](https://github.com/citrolabs/ego-lite/blob/main/observe.ts#L73-L80) | Plain string | Calls `snapshotRaw` with defaults and returns `result.content` only |

When you invoke `snapshot()`, you sacrifice access to the `refs` array and runtime metadata in exchange for a clean, print-ready string. This trade-off is optimal for LLM-based agents that consume page text but do not manipulate specific DOM elements via references.

## Code Examples: Capturing Page State

The following examples demonstrate the practical difference between the two methods. Note that `snapshotRaw` requires you to access the `.content` property explicitly, while `snapshot` returns the string directly.

**Accessing the full raw snapshot (content + metadata):**

```javascript
const raw = await page.snapshotRaw({
  scope: "full_page",
  includeActionMarks: true,
  includeStableLocator: true,
});

console.log(raw.content);  // Page text
console.log(raw.refs);     // Array of references for element resolution

```

**Accessing only the page text (simplified API):**

```javascript
const text = await page.snapshot();  // Defaults applied automatically
console.log(text);                   // Plain string of visible text

```

The helper signatures and public API documentation are further defined in [`package/ego-browser/src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/format.ts) (lines 416–423).

## Summary

- **`snapshotRaw`** provides the complete snapshot payload including `content`, `refs`, and browser metadata—ideal for programmatic element resolution.
- **`snapshot`** returns a simple string of page text by internally calling `snapshotRaw` with defaults and extracting only the `content` field.
- Both functions reside in [`package/ego-browser/src/driver/observe.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/observe.ts), with `snapshotRaw` also exported via [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts).
- Choose `snapshot` for readability and convenience; choose `snapshotRaw` when you need reference mappings or low-level snapshot data.

## Frequently Asked Questions

### When should I use `snapshotRaw` instead of `snapshot`?

Use `snapshotRaw` when your agent needs to programmatically interact with specific DOM elements using the `refs` array, or when you need to inspect snapshot metadata such as stable locators. Use `snapshot` when you only need the human-readable page text for LLM consumption or logging.

### What default options does `snapshot` pass to `snapshotRaw`?

According to the implementation in [`observe.ts`](https://github.com/citrolabs/ego-lite/blob/main/observe.ts), `snapshot` invokes `snapshotRaw` with `scope: "full_page"`, `includeActionMarks: true`, and `includeStableLocator: true` before extracting the `content` property.

### Where are these functions defined in the Ego‑Lite source code?

Both functions are defined in [`package/ego-browser/src/driver/observe.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/observe.ts)—`snapshotRaw` at lines 49–63 and `snapshot` at lines 73–80. The `snapshotRaw` function is additionally re-exported from [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts) for external use, and both are documented in [`package/ego-browser/src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/format.ts).

### Can I access the reference array when using `snapshot`?

No. The `snapshot` function explicitly returns only the `content` string. If you need access to the `refs` array or any other metadata fields, you must call `snapshotRaw` directly and handle the full returned object.