lingxia_webview/

traits.rs

use crate::{LogLevel, WebViewError, WebViewInputError, WebViewScriptError};
use async_trait::async_trait;
use serde::{Deserialize, Serialize};
use std::future::Future;
use std::path::PathBuf;
use std::pin::Pin;
use std::sync::Arc;

/// Opaque identity for one native WebView instance.
///
/// A [`crate::WebTag`] is a logical lookup key and may be reused after a
/// WebView is destroyed. This identity is allocated for one concrete native
/// instance and is therefore the only identity suitable for message binding.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct NativeWebViewId(u64);

impl NativeWebViewId {
    pub(crate) const fn new(raw: u64) -> Self {
        Self(raw)
    }

    /// Construct a synthetic native identity in downstream unit tests.
    #[cfg(feature = "test-support")]
    pub const fn for_test(raw: u64) -> Self {
        Self(raw)
    }

    // Android's JNI binding consumes this only on its conditionally compiled target.
    #[allow(dead_code)]
    pub(crate) const fn raw(self) -> u64 {
        self.0
    }
}

/// Monotonic generation of a committed document within one native WebView.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct DocumentGeneration(u64);

impl DocumentGeneration {
    /// Constructed only by the navigation normalizer after reliable commit
    /// evidence. Adapters never receive this constructor.
    pub(crate) const fn new(raw: u64) -> Self {
        Self(raw)
    }

    /// Construct a synthetic document generation in downstream unit tests.
    #[cfg(feature = "test-support")]
    pub const fn for_test(raw: u64) -> Self {
        Self(raw)
    }

    /// The platform-owned ordinal, intended only for equality binding.
    pub const fn get(self) -> u64 {
        self.0
    }
}

/// Opaque capability issued for one native-owned direct HTML load.
///
/// This is deliberately useful only for equality binding. It has no public
/// constructor, raw representation, formatting implementation, or wire
/// encoding: URL and HTML data are not authority, and neither is this token
/// until the navigation normalizer attests it at a committed document.
#[derive(Clone, Copy, PartialEq, Eq, Hash)]
pub struct TrustedLoadIntent(u64);

impl TrustedLoadIntent {
    pub(crate) const fn new(raw: u64) -> Self {
        Self(raw)
    }
}

/// Non-forgeable evidence that a trusted native HTML load committed.
///
/// The normalizer creates this only after it correlates one issued
/// [`TrustedLoadIntent`] with the exact native WebView, the platform-native
/// navigation key, and an accepted navigation lifecycle.
#[derive(Clone, Copy)]
pub struct TrustedDocumentAdmission {
    native_view: NativeWebViewId,
    generation: DocumentGeneration,
    navigation_id: crate::events::NavigationId,
    intent: TrustedLoadIntent,
}

impl TrustedDocumentAdmission {
    pub(crate) const fn new(
        native_view: NativeWebViewId,
        generation: DocumentGeneration,
        navigation_id: crate::events::NavigationId,
        intent: TrustedLoadIntent,
    ) -> Self {
        Self {
            native_view,
            generation,
            navigation_id,
            intent,
        }
    }

    pub const fn native_view(&self) -> NativeWebViewId {
        self.native_view
    }

    pub const fn generation(&self) -> DocumentGeneration {
        self.generation
    }

    pub const fn navigation_id(&self) -> crate::events::NavigationId {
        self.navigation_id
    }

    pub const fn intent(&self) -> TrustedLoadIntent {
        self.intent
    }
}

/// Whether a platform callback is bound to a committed document generation.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum DocumentBinding {
    /// The adapter cannot prove which committed document emitted the message.
    Unbound,
    /// The adapter captured the native WebView's committed document generation.
    Bound(DocumentGeneration),
}

/// A document-session authority check for one outbound native message.
///
/// Implementations must invoke `action` only while the document session is
/// still active. The closure makes it possible for a registry-backed gate to
/// keep its lock for the check and the native post as one operation.
pub trait DocumentOutboundGate: Send + Sync {
    fn with_active(&self, action: &mut dyn FnMut()) -> bool;
}

/// Platform proof of the emitting frame.
///
/// Authorization-sensitive consumers must accept only [`Self::TopLevel`].
/// `Unproven` is deliberately distinct from `TopLevel` so an adapter cannot
/// silently upgrade an unavailable platform signal into authority.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum WebMessageFrame {
    TopLevel,
    Subframe,
    Unproven,
}

/// Native transport which delivered a WebView message.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum WebMessageTransport {
    AppleScriptMessage,
    AndroidMessagePort,
    AndroidJavascriptInterface,
    WindowsWebMessage,
    HarmonyMessagePort,
    Other,
}

