ferridriver 0.3.0

#![allow(clippy::missing_errors_doc)]
//! Backend abstraction layer for browser automation.
//!
//! Provides a unified API across multiple browser backends:
//! - `CdpPipe`: Chrome `DevTools` Protocol over pipes (--remote-debugging-pipe, fd 3/4)
//! - `CdpRaw`: Chrome `DevTools` Protocol over WebSocket (our own, fully parallel)
//! - `WebKit`: Native `WKWebView` on macOS (subprocess model)
//!
//! Uses enum dispatch (not trait objects) for zero-cost abstraction and Clone support.

pub(crate) mod async_tempdir;
pub mod cdp;
pub(crate) mod json_scan;
pub(crate) mod process;
pub mod webkit;

pub mod bidi;

/// Empty JSON object `{}` — avoids `serde_json::json!({})` heap allocation per call.
#[inline]
pub(crate) fn empty_params() -> serde_json::Value {
  serde_json::Value::Object(serde_json::Map::new())
}

use crate::console_message::ConsoleMessage;
use crate::error::Result;
use crate::events::EventEmitter;
use crate::network::Request as NetworkRequest;
use std::sync::Arc;
use tokio::sync::RwLock;

/// Mutable weak back-reference to the outer `Arc<Page>`. Every backend
/// page struct carries one of these so async event listeners
/// (file-chooser, future per-frame probes) can upgrade the weak on
/// demand and build `ElementHandle`s without threading the page
/// through the backend.
///
/// Why `Mutex<Weak<Page>>` and not `OnceLock<Weak<Page>>`: callers
/// like the MCP server construct a fresh `Arc<Page>` on every tool
/// invocation and drop it when the tool returns. A one-shot slot
/// would lock in the first `Arc<Page>`'s weak — whose target dies as
/// soon as that tool call completes, leaving every subsequent event
/// unable to resolve. The mutex lets successive `Page::new` calls
/// overwrite the slot with a weak that tracks the currently-live
/// outer page.
#[derive(Clone, Default)]
pub struct PageBackref {
  inner: Arc<std::sync::Mutex<std::sync::Weak<crate::page::Page>>>,
}

impl PageBackref {
  #[must_use]
  pub fn new() -> Self {
    Self::default()
  }

  /// Set the stored weak reference. Called by `Page::new` /
  /// `Page::with_context` on every construction.
  ///
  /// **Always overwrites.** Earlier behaviour was "skip overwrite if
  /// the existing weak still upgrades" to protect against transient
  /// `Page` wrappers (`ContextRef::pages()`, `frame.page()`) clobbering
  /// a long-lived persistent wrapper. In the MCP / script-engine path
  /// there IS no persistent outer `Page` -- every script call mints a
  /// new wrapper via `page_and_context` and drops it when the
  /// `RunContext` drops. With skip-on-upgrade, the very first transient
  /// wrapper "won" and stayed pinned in `page_backref`; once GC reaped
  /// its JS heap reference, the weak dangled while the listener thread
  /// kept silently dropping every console / file-chooser / dialog event
  /// for the rest of the session (reproduced via
  /// `test_file_chooser_multiple_string_array` running after
  /// `test_file_chooser_single_string_path`). Last-writer-wins matches
  /// the actual lifetime story: the wrapper most recently registered is
  /// the one the current call is using.
  pub fn set(&self, weak: std::sync::Weak<crate::page::Page>) {
    if let Ok(mut guard) = self.inner.lock() {
      *guard = weak;
    }
  }

  /// Upgrade to an `Arc<Page>` if the outer page is still alive.
  /// Backend listeners call this per event and silently skip events
  /// that arrive when no outer page wraps this backend page.
  #[must_use]
  pub fn upgrade(&self) -> Option<Arc<crate::page::Page>> {
    self.inner.lock().ok()?.upgrade()
  }
}

// ─── Backend-agnostic types ─────────────────────────────────────────────────

/// Frame metadata (backend-agnostic).
#[derive(Debug, Clone, serde::Serialize)]
pub struct FrameInfo {
  pub frame_id: String,
  pub parent_frame_id: Option<String>,
  pub name: String,
  pub url: String,
}

/// Accessibility tree node (backend-agnostic).
#[derive(Debug, Clone)]
pub struct AxNodeData {
  pub node_id: String,
  pub parent_id: Option<String>,
  pub backend_dom_node_id: Option<i64>,
  pub ignored: bool,
  pub role: Option<String>,
  pub name: Option<String>,
  pub description: Option<String>,
  pub properties: Vec<AxProperty>,
}

#[derive(Debug, Clone)]
pub struct AxProperty {
  pub name: String,
  pub value: Option<serde_json::Value>,
}

/// Cookie `SameSite` attribute (matches Playwright's `Strict | Lax | None`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum SameSite {
  Strict,
  Lax,
  None,
}

impl SameSite {
  /// Convert to a CDP/WebKit string.
  #[must_use]
  pub fn as_str(self) -> &'static str {
    match self {
      Self::Strict => "Strict",
      Self::Lax => "Lax",
      Self::None => "None",
    }
  }
}

impl std::str::FromStr for SameSite {
  type Err = ();

  fn from_str(s: &str) -> std::result::Result<Self, Self::Err> {
    match s {
      "Strict" => Ok(Self::Strict),
      "Lax" => Ok(Self::Lax),
      "None" => Ok(Self::None),
      _ => Err(()),
    }
  }
}

/// Cookie data (backend-agnostic, matches Playwright's `NetworkCookie`).
///
/// Wire format is camelCase (`httpOnly`, `sameSite`) to match Playwright /
/// CDP / Web Cookies RFC; Rust field names stay `snake_case` per convention.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct CookieData {
  pub name: String,
  pub value: String,
  pub domain: String,
  pub path: String,
  pub secure: bool,
  pub http_only: bool,
  pub expires: Option<f64>,
  /// `SameSite` attribute (`Strict`, `Lax`, or `None`).
  #[serde(default, skip_serializing_if = "Option::is_none")]
  pub same_site: Option<SameSite>,
  /// Playwright `SetNetworkCookieParam.url`: when set, the backend
  /// derives domain/path from it (CDP `Network.setCookie` accepts
  /// `url`; `BiDi`/`WebKit` have no `url`, so the host/path is parsed
  /// from it). Never populated on cookies READ back from the browser.
  #[serde(default, skip_serializing_if = "Option::is_none")]
  pub url: Option<String>,
}

/// Options for setting a cookie (matches Playwright's `SetNetworkCookieParam`).
/// Use `url` to derive domain/path automatically, or set `domain`/`path` directly.
#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct SetCookieParams {
  pub name: String,
  pub value: String,
  /// URL to derive domain/path from. Mutually exclusive with domain/path.
  #[serde(default, skip_serializing_if = "Option::is_none")]
  pub url: Option<String>,
  #[serde(default)]
  pub domain: String,
  #[serde(default)]
  pub path: String,
  #[serde(default)]
  pub secure: bool,
  #[serde(default)]
  pub http_only: bool,
  #[serde(default, skip_serializing_if = "Option::is_none")]
  pub expires: Option<f64>,
  #[serde(default, skip_serializing_if = "Option::is_none")]
  pub same_site: Option<SameSite>,
}

impl From<SetCookieParams> for CookieData {
  fn from(p: SetCookieParams) -> Self {
    Self {
      name: p.name,
      value: p.value,
      domain: p.domain,
      path: if p.path.is_empty() { "/".to_string() } else { p.path },
      secure: p.secure,
      http_only: p.http_only,
      expires: p.expires,
      same_site: p.same_site,
      url: p.url,
    }
  }
}

