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

> Explore ego-lite's helperContext API reference. Discover page, browser, taskSpaces, site, and fetch facades plus Playwright-style utilities for effortless browser automation.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: api-reference
- Published: 2026-08-23

---

**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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/keyboard.js).

### Locator and Element Helpers

Element inspection utilities from [`package/ego-browser/src/driver/locator.js`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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:

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

```

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

```

```javascript
// 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 })

```

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

```

```javascript
// 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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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.