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

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 (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 (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 (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:

// 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:

// 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 and exported through 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, 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 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.

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