/// Options for clearing cookies (matches Playwright's `ClearNetworkCookieOptions`).
/// All fields are optional filters -- only cookies matching ALL specified filters are cleared.
/// If no filters are specified, all cookies are cleared.
#[derive(Debug, Clone, Default)]
pub struct ClearCookieOptions {
  /// Filter by cookie name (exact match).
  pub name: Option<String>,
  /// Filter by domain (exact match).
  pub domain: Option<String>,
  /// Filter by path (exact match).
  pub path: Option<String>,
}

/// Backend-level screenshot options — the flat, Playwright-independent
/// wire struct each backend consumes. `crate::options::ScreenshotOptions`
/// (the user-facing Playwright-shaped bag) is lowered into this by
/// [`crate::page::Page::screenshot`], which also handles the Rust-side
/// concerns (`path` write-to-disk, `timeout` race) that don't belong in
/// the per-backend dispatch path.
#[derive(Debug, Clone)]
pub struct ScreenshotOpts {
  pub format: ImageFormat,
  pub quality: Option<i64>,
  pub full_page: bool,
  /// Pixel rectangle relative to the viewport (or full-page bounds
  /// when `full_page` is true). `None` captures the whole viewport /
  /// full page.
  pub clip: Option<crate::options::ClipRect>,
  /// When `true`, emit a PNG with transparent pixels where the page
  /// doesn't have its own background. Ignored for JPEG (no alpha).
  pub omit_background: bool,
  /// `"css"` → one image pixel per CSS pixel (smaller, stable across
  /// DPR); `"device"` → one image pixel per device pixel (default,
  /// Retina captures are 2× bigger). `None` = Playwright default.
  pub scale: Option<ScreenshotScale>,
  /// `"disabled"` pauses CSS animations and Web Animations during
  /// capture; finite animations fast-forward to completion, infinite
  /// ones revert to their initial state. `"allow"` leaves them
  /// running. `None` = Playwright default (`"allow"`).
  pub animations: Option<ScreenshotAnimations>,
  /// `"hide"` (Playwright default) hides the text caret; `"initial"`
  /// leaves it visible. `None` = Playwright default.
  pub caret: Option<ScreenshotCaret>,
  /// Selectors whose matches are overlaid with [`Self::mask_color`]
  /// before capture. Backends resolve each against the target and
  /// paint a fixed-position div at each element's bounding rect.
  pub mask: Vec<String>,
  /// CSS color for the mask overlay. Backends default to `#FF00FF`
  /// (Playwright's pink) when this is `None`.
  pub mask_color: Option<String>,
  /// Raw CSS injected before capture and removed afterwards. Pierces
  /// shadow DOM, applies to subframes.
  pub style: Option<String>,
}

impl Default for ScreenshotOpts {
  fn default() -> Self {
    Self {
      format: ImageFormat::Png,
      quality: None,
      full_page: false,
      clip: None,
      omit_background: false,
      scale: None,
      animations: None,
      caret: None,
      mask: Vec::new(),
      mask_color: None,
      style: None,
    }
  }
}

/// `scale` option for screenshots — mirrors Playwright's `"css" | "device"`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ScreenshotScale {
  /// One image pixel per CSS pixel — small, DPR-independent output.
  Css,
  /// One image pixel per device pixel — sharp, larger on Retina.
  Device,
}

/// `animations` option for screenshots — mirrors Playwright's
/// `"disabled" | "allow"`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ScreenshotAnimations {
  /// Pause animations during capture.
  Disabled,
  /// Leave animations running.
  Allow,
}

/// `caret` option for screenshots — mirrors Playwright's `"hide" | "initial"`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ScreenshotCaret {
  /// Hide the text input caret (Playwright default).
  Hide,
  /// Leave the caret visible in its natural state.
  Initial,
}

/// Backend-agnostic JS helpers for the DOM-side part of `screenshot()`
/// — caret hiding, user-style injection, animation pause via CSS, and
/// mask overlay painting. Each backend wraps its own
/// protocol-specific execution (CDP `Runtime.evaluate`, `BiDi`
/// `script.callFunction`, `WebKit` `evaluate`) around these helpers so
/// all three produce the same observable DOM state before capturing.
pub mod screenshot_js {
  use super::{ScreenshotAnimations, ScreenshotCaret, ScreenshotOpts};

  /// Build the combined CSS rules that `screenshot()` injects before
  /// capture: caret-hide (unless the caller explicitly opted into
  /// `Initial`), optional user `style`, and optional animation pause.
  /// Returns an empty string when no rules apply — the caller should
  /// skip the install/teardown JS entirely in that case.
  #[must_use]
  pub fn build_css(opts: &ScreenshotOpts) -> String {
    let mut css = String::new();
    if !matches!(opts.caret, Some(ScreenshotCaret::Initial)) {
      css.push_str("* { caret-color: transparent !important; }");
    }
    if matches!(opts.animations, Some(ScreenshotAnimations::Disabled)) {
      css.push_str(" *, *::before, *::after { animation-play-state: paused !important; transition: none !important; }");
    }
    if let Some(ref user) = opts.style {
      css.push_str(user);
    }
    css
  }

  /// Build a JS expression that installs a `<style id="__fd_screenshot_style__">`
  /// element carrying the supplied CSS. Paired with [`uninstall_style_js`]
  /// for teardown.
  #[must_use]
  pub fn install_style_js(css: &str) -> String {
    let esc = css.replace('\\', "\\\\").replace('`', "\\`");
    format!(
      r"(function(){{
        const s = document.createElement('style');
        s.id = '__fd_screenshot_style__';
        s.textContent = `{esc}`;
        (document.head || document.documentElement).appendChild(s);
      }})()"
    )
  }

  /// Removes the style element installed by [`install_style_js`].
  #[must_use]
  pub fn uninstall_style_js() -> &'static str {
    "document.getElementById('__fd_screenshot_style__')?.remove()"
  }

  /// Build a JS expression that paints a fixed `<div>` over every
  /// match of each selector in [`ScreenshotOpts::mask`]. Returns
  /// `None` when there are no selectors to mask — caller should skip
  /// the install/teardown JS entirely.
  ///
  /// The overlay divs are tagged with a random class name stored on
  /// `window.__fd_mask_tag` so [`uninstall_mask_js`] can remove them
  /// without relying on the selectors resolving to the same matches
  /// a second time.
  #[must_use]
  pub fn install_mask_js(opts: &ScreenshotOpts) -> Option<String> {
    if opts.mask.is_empty() {
      return None;
    }
    let selectors_json = serde_json::to_string(&opts.mask).unwrap_or_else(|_| "[]".into());
    let color = opts.mask_color.clone().unwrap_or_else(|| "#FF00FF".into());
    let color_json = serde_json::to_string(&color).unwrap_or_else(|_| "\"#FF00FF\"".into());
    Some(format!(
      r"(function(){{
        const selectors = {selectors_json};
        const color = {color_json};
        const tag = '__fd_mask_' + Math.random().toString(36).slice(2);
        window.__fd_mask_tag = tag;
        for (const sel of selectors) {{
          try {{
            const els = document.querySelectorAll(sel);
            for (const el of els) {{
              const r = el.getBoundingClientRect();
              const o = document.createElement('div');
              o.className = tag;
              o.style.cssText = `all: initial; position: fixed; left: ${{r.left}}px; top: ${{r.top}}px; width: ${{r.width}}px; height: ${{r.height}}px; background: ${{color}}; z-index: 2147483647; pointer-events: none;`;
              document.body.appendChild(o);
            }}
          }} catch (e) {{}}
        }}
      }})()"
    ))
  }

  /// Removes the mask overlay divs installed by [`install_mask_js`].
  #[must_use]
  pub fn uninstall_mask_js() -> &'static str {
    "(function(){const t=window.__fd_mask_tag;if(!t)return;document.querySelectorAll('.'+t).forEach(n=>n.remove());delete window.__fd_mask_tag;})()"
  }
}

