# ego-lite `page` Facade: Complete Capabilities and API Reference

> Explore the ego-lite page facade capabilities. Get a Playwright-style API for navigation, element location, waiting, interaction, screenshots, and screencasts. Learn more.

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

---

**The `page` facade in citrolabs/ego-lite exposes a Playwright-style API through `createPageFacade()` in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts), aggregating navigation, element location, waiting, interaction, screenshot, and screencast utilities.**

The `page` facade serves as the central automation interface for scripts running inside the ego-lite browser environment. Implemented in [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts), this facade wraps Playwright functionality with a secure, serialized boundary while maintaining familiar patterns like promise-based returns and automatic stability waits. All methods are documented in the `FACADE_HELP` map (lines 84–110), providing inline reference for the eight major capability categories exposed to users.

## Architecture and Factory Implementation

The facade is instantiated via `createPageFacade()`, a factory function defined in **[`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)**. This function aggregates browser context methods and exposes them through a single, serializable interface suitable for ego-lite's isolated execution model. The `FACADE_HELP` constant within the same file serves as the canonical documentation source, mapping method names to descriptive help text that covers parameters, return types, and usage examples.

Underlying selector resolution logic resides in **[`src/element-resolver.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/element-resolver.ts)**, which parses CSS and text selectors for the `locator` method. Comprehensive behavioral validation exists in **`src/helpers.test.mjs`**, ensuring parity with Playwright's contract.

## Navigation and Page State Management

The facade provides full browser navigation control with methods that mirror Playwright's `Page` class. These methods return promises and automatically handle navigation timeouts based on the default timeout configuration.

**`goto(url, options)`** initiates navigation to a specified URL with optional wait conditions. **`reload(options)`** refreshes the current page, while **`url()`** and **`title()`** return the current address and document title respectively. The **`info()`** method aggregates basic page metadata into a single call.

```javascript
await page.goto('https://example.com');
const currentUrl = await page.url();   // "https://example.com"
const title = await page.title();      // "Example Domain"

```

## Element Location Strategies

The facade exposes Playwright's semantic locator API, allowing resilient element selection without brittle XPath expressions. All locator methods return a chainable locator object that supports subsequent filtering and actions.

**Core locator methods include:**
- **`locator(selector)`** – Generic CSS selector entry point
- **`getByRole(role, options)`** – ARIA role-based selection
- **`getByText(text, options)`** – Text content matching
- **`getByLabel(text, options)`** – Associated label text
- **`getByPlaceholder(text, options)`** – Placeholder attribute
- **`getByAltText(text, options)`** – Image alternative text
- **`getByTitle(text, options)`** – Title attribute matching
- **`getByTestId(testId)`** – Data-testid attribute

The `locator` object exposes additional chainable methods like `first()` and `nth()` to disambiguate multiple matches, preventing the "strict mode violation" errors that occur when selectors match multiple elements.

## Waiting and Timeout Management

 ego-lite scripts can configure global timeouts and wait for specific page conditions before proceeding. **`setDefaultTimeout(ms)`** establishes the global timeout for all subsequent operations, while **`waitForTimeout(ms)`** performs explicit delays.

**State and selector waiting:**
- **`waitForLoadState(state, options)`** – Waits for network idle or DOM content loaded
- **`waitForSelector(selector, options)`** – Waits until element appears in DOM
- **`waitForFunction(pageFunction, options)`** – Polls until JavaScript function returns truthy

**Event-based waiting:**
- **`waitForURL(urlOrPredicate, options)`** – Waits for navigation matching pattern
- **`waitForRequest(urlOrPredicate, options)`** – Waits for outgoing HTTP request
- **`waitForResponse(urlOrPredicate, options)`** – Waits for HTTP response
- **`waitForEvent(eventName, options)`** – Generic event listener waiting

## Evaluation and User Interaction

The facade supports arbitrary JavaScript execution within the page context and provides low-level input device simulation.

