# snapshot vs snapshotRaw in ego-lite: When to Use Each Browser Automation Helper

> Understand the difference between snapshot and snapshotRaw in ego-lite. Learn when to use snapshot for readable text and snapshotRaw for advanced DOM manipulation with structured data.

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

---

**`snapshot` returns readable page text as a string, while `snapshotRaw` returns a structured object with content, element references, and metadata for advanced DOM manipulation.**

In ego-lite's browser automation toolkit, these two helpers serve distinct purposes in the agent runtime. Understanding when to use each will help you build more effective automation workflows, whether you need simple text extraction or full programmatic control over page elements.

## What `snapshot` Does: Simple Text Extraction

The `snapshot` helper is designed for the most common use case: extracting human-readable text from the current page. It strips HTML markup and returns clean, parseable content that agents can analyze or display directly.

According to the ego-lite source code in [`src/driver/observe.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/observe.ts) (lines 73-80), `snapshot` is implemented as a thin wrapper around `snapshotRaw`:

```typescript
// observe.ts lines 73-80 - snapshot implementation
export async function snapshot(options?: SnapshotOptions): Promise<string> {
  const raw = await snapshotRaw(options);
  return raw.content;  // Extracts only the text content
}

```

The helper applies sensible defaults automatically, including full-page scope, action marks, and stable locators. This makes it ideal for quick integrations where you don't need to manipulate specific elements.

### Typical `snapshot` Usage

```typescript
// Extract readable page text for analysis
const pageText = await page.snapshot();
console.log(pageText);
// Output: "Welcome to the site. Sign in to continue..."

```

## What `snapshotRaw` Does: Full Structured Access

The `snapshotRaw` helper provides complete access to the snapshot's internal structure. Defined in [`src/driver/observe.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/observe.ts) (lines 49-63), it performs a low-level driver call that forwards directly to the embedded ego runtime and returns a comprehensive object containing:

- **`content`** – The readable text (same as `snapshot` returns)
- **`refs`** – Array of element references for DOM interaction
- **Metadata** – Additional snapshot properties for inspection

Crucially, `snapshotRaw` also updates the internal reference map in [`src/state.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/state.ts). This enables subsequent calls to resolve `@N` references—compact identifiers that point to specific DOM elements captured in the snapshot.

### Typical `snapshotRaw` Usage

```typescript
// Capture full snapshot with element references
const raw = await page.snapshotRaw({
  scope: "full_page",
  includeActionMarks: true,
  includeStableLocator: true
});

console.log(raw.content);  // Readable text
console.log(raw.refs);      // Element references for interaction

```

## Key Differences: snapshot vs snapshotRaw

| Aspect | `snapshot` | `snapshotRaw` |
|--------|-----------|---------------|
| **Return type** | `Promise<string>` | `Promise<object>` |
| **Primary output** | Clean text content | Structured object with multiple fields |
| **Element access** | None | Full `refs` array with backend node IDs |
| **Ref resolution** | Not applicable | Enables `@N` reference resolution |
| **Use case** | Text analysis, LLM prompts | DOM manipulation, element interaction |
| **Implementation** | Wrapper around `snapshotRaw` | Direct driver call to ego runtime |

## Practical Code Examples

### Basic Text Extraction

```typescript
// Most common pattern - just get readable content
const text = await page.snapshot();
// Process with LLM or display to user

```

### Element Interaction Workflow

```typescript
// Step 1: Capture raw snapshot to get references
const raw = await page.snapshotRaw();

// Step 2: Inspect refs to find target element
const buttonRef = raw.refs.find(ref => 
  ref.tagName === 'button' && raw.content.includes('Submit')
);

// Step 3: Click using the @N reference syntax
if (buttonRef) {
  await page.click(`@${buttonRef.backendNodeId}`);
}

```

### Accessing Snapshot Metadata

```typescript
const raw = await page.snapshotRaw();

// Available fields beyond content and refs
console.log(raw.content);           // Readable text
console.log(raw.refs);               // Element reference array
// Additional metadata fields may include timing, URL, viewport info

```

## Where These Helpers Are Defined

The ego-lite source code organizes these functions across several files:

- **[`src/driver/observe.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/observe.ts)** – Core implementations: `snapshotRaw` (lines 49-63) and `snapshot` (lines 73-80)
- **[`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)** – Public API exposure via `page.snapshot` and `page.snapshotRaw`
- **[`src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/format.ts)** – Documentation strings visible in `help()` output (line 416 describes both helpers)
- **[`src/state.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/state.ts)** – Internal reference map that `snapshotRaw` populates

As documented in [`src/format.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/format.ts), the `help()` system describes:
- `page.snapshot()` — "Return snapshot content with agent-friendly defaults"
- `page.snapshotRaw()` — "Return the raw structured snapshot object"

## Summary

- **Choose `snapshot`** when you need clean, readable text for analysis, LLM prompts, or simple display—this covers most agent use cases.

- **Choose `snapshotRaw`** when you need programmatic access to DOM elements, plan to use `@N` reference syntax for interactions, or require snapshot metadata for advanced workflows.

- **`snapshot` is a convenience wrapper** around `snapshotRaw` that extracts just the `content` field, making it the simpler choice when full structure isn't needed.

- **`snapshotRaw` enables element interaction** by populating the reference map and exposing the `refs` array for precise DOM manipulation.

## Frequently Asked Questions

### Can I use element references from a `snapshot` call?

No. Only `snapshotRaw` populates the internal reference map and returns the `refs` array. If you need to interact with specific elements using `@N` syntax, you must call `snapshotRaw` first.

### Is `snapshot` slower than `snapshotRaw`?

No meaningful difference exists. Since `snapshot` internally calls `snapshotRaw` and merely extracts the `content` field, both perform the same underlying capture operation. The string extraction adds negligible overhead.

### When should I pass options to these helpers?

Both accept optional `SnapshotOptions` for customizing scope (viewport vs. full page), action marks, and stable locators. Pass options to `snapshotRaw` when you need non-default behavior; `snapshot` passes these through unchanged. The defaults work well for most automation scenarios.