teksilo-webview 0.13.1

// SPDX-License-Identifier: MPL-2.0
// SPDX-FileCopyrightText: 2026 FernTech

//! `WryBackend` — production engine backend (macOS WKWebView / Windows
//! WebView2 / Linux-X11 WebKitGTK) via the [`wry`] crate.
//!
//! Gated behind the `wry-backend` feature. The native engine subview is
//! created with [`WebViewBuilder::build_as_child`] against the OS parent
//! window handle that the `WebView` widget hands us from its post-mount
//! [`EventContext`](teksilo_core::widget::EventContext) (see
//! `BuildContext::run_after_mount`). Browser events (IPC messages, page-load
//! status, title changes, navigations) are translated into [`WebViewEvent`]s
//! and posted back through the supplied [`AppEventPoster`].
//!
//! Per the plan, this is the macOS / Windows / Linux-X11 backend.
//!
//! **Linux requirements.** WebKitGTK runs on the GTK / GLib main loop and can
//! only embed as a child window under **X11**:
//! - GTK must be initialised before the first webview — `open` calls
//!   `gtk::init()` (idempotent, main-thread) since winit doesn't.
//! - The host must pump the GLib loop each turn or the page never paints — see
//!   [`crate::pump_gtk_events`], driven from `TeksiloAppBuilder::on_loop_tick`.
//! - The parent must be an X11 window. winit 0.30 picks Wayland whenever
//!   `WAYLAND_DISPLAY` is set, handing wry a Wayland handle it can't embed into
//!   ("window handle kind is not supported"). On a Wayland session, run under
//!   XWayland (unset `WAYLAND_DISPLAY` + `GDK_BACKEND=x11` before winit init),
//!   or use the Servo backend.
//!
//! **Engine focus.** wry exposes no focus-changed callback, so the page's own
//! focus is reported by the page: an initialization script forwards `window`'s
//! `focus` / `blur` events over the same IPC channel, prefixed with
//! [`FOCUS_IPC_PREFIX`], and the IPC handler turns those into
//! [`WebViewEvent::EngineFocusChanged`] instead of a user message. A page that
//! posts that exact prefix itself therefore loses the message — the prefix is
//! chosen to make that a deliberate act.
//!
//! **Input pass-through** ([`crate::WebViewInput::Transparent`]) is **not
//! available** here: `wry::WebView`'s whole mutating surface is `set_cookie`,
//! `set_background_color`, `set_bounds` and `set_visible`, none of which touches
//! the native surface's hit region. The call is answered with a
//! [`WebViewEvent::ConsoleMessage`], which is this crate's channel for an
//! operation a backend cannot perform.
//!
//! **Known gaps (tracked):** custom-protocol *handlers* are not yet plumbed
//! through `WebViewAttributes` (only scheme names are carried), so `app://`
//! style local serving is not wired here; `go_back`/`go_forward` are driven
//! via `history.back()/forward()` (wry 0.55 exposes no direct history API).

use std::sync::Arc;

use teksilo_canvas::Rect;
use teksilo_core::AppEventPoster;
use teksilo_core::raw_handle::ParentHandle;
use teksilo_core::window::TeksiloWindowId;

use wry::{PageLoadEvent, WebView, WebViewBuilder};
// Logical positioning is the macOS / Windows path; Linux converts to Physical.
#[cfg(not(target_os = "linux"))]
use wry::dpi::{LogicalPosition, LogicalSize};

use crate::backend::{
    ConsoleLevel, NoopWebViewHandle, WebSource, WebViewAttributes, WebViewBackend, WebViewEvent,
    WebViewHandle, WebViewId, js_string, post_event,
};

/// The IPC message prefix reserved for the page-focus bridge.
///
/// Deliberately unlovely: it has to be a string no application would post by
/// accident, because a message that starts with it is consumed as a focus
/// report rather than delivered to `on_message`.
pub const FOCUS_IPC_PREFIX: &str = "__teksilo_webview_focus:";

/// Initialization script installing the page-focus bridge.
///
/// `window`'s `focus` / `blur` fire when the web content takes and gives up the
/// keyboard, which is the closest thing to an engine focus event wry offers —
/// there is no callback for it on the Rust side.
fn focus_bridge_script() -> String {
    format!(
        "(function(){{\
           var p={prefix};\
           var send=function(v){{try{{window.ipc.postMessage(p+v)}}catch(e){{}}}};\
           window.addEventListener('focus',function(){{send('1')}});\
           window.addEventListener('blur',function(){{send('0')}});\
         }})()",
        prefix = js_string(FOCUS_IPC_PREFIX)
    )
}

/// Production engine backend. Construct and hand to
/// `install_web_view(WryBackend::new())`.
#[derive(Debug, Default)]
pub struct WryBackend {
    _private: (),
}

impl WryBackend {
    /// Construct the wry backend.
    pub fn new() -> Self {
        Self { _private: () }
    }
}

