lingxia_browser/

lib.rs

#[cfg(all(test, target_vendor = "apple"))]
#[path = "../../lingxia-platform/tests/support/apple_host_stubs.rs"]
mod apple_host_stubs;

mod automation;
mod chooser;
mod document_session;
mod downloads;
mod inbound;
mod internal_pages;
mod policy;
mod tabs;
mod types;
mod webview;

pub use lingxia_webview::{
    NetworkBody, NetworkCaptureSnapshot, NetworkEntry, WebViewCookie, WebViewCookieSameSite,
    WebViewCookieSetRequest,
};
pub use policy::{extract_url_scheme, is_lingxia_startup_url, normalize_url_for_wait_compare};
use std::sync::Arc;
use std::time::Duration;
pub use types::{
    BrowserAddressAction, BrowserAddressInputContext, BrowserAddressInputError,
    BrowserAddressInputRequest, BrowserAddressInputResponse, BrowserAddressInputTrigger,
    BrowserAddressNavigation, BrowserAddressState, BrowserAddressSuggestion,
    BrowserAddressValueKind, BrowserAutomationError, BrowserElementInfo, BrowserNativeInputHost,
    BrowserNavigationPolicyDecision, BrowserNavigationPolicyRequest,
    BrowserNavigationPolicyResponse, BrowserNavigationTarget, BrowserRect, BrowserTabInfo,
    BrowserWaitCondition, BrowserWaitResult, TrustedControlPageNavigation,
};

pub use lxapp::LxAppError;

pub const BUILTIN_BROWSER_APPID: &str = "app.lingxia.browser";
/// Exact browser webui-to-host control protocol supported by this runtime.
pub const CONTROL_PROTOCOL_VERSION: u32 = 3;
/// `(url, title)` observer; `title` is empty when no title has been reported
/// for that URL yet.
pub type BrowserPageMetadataHandler = Arc<dyn Fn(&str, &str) + Send + Sync>;

pub fn classify_navigation(
    request: BrowserNavigationPolicyRequest,
) -> BrowserNavigationPolicyResponse {
    policy::handle_browser_navigation_policy(request)
}

pub fn classify_navigation_json(request_json: &str) -> Option<String> {
    policy::handle_browser_navigation_policy_json(request_json)
}

#[doc(hidden)]
pub fn set_navigation_finished_handler(handler: BrowserPageMetadataHandler) {
    tabs::set_navigation_finished_handler(handler);
}

#[doc(hidden)]
pub fn set_title_changed_handler(handler: BrowserPageMetadataHandler) {
    tabs::set_title_changed_handler(handler);
}

#[doc(hidden)]
pub fn register_document_script(
    native_authority: &lxapp::NativeControlPlaneAuthority,
    js: impl Into<String>,
) -> Result<(), LxAppError> {
    require_native_control_authority(native_authority)?;
    internal_pages::register_browser_document_script(js)
}

#[doc(hidden)]
pub fn install_runtime() {
    lxapp::register_page_resolver(internal_pages::browser_logic_page_path_for_tab_path);
    lingxia_transfer::runtime::register_browser_tab_path_resolver(tabs::browser_tab_path_for_id);
    lingxia_transfer::runtime::register_browser_retry_handler(
        downloads::retry_browser_owned_download,
    );
}

/// Seal the native authority used by browser document lifecycle operations.
/// Duplicate installation is rejected; there is no getter.
#[doc(hidden)]
pub fn __install_native_control_authority(authority: lxapp::NativeControlPlaneAuthority) -> bool {
    document_session::install_browser_document_authority(authority)
}

#[doc(hidden)]
pub fn register_internal_page(
    native_authority: &lxapp::NativeControlPlaneAuthority,
    route: impl Into<String>,
    entry_asset: impl Into<String>,
) -> Result<(), LxAppError> {
    require_native_control_authority(native_authority)?;
    internal_pages::register_browser_internal_page(route, entry_asset)
}

