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

The page facade in citrolabs/ego-lite exposes a Playwright-style API through createPageFacade() in 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, 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. 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, 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.

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

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

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 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, 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. 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. 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.

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