/// Image format for screenshots.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ImageFormat {
  Png,
  Jpeg,
  Webp,
}

/// Performance metric (backend-agnostic).
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct MetricData {
  pub name: String,
  pub value: f64,
}

/// Backend-ready click arguments. Produced by
/// `BackendClickArgs::from_options` from the user's
/// [`crate::options::ClickOptions`]. Every per-backend `click_at_with`
/// receives this struct — keeps the wire-level per-backend impls free
/// of `ClickOptions` parsing and defaulting logic.
///
/// Modifiers are carried as the raw Playwright enum slice so each
/// backend can compute its own bitmask / key-name / wire format; the
/// CDP bitmask (`u32`) is cached in [`Self::modifiers_bitmask`] so the
/// hot mouse-dispatch paths don't recompute it.
#[derive(Debug, Clone)]
pub struct BackendClickArgs {
  pub button: crate::options::MouseButton,
  pub click_count: u32,
  /// Milliseconds to sleep between `mousedown` and `mouseup`.
  pub delay_ms: u64,
  /// CDP modifier bitmask (cached from [`Self::modifiers`]).
  pub modifiers_bitmask: u32,
  /// Full modifier list (for backends that need key-name strings).
  pub modifiers: Vec<crate::options::Modifier>,
  /// Interpolated `mousemove` events between the current cursor and
  /// `(x, y)`. `1` = single move at destination.
  pub steps: u32,
}

impl BackendClickArgs {
  #[must_use]
  pub fn from_options(opts: &crate::options::ClickOptions) -> Self {
    Self {
      button: opts.resolved_button(),
      click_count: opts.resolved_click_count(),
      delay_ms: opts.resolved_delay_ms(),
      modifiers_bitmask: crate::options::modifiers_bitmask(&opts.modifiers),
      modifiers: opts.modifiers.clone(),
      steps: opts.resolved_steps(),
    }
  }

  /// Convenience factory for the "no options, just click once with left"
  /// default path — wire for existing `click_at` call sites.
  #[must_use]
  pub fn default_left() -> Self {
    Self {
      button: crate::options::MouseButton::Left,
      click_count: 1,
      delay_ms: 0,
      modifiers_bitmask: 0,
      modifiers: Vec::new(),
      steps: 1,
    }
  }
}

/// Backend-ready hover arguments. Produced by
/// [`crate::actions::hover_with_opts`] from the user's
/// [`crate::options::HoverOptions`]. Shape is the subset of
/// [`BackendClickArgs`] a hover needs — modifiers bitmask + `steps`
/// interpolated `mousemove` events.
#[derive(Debug, Clone, Copy)]
pub struct BackendHoverArgs {
  /// CDP modifier bitmask carried on each synthesised mouse event.
  pub modifiers_bitmask: u32,
  /// Interpolated `mousemove` events between the current cursor and
  /// `(x, y)`. `1` = single move at destination.
  pub steps: u32,
}

/// Backend-ready tap arguments. Produced by
/// [`crate::actions::tap_with_opts`] from the user's
/// [`crate::options::TapOptions`]. Only CDP implements this natively
/// via `Input.dispatchTouchEvent`; `BiDi` and `WebKit` return
/// `FerriError::Unsupported` because neither exposes a public touch
/// injection primitive.
#[derive(Debug, Clone, Copy)]
pub struct BackendTapArgs {
  /// CDP modifier bitmask (same scheme as mouse/key events) carried on
  /// the dispatched touch events so `event.shiftKey` etc. are true when
  /// the caller requested them.
  pub modifiers_bitmask: u32,
}

/// Navigation lifecycle target — which CDP event to wait for after Page.navigate.
/// Matches Playwright's `waitUntil` semantics exactly.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NavLifecycle {
  /// `Page.frameNavigated` — response committed, new document started.
  Commit,
  /// `Page.lifecycleEvent` name="`DOMContentLoaded`" — HTML parsed, DOM ready.
  DomContentLoaded,
  /// `Page.lifecycleEvent` name="load" — all resources loaded.
  Load,
}

impl NavLifecycle {
  /// Parse from a `waitUntil` string (Playwright / MCP convention).
  /// Unknown values default to `Load`.
  #[must_use]
  pub fn parse_lifecycle(s: &str) -> Self {
    match s {
      "commit" => Self::Commit,
      "domcontentloaded" => Self::DomContentLoaded,
      _ => Self::Load,
    }
  }
}

/// Which backend to use.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BackendKind {
  /// Chrome `DevTools` Protocol over pipes (--remote-debugging-pipe)
  CdpPipe,
  /// Chrome `DevTools` Protocol over WebSocket (our own, fully parallel)
  CdpRaw,
  /// Playwright `WebKit` Inspector protocol (cross-platform, bundled binary)
  WebKit,
  /// `WebDriver` `BiDi` protocol (cross-browser: Chrome, Firefox, future Safari)
  Bidi,
}

// ─── AnyBrowser ─────────────────────────────────────────────────────────────

/// Browser instance — enum dispatch across backends.
#[derive(Clone)]
pub enum AnyBrowser {
  CdpPipe(cdp::CdpBrowser<cdp::pipe::PipeTransport>),
  CdpRaw(cdp::CdpBrowser<cdp::ws::WsTransport>),
  WebKit(webkit::WebKitBrowser),
  Bidi(bidi::BidiBrowser),
}

impl AnyBrowser {
  /// List all open pages in this browser.
  ///
  /// # Errors
  ///
  /// Returns an error if the backend fails to enumerate targets or pages.
  pub async fn pages(&self) -> Result<Vec<AnyPage>> {
    match self {
      Self::CdpPipe(b) => Box::pin(b.pages()).await,
      Self::CdpRaw(b) => Box::pin(b.pages()).await,
      Self::WebKit(b) => Box::pin(b.pages()).await,
      Self::Bidi(b) => Box::pin(b.pages()).await,
    }
  }

  /// Create a new browser context (isolated cookies, storage, cache).
  ///
  /// `options` carries the full `BrowserContextOptions` bag — most
  /// backends only need `proxy`, but webkit applies `locale` (via
  /// `Playwright.setLanguages`) at context-creation time and stashes
  /// the remainder so per-page settings (userAgent, timezone, JS-disabled)
  /// can be sent during `attach()` BEFORE the about:blank document is
  /// live. Mirrors PW's `WKBrowserContext.initialize` flow.
  ///
  /// # Errors
  ///
  /// Returns an error if context creation fails.
  pub async fn new_context(&self, options: Option<&crate::options::BrowserContextOptions>) -> Result<String> {
    let proxy = options.and_then(|o| o.proxy.as_ref());
    match self {
      Self::CdpPipe(b) => b.new_context(proxy).await,
      Self::CdpRaw(b) => b.new_context(proxy).await,
      Self::WebKit(b) => b.new_context_with_options(options).await,
      Self::Bidi(b) => b.new_context(proxy).await,
    }
  }

  /// Dispose a browser context.
  ///
  /// # Errors
  ///
  /// Returns an error if context disposal fails.
  pub async fn dispose_context(&self, browser_context_id: &str) -> Result<()> {
    match self {
      Self::CdpPipe(b) => b.dispose_context(browser_context_id).await,
      Self::CdpRaw(b) => b.dispose_context(browser_context_id).await,
      Self::WebKit(b) => b.dispose_context(browser_context_id).await,
      Self::Bidi(b) => b.dispose_context(browser_context_id).await,
    }
  }

