Ego-Lite helperContext Helpers: Complete API Reference for Browser Automation

Ego-Lite's helperContext injects a global scope containing five specialized facades—page, browser, taskSpaces, site, and fetch—alongside dozens of top-level Playwright-style utilities for navigation, DOM interaction, and network requests.

Ego-Lite is an open-source browser automation framework that provides agents with a high-level API for controlling web browsers through the ego-browser runtime. At the heart of this system lies the helperContext defined in package/ego-browser/src/helpers.ts, a curated collection of utilities that eliminates the need for manual imports by exposing Playwright-style methods directly to agent scripts.

The Five Facade Groups

The helperContext organizes functionality into five distinct facades, each handling a specific domain of browser automation. These are assembled in lines 22-27 of package/ego-browser/src/helpers.ts and injected as global objects.

The page Facade

The page facade provides Playwright-compatible page interaction methods. According to the source code (lines 85-108), this includes navigation helpers like goto, reload, url, and title, plus element location via locator, getByRole, and getByText. Agents can control input through the keyboard.* and mouse.* sub-objects, capture visual state with screenshot, and execute arbitrary JavaScript via evaluate and waitForLoadState.

The browser Facade

For tab-level operations, the browser facade (lines 73-82) exposes listTabs, currentTab, switchTab, and closeTab. The openOrReuseTab helper optimizes resource usage by reusing existing tabs when possible, while ensureRealTab and iframeTarget handle complex scenarios involving iframe targeting and tab verification.

The taskSpaces Facade

Task spaces represent isolated browsing contexts for multi-step workflows. The taskSpaces facade (lines 86-96) provides lifecycle management through list, switch, new, and useOrCreate. Coordination primitives include claim, handOff, takeOver, and waitForAgentControl for multi-agent scenarios. The complete method finalizes a task space with an optional keep parameter to persist the context.

The site Facade

This facade enables learned automation skills and site-specific behaviors. As implemented in lines 99-106, site.skills and site.skillsForUrl retrieve learned automation patterns, while site.runTool and site.runBrowserTool execute them against specific domains. The learnContext helper captures new site-specific patterns for future reuse.

The fetch Facade

Network utilities are exposed through fetch.server and fetch.browser (lines 18-19), implemented in package/ego-browser/src/http.js. The fetch.server method executes HTTP requests from the Node.js runtime context, while fetch.browser performs requests within the browser's origin, effectively bypassing CORS limitations for agent scripts.

Top-Level Utility Functions

Beyond the facades, helperContext exports numerous low-level utilities directly into the global scope (lines 27-101 of helpers.ts). These utilities are sourced from specialized driver modules and require no facade prefix.

Pointer and Keyboard Actions

Pointer actions including click, dblclick, hover, drag, and wheel are implemented in package/ego-browser/src/driver/pointer.js. Keyboard operations such as press, down, up, insertText, fill, and check reside in package/ego-browser/src/driver/keyboard.js.

Locator and Element Helpers

Element inspection utilities from package/ego-browser/src/driver/locator.js include textContent, innerText, isVisible, getAttribute, boundingBox, count, and evaluateAll. The scrollIntoViewIfNeeded helper ensures elements are interactable before actions.

Observation and Screencast

Snapshot and screenshot utilities from package/ego-browser/src/driver/observe.js provide snapshot, screenshot, elementCenter, and drainEvents. Screencast controls include startScreencast and stopScreencast for recording automation sessions.

Navigation and Waits

Low-level navigation and file upload helpers include cdp for Chrome DevTools Protocol access, setInputFiles for file uploads, and waiting primitives from package/ego-browser/src/driver/waits.js such as waitForTimeout, waitForLoadState, and waitForSelector.

Practical Usage Examples

The following examples demonstrate how agents interact with the helperContext without import statements:

// Navigate and click using the page facade
await page.goto('https://example.com')
await page.locator('text=Login').click()

// Execute keyboard shortcuts
await page.keyboard.press('Enter')

// Manage isolated task spaces
const ts = await taskSpaces.useOrCreate('my-space')
await page.goto('https://news.ycombinator.com')
await taskSpaces.complete(ts.id, { keep: true })

// Fetch data from the Node.js context
const json = await fetch.server('https://api.github.com/repos/citrolabs/ego-lite')
console.log(json)

// Execute learned site-specific skills
const result = await site.runTool('example.com', 'search', { query: 'ego-lite' })
console.log(result)

Summary

• Five facades organize helpers into page, browser, taskSpaces, site, and fetch domains.
• Global scope injection via helperContext() (lines 22-27) eliminates the need for import statements in agent scripts.
• Playwright compatibility means page.goto, page.locator, and keyboard.press work identically to standard Playwright APIs.
• Specialized drivers in package/ego-browser/src/driver/ implement low-level actions for pointers, keyboards, locators, navigation, and observation.
• Dual-context fetching via fetch.server and fetch.browser handles both API calls and browser-origin requests.

Frequently Asked Questions

What is the difference between fetch.server and fetch.browser in ego-lite?

fetch.server executes HTTP requests from the Node.js runtime side, making it ideal for API calls that don't require browser cookies or CORS bypass. fetch.browser performs requests within the browser's execution context, which allows it to access authenticated sessions and bypass cross-origin restrictions. Both are exposed through the fetch facade defined in package/ego-browser/src/http.js.

How do task spaces isolate browsing contexts in helperContext?

Task spaces create isolated browsing sessions through the taskSpaces facade methods like new, useOrCreate, and claim. Each task space maintains separate cookies, local storage, and session state. The handOff and takeOver methods enable transferring control between agents while preserving isolation, and complete terminates the context with an optional keep flag for persistence.

Can I use standard Playwright methods with ego-lite's page facade?

Yes, the page facade exposes Playwright-compatible methods including goto, reload, locator, getByRole, getByText, evaluate, and screenshot. The implementation in package/ego-browser/src/helpers.ts (lines 85-108) maps these familiar APIs to the underlying ego-browser runtime, allowing migration of existing Playwright scripts with minimal changes.

Where are the low-level pointer and keyboard helpers implemented?

Pointer actions like click, hover, and drag are implemented in package/ego-browser/src/driver/pointer.js, while keyboard utilities such as press, fill, and check reside in package/ego-browser/src/driver/keyboard.js. These are exported as top-level utilities in the helperContext, making them available globally without requiring direct imports from driver modules.

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