pub fn open(url: &str, tab_id: Option<&str>) -> Result<String, LxAppError> {
    reject_trusted_control_url(url)?;
    tabs::open_internal_browser_tab(url, tab_id)
}

#[doc(hidden)]
pub fn open_trusted(
    native_authority: &lxapp::NativeControlPlaneAuthority,
    url: &str,
    tab_id: Option<&str>,
) -> Result<String, LxAppError> {
    require_native_control_authority(native_authority)?;
    tabs::open_internal_browser_tab(url, tab_id)
}

#[doc(hidden)]
pub fn open_trusted_for_app(
    native_authority: &lxapp::NativeControlPlaneAuthority,
    appid: &str,
    session_id: u64,
    url: &str,
    tab_id: Option<&str>,
) -> Result<String, LxAppError> {
    require_native_control_authority(native_authority)?;
    tabs::open_internal_browser_tab_for_owner(
        appid,
        session_id,
        url,
        tab_id,
        false,
        false,
        lingxia_webview::WebViewDataMode::ProfileDefault,
        false,
    )
}

/// Bootstrap-TCB entry that always requests a new trusted top-level load of a
/// registered internal control page. It never returns document authority.
#[doc(hidden)]
pub fn navigate_trusted_control_page(
    native_authority: &lxapp::NativeControlPlaneAuthority,
    url: &str,
) -> Result<TrustedControlPageNavigation, LxAppError> {
    require_native_control_authority(native_authority)?;
    tabs::navigate_trusted_control_page(url)
}

fn require_native_control_authority(
    native_authority: &lxapp::NativeControlPlaneAuthority,
) -> Result<(), LxAppError> {
    native_authority.is_live().then_some(()).ok_or_else(|| {
        LxAppError::UnsupportedOperation(
            "trusted browser control operation requires live native host authority".to_string(),
        )
    })
}

fn reject_trusted_control_url(url: &str) -> Result<(), LxAppError> {
    (extract_url_scheme(url).as_deref() != Some("lingxia"))
        .then_some(())
        .ok_or_else(|| {
            LxAppError::UnsupportedOperation(
                "lingxia:// navigation requires sealed native browser authority".to_string(),
            )
        })
}

#[doc(hidden)]
pub fn seal_control_registration(
    native_authority: &lxapp::NativeControlPlaneAuthority,
) -> Result<(), LxAppError> {
    require_native_control_authority(native_authority)?;
    internal_pages::seal_browser_control_registration();
    Ok(())
}

pub fn open_for_app(
    appid: &str,
    session_id: u64,
    url: &str,
    tab_id: Option<&str>,
) -> Result<String, LxAppError> {
    reject_trusted_control_url(url)?;
    tabs::open_internal_browser_tab_for_owner(
        appid,
        session_id,
        url,
        tab_id,
        false,
        false,
        lingxia_webview::WebViewDataMode::ProfileDefault,
        false,
    )
}

/// Open a tab in the API-managed aside browser group.
pub fn open_aside_for_app(
    appid: &str,
    session_id: u64,
    url: &str,
    tab_id: Option<&str>,
) -> Result<String, LxAppError> {
    reject_trusted_control_url(url)?;
    tabs::open_internal_browser_tab_for_owner(
        appid,
        session_id,
        url,
        tab_id,
        false,
        true,
        lingxia_webview::WebViewDataMode::ProfileDefault,
        false,
    )
}

/// Open a standalone browser tab hosted outside the product browser chrome.
/// This supports docked asides and URL surfaces. New-window requests load
/// inline in the same WebView rather than spawning a main-area tab.
pub fn open_standalone_for_app(
    appid: &str,
    session_id: u64,
    url: &str,
    tab_id: Option<&str>,
    data_mode: lingxia_webview::WebViewDataMode,
    url_callback: bool,
) -> Result<String, LxAppError> {
    reject_trusted_control_url(url)?;
    tabs::open_internal_browser_tab_for_owner(
        appid,
        session_id,
        url,
        tab_id,
        true,
        false,
        data_mode,
        url_callback,
    )
}

