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

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 (lines 73-80), snapshot is implemented as a thin wrapper around snapshotRaw:

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

// 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 (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. This enables subsequent calls to resolve @N references—compact identifiers that point to specific DOM elements captured in the snapshot.

Typical snapshotRaw Usage

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

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

Element Interaction Workflow

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

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 – Core implementations: snapshotRaw (lines 49-63) and snapshot (lines 73-80)
• src/helpers.ts – Public API exposure via page.snapshot and page.snapshotRaw
• src/format.ts – Documentation strings visible in help() output (line 416 describes both helpers)
• src/state.ts – Internal reference map that snapshotRaw populates

As documented in 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.

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