/// Platform-reported source information for diagnostics and auditing.
///
/// It is intentionally not an authorization credential: URLs and origins can
/// be stale, unavailable, or insufficient to bind a message to an app
/// session. Authorization must use the native view identity, document binding,
/// and frame proof in [`WebMessageContext`].
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct WebMessageSource {
    reported_url: Option<String>,
    reported_origin: Option<String>,
}

impl WebMessageSource {
    pub const fn unavailable() -> Self {
        Self {
            reported_url: None,
            reported_origin: None,
        }
    }

    pub fn diagnostic_url(reported_url: Option<String>) -> Self {
        Self {
            reported_url,
            reported_origin: None,
        }
    }

    pub fn diagnostic_origin(reported_origin: Option<String>) -> Self {
        Self {
            reported_url: None,
            reported_origin,
        }
    }

    pub fn diagnostic(reported_url: Option<String>, reported_origin: Option<String>) -> Self {
        Self {
            reported_url,
            reported_origin,
        }
    }

    /// A platform-reported URL. This is diagnostic data, never authorization.
    pub fn reported_url(&self) -> Option<&str> {
        self.reported_url.as_deref()
    }

    /// A platform-reported origin. This is diagnostic data, never authorization.
    pub fn reported_origin(&self) -> Option<&str> {
        self.reported_origin.as_deref()
    }
}

/// Non-forgeable platform context bound to an incoming WebView message.
///
/// Carrying this context does not by itself authorize bridge dispatch. The
/// bridge admission layer must explicitly evaluate its binding and proof.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct WebMessageContext {
    native_view: NativeWebViewId,
    document: DocumentBinding,
    frame: WebMessageFrame,
    transport: WebMessageTransport,
    source: WebMessageSource,
}

impl WebMessageContext {
    pub(crate) const fn new(
        native_view: NativeWebViewId,
        document: DocumentBinding,
        frame: WebMessageFrame,
        transport: WebMessageTransport,
        source: WebMessageSource,
    ) -> Self {
        Self {
            native_view,
            document,
            frame,
            transport,
            source,
        }
    }

    pub const fn native_view(&self) -> NativeWebViewId {
        self.native_view
    }

    pub const fn document(&self) -> DocumentBinding {
        self.document
    }

    pub const fn frame(&self) -> WebMessageFrame {
        self.frame
    }

    pub const fn transport(&self) -> WebMessageTransport {
        self.transport
    }

    pub fn source(&self) -> &WebMessageSource {
        &self.source
    }
}

/// A page-originated WebView message plus platform-attested context.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct IncomingWebMessage {
    body: String,
    context: WebMessageContext,
}

impl IncomingWebMessage {
    pub(crate) fn new(body: String, context: WebMessageContext) -> Self {
        Self { body, context }
    }

    pub fn body(&self) -> &str {
        &self.body
    }

    pub fn context(&self) -> &WebMessageContext {
        &self.context
    }
}

/// Platform proof of which document scope initiated a scheme request.
///
/// `Unproven` is intentionally not treated as a top-level document. Platform
/// adapters must preserve unavailable or ambiguous evidence rather than
/// upgrading it at the Rust boundary.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum SchemeRequestFrame {
    TopLevelDocument,
    Subresource,
    Unproven,
}

/// A scheme request plus the concrete native WebView and frame proof which
/// delivered it.
///
/// Construction is crate-private: only platform adapters, after validating
/// their callback's native identity, may attach this authority-relevant
/// context. Consumers can inspect it but cannot forge a replacement.
#[derive(Debug)]
pub struct ContextualSchemeRequest {
    request: http::Request<Vec<u8>>,
    native_view: NativeWebViewId,
    frame: SchemeRequestFrame,
}

impl ContextualSchemeRequest {
    pub(crate) fn new(
        request: http::Request<Vec<u8>>,
        native_view: NativeWebViewId,
        frame: SchemeRequestFrame,
    ) -> Self {
        Self {
            request,
            native_view,
            frame,
        }
    }

    pub fn request(&self) -> &http::Request<Vec<u8>> {
        &self.request
    }

    pub fn into_request(self) -> http::Request<Vec<u8>> {
        self.request
    }

    pub const fn native_view(&self) -> NativeWebViewId {
        self.native_view
    }

    pub const fn frame(&self) -> SchemeRequestFrame {
        self.frame
    }
}

/// Outcome of handling a scheme request.
#[derive(Debug)]
pub enum SchemeOutcome {
    /// Handler produced a response.
    Handled(WebResourceResponse),
    /// Handler intentionally declined the request.
    PassThrough,
}

/// Async scheme handler signature.
pub(crate) type AsyncSchemeFuture = Pin<Box<dyn Future<Output = SchemeOutcome> + Send + 'static>>;
pub(crate) type AsyncSchemeHandler =
    Arc<dyn Fn(ContextualSchemeRequest) -> AsyncSchemeFuture + Send + Sync>;