  /// Open a new page, optionally in a specific browser context.
  ///
  /// # Errors
  ///
  /// Returns an error if the backend fails to create a new target or navigate to the URL.
  pub async fn new_page(
    &self,
    url: &str,
    browser_context_id: Option<&str>,
    viewport: Option<&crate::options::ViewportConfig>,
  ) -> Result<AnyPage> {
    match self {
      Self::CdpPipe(b) => Box::pin(b.new_page(url, browser_context_id, viewport)).await,
      Self::CdpRaw(b) => Box::pin(b.new_page(url, browser_context_id, viewport)).await,
      Self::WebKit(b) => Box::pin(b.new_page(url, browser_context_id, viewport)).await,
      Self::Bidi(b) => Box::pin(b.new_page(url, browser_context_id, viewport)).await,
    }
  }

  /// Close the browser and all its pages.
  ///
  /// # Errors
  ///
  /// Returns an error if the browser process fails to shut down cleanly.
  pub async fn close(&mut self) -> Result<()> {
    match self {
      Self::CdpPipe(b) => b.close().await,
      Self::CdpRaw(b) => b.close().await,
      Self::WebKit(b) => b.close().await,
      Self::Bidi(b) => b.close().await,
    }
  }

  /// Real product version string for the running browser, captured at
  /// handshake/session-open time. Every backend surfaces a genuine value
  /// — no placeholders:
  ///
  /// * `cdp-pipe` / `cdp-raw` → CDP `Browser.getVersion().product`
  ///   (e.g. `"HeadlessChrome/120.0.6099.109"`).
  /// * `webkit` → `Op::GetWebKitVersion` IPC → `CFBundleShortVersionString`
  ///   from the running `WebKit.framework` (e.g. `"WebKit/617.1.2 (17618)"`).
  /// * `bidi` → `BiDi` `session.new` response capabilities, formatted as
  ///   `"{browserName}/{browserVersion}"` (e.g. `"firefox/135.0.1"`).
  #[must_use]
  pub fn version(&self) -> String {
    match self {
      Self::CdpPipe(b) => b.version().to_string(),
      Self::CdpRaw(b) => b.version().to_string(),
      Self::WebKit(b) => b.version(),
      Self::Bidi(b) => b.version(),
    }
  }
}

// ─── AnyPage ────────────────────────────────────────────────────────────────

/// Page handle — enum dispatch across backends. Cheaply cloneable (Arc-based).
#[derive(Clone)]
pub enum AnyPage {
  CdpPipe(cdp::CdpPage<cdp::pipe::PipeTransport>),
  CdpRaw(cdp::CdpPage<cdp::ws::WsTransport>),
  WebKit(webkit::WebKitPage),
  Bidi(bidi::BidiPage),
}

/// Macro to dispatch a method call across all `AnyPage` variants.
macro_rules! page_dispatch {
    ($self:expr, $method:ident ( $($arg:expr),* $(,)? )) => {
        match $self {
            AnyPage::CdpPipe(p) => p.$method($($arg),*).await,
            AnyPage::CdpRaw(p) => p.$method($($arg),*).await,
            AnyPage::WebKit(p) => p.$method($($arg),*).await,
            AnyPage::Bidi(p) => p.$method($($arg),*).await,
        }
    };
}

impl AnyPage {
  // ── Events ──

  /// Get the event emitter for this page.
  #[must_use]
  pub fn events(&self) -> &EventEmitter {
    match self {
      AnyPage::CdpPipe(p) => &p.events,
      AnyPage::CdpRaw(p) => &p.events,
      AnyPage::WebKit(p) => &p.events,

      AnyPage::Bidi(p) => &p.events,
    }
  }

  /// Per-page dialog handler registry. Mirrors Playwright's server-side
  /// `DialogManager`. Register with
  /// [`crate::dialog::DialogManager::add_handler`] to receive live
  /// [`crate::dialog::Dialog`] handles when `alert` / `confirm` /
  /// `prompt` / `beforeunload` fire.
  #[must_use]
  pub fn dialog_manager(&self) -> &crate::dialog::DialogManager {
    match self {
      AnyPage::CdpPipe(p) => &p.dialog_manager,
      AnyPage::CdpRaw(p) => &p.dialog_manager,
      AnyPage::WebKit(p) => &p.dialog_manager,
      AnyPage::Bidi(p) => &p.dialog_manager,
    }
  }

  /// Per-page file-chooser handler registry. Mirrors Playwright's
  /// `FileChooser` dispatch path. Register with
  /// [`crate::file_chooser::FileChooserManager::add_handler`] to
  /// receive live [`crate::file_chooser::FileChooser`] handles when
  /// an `<input type=file>` click (or `showPicker()`) fires.
  #[must_use]
  pub fn file_chooser_manager(&self) -> &crate::file_chooser::FileChooserManager {
    match self {
      AnyPage::CdpPipe(p) => &p.file_chooser_manager,
      AnyPage::CdpRaw(p) => &p.file_chooser_manager,
      AnyPage::WebKit(p) => &p.file_chooser_manager,
      AnyPage::Bidi(p) => &p.file_chooser_manager,
    }
  }

  /// Per-page download handler registry. Mirrors Playwright's
  /// server-side download dispatch path. Register with
  /// [`crate::download::DownloadManager::add_handler`] to receive live
  /// [`crate::download::Download`] handles when the browser starts
  /// writing a file download.
  #[must_use]
  pub fn download_manager(&self) -> &crate::download::DownloadManager {
    match self {
      AnyPage::CdpPipe(p) => &p.download_manager,
      AnyPage::CdpRaw(p) => &p.download_manager,
      AnyPage::WebKit(p) => &p.download_manager,
      AnyPage::Bidi(p) => &p.download_manager,
    }
  }

  /// Idempotently fire the backend command that turns on
  /// file-chooser interception. Lazy parity with Playwright's
  /// `_updateFileChooserInterception` — the page-level listener
  /// loop is already subscribed to events, but the underlying
  /// browser only emits `fileChooserOpened` after we ask it to.
  /// Called from `Page::wait_for_file_chooser` and
  /// `Page::on('filechooser', ...)`.
  pub async fn enable_file_chooser_intercept(&self) -> Result<()> {
    match self {
      AnyPage::CdpPipe(p) => p.enable_file_chooser_intercept().await,
      AnyPage::CdpRaw(p) => p.enable_file_chooser_intercept().await,
      AnyPage::WebKit(p) => p.enable_file_chooser_intercept().await,
      AnyPage::Bidi(_) => Ok(()),
    }
  }

  /// Idempotently fire the backend command that turns on download
  /// reporting. Lazy parity with Playwright's per-context
  /// `Browser.setDownloadBehavior` (`crBrowser.ts:354`). Called from
  /// `Page::wait_for_download` and `Page::on('download', ...)`.
  pub async fn enable_download_behavior(&self) -> Result<()> {
    match self {
      AnyPage::CdpPipe(p) => p.enable_download_behavior().await,
      AnyPage::CdpRaw(p) => p.enable_download_behavior().await,
      AnyPage::WebKit(p) => p.enable_download_behavior().await,
      AnyPage::Bidi(_) => Ok(()),
    }
  }

  /// Populate the weak back-reference to the outer `Arc<Page>`.
  /// Called by [`crate::page::Page::new`] / `Page::with_context`
  /// every time a new `Arc<Page>` is constructed — callers like the
  /// MCP server wrap the same backend page fresh on every tool
  /// invocation, so successive calls must be able to overwrite the
  /// slot. See [`PageBackref`] for the rationale.
  pub fn set_page_backref(&self, weak: std::sync::Weak<crate::page::Page>) {
    let slot = match self {
      AnyPage::CdpPipe(p) => &p.page_backref,
      AnyPage::CdpRaw(p) => &p.page_backref,
      AnyPage::WebKit(p) => &p.page_backref,
      AnyPage::Bidi(p) => &p.page_backref,
    };
    slot.set(weak);
  }

