# Ego-Browser Public Helpers for Agent Scripts: Complete API Reference (2024) > Explore the ego-browser package's 40+ public helpers for agent scripts, including CDP methods, navigation, and observation tools. Access the complete API reference for efficient automation. - Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite) - Tags: api-reference - Published: 2026-08-28 --- **The `ego-browser` package exposes 40+ public helpers to agent scripts through a globally injected SDK, including CDP methods, pointer/keyboard actions, navigation controls, observation tools, waits, and site-specific skill runners—all defined in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) and installed via `installEgoSdk()`.** The `ego-browser` package from the [citrolabs/ego-lite](https://github.com/citrolabs/ego-lite) repository provides a thin SDK that injects a **helper context** into the global runtime for agent scripts. These **ego-browser public helpers** enable browser automation, observation, navigation, and AI-powered site interactions without requiring external dependencies. All helpers are defined in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) and re-exported from [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts), making them available as top-level globals like `click`, `page`, and `site.skills`. This guide covers every public helper grouped by functional area, with implementation details from the source code and practical usage examples. --- ## Core CDP and Evaluation Helpers The lowest-level helpers provide direct access to the Chrome DevTools Protocol (CDP) and raw JavaScript evaluation. | Helper | Purpose | Source | |--------|---------|--------| | `cdp` | Send raw CDP commands to the browser | [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) lines 5–9 | | `evaluate` | Execute JavaScript in the page context | [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) lines 5–9 | These form the foundation that higher-level helpers build upon. --- ## Pointer and Mouse Action Helpers All mouse and pointer interactions are imported from [`src/driver/pointer.js`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/pointer.js) and re-exported through the main helpers module. ```javascript // Click with options await click('#submit', { button: 'left', modifiers: ['Control'] }); // Drag and drop await drag('#source', '#target'); // Hover with precise positioning await hover('.tooltip-trigger', { position: { x: 10, y: 5 } }); // Scroll element into view if needed await scrollIntoViewIfNeeded('.lazy-image'); ``` **Available pointer helpers:** - `click` — Single click with configurable button and modifiers - `dblclick` — Double-click action - `hover` — Mouse hover with optional positioning - `drag` — Drag-and-drop between elements - `wheel` — Scroll wheel events - `scrollIntoViewIfNeeded` — Conditional scroll into viewport Defined in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) lines 30–36. --- ## Keyboard and Input Helpers Text entry, form interaction, and keyboard events come from [`src/driver/keyboard.js`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/keyboard.js). ```javascript // Type with human-like delays await fill('#search', 'ego-browser helpers', { timeout: 5000 }); // Press special keys await press('Enter'); await press('Control+a'); // Sequential keystroke simulation await pressSequentially('#otp-input', '123456', { delay: 100 }); // Checkbox state management await check('#terms'); await uncheck('#newsletter'); await setChecked('#remember-me', true); // Focus and dispatch custom events await focus('#email'); await dispatchEvent('#form', 'submit'); ``` **Full list of input helpers:** - `press`, `down`, `up` — Key press, hold, and release - `insertText` — Direct text insertion - `focus` — Element focus - `fill` — Clear and type into field - `pressSequentially` — Keystroke-by-keystroke typing - `check`, `uncheck`, `setChecked` — Checkbox manipulation - `selectOption` — Dropdown selection - `dispatchEvent` — Custom DOM event firing Defined in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) lines 37–49. --- ## Locator and Element Query Helpers Extract data from page elements using helpers from [`src/driver/locator.js`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/locator.js). ```javascript // Basic text extraction const heading = await textContent('h1'); const visibleText = await innerText('.article-body'); // Form state inspection const emailValue = await inputValue('#email'); const isAgreed = await isChecked('#consent'); // Multiple element handling const allLinks = await allTextContents('a[href]'); const count = await count('.list-item'); // Evaluate within element context const computedStyle = await evaluateLocator('.banner', el => getComputedStyle(el).height); ``` **Available locator utilities:** - `textContent`, `innerText` — Text extraction variants - `inputValue` — Current form field value - `isChecked` — Checkbox state - `getAttribute` — DOM attribute retrieval - `count` — Element count matching selector - `allInnerTexts`, `allTextContents` — Batch text extraction - `innerHTML` — Raw HTML content - `evaluateLocator`, `evaluateAll` — Custom JS execution in element scope Defined in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) lines 50–70. --- ## Navigation and Tab Control Helpers Manage browser tabs, frames, and navigation state via [`src/driver/nav.js`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/nav.js). ```javascript // Tab management const tabs = await listTabs(); await switchTab(tabs[1].id); await closeTab(tabs[0].id); // Navigation with error handling await goto('https://example.com', { waitUntil: 'networkidle' }); await openOrReuseTab('https://docs.example.com'); // Frame/iframe targeting const frame = await iframeTarget('#preview-frame'); // Ensure we're on a real tab (not devtools/extension) await ensureRealTab(); // Page metadata const info = await pageInfo(); console.log(info.url, info.title); ``` **Navigation helpers include:** - `INTERNAL_URL_PREFIXES` — Constants for internal URL schemes - `pageInfo` — Current page metadata - `listTabs`, `currentTab` — Tab enumeration - `switchTab`, `openOrReuseTab`, `closeTab` — Tab lifecycle - `goto` — Navigation with load state waiting - `ensureRealTab` — Validation helper - `iframeTarget` — Frame context targeting Defined in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) lines 71–82. --- ## Observation and Screenshot Helpers Capture page state for analysis or debugging through [`src/driver/observe.js`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/observe.js). ```javascript // Structured accessibility snapshot const snap = await snapshot(); // Returns AX tree for LLM consumption const raw = await snapshotRaw(); // Unprocessed snapshot data // Visual capture await screenshot({ path: 'debug.png', fullPage: true }); // Coordinate calculation for pointer actions const center = await elementCenter('#target'); // Event drainage for synchronization await drainEvents(); ``` **Observation helpers:** - `snapshot` — Accessibility tree snapshot (AI-optimized format) - `snapshotRaw` — Raw snapshot without processing - `screenshot` — PNG capture with sizing options - `elementCenter` — Coordinate calculation - `drainEvents` — Process pending browser events Defined in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) lines 83–89. --- ## Wait and Synchronization Helpers Control timing and conditions for action execution via [`src/driver/waits.js`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/waits.js). ```javascript // Explicit delays await waitForTimeout(1000); // 1 second // Page state waits await waitForLoadState('domcontentloaded'); await waitForLoadState('networkidle'); // Element availability await waitForSelector('.dynamic-content', { timeout: 10000 }); // Custom conditions await waitForFunction(() => window.__appReady === true, { polling: 100 }); // Network waits await waitForURL(/\/dashboard/); await waitForRequest('**/api/session'); await waitForResponse(req => req.url().includes('/api/data')); ``` **Wait helpers:** - `waitForTimeout` — Fixed delay - `waitForLoadState` — Page lifecycle events - `waitForSelector` — Element availability - `waitForFunction` — Custom predicate polling - `waitForURL` — Navigation pattern matching - `waitForRequest`, `waitForResponse` — Network event waiting Defined in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) lines 90–98. --- ## File Upload and Screencast Helpers Specialized utilities for file handling and video recording. ```javascript // File upload await setInputFiles('#file-input', ['/path/to/upload.pdf']); // Screencast recording await startScreencast({ outputPath: '/recordings/session.webm' }); // ... perform actions ... await stopScreencast(); ``` | Helper | Source | |--------|--------| | `setInputFiles` | [`src/driver/files.js`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/files.js) via [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) line 99 | | `startScreencast`, `stopScreencast` | [`src/driver/screencast.js`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/screencast.js) via [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) lines 100–101 | --- ## Network Fetch Helpers HTTP requests from both browser and Node contexts. ```javascript // Browser-context fetch (uses page's cookies, headers) const html = await browserFetch('https://api.example.com/data', { headers: { 'Accept': 'application/json' } }); // Server-side fetch (bypasses CORS, uses proxy config) const proxyData = await serverFetch('https://internal.service/metrics'); ``` **Source:** [`src/http.js`](https://github.com/citrolabs/ego-lite/blob/main/src/http.js) via [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) lines 18–22. --- ## Task-Space Management Helpers Advanced session isolation and handoff controls implemented directly in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) starting at line 107. ```javascript // Create isolated automation context const space = await newTaskSpace('invoice-processing'); await switchTaskSpace(space.id); // Or reuse existing const existing = await useOrCreateTaskSpace('customer-onboarding'); // Hand control to human user await handOffTaskSpace({ message: 'Please solve the CAPTCHA' }); // Resume after human intervention await waitForAgentControl(); await takeOverTaskSpace(); // Cleanup await completeTaskSpace(space.id); ``` **Task-space API:** - `listTaskSpaces` — Enumerate active spaces - `switchTaskSpace` — Change active context - `newTaskSpace`, `useOrCreateTaskSpace` — Space acquisition - `claimTaskSpace` — Exclusive access locking - `completeTaskSpace` — Clean termination - `handOffTaskSpace`, `takeOverTaskSpace` — Human/AI control transfer - `waitForAgentControl` — Resume signal --- ## Site-Skill and Learning Helpers AI-powered site-specific automation through learned patterns, defined near lines 64–78 in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts). ```javascript // Discover available skills for current URL const skills = await siteSkillsForUrl(); console.log(skills); // ['searchProducts', 'addToCart', 'checkout'] // Invoke learned skill const result = await runSiteTool('github', 'searchRepos', { query: 'ego-lite', language: 'typescript' }); // Browser-side skill execution await runSiteBrowserTool('linkedin', 'sendConnectionRequest', { profileUrl: 'https://linkedin.com/in/example' }); // Context enrichment for skill learning await learnContext(['.product-card', '.price', '.add-to-cart']); ``` **Site-skill helpers:** - `siteSkillsForUrl` — Skill discovery for URL - `siteSkills` — Direct skill access - `runSiteTool` — Node-side skill execution - `runSiteBrowserTool` — Browser-context skill execution - `learnContext` — Feedback for skill improvement --- ## SDK Installation and Helper Context Helpers are not automatically global—they must be installed via the SDK entry point. According to [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts) lines 51–63, `installEgoSdk()` performs the injection: ```javascript // Inside ego-browser runtime import { installEgoSdk } from 'ego-browser'; // Installs all helpers as globals: click, page, site.skills, etc. installEgoSdk(); // Now helpers are available globally await goto('https://example.com'); await click('button'); ``` The `helperContext()` function (line 822 in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)) builds the complete facade object containing all exported helpers. Additional utilities include: - `loadAgentHelpers` (lines 52–65) — Load custom helper extensions - `__testing` (line 667) — Internal testing utilities (not for production use) --- ## Summary The **ego-browser public helpers** provide a comprehensive browser automation API for agent scripts: - **40+ documented helpers** across 11 functional categories - **Zero external dependencies** once SDK is installed - **Global availability** after `installEgoSdk()` runs - **Layered architecture** from low-level CDP to high-level site skills Key implementation files to reference: - [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) — Central definition and export hub - [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts) — SDK installation and global injection - `src/driver/*.js` — Core automation implementations - [`src/http.js`](https://github.com/citrolabs/ego-lite/blob/main/src/http.js) — Network utilities - `src/learning/*` — Site-skill discovery and execution --- ## Frequently Asked Questions ### How do I access ego-browser helpers in my agent script? Call `installEgoSdk()` from `ego-browser` at script startup. This injects all helpers into the global scope as properties of `helperContext()`, making functions like `click`, `goto`, and `snapshot` available without imports, as implemented in [`src/index.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/index.ts) lines 51–63. ### What is the difference between `browserFetch` and `serverFetch`? **`browserFetch`** executes requests within the page context, inheriting cookies, session storage, and CORS policies. **`serverFetch`** runs from the Node.js side, bypassing CORS and using configured proxy settings, making it suitable for internal API calls. ### Can I extend ego-browser with custom helpers? Yes. Use `loadAgentHelpers()` (defined in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) lines 52–65) to load additional helper modules. Custom helpers integrate into the same `helperContext()` facade and become available to agent scripts after SDK installation. ### How do site skills work in ego-browser? Site skills are AI-learned automation patterns for specific websites. The `siteSkillsForUrl()` function discovers available skills, while `runSiteTool()` and `runSiteBrowserTool()` execute them in Node or browser contexts respectively. The `learnContext()` helper provides feedback to improve skill accuracy over time.