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

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 (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 (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 (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	Structured object ({ content, refs, ... })	Returns the exact payload from browserEgo().snapshot
snapshot	observe.ts	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):

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

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 (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, with snapshotRaw also exported via 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, 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—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 for external use, and both are documented in 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.

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