  /// Backend-owned frame cache shared across `Arc<crate::page::Page>`
  /// wrappers. MCP tool handlers construct a fresh wrapper per call,
  /// so storing the cache on the wrapper would reset it between
  /// `navigate` and the next `run_script` — losing the subframe
  /// entries the navigate's frame-event listener wrote. Pinning the
  /// cache to the backend keeps it alive for the lifetime of the
  /// underlying browser page.
  pub(crate) fn frame_cache(&self) -> &std::sync::Arc<std::sync::Mutex<crate::frame_cache::FrameCache>> {
    match self {
      AnyPage::CdpPipe(p) => &p.frame_cache,
      AnyPage::CdpRaw(p) => &p.frame_cache,
      AnyPage::WebKit(p) => &p.frame_cache,
      AnyPage::Bidi(p) => &p.frame_cache,
    }
  }

  /// Atomic latch consulted by `Page::new` to spawn the frame-event
  /// listener exactly once per backend page (instead of once per
  /// wrapper). Subsequent wrappers see the latch set and skip the
  /// spawn — see `Page::seed_frame_cache`.
  pub(crate) fn frame_listener_started(&self) -> &std::sync::Arc<std::sync::atomic::AtomicBool> {
    match self {
      AnyPage::CdpPipe(p) => &p.frame_listener_started,
      AnyPage::CdpRaw(p) => &p.frame_listener_started,
      AnyPage::WebKit(p) => &p.frame_listener_started,
      AnyPage::Bidi(p) => &p.frame_listener_started,
    }
  }

  /// The backend kind this page lives on. Used by action paths that
  /// branch per-backend (e.g. `tap` needs a CDP-only native touch API
  /// and returns `FerriError::Unsupported` on `BiDi` / `WebKit` where
  /// the protocol has no public touch injection primitive).
  #[must_use]
  pub fn kind(&self) -> BackendKind {
    match self {
      AnyPage::CdpPipe(_) => BackendKind::CdpPipe,
      AnyPage::CdpRaw(_) => BackendKind::CdpRaw,
      AnyPage::WebKit(_) => BackendKind::WebKit,
      AnyPage::Bidi(_) => BackendKind::Bidi,
    }
  }

  // ── Frames ──

  pub async fn get_frame_tree(&self) -> Result<Vec<FrameInfo>> {
    page_dispatch!(self, get_frame_tree())
  }

  /// Backend's cached top-level `frameId`, if a prior op (page-init
  /// or navigation) populated it without a `Page.getFrameTree`
  /// round-trip. Used by `crate::Page::ensure_frame_cache_seeded`
  /// to seed the wrapper's frame cache for free after a `goto`,
  /// avoiding the extra RTT that would otherwise fire when the
  /// frameNavigated event hadn't propagated through the listener
  /// yet by goto-return time.
  #[must_use]
  pub fn peek_main_frame_id(&self) -> Option<String> {
    match self {
      Self::CdpPipe(p) => p.peek_main_frame_id(),
      Self::CdpRaw(p) => p.peek_main_frame_id(),
      Self::WebKit(p) => p.peek_main_frame_id(),
      // BiDi's top-level browsing context id IS the page's main-frame
      // identifier — `browsingContext.navigate` / `browsingContext.tree`
      // all key off the same value. Surface it through the same peek
      // hook so `Page::main_frame()` can seed the frame cache without
      // an extra `browsingContext.getTree` RTT.
      Self::Bidi(p) => Some(p.context_id.to_string()),
    }
  }

  pub async fn evaluate_in_frame(&self, expression: &str, frame_id: &str) -> Result<Option<serde_json::Value>> {
    page_dispatch!(self, evaluate_in_frame(expression, frame_id))
  }

  /// The content-frame id for an `<iframe>`/`<frame>` element given its
  /// remote-object id. Deterministic on CDP (`DOM.describeNode`);
  /// `None` on BiDi/WebKit (no equivalent — callers fall back to the
  /// frame-cache heuristic) or when the element hosts no frame.
  pub async fn content_frame_id(&self, object_id: &str) -> Result<Option<String>> {
    match self {
      AnyPage::CdpPipe(p) => p.content_frame_id(object_id).await,
      AnyPage::CdpRaw(p) => p.content_frame_id(object_id).await,
      AnyPage::WebKit(p) => p.content_frame_id(object_id).await,
      AnyPage::Bidi(_) => Ok(None),
    }
  }

  // ── Navigation ──

  pub async fn goto(
    &self,
    url: &str,
    lifecycle: NavLifecycle,
    timeout_ms: u64,
    referer: Option<&str>,
  ) -> Result<Option<crate::network::Response>> {
    page_dispatch!(self, goto(url, lifecycle, timeout_ms, referer))
  }

  pub async fn wait_for_navigation(&self) -> Result<()> {
    page_dispatch!(self, wait_for_navigation())
  }

  pub async fn reload(&self, lifecycle: NavLifecycle, timeout_ms: u64) -> Result<Option<crate::network::Response>> {
    page_dispatch!(self, reload(lifecycle, timeout_ms))
  }

  pub async fn go_back(&self, lifecycle: NavLifecycle, timeout_ms: u64) -> Result<Option<crate::network::Response>> {
    page_dispatch!(self, go_back(lifecycle, timeout_ms))
  }

  pub async fn go_forward(&self, lifecycle: NavLifecycle, timeout_ms: u64) -> Result<Option<crate::network::Response>> {
    page_dispatch!(self, go_forward(lifecycle, timeout_ms))
  }

  pub async fn url(&self) -> Result<Option<String>> {
    page_dispatch!(self, url())
  }

  pub async fn title(&self) -> Result<Option<String>> {
    page_dispatch!(self, title())
  }

  // ── JavaScript ──

  /// Returns a script that ensures the selector engine is injected.
  /// Mirrored after Playwright's `injectedScript()`.
  pub async fn injected_script(&self) -> Result<String> {
    page_dispatch!(self, injected_script())
  }

  pub async fn ensure_engine_injected(&self) -> Result<()> {
    page_dispatch!(self, ensure_engine_injected())
  }

  pub async fn evaluate(&self, expression: &str) -> Result<Option<serde_json::Value>> {
    page_dispatch!(self, evaluate(expression))
  }

  // ── Elements ──

  pub async fn find_element(&self, selector: &str) -> Result<AnyElement> {
    page_dispatch!(self, find_element(selector))
  }

  /// Evaluate `js` and return the resulting DOM element, resolving in
  /// the execution context of `frame_id` (or the main frame when
  /// `frame_id` is `None`). Mirrors Playwright's `Frame`-bound element
  /// resolution: every Locator carries a Frame, and actions reach the
  /// backend with that frame's id threaded all the way through. CDP
  /// uses `Runtime.evaluate.contextId`; `BiDi` uses the browsing-context
  /// realm; `WebKit` currently has no per-frame execution context, so
  /// non-main `frame_id` values fall back to the main page (DOM access
  /// via `WKFrameInfo` is a separate gap tracked in Section B of
  /// `PLAYWRIGHT_COMPAT.md`).
  pub async fn evaluate_to_element(&self, js: &str, frame_id: Option<&str>) -> Result<AnyElement> {
    page_dispatch!(self, evaluate_to_element(js, frame_id))
  }

  // ── Content ──

