# What Is the Site Facade in ego-lite? Purpose, API, and Implementation

> Discover the site facade in ego-lite. This abstraction layer unifies website interactions, simplifying navigation, element resolution, and action execution for automation agents.

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

---

**The site facade in ego-lite is an abstraction layer that normalizes how automation agents interact with any website by wrapping site-specific configurations into a unified API for navigation, element resolution, and action execution.**

In the `citrolabs/ego-lite` repository, the **site facade** serves as the critical bridge between the core browser-automation runtime and site-specific "learnings." By decoupling site-specific knowledge from the underlying automation logic, this facade enables the platform to support new websites simply by adding learning packages—bundles of selectors, tools, and validation rules—without modifying the core runtime.

## Core Responsibilities of the Site Facade

The facade operates as a normalization layer that presents every website as if it exposes an identical set of high-level operations. Its architecture handles five primary responsibilities.

### Uniform API for Cross-Site Automation

Regardless of underlying page structure, the facade exposes consistent helper functions to agent scripts. These include `click`, `type`, `waitFor`, and `snapshot`, along with site-specific tool execution via `runSiteTool`. This standardization means that automation scripts written for one site work identically on any other site with an installed learning.

### Locator Translation and Resolution

Site-specific locator shortcuts—such as `loc=css:` or `loc=role:`—are converted into concrete Chrome DevTools Protocol (CDP) queries or DOM/A11Y queries. According to the source code in [`src/element-resolver.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/element-resolver.ts), this translation layer resolves abstract selectors into concrete element references before any interaction occurs.

### Error Classification and Retry Logic

The facade classifies resolution failures as either **transient** (retryable) or **permanent** (hard errors). As implemented in [`src/element-resolver.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/element-resolver.ts), this classification enables the engine’s retry loops to operate reliably across different sites, distinguishing between network timing issues and invalid selectors.

### Session Management and Stability

Before executing any operation, the facade validates that a valid CDP session is attached. If a session is lost—due to page navigation or browser disconnection—the facade automatically re-attaches or re-snapshots the page state, ensuring continuity without manual intervention.

### Learning Validation and Safety

When a site learning loads, the facade validates its manifest and available tools in `src/learning/*`. This verification guarantees that only well-formed, stable selectors are used in production, preventing malformed learning packages from crashing automation runs.

## How the Site Facade Decouples Site Logic from Runtime

By wrapping site-specific learnings, the facade isolates the core runtime from the complexity of individual website implementations. The runtime interacts only with the facade's standardized interface, while the facade handles the translation to site-specific commands. This separation allows developers to add support for new domains by creating learning packages in `src/learning/*` rather than modifying core browser drivers in `src/driver/*`.

## Working with the Site Facade API

The facade injects helper functions directly into agent scripts, enabling concise, portable automation code.

Click a button using semantic role locators:

```javascript
await click('loc=role:button[name="Submit"]');

```

Wait for dynamic content with configurable timeouts:

```javascript
await waitFor('loc=css:#results', { timeout: 10 });

```

Capture the current page state for debugging or validation:

```javascript
const snapshot = await observe.snapshot();

```

Execute site-specific tools exposed by the learning package:

```javascript
await runSiteTool('login', { username: 'alice', password: '••••' });

```

These helpers are defined in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts), which builds the execution context that the facade injects into every script.

## Key Implementation Files

The site facade functionality spans several critical source directories:

- **[`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts)** – Constructs the helper context injected into agent scripts, providing the unified `click`, `type`, and `waitFor` functions.
- **[`src/element-resolver.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/element-resolver.ts)** – Implements locator translation logic and error classification algorithms that determine retry eligibility.
- **`src/driver/*`** – Contains low-level CDP drivers for navigation, pointer events, and keyboard input that the facade orchestrates.
- **`src/learning/*`** – Handles discovery, validation, and execution of site-specific learnings that the facade wraps and exposes.

## Summary

- The **site facade** normalizes interactions between automation agents and diverse websites in ego-lite.
- It provides a **uniform API** (`click`, `waitFor`, `snapshot`) regardless of underlying page structure.
- **Locator translation** converts site-specific shortcuts like `loc=css:` into concrete CDP or DOM queries via [`src/element-resolver.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/element-resolver.ts).
- **Error classification** distinguishes transient failures from permanent errors, enabling intelligent retry logic.
- **Session management** automatically re-attaches lost CDP sessions to maintain automation stability.
- The architecture decouples site-specific logic from the core runtime, allowing new sites to be supported solely through learning packages in `src/learning/*`.

## Frequently Asked Questions

### What is the primary purpose of the site facade in ego-lite?

The site facade serves as an abstraction layer that allows the core automation runtime to treat every website identically. It wraps site-specific "learnings"—containing selectors, tools, and validation rules—and exposes them through a standardized API, eliminating the need to modify core code when adding support for new sites.

### How does the site facade handle different locator strategies?

The facade accepts abstract locator shortcuts such as `loc=css:` or `loc=role:` and translates them into concrete queries. According to [`src/element-resolver.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/element-resolver.ts), this translation supports both CDP-based queries and standard DOM/A11Y lookups, enabling flexible element resolution across different page architectures.

### What happens when a CDP session is lost during execution?

The facade includes session management logic that detects disconnected Chrome DevTools Protocol sessions. When a session is lost—typically during navigation or browser events—the facade automatically re-attaches to the target or re-snapshots the page state, ensuring that subsequent operations proceed without manual session restoration.

### Where is the site facade implemented in the codebase?

The facade's functionality is distributed across [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) (API construction), [`src/element-resolver.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/element-resolver.ts) (locator translation and error handling), `src/driver/*` (low-level CDP automation drivers), and `src/learning/*` (site-specific learning validation and execution).