**Script evaluation:**
**`evaluate(pageFunction, arg?)`** executes arbitrary JavaScript in the page context and returns serializable results, enabling extraction of JavaScript variables or execution of page-side functions.

**Keyboard input:**
The **`keyboard`** property exposes:
- **`press(key)`** – Single key press
- **`down(key)`** / **`up(key)`** – Individual key state
- **`insertText(text)`** – Direct text insertion
- **`type(text)`** – Simulated typing with delays

**Mouse control:**
The **`mouse`** property provides:
- **`click(x, y)`** / **`dblclick(x, y)`** – Pointer activation
- **`move(x, y)`** – Cursor repositioning
- **`down()`** / **`up()`** – Button state toggling
- **`wheel(deltaX, deltaY)`** – Scroll simulation
- **`drag(x, y)`** – Drag-and-drop operations

```javascript
await page.keyboard.type('Hello, world!');
await page.mouse.click(400, 300);

const token = await page.evaluate(() => localStorage.getItem('authToken'));

```

## Screenshots and Video Recording

The facade supports visual debugging and documentation through static and dynamic capture methods.

**Static captures:**
**`screenshot(options)`** generates PNG images of the current viewport or specific elements, accepting standard Playwright screenshot options including `path`, `fullPage`, and `clip`.

**Screencasting:**
The **`screencast`** namespace provides video recording capabilities:
- **`screencast.start(options)`** – Begins recording to specified path with configurable dimensions
- **`screencast.stop()`** – Finalizes and saves the video file

```javascript
await page.screenshot({ path: 'screen.png' });
await page.screencast.start({ path: 'record.webm', size: { width: 1280, height: 720 } });
// ... automated interactions ...
await page.screencast.stop();

```

## Observation and Debugging Utilities

The facade includes introspection methods for debugging automation scripts. **`snapshot()`** returns a serialized representation of the page DOM structure, while **`snapshotRaw()`** provides the unprocessed HTML. **`elementCenter(selector)`** calculates the geometric center of an element for precise clicking, and **`drainEvents()`** clears the internal event queue to prevent stale event processing.

## Summary

- The `page` facade is constructed by `createPageFacade()` in **[`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)** and documented in the `FACADE_HELP` map (lines 84–110).
- It exposes Playwright-compatible methods for navigation (`goto`, `reload`), element location (`getByText`, `getByRole`), and waiting (`waitForSelector`, `waitForFunction`).
- Input simulation is available through the `keyboard` and `mouse` properties, supporting complex user interactions.
- Visual capture capabilities include `screenshot()` for images and the `screencast` object for video recording.
- Selector resolution logic is implemented in **[`src/element-resolver.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/element-resolver.ts)**, with behavioral tests in **`src/helpers.test.mjs`**.

## Frequently Asked Questions

### How is the `page` facade created in ego-lite?

The facade is instantiated by the `createPageFacade()` factory function exported from [`package/ego-browser/src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/helpers.ts). This function accepts a Playwright `Page` instance and wraps its methods with serialization logic suitable for ego-lite's isolated execution environment, returning a proxy object that matches the Playwright API surface.

### What file contains the selector resolution logic for the `page` facade?

Selector parsing and resolution logic resides in **[`src/element-resolver.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/element-resolver.ts)**. This module handles the transformation of CSS selectors and text-based queries into element handles that the facade can interact with, supporting the various `getBy*` locator methods.

### Does the `page` facade support video recording of automation sessions?

Yes. The facade exposes `screencast.start(options)` and `screencast.stop()` methods under the `page.screencast` namespace. These methods initiate and terminate WebM video recording to a specified file path, with configurable dimensions passed through the options parameter.

### How does the `page` facade handle multiple matching elements?

The facade follows Playwright's strict mode conventions: if a selector matches multiple elements, the operation throws a descriptive error unless explicitly narrowed. Users can chain `.first()`, `.last()`, or `.nth(index)` methods on locator objects to select specific instances from a set of matches.