Enum PageSession 

pub enum PageSession {
    Cdp(CdpPage),
    Bidi(BidiPage),
}

A bound page-level session. Variants are not constructed directly outside this module; use PageSession::attach.

Variants

Cdp(CdpPage)

Bidi(BidiPage)

A BiDi page session. The client is shared via Arc so the MCP server can keep a single persistent BiDi session across many tool calls (Firefox limits a browser to one BiDi session at a time).

Implementations

impl PageSession

pub async fn attach( endpoint: &str, engine: Engine, url_regex: Option<&str>, ) -> Result<Self>

Attach to a fresh page session over engine.

If url_regex is Some, the first page target whose URL matches is selected; otherwise the first page (or top-level browsing context) is used.

pub async fn from_bidi_cache( client: Arc<BidiClient>, url_regex: Option<&str>, ) -> Result<Self>

Build a BiDi session from a pre-opened, possibly cached client.

The MCP server uses this to share one BiDi client across tool calls; session.new is invoked only when the client was freshly opened (the caller is expected to have done so).

pub async fn attach_for_origin( endpoint: &str, engine: Engine, origin: &str, ) -> Result<Self>

Attach to (or create) a page whose document origin matches origin.

Strategy:

1. List existing page targets / browsing contexts.
2. If any has the same origin as origin, attach to it.
3. Otherwise create a new tab navigated to the origin’s root and attach to that tab.

origin is parsed for its scheme, host, and port; path/query/fragment are ignored when comparing existing target URLs.

pub async fn evaluate( &self, expression: &str, await_promise: bool, ) -> Result<Value>

Evaluate expression in the page’s main world.

await_promise = true mirrors Runtime.evaluate({awaitPromise:true}) and is appropriate for fetch / promise-returning code. The returned value is the raw result.value from CDP / BiDi after returnByValue.

Equivalent to evaluate_with_timeout with timeout = None (bounded only by the upstream client’s protocol timeout, currently 30 s). Prefer the bounded form in any path where the renderer’s responsiveness is uncertain — see the module docs.

pub async fn evaluate_with_timeout( &self, expression: &str, await_promise: bool, timeout: Option<Duration>, ) -> Result<Value>

Bounded variant of evaluate.

If timeout is Some, the call races the upstream send against a tokio::time::sleep. On expiry, returns a typed SessionError::TabHung tagged with the target’s id and URL — this is the catch-all for the alive-but-unresponsive renderer case that has no protocol event signal (service-worker-paused page, JS infinite loop, modal dialog, devtools-paused, embedded admin UIs whose renderer ignores Runtime.evaluate).

On the CDP arm, the in-flight Runtime.evaluate is additionally raced against the renderer-crash events (Target.targetCrashed / Inspector.targetCrashed) for this target/session — a matching event short-circuits the call with a typed SessionError::TabCrashed instead of waiting for the timeout. BiDi has no equivalent protocol event; a context crash surfaces as no such frame/context on the next request and is classified as TargetGone by the client layer.

If timeout is None, the call is bounded only by the underlying client’s protocol timeout (CDP: 30 s, BiDi: 30 s).

pub fn target_id(&self) -> Option<String>

Engine-specific target id for diagnostics (CDP targetId, BiDi browsing context id).

pub async fn navigate(&self, url: &str) -> Result<()>

Navigate the current page to url.

pub async fn ensure_fresh(&self, max_age: Duration) -> Result<()>

Reload an old HTTP(S) page before reading auth-sensitive page state.

The age is measured from the document’s performance.timeOrigin. about:blank, chrome://, devtools://, and other non-web pages are left untouched.

pub async fn screenshot(&self, full_page: bool) -> Result<String>

Capture a PNG screenshot of the current page; returns base64 data.

pub fn engine(&self) -> Engine

Engine this session is bound to.

pub async fn close(self)

Release the underlying connection. For BiDi sessions that this PageSession opened, also calls session.end so that Firefox (which enforces one BiDi session per browser) accepts a fresh session.new on the next invocation.