  pub async fn content(&self) -> Result<String> {
    page_dispatch!(self, content())
  }

  pub async fn set_content(&self, html: &str) -> Result<()> {
    page_dispatch!(self, set_content(html))
  }

  // ── Screenshots ──

  pub async fn screenshot(&self, opts: ScreenshotOpts) -> Result<Vec<u8>> {
    page_dispatch!(self, screenshot(opts))
  }

  // ── Accessibility ──

  pub async fn accessibility_tree(&self) -> Result<Vec<AxNodeData>> {
    page_dispatch!(self, accessibility_tree())
  }

  pub async fn accessibility_tree_with_depth(&self, depth: i32) -> Result<Vec<AxNodeData>> {
    page_dispatch!(self, accessibility_tree_with_depth(depth))
  }

  // ── Input ──

  pub async fn click_at(&self, x: f64, y: f64) -> Result<()> {
    page_dispatch!(self, click_at(x, y))
  }

  pub async fn click_at_opts(&self, x: f64, y: f64, button: &str, click_count: u32) -> Result<()> {
    page_dispatch!(self, click_at_opts(x, y, button, click_count))
  }

  /// Dispatch a click at page-level coordinates `(x, y)` with the full
  /// Playwright option bag: `button`, `click_count`, modifiers, delay
  /// between press/release, and `steps` interpolated `mousemove` events
  /// between the current cursor and the target. Modifier keydown/keyup
  /// is the caller's responsibility — use [`Self::press_modifiers`] /
  /// [`Self::release_modifiers`] around this call when
  /// `!args.modifiers.is_empty()`.
  pub async fn click_at_with(&self, x: f64, y: f64, args: &BackendClickArgs) -> Result<()> {
    page_dispatch!(self, click_at_with(x, y, args))
  }

  /// Dispatch a hover (no press/release) at `(x, y)` with `steps`
  /// interpolated `mousemove` events and the caller's modifier bitmask
  /// on each. Modifier keydown/keyup is the caller's responsibility.
  pub async fn hover_at_with(&self, x: f64, y: f64, args: &BackendHoverArgs) -> Result<()> {
    page_dispatch!(self, hover_at_with(x, y, args))
  }

  /// Dispatch a native tap at `(x, y)` — CDP `Input.dispatchTouchEvent`
  /// (`touchStart` + `touchEnd`), matching Playwright's
  /// `server/chromium/crInput.ts::RawTouchscreenImpl::tap`. `BiDi` and
  /// `WebKit` do not expose a public touch injection primitive and
  /// return a backend-level error with the `unsupported:` prefix;
  /// callers should surface it as [`crate::error::FerriError::Unsupported`].
  pub async fn tap_at_with(&self, x: f64, y: f64, args: &BackendTapArgs) -> Result<()> {
    page_dispatch!(self, tap_at_with(x, y, args))
  }

  /// Press all modifiers in `mods` via the backend's keyboard input
  /// protocol (CDP `Input.dispatchKeyEvent { type: "keyDown" }`, `BiDi`
  /// `input.performActions`, or `WebKit` host IPC). Idempotent for empty
  /// lists. Callers pair this with [`Self::release_modifiers`].
  pub async fn press_modifiers(&self, mods: &[crate::options::Modifier]) -> Result<()> {
    page_dispatch!(self, press_modifiers(mods))
  }

  /// Release all modifiers in `mods`. See [`Self::press_modifiers`].
  pub async fn release_modifiers(&self, mods: &[crate::options::Modifier]) -> Result<()> {
    page_dispatch!(self, release_modifiers(mods))
  }

  pub async fn move_mouse(&self, x: f64, y: f64) -> Result<()> {
    page_dispatch!(self, move_mouse(x, y))
  }

  pub async fn move_mouse_smooth(&self, from_x: f64, from_y: f64, to_x: f64, to_y: f64, steps: u32) -> Result<()> {
    page_dispatch!(self, move_mouse_smooth(from_x, from_y, to_x, to_y, steps))
  }

  pub async fn mouse_wheel(&self, delta_x: f64, delta_y: f64) -> Result<()> {
    page_dispatch!(self, mouse_wheel(delta_x, delta_y))
  }

  pub async fn mouse_down(&self, x: f64, y: f64, button: &str) -> Result<()> {
    page_dispatch!(self, mouse_down(x, y, button))
  }

  pub async fn mouse_up(&self, x: f64, y: f64, button: &str) -> Result<()> {
    page_dispatch!(self, mouse_up(x, y, button))
  }

  pub async fn click_and_drag(&self, from: (f64, f64), to: (f64, f64), steps: u32) -> Result<()> {
    page_dispatch!(self, click_and_drag(from, to, steps))
  }

  pub async fn type_str(&self, text: &str) -> Result<()> {
    page_dispatch!(self, type_str(text))
  }

  /// Insert text without emitting keyboard events (only `input` event).
  /// This is Playwright's `keyboard.insertText()` semantic.
  pub async fn insert_text(&self, text: &str) -> Result<()> {
    // type_str on all backends uses Input.insertText / equivalent
    self.type_str(text).await
  }

  pub async fn key_down(&self, key: &str) -> Result<()> {
    page_dispatch!(self, key_down(key))
  }

  pub async fn key_up(&self, key: &str) -> Result<()> {
    page_dispatch!(self, key_up(key))
  }

  pub async fn press_key(&self, key: &str) -> Result<()> {
    page_dispatch!(self, press_key(key))
  }

  // ── Cookies ──

  pub async fn get_cookies(&self) -> Result<Vec<CookieData>> {
    page_dispatch!(self, get_cookies())
  }

  pub async fn set_cookie(&self, cookie: CookieData) -> Result<()> {
    page_dispatch!(self, set_cookie(cookie))
  }

  pub async fn delete_cookie(&self, name: &str, domain: Option<&str>) -> Result<()> {
    page_dispatch!(self, delete_cookie(name, domain))
  }

  pub async fn clear_cookies(&self) -> Result<()> {
    page_dispatch!(self, clear_cookies())
  }

  /// Clear cookies matching the given filters. If no filters, clears all.
  pub async fn clear_cookies_filtered(&self, options: &ClearCookieOptions) -> Result<()> {
    if options.name.is_none() && options.domain.is_none() && options.path.is_none() {
      return self.clear_cookies().await;
    }
    // Get all cookies, delete the ones that match the filters.
    let cookies = self.get_cookies().await?;
    for c in &cookies {
      let name_match = options.name.as_ref().is_none_or(|n| &c.name == n);
      let domain_match = options.domain.as_ref().is_none_or(|d| &c.domain == d);
      let path_match = options.path.as_ref().is_none_or(|p| &c.path == p);
      if name_match && domain_match && path_match {
        self.delete_cookie(&c.name, Some(&c.domain)).await?;
      }
    }
    Ok(())
  }

  // ── Emulation ──

  /// Apply a full [`crate::options::BrowserContextOptions`] bag. The
  /// single dispatch point for context-level state — each backend
  /// implementation fires the relevant protocol commands in parallel
  /// via `tokio::join!` and aggregates errors. Callers in
  /// `ContextRef::new_page` and the context-level public setters
  /// (`setOffline`, `setGeolocation`, etc.) mutate the bag and
  /// re-apply.
  pub async fn apply_context_options(&self, opts: &crate::options::BrowserContextOptions) -> Result<()> {
    page_dispatch!(self, apply_context_options(opts))
  }

  pub async fn emulate_viewport(&self, config: &crate::options::ViewportConfig) -> Result<()> {
    page_dispatch!(self, emulate_viewport(config))
  }