/// Report engine-init failure: drive the widget to its Error chrome via
/// `NavigationFinished { success: false }` (the visual-state signal), plus a
/// console message for diagnostics. Returns a no-op handle so the (now-Some)
/// widget handle stops the open from being retried into the same failure.
fn fail(
    poster: &Option<Arc<dyn AppEventPoster>>,
    window_id: TeksiloWindowId,
    web_view_id: WebViewId,
    text: String,
) -> Box<dyn WebViewHandle> {
    post_event(
        poster,
        window_id,
        web_view_id,
        WebViewEvent::ConsoleMessage {
            level: ConsoleLevel::Error,
            text,
        },
    );
    post_event(
        poster,
        window_id,
        web_view_id,
        WebViewEvent::NavigationFinished {
            url: String::new(),
            success: false,
        },
    );
    Box::new(NoopWebViewHandle)
}

impl WebViewBackend for WryBackend {
    fn open(
        &mut self,
        web_view_id: WebViewId,
        window_id: TeksiloWindowId,
        parent: Option<ParentHandle>,
        attrs: WebViewAttributes,
        poster: Option<Arc<dyn AppEventPoster>>,
    ) -> Box<dyn WebViewHandle> {
        // On Linux, WebKitGTK requires GTK to be initialised before any webview
        // is created (and its GLib loop pumped each turn — see
        // `crate::pump_gtk_events`). winit doesn't init GTK, so do it here. It's
        // idempotent and main-thread-only; `open` always runs on the main thread.
        #[cfg(target_os = "linux")]
        if gtk::init().is_err() {
            return fail(
                &poster,
                window_id,
                web_view_id,
                "WryBackend: gtk::init() failed — WebKitGTK needs GTK initialised".to_string(),
            );
        }

        let Some(parent) = parent else {
            // No OS parent handle — can't create a child subview. Surface the
            // Error state so the widget doesn't sit in Loading forever.
            return fail(
                &poster,
                window_id,
                web_view_id,
                "WryBackend: no parent window handle available; webview not created".to_string(),
            );
        };

        let mut builder = WebViewBuilder::new();

        match &attrs.source {
            Some(WebSource::Url(url)) => builder = builder.with_url(url.clone()),
            Some(WebSource::Html { html, .. }) => builder = builder.with_html(html.clone()),
            None => {}
        }
        if let Some(ua) = &attrs.user_agent {
            builder = builder.with_user_agent(ua.clone());
        }
        builder = builder
            .with_transparent(attrs.transparent)
            .with_devtools(attrs.devtools);

        // --- Browser event handlers → WebViewEvent (each gets its own clone) ---
        builder = builder.with_initialization_script(focus_bridge_script());
        {
            let poster = poster.clone();
            builder = builder.with_ipc_handler(move |req| {
                let body = req.body();
                let event = match body.strip_prefix(FOCUS_IPC_PREFIX) {
                    Some(flag) => WebViewEvent::EngineFocusChanged(flag == "1"),
                    None => WebViewEvent::Message(body.clone()),
                };
                post_event(&poster, window_id, web_view_id, event);
            });
        }
        {
            let poster = poster.clone();
            builder = builder.with_on_page_load_handler(move |event, url| {
                let ev = match event {
                    PageLoadEvent::Started => WebViewEvent::PageLoadStarted,
                    PageLoadEvent::Finished => WebViewEvent::PageLoadFinished,
                };
                post_event(&poster, window_id, web_view_id, ev);
                // Surface a NavigationFinished on load completion so the
                // url/Ready bindings settle even without a separate nav-finish
                // callback in wry 0.55.
                if matches!(event, PageLoadEvent::Finished) {
                    post_event(
                        &poster,
                        window_id,
                        web_view_id,
                        WebViewEvent::NavigationFinished { url, success: true },
                    );
                }
            });
        }
        {
            let poster = poster.clone();
            builder = builder.with_navigation_handler(move |url| {
                post_event(
                    &poster,
                    window_id,
                    web_view_id,
                    WebViewEvent::NavigationStarted {
                        url,
                        can_cancel: false,
                    },
                );
                true // allow — pre-navigation veto is not yet exposed app-side
            });
        }
        {
            let poster = poster.clone();
            builder = builder.with_document_title_changed_handler(move |title| {
                post_event(
                    &poster,
                    window_id,
                    web_view_id,
                    WebViewEvent::TitleChanged(title),
                );
            });
        }
        // Downloads are observed, not steered: the started handler returns
        // `true` (allow) with wry's default destination, because the app's
        // callback runs on a later event-loop tick (events are posted, not
        // delivered inline) and so cannot supply a path synchronously. Apps
        // get start/finish notifications for progress UI / toasts.
        {
            let poster = poster.clone();
            builder = builder.with_download_started_handler(move |url, path| {
                post_event(
                    &poster,
                    window_id,
                    web_view_id,
                    WebViewEvent::DownloadStarted {
                        url,
                        suggested_path: path.clone(),
                    },
                );
                true
            });
        }
        {
            let poster = poster.clone();
            builder = builder.with_download_completed_handler(move |_url, path, success| {
                post_event(
                    &poster,
                    window_id,
                    web_view_id,
                    WebViewEvent::DownloadFinished {
                        path: path.unwrap_or_default(),
                        success,
                    },
                );
            });
        }

        match builder.build_as_child(&parent) {
            Ok(webview) => Box::new(WryHandle {
                webview,
                poster: poster.clone(),
                window_id,
                web_view_id,
            }),
            Err(e) => fail(
                &poster,
                window_id,
                web_view_id,
                format!("WryBackend: failed to create webview: {e}"),
            ),
        }
    }
}

