# How to Use the API Provided by ego-lite: Complete SDK Reference

> Explore the ego-lite API with this comprehensive SDK reference. Learn to initialize the SDK and inject powerful navigation, element control, and task management helpers into your projects.

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

---

**Initialize the ego-browser SDK by importing `installEgoSdk` from [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts) and invoking it to inject navigation, element control, and task-management helpers into the global scope.**

The citrolabs/ego-lite repository ships a lightweight JavaScript SDK that bridges your automation scripts to the ego lite browser runtime. Located in `package/ego-browser/`, this SDK exposes a comprehensive API for browser automation without requiring additional binaries. Learning how to use the API provided by ego-lite lets you navigate pages, resolve DOM elements, manage isolated task spaces, and execute site-specific skills through the Chrome DevTools Protocol (CDP) bridge.

## Installing and Initializing the SDK

Every script starts with the **`installEgoSdk`** function exported from [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts). This function bootstraps the SDK by injecting all public helpers into your chosen target object (defaults to `globalThis`).

Under the hood, `installEgoSdk` calls `helperContext()` to instantiate the helper functions and wraps asynchronous calls so they block until an optional *ready* signal resolves (see implementation lines 57–66 in [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts)). Once initialized, your script can access the full ego-lite API surface without additional imports.

```javascript
import { installEgoSdk } from "./package/ego-browser/src/index.js";

// Inject all helpers into globalThis
installEgoSdk();

// SDK is now ready for use
await goto("https://example.com");

```

## Core API Categories

The ego-browser SDK organizes functionality into logical groups defined in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts). Each category routes commands through the CDP runtime ([`src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts)) and CDP evaluator ([`src/cdp-eval.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/cdp-eval.ts)).

### Navigation and Tab Control

These functions manage browser navigation and tab lifecycle:

- **`goto(url)`** – Navigates the current tab to the specified URL using the `nav` driver in [`src/driver/nav.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/nav.ts), which dispatches `ego.sendCDPMessage`.
- **`openOrReuseTab(url, opts)`** – Opens a new tab or reuses an existing one matching the criteria.
- **`switchTab(target)`** and **`listTabs()`** – Switch context between tabs or enumerate open tabs.

### Element Interaction

Element helpers perform actions after resolving locators through [`src/element-resolver.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/element-resolver.ts), which translates selectors like `loc=css:button` or `@23` into CDP node IDs:

- **`click(locator)`**, **`dblclick(locator)`**, **`hover(locator)`** – Pointer interactions.
- **`press(key)`**, **`fill(locator, value)`** – Keyboard input and form population.
- **`evaluateLocator(locator, expression)`** – Execute JavaScript in the context of a resolved element.

### Waiting and Synchronization

Control script execution flow until DOM or network conditions are met:

- **`waitForSelector(locator, opts)`** – Pause until an element appears.
- **`waitForLoadState(state)`** – Wait for network idle or document load.
- **`waitForTimeout(ms)`** – Explicit delay.

### Screenshots and Snapshots

Capture visual state and event logs:

- **`screenshot(opts)`** – Save a PNG of the current viewport.
- **`snapshot()`** – Retrieve a serialized DOM representation.
- **`drainEvents()`** – Flush buffered CDP events for inspection.

### Task-Space Management

Isolate browser state into named containers to prevent cross-contamination between workflows:

- **`newTaskSpace(name)`** – Create a fresh isolation context.
- **`useOrCreateTaskSpace(name)`** – Switch to an existing space or create one.
- **`switchTaskSpace(name)`** and **`handOffTaskSpace(name)`** – Transfer control between spaces.
- **`completeTaskSpace(name, opts)`** – Clean up and optionally persist the space.

### Network Requests

Perform HTTP operations without leaving the script context:

- **`browserFetch(url, opts)`** – Fetch via the browser's network stack.
- **`serverFetch(url, opts)`** – Fetch via the ego lite backend.

### Site-Specific Skills

Execute learned behaviors bundled for specific domains:

