# How to Navigate to a URL Using the ego-browser Page Facade

> Learn to navigate to a URL using the ego-browser page facade with the page.goto method. This guide explains how to send CDP Page navigate commands and handle load events efficiently.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: how-to-guide
- Published: 2026-08-21

---

**To navigate to a URL in ego-browser, call `await page.goto(url, options)` on the page facade, which sends a CDP `Page.navigate` command and waits for the load event by default.**

The `ego-browser` library (from the `citrolabs/ego-lite` repository) provides a Playwright-style **page facade** that simplifies browser automation. This facade exposes navigation controls through a clean API while internally managing Chrome DevTools Protocol (CDP) commands. Understanding how to invoke URL navigation requires examining the relationship between the public facade in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) and the underlying driver implementation in [`src/driver/nav.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/nav.ts).

## Understanding the Page Facade Structure

The page facade that agents import is constructed by the `createPageFacade` function in **src/helpers.ts**. This factory function wires the public `goto` method directly to the navigation implementation defined in the driver layer:

```typescript
// src/helpers.ts – page facade definition
goto: nav.goto,

```

As shown in lines 94-96 of [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts), the facade acts as a thin proxy. When your agent script calls `page.goto()`, it invokes the actual navigation logic located in **src/driver/nav.ts**. This separation keeps the public API stable while allowing the driver implementation to handle complex CDP interactions.

## How the goto Method Works Internally

The navigation implementation follows a three-step execution flow when `page.goto(url, options)` is invoked:

### Sending the CDP Command

First, the method transmits the navigation instruction to the browser using the `cdp` wrapper function:

```typescript
// src/driver/nav.ts (lines 60-62)
await cdp("Page.navigate", { url, frameId, ... });

```

This command initiates the browser tab's navigation to the specified URL.

### Waiting for Document Load

Unless configured otherwise, the method waits for the page to finish loading. The waiting logic resides in `waitForDocumentLoad` from **src/driver/load.ts**:

```typescript
// src/driver/nav.ts (lines 63-71)
if (options.waitUntil !== "commit") {
  loaded = await waitForDocumentLoad(cdp, options.waitUntil);
}

```

By default, `waitUntil` is set to `"load"`, meaning the promise resolves only after the window load event fires. Setting `waitUntil: "commit"` skips this wait and returns immediately after the navigation command is acknowledged.

### Optional Settle Period

Finally, the method optionally pauses for an extra "settle" period to ensure network activity stabilizes:

```typescript
// src/driver/nav.ts (lines 72-75)
if (options.settle > 0) {
  await state.sleep(options.settle);
}

```

This delay occurs after the document load event and before the function returns control to your script.

## Practical Code Examples

The following examples demonstrate how to navigate using the ego-browser page facade with different configurations:

### Basic Navigation

```javascript
// Default behavior: waits for load event, 20s timeout
await page.goto('https://example.com');
console.log('Current URL:', await page.url());

```

### Fast Navigation Without Loading

```javascript
// Skip load wait, return immediately after navigation command
await page.goto('https://example.com', { waitUntil: 'commit' });
console.log('Navigation command sent.');

```

### Custom Timeout and Settle Delay

```javascript
// 30s total timeout with 0.5s settle time after load
await page.goto('https://example.com', {
  timeout: 30000,
  settle: 500,
});

```

All examples invoke the same underlying implementation in [`src/driver/nav.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/nav.ts), sharing identical error handling for invalid URLs or navigation failures provided by the CDP wrapper.

## Configuration Options and Return Values

The `goto` method accepts an options object that controls timing and load states:

- **`timeout`**: Maximum milliseconds to wait for navigation and loading (default: **20000** ms or 20 seconds)
- **`waitUntil`**: Load state to wait for; accepts `"load"` (default), `"domcontentloaded"`, or `"commit"`
- **`settle`**: Additional milliseconds to sleep after the load event resolves (default: 0)

The method returns an object containing two properties:

```typescript
{
  navigation: /* Raw CDP response from Page.navigate */,
  loaded: boolean /* True if document finish-load was observed */
}

```

## Error Handling Behavior

Navigation failures (invalid URLs, network errors, or CDP command rejections) propagate through the `cdp` wrapper defined in **src/cdp-eval.ts**. The `goto` method does not suppress these errors; instead, it allows them to bubble up to your agent script. This design ensures that navigation failures halt execution unless explicitly caught, preventing agents from interacting with incomplete or failed page loads.

## Summary

- The **page facade** in [`src/helpers.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/helpers.ts) exposes `goto` as `nav.goto`, providing a Playwright-style API for agents.
- The implementation in [`src/driver/nav.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/nav.ts) sends CDP `Page.navigate` commands and manages load state via `waitForDocumentLoad` from [`src/driver/load.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/load.ts).
- Default behavior waits for the window load event with a 20-second timeout, but `waitUntil: "commit"` allows immediate return.
- The method returns `{ navigation, loaded }` to indicate both the CDP response and whether the document fully loaded.

## Frequently Asked Questions

### What is the default timeout for page.goto in ego-browser?

The default timeout is **20 seconds** (20000 ms). This value is managed through the global `state` object defined in **src/state.ts**, which provides timing controls for all driver operations. You can override this by passing a `timeout` option in milliseconds to any `goto` call.

### How do I skip waiting for the page to fully load?

Pass `{ waitUntil: "commit" }` as the options argument. This configuration causes `goto` to return immediately after issuing the CDP `Page.navigate` command (lines 63-71 in [`src/driver/nav.ts`](https://github.com/citrolabs/ego-lite/blob/main/src/driver/nav.ts)), without waiting for `waitForDocumentLoad` to resolve. Use this when you need to send navigation commands rapidly without blocking on resource loading.

### Where is the goto method implemented in the source code?

The business logic resides in **src/driver/nav.ts**, specifically in the exported `goto` function (starting around line 60). However, the public API surface exposed to agent scripts is defined in **src/helpers.ts** within the `createPageFacade` function, where `goto` is mapped to `nav.goto` (lines 94-96).

### What does the goto method return?

The method returns an object with two properties: `navigation` (containing the raw CDP response from the `Page.navigate` command) and `loaded` (a boolean indicating whether the document finish-load event was observed). The `loaded` property will be `false` if you use `waitUntil: "commit"` or if the load event times out.