/// Live handle wrapping a `wry::WebView`. `!Send`, but the backend lives in
/// app-state and only ever runs on the main thread, so every call here is
/// main-thread. Dropping the handle drops the `WebView`, tearing the native
/// subview down (RAII).
struct WryHandle {
    webview: WebView,
    /// Kept so the handle can report an operation this engine cannot perform
    /// (see [`WebViewHandle::set_input_passthrough`]) through the same
    /// `ConsoleMessage` channel the open path uses.
    poster: Option<Arc<dyn AppEventPoster>>,
    window_id: TeksiloWindowId,
    web_view_id: WebViewId,
}

impl WebViewHandle for WryHandle {
    fn set_bounds(&self, bounds: Rect, scale_factor: f32) {
        // On Linux the subview is a WebKitGTK child window using integer GDK
        // scaling (GDK_SCALE), which ignores the fractional factor wgpu renders
        // at — so logical bounds land at the wrong place and size. Convert to
        // device pixels (logical × scale) and pass them as Physical so the
        // child lands correctly regardless of GTK's own scale. macOS WKWebView
        // / Windows WebView2 position in logical units and handle DPI
        // themselves, so keep the proven logical path there.
        #[cfg(target_os = "linux")]
        let rect = wry::Rect {
            position: wry::dpi::PhysicalPosition::new(
                (bounds.x * scale_factor) as f64,
                (bounds.y * scale_factor) as f64,
            )
            .into(),
            size: wry::dpi::PhysicalSize::new(
                (bounds.width * scale_factor) as f64,
                (bounds.height * scale_factor) as f64,
            )
            .into(),
        };
        #[cfg(not(target_os = "linux"))]
        let rect = {
            let _ = scale_factor;
            wry::Rect {
                position: LogicalPosition::new(bounds.x, bounds.y).into(),
                size: LogicalSize::new(bounds.width, bounds.height).into(),
            }
        };
        let _ = self.webview.set_bounds(rect);
    }
    fn load_url(&self, url: &str) {
        let _ = self.webview.load_url(url);
    }
    fn load_html(&self, html: &str, _base_url: Option<&str>) {
        // wry 0.55 has no runtime load_html; emulate via document.write so a
        // post-open HTML swap still works.
        let _ = self.webview.evaluate_script(&format!(
            "document.open();document.write({});document.close();",
            js_string(html)
        ));
    }
    fn eval(&self, script: &str) {
        let _ = self.webview.evaluate_script(script);
    }
    fn post_message(&self, msg: &str) {
        // Rust → JS: dispatch a `teksilo-message` event carrying `msg` as data.
        let _ = self.webview.evaluate_script(&format!(
            "window.dispatchEvent(new MessageEvent('teksilo-message',{{data:{}}}))",
            js_string(msg)
        ));
    }
    fn reload(&self) {
        let _ = self.webview.reload();
    }
    fn go_back(&self) {
        let _ = self.webview.evaluate_script("history.back()");
    }
    fn go_forward(&self) {
        let _ = self.webview.evaluate_script("history.forward()");
    }
    fn stop(&self) {
        let _ = self.webview.evaluate_script("window.stop()");
    }
    fn set_visible(&self, visible: bool) {
        let _ = self.webview.set_visible(visible);
    }
    fn set_focus(&self) {
        let _ = self.webview.focus();
    }
    fn set_input_passthrough(&self, passthrough: bool) {
        if !passthrough {
            // Native input is this engine's only mode, so being asked for it is
            // not worth a diagnostic.
            return;
        }
        post_event(
            &self.poster,
            self.window_id,
            self.web_view_id,
            WebViewEvent::ConsoleMessage {
                level: ConsoleLevel::Warn,
                text: "WryBackend: input pass-through is unsupported — this engine \
                       exposes no control over its surface's hit region, so the page \
                       keeps taking presses over its own rectangle"
                    .to_string(),
            },
        );
    }
    fn open_devtools(&self) {
        self.webview.open_devtools();
    }
    fn close_devtools(&self) {
        self.webview.close_devtools();
    }
}