  pub async fn emulate_media(&self, opts: &crate::options::EmulateMediaOptions) -> Result<()> {
    page_dispatch!(self, emulate_media(opts))
  }

  pub async fn set_extra_http_headers(&self, headers: &rustc_hash::FxHashMap<String, String>) -> Result<()> {
    page_dispatch!(self, set_extra_http_headers(headers))
  }

  /// Reset any context-granted permissions. Backs
  /// [`crate::ContextRef::clear_permissions`] (Playwright
  /// `browserContext.clearPermissions`).
  pub async fn reset_permissions(&self) -> Result<()> {
    page_dispatch!(self, reset_permissions())
  }

  // ── Tracing ──

  pub async fn start_tracing(&self) -> Result<()> {
    page_dispatch!(self, start_tracing())
  }

  pub async fn stop_tracing(&self) -> Result<()> {
    page_dispatch!(self, stop_tracing())
  }

  pub async fn metrics(&self) -> Result<Vec<MetricData>> {
    page_dispatch!(self, metrics())
  }

  // ── Ref resolution ──

  pub async fn resolve_backend_node(&self, backend_node_id: i64, ref_id: &str) -> Result<AnyElement> {
    page_dispatch!(self, resolve_backend_node(backend_node_id, ref_id))
  }

  // ── Event listeners ──

  pub fn attach_listeners(
    &self,
    console_log: Arc<RwLock<Vec<ConsoleMessage>>>,
    network_log: Arc<RwLock<Vec<NetworkRequest>>>,
    dialog_log: Arc<RwLock<Vec<crate::state::DialogEvent>>>,
  ) {
    match self {
      Self::CdpPipe(p) => p.attach_listeners(console_log, network_log, dialog_log),
      Self::CdpRaw(p) => p.attach_listeners(console_log, network_log, dialog_log),
      Self::WebKit(p) => p.attach_listeners(console_log, network_log, dialog_log),

      Self::Bidi(p) => p.attach_listeners(console_log, network_log, dialog_log),
    }
  }

  // ── Element screenshot (by selector) ──

  pub async fn screenshot_element(&self, selector: &str, format: ImageFormat) -> Result<Vec<u8>> {
    page_dispatch!(self, screenshot_element(selector, format))
  }

  // ── PDF generation ──

  pub async fn pdf(&self, opts: crate::options::PdfOptions) -> Result<Vec<u8>> {
    page_dispatch!(self, pdf(opts))
  }

  // ── Screencast (video recording) ──

  pub async fn start_screencast(
    &self,
    quality: u8,
    max_width: u32,
    max_height: u32,
  ) -> Result<(
    tokio::sync::mpsc::UnboundedReceiver<(Vec<u8>, f64)>,
    tokio::sync::oneshot::Sender<()>,
  )> {
    match self {
      AnyPage::CdpPipe(p) => p.start_screencast(quality, max_width, max_height).await,
      AnyPage::CdpRaw(p) => p.start_screencast(quality, max_width, max_height).await,
      AnyPage::WebKit(p) => {
        let rx = p.start_screencast(quality, max_width, max_height).await?;
        let (tx, _rx_shutdown) = tokio::sync::oneshot::channel();
        Ok((rx, tx))
      },
      AnyPage::Bidi(p) => {
        // BiDi backend does not yet expose a cooperative shutdown
        // channel; synthesise one so the unified return shape holds.
        // The signal is dropped (recorder doesn't use it for BiDi);
        // BiDi's own teardown drives the pump via `stop_screencast`.
        let rx = p.start_screencast(quality, max_width, max_height).await?;
        let (tx, _rx_shutdown) = tokio::sync::oneshot::channel();
        Ok((rx, tx))
      },
    }
  }

  pub async fn stop_screencast(&self) -> Result<()> {
    match self {
      AnyPage::CdpPipe(p) => p.stop_screencast().await,
      AnyPage::CdpRaw(p) => p.stop_screencast().await,
      AnyPage::WebKit(p) => p.stop_screencast().await,

      AnyPage::Bidi(p) => p.stop_screencast().await,
    }
  }

  // ── File upload ──

  pub async fn set_file_input(&self, selector: &str, paths: &[String]) -> Result<()> {
    page_dispatch!(self, set_file_input(selector, paths))
  }

  // ── Dialog handling ──
  //
  // `set_dialog_handler` was removed — dialogs are now observed via
  // `page.on('dialog', ...)` with live `crate::dialog::Dialog`
  // handles. When no listener is registered, each backend's dialog
  // listener auto-closes (accept for `beforeunload`, dismiss
  // otherwise).

  // ── Network Interception ──

  pub async fn route(
    &self,
    matcher: crate::url_matcher::UrlMatcher,
    handler: crate::route::RouteHandler,
  ) -> Result<()> {
    page_dispatch!(self, route(matcher, handler))
  }

  pub async fn unroute(&self, matcher: &crate::url_matcher::UrlMatcher) -> Result<()> {
    page_dispatch!(self, unroute(matcher))
  }

  // ── Lifecycle ──

  pub async fn close_page(&self, opts: crate::options::PageCloseOptions) -> Result<()> {
    page_dispatch!(self, close_page(opts))
  }

  #[must_use]
  pub fn is_closed(&self) -> bool {
    match self {
      Self::CdpPipe(p) => p.is_closed(),
      Self::CdpRaw(p) => p.is_closed(),
      Self::WebKit(p) => p.is_closed(),

      Self::Bidi(p) => p.is_closed(),
    }
  }

  // ── Exposed Functions ──

  pub async fn expose_function(&self, name: &str, func: crate::events::ExposedFn) -> Result<()> {
    page_dispatch!(self, expose_function(name, func))
  }

  pub async fn remove_exposed_function(&self, name: &str) -> Result<()> {
    page_dispatch!(self, remove_exposed_function(name))
  }

  // ── Init Scripts ──

  pub async fn add_init_script(&self, source: &str) -> Result<String> {
    page_dispatch!(self, add_init_script(source))
  }

  pub async fn remove_init_script(&self, identifier: &str) -> Result<()> {
    page_dispatch!(self, remove_init_script(identifier))
  }

  // ── Handle lifecycle ──

  /// Release the backend object the given [`crate::js_handle::HandleRemote`] refers to.
  ///
  /// Each backend uses its native release primitive:
  ///
  /// * CDP: `Runtime.releaseObject { objectId }`.
  /// * `BiDi`: `script.disown { handles: [sharedId], target: {context} }`.
  /// * `WebKit`: `Op::ReleaseRef` IPC — deletes the host-side
  ///   `window.__wr` entry so a subsequent `window.__wr[id]` returns
  ///   `undefined`.
  ///
  /// # Errors
  ///
  /// Forwards the backend's protocol error if the release call fails.
  /// Already-released handles are silently tolerated where the backend
  /// allows it (CDP raises an error only on structural issues like an
  /// invalid session id; `BiDi` returns `invalid argument` for an unknown
  /// `sharedId` which we surface).
  /// ferridriver's equivalent of Playwright's
  /// `evaluateExpression(context, expr, { returnByValue, isFunction }, ...args)`
  /// (`/tmp/playwright/packages/playwright-core/src/server/javascript.ts:248`).
  /// Dispatches to each backend's native `call_utility_evaluate`.
  ///
  /// `args` are the variadic user-function arguments after isomorphic
  /// serialization; `handles` is the shared handle table every
  /// `{h: idx}` reference inside `args` indexes into. For
  /// `page.evaluate(fn, arg)` that's `args = [arg], handles = [...]`;
  /// for `handle.evaluate(fn, arg)` it's `args = [handle, arg]`,
  /// `handles = [self, ...]` — matching Playwright's
  /// `JSHandle.evaluate`'s `evaluate(ctx, ..., this, arg)` shape at
  /// `javascript.ts:161-163`. There is no separate receiver / `this`
  /// binding; Playwright doesn't have one either.
  ///
  /// # Errors
  ///
  /// Forwards backend errors (protocol failure, page-side exception,
  /// handle/backend mismatch).
  #[allow(clippy::too_many_arguments)]
  pub async fn call_utility_evaluate(
    &self,
    fn_source: &str,
    args: &[crate::protocol::SerializedValue],
    handles: &[crate::protocol::HandleId],
    frame_id: Option<&str>,
    is_function: Option<bool>,
    return_by_value: bool,
  ) -> crate::error::Result<crate::js_handle::EvaluateResult> {
    match self {
      Self::CdpPipe(p) => {
        p.call_utility_evaluate(fn_source, args, handles, frame_id, is_function, return_by_value)
          .await
      },
      Self::CdpRaw(p) => {
        p.call_utility_evaluate(fn_source, args, handles, frame_id, is_function, return_by_value)
          .await
      },
      Self::WebKit(p) => {
        p.call_utility_evaluate(fn_source, args, handles, frame_id, is_function, return_by_value)
          .await
      },
      Self::Bidi(p) => {
        p.call_utility_evaluate(fn_source, args, handles, frame_id, is_function, return_by_value)
          .await
      },
    }
  }