/// Navigation policy decision returned by the navigation handler.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NavigationPolicy {
    /// Allow the WebView to navigate to this URL.
    Allow,
    /// Cancel the navigation. The handler is responsible for any side effects
    /// (e.g., opening the URL externally via `AppRuntime::open_url()`).
    Cancel,
}

/// A platform navigation request passed to the registered policy handler.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct NavigationRequest {
    pub url: String,
    pub has_user_gesture: bool,
    pub is_main_frame: bool,
}

impl NavigationRequest {
    pub fn new(url: impl Into<String>, has_user_gesture: bool, is_main_frame: bool) -> Self {
        Self {
            url: url.into(),
            has_user_gesture,
            is_main_frame,
        }
    }
}

/// New-window policy decision returned by the new-window handler.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum NewWindowPolicy {
    /// Load the URL in the current WebView (replaces current page).
    LoadInSelf,
    /// Cancel the new-window request without doing anything.
    Cancel,
}

pub type NavigationHandler = Box<dyn Fn(&NavigationRequest) -> NavigationPolicy + Send + Sync>;
pub type NewWindowHandler = Box<dyn Fn(&str) -> NewWindowPolicy + Send + Sync>;

/// Per-WebView user-agent override.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum UserAgentOverride {
    /// Restore the user agent supplied by the platform WebView engine.
    Default,
    /// Replace the complete user-agent string. The value must be non-empty and
    /// engine-compatible. This does not emulate other browser capabilities or
    /// synchronize User-Agent Client Hints.
    Custom(String),
}

