Enum TabBackend 

pub enum TabBackend {
    Cdp(Arc<CdpClient>),
    Bidi(Arc<BidiClient>),
}

Engine-agnostic tab operations. Two variants because CDP and BiDi have different protocols and clients; the methods abstract over the difference.

Variants

Cdp(Arc<CdpClient>)

Bidi(Arc<BidiClient>)

Implementations

impl TabBackend

pub async fn shutdown(&self)

Release the engine session before the client goes away. Firefox does not end a BiDi session when its WebSocket closes, so a backend that is dropped without session.end leaves the browser refusing every later session.new (“Maximum number of active sessions”). CDP has nothing to release. Best-effort and idempotent.

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

Create a fresh top-level tab. Returns the engine-specific id (CDP targetId, BiDi context) the registry stores verbatim. url defaults to about:blank.

pub async fn close_tab(&self, target_id: &str) -> Result<()>

Close a tab by id. Best-effort — both CDP and BiDi handle a missing id gracefully, and the caller’s intent (“this tab is gone”) is satisfied either way.

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

Navigate an existing tab to url. CDP requires attaching a transient session; BiDi takes the context id directly.

pub async fn show_tab(&self, target_id: &str) -> Result<()>

Make a tab visible and focused inside the browser window. This is intentionally explicit: normal automation creates/navigates tabs in the background so agents don’t steal the user’s foreground app unless they need interactive debugging or login.

pub async fn target_for_show(&self) -> Result<String>

Return a tab suitable for show: prefer an existing live tab, create about:blank if the browser currently has none.

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

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

The age is measured from the document’s performance.timeOrigin. Non-web pages such as about:blank are left untouched.

pub async fn live_target_ids(&self) -> Result<HashSet<String>>

Snapshot of every live top-level tab id in the browser. Used by the registry’s sweep-on-read to drop rows whose target no longer exists.

pub async fn live_targets(&self) -> Result<Vec<LiveTarget>>

Snapshot of every live top-level tab with id + URL + title. Used by tab list --all to merge the named-tab registry with the browser’s view of the world. CDP filters to type == "page"; BiDi returns every top-level browsing context.

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

Resolve a target whose document origin matches url’s origin, reusing a live tab already on that origin if one exists and creating one rooted at the origin otherwise. Returns the engine-specific id.

This is the routing primitive for browser_fetch: running the in-page fetch from a same-origin document is what lets cookies and credentials propagate and lets the response bypass CORS. Routing a fetch through an about:blank scratch tab (this backend’s default active tab) gives it an opaque origin, which silently breaks authenticated and CORS-sensitive requests — see cli::fetch’s origin-bound path for the same contract.

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

Evaluate expression in target_id’s main world, returning the raw result value (after returnByValue). Bounded by timeout; expiry returns typed SessionError::TabHung.

CDP path attaches a transient session, calls Runtime.evaluate, detaches. BiDi path calls script.evaluate against the context. On BiDi, await_promise is ignored — BiDi always awaits per script.evaluate semantics.

pub async fn screenshot( &self, target_id: &str, opts: &ScreenshotOptions, ) -> Result<String>

Capture a screenshot of target_id and return base64-encoded bytes.

CDP path attaches a transient session, calls Page.captureScreenshot, detaches. BiDi path calls browsingContext.captureScreenshot — the BiDi protocol always captures the viewport (no full_page equivalent) and has no downscale, so full_page and max_width are honoured only on CDP.

When opts.clip is Some({x, y, width, height}) (document coordinates, as produced by crate::dom::scripts::GET_CLIP_RECT_JS) the capture is restricted to that rectangle, which takes precedence over full_page. opts.max_width downscales through clip.scale, which needs no emulation override and no restore step.

pub async fn accessibility_tree( &self, target_id: &str, depth: Option<u32>, timeout: Duration, ) -> Result<Value>

Full accessibility tree (Accessibility.getFullAXTree). depth bounds the tree the browser serialises; None means everything.

pub async fn document_token( &self, target_id: &str, timeout: Duration, ) -> Result<u64>

Identity of the current document (see crate::session::input::document_token).

pub async fn click_node( &self, target_id: &str, backend_node_id: u64, timeout: Duration, ) -> Result<Point>

Click the element with backend_node_id. Returns the viewport point that was clicked.

pub fn ids_are_session_scoped(&self) -> bool

Whether this engine’s target ids are scoped to the connection.

Firefox mints fresh browsing-context ids for every BiDi session, so an id stored by one process means nothing to the next. CDP target ids live as long as the tab.

pub async fn release(&self)

End the BiDi session, if this is one.

BiDi permits one session per browser, so a backend opened and left without ending its session makes the browser refuse every later connection with “Maximum number of active sessions” — which is exactly what a short-lived CLI command does unless it calls this. The socket itself needs no attention: the process exits.

A no-op on CDP, which is happy with many concurrent clients.

pub async fn type_into_focused( &self, target_id: &str, text: &str, press_sequentially: bool, submit: bool, timeout: Duration, ) -> Result<()>

Type into whatever currently has focus.

Addresses no node, so it works from a separate process that has no access to the MCP server’s ref table — which is what lets a shell pipeline deliver a secret straight into a field.

pub async fn press_key_on_tab( &self, target_id: &str, chord: &Chord, timeout: Duration, ) -> Result<()>

Press a key, with any modifiers held around it.

Keyboard input goes to whatever currently has focus, so unlike the other native actions this addresses no node.

pub async fn hover_node( &self, target_id: &str, backend_node_id: u64, timeout: Duration, ) -> Result<Point>

Hover the element with backend_node_id.

pub async fn type_into_node( &self, target_id: &str, backend_node_id: u64, text: &str, press_sequentially: bool, submit: bool, timeout: Duration, ) -> Result<()>

Replace the element’s content with text (see crate::session::input::type_text).

pub async fn drag_nodes( &self, target_id: &str, from: u64, to: u64, timeout: Duration, ) -> Result<()>

Pointer drag from one element to another.

pub async fn node_clip_rect( &self, target_id: &str, backend_node_id: u64, timeout: Duration, ) -> Result<Value>

Border box of the element in document coordinates, for clipped screenshots.

Trait Implementations

impl Clone for TabBackend

fn clone(&self) -> TabBackend

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.