  pub async fn release_handle(&self, remote: &crate::js_handle::HandleRemote) -> crate::error::Result<()> {
    use crate::js_handle::HandleRemote;
    match (self, remote) {
      (Self::CdpPipe(p), HandleRemote::Cdp(obj)) => p.release_object(obj).await,
      (Self::CdpRaw(p), HandleRemote::Cdp(obj)) => p.release_object(obj).await,
      (Self::WebKit(p), HandleRemote::WebKit(obj)) => p.release_object(obj).await,
      (Self::Bidi(p), HandleRemote::Bidi { shared_id, handle }) => p.release_handle(shared_id, handle.as_deref()).await,
      // A HandleRemote shape that doesn't match the backend kind is a
      // programming error — mixed-backend handle use.
      (page, remote) => Err(crate::error::FerriError::Backend(format!(
        "handle/backend mismatch: {:?} handle on {:?} backend",
        remote,
        page.kind()
      ))),
    }
  }
}

/// Extract a [`crate::js_handle::HandleRemote`] from a backend `AnyElement`.
///
/// Called by `crate::element_handle::ElementHandle::from_any_element`
/// when wrapping a backend element into a public `ElementHandle`. Each
/// backend exposes its native wire reference (CDP `objectId` string,
/// `BiDi` `sharedId`, `WebKit` `ref_id`); this helper maps them into
/// the unified [`crate::js_handle::HandleRemote`] enum.
///
/// # Errors
///
/// Returns an error if a CDP element has neither a cached `object_id`
/// nor a `node_id` that can be resolved into one — this should never
/// happen for elements freshly returned from `find_element` /
/// `evaluate_to_element` / `DOM.resolveNode`, which always produce at
/// least one of the two.
/// Re-wrap a [`crate::js_handle::HandleRemote`] as a backend
/// [`AnyElement`]. Inverse of [`element_handle_remote`] — used by
/// [`crate::js_handle::JSHandle::as_element`] when a
/// [`crate::js_handle::JSHandle`] turns out to reference a DOM node
/// and needs to be re-packaged as an
/// [`crate::element_handle::ElementHandle`].
///
/// The remote reference must match the backend the page is running on
/// (CDP remote on CDP page, etc.) — this is an invariant guaranteed
/// by [`crate::js_handle::JSHandle`]'s construction site, so a
/// mismatch is a programming error and surfaces as
/// [`crate::error::FerriError::Backend`].
///
/// # Errors
///
/// Returns a backend-mismatch error when the remote's variant doesn't
/// line up with the page's backend kind.
pub fn element_from_remote(
  page: &AnyPage,
  remote: &crate::js_handle::HandleRemote,
) -> crate::error::Result<AnyElement> {
  use crate::js_handle::HandleRemote;
  match (page, remote) {
    (AnyPage::CdpPipe(p), HandleRemote::Cdp(obj)) => Ok(AnyElement::CdpPipe(p.element_from_object_id(obj.clone()))),
    (AnyPage::CdpRaw(p), HandleRemote::Cdp(obj)) => Ok(AnyElement::CdpRaw(p.element_from_object_id(obj.clone()))),
    (AnyPage::WebKit(p), HandleRemote::WebKit(obj)) => {
      Ok(AnyElement::WebKit(p.element_from_object_id(obj.to_string())))
    },
    (AnyPage::Bidi(p), HandleRemote::Bidi { shared_id, .. }) => {
      Ok(AnyElement::Bidi(p.element_from_shared_id(shared_id.clone())))
    },
    (page, remote) => Err(crate::error::FerriError::Backend(format!(
      "element_from_remote: backend mismatch — {:?} remote on {:?} backend",
      remote,
      page.kind()
    ))),
  }
}

pub async fn element_handle_remote(element: &AnyElement) -> crate::error::Result<crate::js_handle::HandleRemote> {
  use crate::js_handle::HandleRemote;
  match element {
    AnyElement::CdpPipe(e) => {
      let obj = e.ensure_object_id().await?;
      Ok(HandleRemote::Cdp(obj))
    },
    AnyElement::CdpRaw(e) => {
      let obj = e.ensure_object_id().await?;
      Ok(HandleRemote::Cdp(obj))
    },
    AnyElement::WebKit(e) => Ok(HandleRemote::WebKit(std::sync::Arc::from(e.object_id()))),
    AnyElement::Bidi(e) => Ok(HandleRemote::Bidi {
      shared_id: e.shared_id.clone(),
      handle: None,
    }),
  }
}

// ─── AnyElement ─────────────────────────────────────────────────────────────

/// Element handle — enum dispatch across backends.
pub enum AnyElement {
  CdpPipe(cdp::CdpElement<cdp::pipe::PipeTransport>),
  CdpRaw(cdp::CdpElement<cdp::ws::WsTransport>),
  WebKit(webkit::WebKitElement),
  Bidi(bidi::BidiElement),
}

macro_rules! element_dispatch {
    ($self:expr, $method:ident ( $($arg:expr),* $(,)? )) => {
        match $self {
            AnyElement::CdpPipe(e) => e.$method($($arg),*).await,
            AnyElement::CdpRaw(e) => e.$method($($arg),*).await,
            AnyElement::WebKit(e) => e.$method($($arg),*).await,

            AnyElement::Bidi(e) => e.$method($($arg),*).await,
        }
    };
}

impl AnyElement {
  pub async fn click(&self) -> Result<()> {
    element_dispatch!(self, click())
  }

  pub async fn dblclick(&self) -> Result<()> {
    element_dispatch!(self, dblclick())
  }

  pub async fn hover(&self) -> Result<()> {
    element_dispatch!(self, hover())
  }

  pub async fn type_str(&self, text: &str) -> Result<()> {
    element_dispatch!(self, type_str(text))
  }

  pub async fn call_js_fn(&self, function: &str) -> Result<()> {
    element_dispatch!(self, call_js_fn(function))
  }

  pub async fn call_js_fn_value(&self, function: &str) -> Result<Option<serde_json::Value>> {
    element_dispatch!(self, call_js_fn_value(function))
  }

  pub async fn scroll_into_view(&self) -> Result<()> {
    element_dispatch!(self, scroll_into_view())
  }

  pub async fn screenshot(&self, format: ImageFormat) -> Result<Vec<u8>> {
    element_dispatch!(self, screenshot(format))
  }
}