- **`siteSkillsForUrl(url)`** – List available skills for a domain.
- **`runSiteTool(domain, toolName, params)`** – Invoke a learned tool implemented in [`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts).
- **`learnContext(opts)`** – Trigger the learning pipeline for the current page.

## How the SDK Works Internally

When you call a helper like `goto`, the SDK routes the request through several layers. The public API in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) delegates to the **CDP runtime** ([`src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts)), which manages the transport session and event buffering. Navigation specifically uses the driver architecture in [`src/driver/nav.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/nav.ts), while element resolution happens in [`src/element-resolver.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/element-resolver.ts), converting locators into CDP node IDs before sending commands via `ego.sendCDPMessage`.

Site-specific skills are loaded and executed by the learning module at [`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts), which dynamically bundles domain-specific logic.

## Complete Usage Examples

### Basic Navigation and Screenshot

This script demonstrates navigation, element waiting, interaction, and image capture:

```javascript
import { installEgoSdk } from "./package/ego-browser/src/index.js";

installEgoSdk();

await goto("https://example.com");
await waitForSelector("text=More information");
await click("text=More information");
const snap = await screenshot();
console.log("Screenshot saved:", snap.path);

```

### Isolating Work with Task Spaces

Use task spaces to isolate cookies, storage, and execution context between runs:

```javascript
import { installEgoSdk } from "./package/ego-browser/src/index.js";

installEgoSdk();

const space = await newTaskSpace("scrape-run");
await useOrCreateTaskSpace(space.name);
await goto("https://news.ycombinator.com");
await waitForSelector("a.storylink");
const titles = await evaluateAll(`
  Array.from(document.querySelectorAll('a.storylink')).map(el => el.textContent)
`);
console.log(titles);
await completeTaskSpace(space.name, { keep: false });

```

### Running Site-Specific Tools

Invoke domain-specific automation bundles without writing custom selectors:

```javascript
import { installEgoSdk } from "./package/ego-browser/src/index.js";

installEgoSdk();

const result = await runSiteTool("github.com", "searchRepos", {
  query: "ego-lite",
});
console.log(result);

```

## Summary

- **Initialize first:** Call `installEgoSdk()` from [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts) to expose the API on `globalThis`.
- **Navigation and elements:** Use `goto`, `click`, and `waitForSelector` for core browser automation, backed by [`src/driver/nav.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/nav.ts) and [`src/element-resolver.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/element-resolver.ts).
- **Isolation:** Leverage `newTaskSpace` and `useOrCreateTaskSpace` to compartmentalize workflows.
- **Extensibility:** Execute learned behaviors with `runSiteTool` from the [`src/learning/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/learning/index.ts) module.
- **Architecture:** All commands route through the CDP bridge managed in [`src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/browser-runtime.ts) and [`src/cdp-eval.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/cdp-eval.ts).

## Frequently Asked Questions

### What is the entry point for the ego-lite API?

The primary entry point is **`installEgoSdk`** exported from [`package/ego-browser/src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/index.ts). Importing and invoking this function injects all helper methods—navigation, element control, task spaces, and network utilities—into the global scope (or a specified target), making them available for the duration of your script.

### How does ego-lite resolve element locators?

ego-lite uses the **element resolver** in [`src/element-resolver.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/element-resolver.ts) to translate locators (such as `css:button`, `text=Submit`, or numeric refs like `@23`) into CDP node IDs. Once resolved, element action helpers like `click` or `fill` send CDP commands through the browser runtime to interact with the specific DOM node.

### What is a task space and when should I use it?

A **task space** is an isolated browser context that segregates cookies, localStorage, and execution environment. Create one with `newTaskSpace()` and switch to it via `useOrCreateTaskSpace()` when you need to run parallel or sequential workflows without cross-contamination, such as scraping multiple accounts on the same domain.

### Does ego-lite require separate browser binaries?

No. The ego-browser SDK is pure JavaScript and communicates with the ego lite runtime through the global **`ego`** bridge object. You only need the citrolabs/ego-lite repository (or its NPM package) and a running ego lite environment that exposes this bridge; no additional driver binaries like Selenium or Playwright are required.