/// Whether `tab_id` belongs to the API-managed aside browser group.
pub fn tab_is_aside(tab_id: &str) -> bool {
    tabs::is_aside_tab(tab_id)
}

/// Whether `tab_id` is hosted outside the product browser chrome, such as a
/// docked aside or URL surface. It remains visible to browser automation.
pub fn tab_is_standalone(tab_id: &str) -> bool {
    tabs::is_standalone_tab(tab_id)
}

pub fn close(tab_id: &str) -> Result<(), LxAppError> {
    let owner_appid = tabs::tab_owner_appid(tab_id);
    tabs::close_browser_tab(tab_id)?;
    if let Some(owner_appid) = owner_appid {
        let payload = serde_json::json!({
            "id": tab_id,
            "reason": "user",
        })
        .to_string();
        let _ =
            lxapp::publish_app_event(&owner_appid, lxapp::BROWSER_TAB_CLOSED_EVENT, Some(payload));
    }
    Ok(())
}

/// Retire browser tabs owned by previous sessions of an lxapp.
pub fn prune_stale_owner_tabs(owner_appid: &str, current_session_id: u64) -> usize {
    tabs::prune_stale_owner_tabs(owner_appid, current_session_id)
}

/// Discard a tab's WebView to free memory while keeping its sidebar entry.
pub fn discard(tab_id: &str) -> Result<(), LxAppError> {
    tabs::discard_browser_tab(tab_id)
}

/// Recreate a discarded tab's WebView, reload its URL, and activate it.
pub fn reactivate(tab_id: &str) -> Result<(), LxAppError> {
    tabs::reactivate_browser_tab(tab_id)
}

/// Sync the Rust-side active tab when the SDK switches to an already-live tab.
pub fn mark_active(tab_id: &str) {
    tabs::mark_browser_tab_active(tab_id)
}

/// Clear active browser state when the host leaves browser UI entirely.
pub fn clear_active() {
    tabs::clear_active_browser_tab()
}

pub fn tabs() -> Vec<BrowserTabInfo> {
    tabs::browser_tabs()
}

pub fn current_tab() -> Option<BrowserTabInfo> {
    tabs::browser_current_tab()
}

/// Current tab selected by browser automation. Standalone surface tabs can be
/// selected here without changing the product browser's active tab.
pub fn automation_current_tab() -> Option<BrowserTabInfo> {
    tabs::browser_automation_current_tab()
}

pub fn activate(tab_id: &str) -> Result<BrowserTabInfo, BrowserAutomationError> {
    tabs::browser_activate_tab(tab_id)
}

/// Registers a process-wide observer invoked whenever the browser tab set
/// or tab metadata changes: tab opened/closed, active tab switched, or a
/// tab's URL/title updated. Intended for shell UIs that mirror the tab
/// list (e.g. sidebar tab rows); the previous handler (if any) is replaced.
///
/// The callback may fire from arbitrary runtime threads (webview UI
/// threads included) and must not block; query [`tabs`]/[`current_tab`]
/// from it to read the new state.
pub fn set_tabs_changed_handler(handler: Arc<dyn Fn() + Send + Sync>) {
    tabs::set_tabs_changed_handler(handler);
}

/// Registers a process-wide observer used to bring a browser tab onscreen.
///
/// Browser core owns tab lifecycle and active-tab state, but only a host shell
/// knows how to present that tab's WebView in its UI. Devtools and other
/// automation surfaces call [`present`] to request this handoff.
pub fn set_tab_present_handler(handler: Arc<dyn Fn(&str) + Send + Sync>) {
    tabs::set_tab_present_handler(handler);
}

/// Mark `tab_id` active and ask the host shell to bring it onscreen.
pub fn present(tab_id: &str) -> Result<BrowserTabInfo, BrowserAutomationError> {
    tabs::browser_present_tab(tab_id)
}

