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

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 and the underlying driver implementation in 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:

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

As shown in lines 94-96 of 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:

// 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:

// 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:

// 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

// 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

// 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

// 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, 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:

{
  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 exposes goto as nav.goto, providing a Playwright-style API for agents.
• The implementation in src/driver/nav.ts sends CDP Page.navigate commands and manages load state via waitForDocumentLoad from 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), 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.

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