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

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 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 (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 (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, 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 (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 (lines 84-85), making them available for import in automation scripts:

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.

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

// 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()

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

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 and serializes the result, while snapshotRaw() invokes the CDP ego.snapshot RPC as implemented in package/ego-browser/src/driver/observe.ts.
• Exports: Both functions are available through 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 (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 (lines 84-85), making them available in the agent scripting environment. The actual implementations reside in package/ego-browser/src/format.ts, with the underlying CDP integration located in package/ego-browser/src/driver/observe.ts.

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