/// PNG-encoded favicon of `tab_id`'s current page, if the platform webview
/// reported one (see `WebViewDelegate::on_favicon_changed`). Kept out of
/// [`BrowserTabInfo`] so the serialized tab projection stays byte-free;
/// shell sidebars query it per tab when mirroring the tab list.
pub fn tab_favicon(tab_id: &str) -> Option<Arc<Vec<u8>>> {
    tabs::browser_tab_favicon(tab_id)
}

pub fn register_native_input_host(host: Arc<dyn BrowserNativeInputHost>) -> bool {
    automation::register_native_input_host(host)
}

pub async fn evaluate_javascript(
    tab_id: &str,
    js: &str,
) -> Result<serde_json::Value, BrowserAutomationError> {
    automation::browser_evaluate_javascript(tab_id, js).await
}

pub async fn take_screenshot(tab_id: &str) -> Result<Vec<u8>, BrowserAutomationError> {
    automation::browser_take_screenshot(tab_id).await
}

pub async fn current_url(tab_id: &str) -> Result<Option<String>, BrowserAutomationError> {
    automation::browser_current_url(tab_id).await
}

pub fn reload(tab_id: &str) -> Result<(), BrowserAutomationError> {
    automation::browser_reload(tab_id)
}

/// Return the complete browser-session user-agent override. `None` means the
/// platform WebView default is in use.
pub fn configured_user_agent() -> Option<String> {
    automation::browser_configured_user_agent()
}

/// Configure a complete user-agent string for all browser tabs, or pass `None`
/// to restore the platform WebView default. The setting also applies to future
/// and recreated browser WebViews for the lifetime of the process.
pub fn set_user_agent_override(user_agent: Option<String>) -> Result<(), BrowserAutomationError> {
    automation::browser_set_user_agent_override(user_agent)
}

pub fn go_back(tab_id: &str) -> Result<(), BrowserAutomationError> {
    automation::browser_go_back(tab_id)
}

pub fn go_forward(tab_id: &str) -> Result<(), BrowserAutomationError> {
    automation::browser_go_forward(tab_id)
}

pub async fn list_cookies(tab_id: &str) -> Result<Vec<WebViewCookie>, BrowserAutomationError> {
    automation::browser_list_cookies(tab_id).await
}

pub async fn list_all_cookies(tab_id: &str) -> Result<Vec<WebViewCookie>, BrowserAutomationError> {
    automation::browser_list_all_cookies(tab_id).await
}

pub async fn set_cookie(
    tab_id: &str,
    request: WebViewCookieSetRequest,
) -> Result<(), BrowserAutomationError> {
    automation::browser_set_cookie(tab_id, request).await
}

pub async fn delete_cookie(
    tab_id: &str,
    name: &str,
    domain: &str,
    path: &str,
) -> Result<(), BrowserAutomationError> {
    automation::browser_delete_cookie(tab_id, name, domain, path).await
}

pub async fn clear_cookies(tab_id: &str) -> Result<(), BrowserAutomationError> {
    automation::browser_clear_cookies(tab_id).await
}

pub async fn clear_site_data(
    tab_id: &str,
    options: lingxia_webview::ClearSiteDataOptions,
) -> Result<lingxia_webview::ClearSiteDataResult, BrowserAutomationError> {
    automation::browser_clear_site_data(tab_id, options).await
}

pub async fn start_network_capture(tab_id: &str) -> Result<(), BrowserAutomationError> {
    automation::browser_start_network_capture(tab_id).await
}

pub async fn stop_network_capture(tab_id: &str) -> Result<(), BrowserAutomationError> {
    automation::browser_stop_network_capture(tab_id).await
}

pub async fn network_entries(
    tab_id: &str,
) -> Result<NetworkCaptureSnapshot, BrowserAutomationError> {
    automation::browser_network_entries(tab_id).await
}

pub async fn clear_network_capture(tab_id: &str) -> Result<(), BrowserAutomationError> {
    automation::browser_clear_network_capture(tab_id).await
}

pub async fn query(
    tab_id: &str,
    selector: &str,
) -> Result<BrowserElementInfo, BrowserAutomationError> {
    automation::browser_query(tab_id, selector).await
}