impl UserAgentOverride {
    /// Validate a complete override before applying or persisting it.
    pub fn validate(&self) -> Result<(), WebViewError> {
        if let Self::Custom(value) = self {
            if value.trim().is_empty() {
                return Err(WebViewError::WebView(
                    "custom user-agent override must not be empty".to_string(),
                ));
            }
            if value.contains(['\r', '\n', '\0']) {
                return Err(WebViewError::WebView(
                    "custom user-agent override must not contain CR, LF, or NUL".to_string(),
                ));
            }
        }
        Ok(())
    }
}

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

    #[test]
    fn custom_user_agent_must_not_be_blank() {
        assert!(UserAgentOverride::Custom(String::new()).validate().is_err());
        assert!(UserAgentOverride::Custom("   ".into()).validate().is_err());
        assert!(
            UserAgentOverride::Custom("Mozilla/5.0 valid".into())
                .validate()
                .is_ok()
        );
        for invalid in [
            "Mozilla/5.0\rInjected",
            "Mozilla/5.0\nInjected",
            "Mozilla\0/5.0",
        ] {
            assert!(
                UserAgentOverride::Custom(invalid.into())
                    .validate()
                    .is_err()
            );
        }
        assert!(UserAgentOverride::Default.validate().is_ok());
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DownloadRequest {
    /// Final download URL reported by the platform callback.
    pub url: String,
    /// Request user-agent if available on this platform.
    pub user_agent: Option<String>,
    /// `Content-Disposition` response header if exposed by the platform.
    pub content_disposition: Option<String>,
    /// Response MIME type if exposed by the platform.
    pub mime_type: Option<String>,
    /// Response content length if known.
    pub content_length: Option<u64>,
    /// Platform-suggested filename (may be absent).
    pub suggested_filename: Option<String>,
    /// Source page URL that initiated the download when available.
    pub source_page_url: Option<String>,
    /// Cookie header string for `url` when available.
    pub cookie: Option<String>,
}

/// Download callback.
///
/// In browser profile, registering this callback makes download requests flow through the host
/// app callback path instead of in-WebView download UI.
pub type DownloadHandler = Box<dyn Fn(DownloadRequest) + Send + Sync>;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum WebViewCookieSameSite {
    Lax,
    Strict,
    None,
}

impl WebViewCookieSameSite {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Lax => "lax",
            Self::Strict => "strict",
            Self::None => "none",
        }
    }
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct WebViewCookie {
    pub name: String,
    pub value: String,
    pub domain: String,
    pub path: String,
    #[serde(default, skip_serializing_if = "is_false")]
    pub host_only: bool,
    #[serde(default)]
    pub secure: bool,
    #[serde(default)]
    pub http_only: bool,
    #[serde(default)]
    pub session: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub expires_unix_ms: Option<i64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub same_site: Option<WebViewCookieSameSite>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct WebViewCookieSetRequest {
    #[serde(default)]
    pub url: String,
    pub name: String,
    pub value: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub domain: Option<String>,
    #[serde(default = "default_cookie_path")]
    pub path: String,
    #[serde(default)]
    pub secure: bool,
    #[serde(default)]
    pub http_only: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub expires_unix_ms: Option<i64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub same_site: Option<WebViewCookieSameSite>,
}

fn default_cookie_path() -> String {
    "/".to_string()
}

fn is_false(value: &bool) -> bool {
    !*value
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FileChooserRequest {
    /// Accepted MIME types / extensions requested by the page.
    pub accept_types: Vec<String>,
    /// Whether multiple files may be selected.
    pub allow_multiple: bool,
    /// Whether directories may be selected.
    pub allow_directories: bool,
    /// Whether the page requested capture/live media.
    pub capture: bool,
    /// Source page URL that initiated the chooser when available.
    pub source_page_url: Option<String>,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FileChooserFile {
    pub path: Option<String>,
    pub uri: Option<String>,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum FileChooserResponse {
    Cancel,
    Error(String),
    Files(Vec<FileChooserFile>),
}

/// Body source for WebResourceResponse
#[derive(Debug)]
pub enum WebResourceBody {
    /// Serve data from a regular file path on disk
    Path(PathBuf),
    /// Serve data from a system pipe (read end)
    Pipe(SystemPipeReader),
    /// Serve data directly from memory
    Bytes(Vec<u8>),
}

/// Cross‑platform system pipe reader (read end)
#[derive(Debug)]
pub struct SystemPipeReader {
    #[cfg(unix)]
    fd: std::os::fd::RawFd,
    #[cfg(windows)]
    handle: std::os::windows::io::RawHandle,
}

impl SystemPipeReader {
    /// Consume and return the raw file descriptor (Unix).
    /// Caller becomes responsible for closing it.
    #[cfg(unix)]
    pub fn into_raw_fd(self) -> std::os::fd::RawFd {
        self.fd
    }

    /// Construct from a raw file descriptor (Unix).
    ///
    /// # Safety
    ///
    /// Caller guarantees that `fd` is a valid read end of a pipe file descriptor.
    #[cfg(unix)]
    pub unsafe fn from_raw_fd(fd: std::os::fd::RawFd) -> Self {
        Self { fd }
    }

    /// Convert into a File for reading (consumes self).
    #[cfg(unix)]
    pub fn into_file(self) -> std::fs::File {
        use std::os::fd::FromRawFd;
        unsafe { std::fs::File::from_raw_fd(self.into_raw_fd()) }
    }

    /// Consume and return the raw handle (Windows).
    /// Caller becomes responsible for closing it.
    #[cfg(windows)]
    pub fn into_raw_handle(self) -> std::os::windows::io::RawHandle {
        self.handle
    }

    /// Construct from a raw handle (Windows).
    ///
    /// # Safety
    ///
    /// Caller guarantees that `handle` is a valid readable OS handle.
    #[cfg(windows)]
    pub unsafe fn from_raw_handle(handle: std::os::windows::io::RawHandle) -> Self {
        Self { handle }
    }

    /// Convert into a File for reading (consumes self).
    #[cfg(windows)]
    pub fn into_file(self) -> std::fs::File {
        use std::os::windows::io::FromRawHandle;
        unsafe { std::fs::File::from_raw_handle(self.into_raw_handle()) }
    }
}

/// Interface for controlling WebView (100% copy from lxapp)
#[async_trait]
pub trait WebViewController: Send + Sync {
    /// Load a URL in the WebView
    fn load_url(&self, url: &str) -> Result<(), WebViewError>;

    /// Load HTML data into the WebView.
    fn load_data(&self, request: LoadDataRequest<'_>) -> Result<(), WebViewError>;

    /// Execute JavaScript in the WebView without observing its return value.
    fn exec_js(&self, js: &str) -> Result<(), WebViewError>;

    /// Evaluate JavaScript in the WebView and return the decoded JSON value.
    ///
    /// Implementations are required to be both CSP-safe (no `(0,eval)` /
    /// `new Function` — pages whose CSP omits `'unsafe-eval'` must still
    /// work) and `await`-aware (top-level `await` in the user expression
    /// resolves before the future returns). Platforms achieve this by
    /// dispatching through the native await-capable API
    /// (`callAsyncJavaScript:` on Apple, `LingXiaProxy.resolveEval` JS
    /// bridge on Android/Harmony).
    async fn eval_js(&self, js: &str) -> Result<serde_json::Value, WebViewScriptError>;

    /// Return the platform WebView's current URL.
    async fn current_url(&self) -> Result<Option<String>, WebViewError> {
        Err(WebViewError::WebView(
            "current_url is not implemented for this platform".to_string(),
        ))
    }

    /// Post a message to the WebView
    fn post_message(&self, message: &str) -> Result<(), WebViewError>;

    /// Post a message only if an exact committed document and its session gate
    /// are still current.
    ///
    /// This is intentionally unsupported unless a platform can perform the
    /// final identity check at its actual JavaScript execution point.
    fn post_message_to_document(
        &self,
        _expected_generation: DocumentGeneration,
        _gate: Arc<dyn DocumentOutboundGate>,
        _message: &str,
    ) -> Result<(), WebViewError> {
        Err(WebViewError::Unsupported(
            "document-bound message posting".to_string(),
        ))
    }

    /// Clear browsing data from the WebView
    fn clear_browsing_data(&self) -> Result<(), WebViewError>;

    /// Override or restore the WebView user agent.
    fn set_user_agent_override(&self, user_agent: UserAgentOverride) -> Result<(), WebViewError>;

    /// Reload the current WebView document.
    fn reload(&self) -> Result<(), WebViewError> {
        Err(WebViewError::WebView(
            "reload is not implemented for this platform".to_string(),
        ))
    }

    /// Navigate back in WebView history.
    fn go_back(&self) -> Result<(), WebViewError> {
        Err(WebViewError::WebView(
            "go_back is not implemented for this platform".to_string(),
        ))
    }

    /// Navigate forward in WebView history.
    fn go_forward(&self) -> Result<(), WebViewError> {
        Err(WebViewError::WebView(
            "go_forward is not implemented for this platform".to_string(),
        ))
    }

    /// List HTTP cookies from the platform WebView cookie store.
    async fn list_cookies(&self) -> Result<Vec<WebViewCookie>, WebViewError> {
        Err(WebViewError::WebView(
            "cookie store is not implemented for this platform".to_string(),
        ))
    }

    /// Set an HTTP cookie through the platform WebView cookie store.
    async fn set_cookie(&self, _request: WebViewCookieSetRequest) -> Result<(), WebViewError> {
        Err(WebViewError::WebView(
            "cookie store is not implemented for this platform".to_string(),
        ))
    }

    /// Delete an HTTP cookie from the platform WebView cookie store.
    async fn delete_cookie(
        &self,
        _name: &str,
        _domain: &str,
        _path: &str,
    ) -> Result<(), WebViewError> {
        Err(WebViewError::WebView(
            "cookie store is not implemented for this platform".to_string(),
        ))
    }

    /// Clear all HTTP cookies from the platform WebView cookie store.
    async fn clear_cookies(&self) -> Result<(), WebViewError> {
        Err(WebViewError::WebView(
            "cookie store is not implemented for this platform".to_string(),
        ))
    }

    /// Clear data owned by the current website without clearing the shared
    /// browser profile. Platforms report whether their network cache supports
    /// site-scoped removal.
    async fn clear_site_data(
        &self,
        _url: &str,
        _options: ClearSiteDataOptions,
    ) -> Result<ClearSiteDataResult, WebViewError> {
        Err(WebViewError::WebView(
            "site-scoped data clearing is not implemented for this platform".to_string(),
        ))
    }

    /// Capture a PNG screenshot of the WebView's visible content.
    /// Returns raw PNG-encoded bytes ready to be base64'd over the wire.
    async fn take_screenshot(&self) -> Result<Vec<u8>, WebViewError> {
        Err(WebViewError::WebView(
            "screenshot is not implemented for this platform".to_string(),
        ))
    }

    /// Begin recording network requests/responses into a bounded per-webview
    /// buffer, retrievable via [`Self::network_entries`]. Dev-tooling only;
    /// implemented on platforms whose WebView exposes an inspection protocol
    /// (currently Windows/WebView2 via the Chrome DevTools Protocol).
    async fn start_network_capture(&self) -> Result<(), WebViewError> {
        Err(WebViewError::WebView(
            "network capture is not implemented for this platform".to_string(),
        ))
    }

    /// Stop recording network traffic. Captured entries are kept until
    /// [`Self::clear_network_capture`] or the webview is torn down.
    async fn stop_network_capture(&self) -> Result<(), WebViewError> {
        Err(WebViewError::WebView(
            "network capture is not implemented for this platform".to_string(),
        ))
    }

    /// Snapshot the captured network entries (oldest first). `dropped` counts
    /// entries evicted from the ring buffer since the last clear.
    async fn network_entries(&self) -> Result<NetworkCaptureSnapshot, WebViewError> {
        Err(WebViewError::WebView(
            "network capture is not implemented for this platform".to_string(),
        ))
    }

    /// Drop all captured entries (leaves capture enabled if it was on).
    async fn clear_network_capture(&self) -> Result<(), WebViewError> {
        Err(WebViewError::WebView(
            "network capture is not implemented for this platform".to_string(),
        ))
    }
}

/// Data categories to remove for one site via
/// [`WebViewController::clear_site_data`].
#[derive(Debug, Clone, Copy)]
pub struct ClearSiteDataOptions {
    pub cache: bool,
    pub site_data: bool,
}

/// Outcome of [`WebViewController::clear_site_data`]. Each flag means "this
/// category was requested AND the platform fully honored it" — `false` both
/// when the category was not requested and when it could not be fully cleared.
///
/// Windows caveat: WebView2 clears the site's Cache Storage/appcache but
/// cannot site-scope the shared HTTP cache, so it reports
/// `cache_cleared: false` even when cache clearing was requested.
#[derive(Debug, Clone, Copy)]
pub struct ClearSiteDataResult {
    pub cache_cleared: bool,
    pub site_data_cleared: bool,
}

/// One captured network request and its response (when it completed).
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct NetworkEntry {
    /// Protocol request id, stable across the request/response events.
    pub request_id: String,
    pub url: String,
    pub method: String,
    /// Resource kind reported by the engine (document, xhr, fetch, script,
    /// image, ...), when available.
    pub resource_type: Option<String>,
    pub request_headers: Vec<(String, String)>,
    /// Request payload (POST body) as reported by the engine, when present.
    pub request_body: Option<String>,
    pub status: Option<u16>,
    pub response_headers: Vec<(String, String)>,
    pub mime_type: Option<String>,
    pub response_body: NetworkBody,
    pub from_cache: bool,
    /// Populated when the request failed (engine error text) instead of
    /// producing a response.
    pub failed: Option<String>,
    /// Wall-clock start time (Unix epoch seconds), when the engine reports it.
    pub wall_time: Option<f64>,
    /// Monotonic engine timestamps (seconds), for ordering and durations.
    pub started: f64,
    pub finished: Option<f64>,
}

impl NetworkEntry {
    /// Request duration in milliseconds, once the response has completed.
    pub fn duration_ms(&self) -> Option<f64> {
        self.finished
            .filter(|finished| *finished >= self.started)
            .map(|finished| (finished - self.started) * 1000.0)
    }
}

/// Response body of a captured entry.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum NetworkBody {
    /// No body captured yet (in flight) or the response had none.
    #[default]
    None,
    /// UTF-8 text body.
    Text { text: String },
    /// Base64-encoded binary body.
    Base64 { base64: String },
    /// Body deliberately not captured (e.g. over the size cap, or evicted
    /// before it could be read); `reason` says which.
    Skipped { reason: String },
}

/// A point-in-time view of the capture buffer.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct NetworkCaptureSnapshot {
    pub entries: Vec<NetworkEntry>,
    /// Entries evicted from the ring buffer since the last clear (buffer
    /// full). Surfaced so truncation is never silent.
    pub dropped: u64,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct ClickOptions {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub index: Option<usize>,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct TypeOptions {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub index: Option<usize>,
    #[serde(default)]
    pub replace: bool,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct FillOptions {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub index: Option<usize>,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct PressOptions {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub selector: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub index: Option<usize>,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct ScrollOptions;

#[async_trait]
pub trait WebViewInputController: WebViewController {
    async fn click(
        &self,
        _selector: &str,
        _options: ClickOptions,
    ) -> Result<(), WebViewInputError> {
        Err(WebViewInputError::Unsupported(
            "input control is not implemented for this platform",
        ))
    }

    async fn type_text(
        &self,
        _selector: &str,
        _text: &str,
        _options: TypeOptions,
    ) -> Result<(), WebViewInputError> {
        Err(WebViewInputError::Unsupported(
            "input control is not implemented for this platform",
        ))
    }

    async fn fill(
        &self,
        _selector: &str,
        _text: &str,
        _options: FillOptions,
    ) -> Result<(), WebViewInputError> {
        Err(WebViewInputError::Unsupported(
            "input control is not implemented for this platform",
        ))
    }

    async fn press(&self, _key: &str, _options: PressOptions) -> Result<(), WebViewInputError> {
        Err(WebViewInputError::Unsupported(
            "input control is not implemented for this platform",
        ))
    }

    async fn scroll(
        &self,
        _dx: f64,
        _dy: f64,
        _options: ScrollOptions,
    ) -> Result<(), WebViewInputError> {
        Err(WebViewInputError::Unsupported(
            "input control is not implemented for this platform",
        ))
    }

    async fn scroll_to(
        &self,
        _selector: &str,
        _options: ScrollOptions,
    ) -> Result<(), WebViewInputError> {
        Err(WebViewInputError::Unsupported(
            "input control is not implemented for this platform",
        ))
    }
}

#[derive(Debug, Clone, Copy)]
pub struct LoadDataRequest<'a> {
    pub data: &'a str,
    pub base_url: &'a str,
    pub history_url: Option<&'a str>,
}

impl<'a> LoadDataRequest<'a> {
    pub fn new(data: &'a str, base_url: &'a str) -> Self {
        Self {
            data,
            base_url,
            history_url: None,
        }
    }

    pub fn with_history_url(mut self, history_url: &'a str) -> Self {
        self.history_url = Some(history_url);
        self
    }
}

/// Normalized category for a main-frame page load failure.
///
/// Cancellation is deliberately not a kind: a cancelled navigation is control
/// flow and terminates as `NavigationEvent::Cancelled`, never as a load error.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LoadErrorKind {
    Dns,
    Network,
    Timeout,
    Security,
    InvalidUrl,
    NotFound,
    Unknown,
}

/// Error reported when a main-frame page load fails (DNS, network, TLS, etc.).
///
/// `kind` is the stable value for program logic; `description` is platform
/// diagnostic text for logs and must not be parsed or shown directly as
/// localized product copy.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LoadError {
    /// URL that failed to load, if the platform exposes it.
    pub failing_url: Option<String>,
    /// Cross-platform error category for application logic and UI.
    pub kind: LoadErrorKind,
    /// Human-readable description from the platform.
    pub description: String,
}

/// WebView delegate: typed navigation lifecycle, observable state, page
/// messaging, and logging for one WebView. Exactly one owner per WebView
/// (an lxapp `PageInstance` or a browser tab delegate); read-only watchers
/// use [`crate::events::normalizer::add_observer`]-registered observers.
///
/// Delivery contract (enforced by the event normalizer):
/// - events arrive by value, serially, synchronously on the submitting
///   thread, flattened FIFO — a callback is never re-entered for the same
///   WebView;
/// - callbacks may arrive on the WebView's own UI thread; fire-and-forget
///   commands (`exec_js`) are safe there, but result-awaiting APIs must not
///   block the callback thread;
/// - every `Started` gets exactly one terminal event; success owns a
///   non-empty final URL; cancellation is control flow, never a load error;
/// - state changes are snapshots, not lifecycle: `Location` alone is never
///   evidence of a successful visit, and `None` clears title/favicon.
///
/// Fold navigation through [`crate::events::NavigationProgress`] and state
/// through [`crate::events::ObservedWebViewState`] instead of hand-rolling
/// attempt correlation:
///
/// ```ignore
/// fn on_navigation_event(&self, event: NavigationEvent) {
///     let mut progress = self.progress.lock().unwrap();
///     progress.apply(&event);
///     if let NavigationEvent::Succeeded { id, final_url } = &event
///         && progress.is_current(*id)
///     {
///         self.loaded(final_url);
///     }
/// }
/// ```
pub trait WebViewDelegate: Send + Sync {
    /// One correlated top-level navigation lifecycle event.
    ///
    /// Required: after the typed-event migration every delegate must decide
    /// how it handles the lifecycle — a silent default would lose page loads.
    fn on_navigation_event(&self, event: crate::events::NavigationEvent);

    /// One observable-state snapshot (location, title, favicon,
    /// back/forward availability), coalesced and generation-scoped by the
    /// normalizer.
    fn on_webview_state_change(&self, _change: crate::events::WebViewStateChange) {}

    /// A top-level document binding minted from reliable, non-stale commit
    /// evidence. It is never emitted for duplicate or ambiguous commits.
    fn on_document_committed(
        &self,
        _native_view: NativeWebViewId,
        _generation: DocumentGeneration,
        _navigation_id: crate::events::NavigationId,
    ) {
    }

    /// A trusted native HTML load that reached a reliably committed document.
    ///
    /// This is stricter than [`Self::on_document_committed`]: it is emitted
    /// only when the platform returned the exact native navigation key for a
    /// direct native load and the normalizer bound that key to this accepted
    /// navigation. The data and base URL used for the load are not authority.
    fn on_trusted_document_admitted(&self, _admission: TrustedDocumentAdmission) {}

    /// The platform terminated this exact WebView's content process. Only
    /// adapters with native evidence emit it; consumers must revoke any
    /// document authority before allowing a replacement to load.
    fn on_web_content_process_terminated(&self, _native_view: NativeWebViewId) {}

    /// A backend proved that a previously committed document was restored
    /// without a fresh native start/commit chain (for example from BFCache).
    /// The adapter revokes its generation before invoking this hook.
    fn on_document_restored(&self, _native_view: NativeWebViewId, _url: &str) {}

    /// Handles a postMessage from the page View(WebView).
    ///
    /// The context is assembled only by the platform adapter and must travel
    /// with the payload through any bridge admission decision.
    fn handle_post_message(&self, message: IncomingWebMessage);

    /// Handles a native-component message posted by the page through the
    /// embedded-component channel (`window.NativeComponentBridge`), where
    /// the platform routes it in-process (currently Windows/WebView2).
    /// `message_json` is the raw component message (`component.mount`,
    /// `component.update`, ...).
    fn handle_native_component_message(&self, _message_json: String) {}

    /// Receive log from WebView
    fn log(&self, level: LogLevel, message: &str);
}

/// Represents an HTTP response whose body is provided by a file path, pipe, or in-memory bytes.
#[derive(Debug)]
pub struct WebResourceResponse {
    parts: http::response::Parts,
    body: WebResourceBody,
}

impl From<Option<WebResourceResponse>> for SchemeOutcome {
    fn from(value: Option<WebResourceResponse>) -> Self {
        match value {
            Some(response) => SchemeOutcome::Handled(response),
            None => SchemeOutcome::PassThrough,
        }
    }
}

impl WebResourceResponse {
    /// Borrow the response parts (status, headers, etc.).
    pub fn parts(&self) -> &http::response::Parts {
        &self.parts
    }

    /// Consume the struct and return the owned parts and file path.
    pub fn into_parts(self) -> (http::response::Parts, WebResourceBody) {
        (self.parts, self.body)
    }
}

/// Convenience conversion from (Parts, PathBuf)
impl From<(http::response::Parts, PathBuf)> for WebResourceResponse {
    fn from(value: (http::response::Parts, PathBuf)) -> Self {
        WebResourceResponse {
            parts: value.0,
            body: WebResourceBody::Path(value.1),
        }
    }
}

/// Convenience conversion from (Parts, SystemPipeReader)
impl From<(http::response::Parts, SystemPipeReader)> for WebResourceResponse {
    fn from(value: (http::response::Parts, SystemPipeReader)) -> Self {
        WebResourceResponse {
            parts: value.0,
            body: WebResourceBody::Pipe(value.1),
        }
    }
}

/// Convenience conversion from (Parts, Vec<u8>)
impl From<(http::response::Parts, Vec<u8>)> for WebResourceResponse {
    fn from(value: (http::response::Parts, Vec<u8>)) -> Self {
        WebResourceResponse {
            parts: value.0,
            body: WebResourceBody::Bytes(value.1),
        }
    }
}

impl WebResourceResponse {
    fn response_parts_with_status(status: u16) -> http::response::Parts {
        let response = match http::Response::builder().status(status).body(()) {
            Ok(response) => response,
            Err(_) => http::Response::new(()),
        };
        let (parts, _) = response.into_parts();
        parts
    }

    /// Create a response serving a file from disk (status 200).
    pub fn file(path: impl Into<PathBuf>) -> Self {
        let path = path.into();
        let content_length = std::fs::metadata(&path).ok().map(|m| m.len());
        let mut parts = Self::response_parts_with_status(200);
        if let Some(len) = content_length {
            parts
                .headers
                .insert(http::header::CONTENT_LENGTH, http::HeaderValue::from(len));
        }
        Self {
            parts,
            body: WebResourceBody::Path(path),
        }
    }

    /// Create a response serving in-memory bytes (status 200).
    pub fn bytes(data: impl Into<Vec<u8>>) -> Self {
        let data = data.into();
        let len = data.len();
        let mut parts = Self::response_parts_with_status(200);
        parts
            .headers
            .insert(http::header::CONTENT_LENGTH, http::HeaderValue::from(len));
        Self {
            parts,
            body: WebResourceBody::Bytes(data),
        }
    }

    /// Create a response serving data from a system pipe (status 200).
    pub fn stream(reader: SystemPipeReader) -> Self {
        let parts = Self::response_parts_with_status(200);
        Self {
            parts,
            body: WebResourceBody::Pipe(reader),
        }
    }

    /// Set the Content-Type header (builder pattern).
    pub fn mime(mut self, content_type: &str) -> Self {
        if let Ok(value) = http::HeaderValue::from_str(content_type) {
            self.parts.headers.insert(http::header::CONTENT_TYPE, value);
        }
        self
    }

    /// Set the HTTP status code (builder pattern).
    pub fn status(mut self, code: u16) -> Self {
        self.parts.status = http::StatusCode::from_u16(code).unwrap_or(self.parts.status);
        self
    }

    /// Add a response header (builder pattern).
    pub fn header(mut self, name: &str, value: &str) -> Self {
        if let (Ok(header_name), Ok(header_value)) = (
            name.parse::<http::header::HeaderName>(),
            http::HeaderValue::from_str(value),
        ) {
            self.parts.headers.insert(header_name, header_value);
        }
        self
    }

    /// Add CORS header `Access-Control-Allow-Origin: null` (builder pattern).
    pub fn cors(self) -> Self {
        self.header("access-control-allow-origin", "null")
    }
}

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

    #[test]
    fn contextual_scheme_request_preserves_platform_context() {
        let request = http::Request::builder()
            .uri("lx://app/index.html")
            .body(vec![1, 2, 3])
            .unwrap();
        let request = ContextualSchemeRequest::new(
            request,
            NativeWebViewId::new(91),
            SchemeRequestFrame::TopLevelDocument,
        );

        assert_eq!(request.native_view(), NativeWebViewId::new(91));
        assert_eq!(request.frame(), SchemeRequestFrame::TopLevelDocument);
        assert_eq!(request.request().uri(), "lx://app/index.html");
        assert_eq!(request.into_request().into_body(), vec![1, 2, 3]);
    }
}