pub async fn query_with_max_text(
    tab_id: &str,
    selector: &str,
    max_text_chars: Option<usize>,
) -> Result<BrowserElementInfo, BrowserAutomationError> {
    automation::browser_query_with_max_text(tab_id, selector, max_text_chars).await
}

pub async fn wait(
    tab_id: &str,
    condition: BrowserWaitCondition,
    timeout: Duration,
) -> Result<BrowserWaitResult, BrowserAutomationError> {
    automation::browser_wait(tab_id, condition, timeout).await
}

pub async fn wait_for_url(
    tab_id: &str,
    url: &str,
    timeout: Duration,
) -> Result<BrowserWaitResult, BrowserAutomationError> {
    automation::browser_wait_for_url(tab_id, url, timeout).await
}

pub async fn wait_for_url_contains(
    tab_id: &str,
    text: &str,
    timeout: Duration,
) -> Result<BrowserWaitResult, BrowserAutomationError> {
    automation::browser_wait_for_url_contains(tab_id, text, timeout).await
}

pub async fn wait_for_navigation(
    tab_id: &str,
    timeout: Duration,
    wait_until_complete: bool,
) -> Result<BrowserWaitResult, BrowserAutomationError> {
    automation::browser_wait_for_navigation(tab_id, timeout, wait_until_complete).await
}

pub async fn click(tab_id: &str, selector: &str) -> Result<(), BrowserAutomationError> {
    automation::browser_click(tab_id, selector).await
}

pub async fn type_text(
    tab_id: &str,
    selector: &str,
    text: &str,
) -> Result<(), BrowserAutomationError> {
    automation::browser_type_text(tab_id, selector, text).await
}

pub async fn fill(tab_id: &str, selector: &str, text: &str) -> Result<(), BrowserAutomationError> {
    automation::browser_fill(tab_id, selector, text).await
}

pub async fn press(tab_id: &str, key: &str) -> Result<(), BrowserAutomationError> {
    automation::browser_press(tab_id, key).await
}

pub async fn scroll(tab_id: &str, dx: f64, dy: f64) -> Result<(), BrowserAutomationError> {
    automation::browser_scroll(tab_id, dx, dy).await
}

pub async fn scroll_to(tab_id: &str, selector: &str) -> Result<(), BrowserAutomationError> {
    automation::browser_scroll_to(tab_id, selector).await
}

pub fn tab_path(tab_id: &str) -> String {
    tabs::browser_tab_path_for_id(tab_id)
}

pub fn update_tab(tab_id: &str, current_url: Option<&str>, title: Option<&str>) -> bool {
    tabs::browser_update_tab_info(tab_id, current_url, title)
}

pub fn start_download(
    tab_id: &str,
    url: &str,
    user_agent: Option<&str>,
    suggested_filename: Option<&str>,
    source_page_url: Option<&str>,
    cookie: Option<&str>,
) -> Result<(), LxAppError> {
    downloads::start_native_browser_download(
        tab_id,
        url,
        user_agent,
        suggested_filename,
        source_page_url,
        cookie,
    )
}

#[doc(hidden)]
pub fn register_bundled_app() {
    tabs::register_builtin_browser_host();
}

#[doc(hidden)]
pub fn warmup() {
    if let Err(err) = internal_pages::warmup_builtin_browser_runtime() {
        lxapp::warn!("[InternalBrowser] warmup failed: {}", err);
    }
}

#[cfg(test)]
mod authority_tests {
    use super::*;

    #[test]
    fn app_owned_navigation_cannot_open_internal_control_routes() {
        let error = open_for_app("app.example", 7, "lingxia://downloads", Some("downloads"))
            .expect_err("ordinary app navigation must reject internal routes");
        assert!(matches!(error, LxAppError::UnsupportedOperation(_)));
        assert!(
            error
                .to_string()
                .contains("sealed native browser authority")
        );
    }
}

pub use tabs::{ClosedBrowserTab, recently_closed, reopen_closed};