@livx.cc/appwrap 0.46.1 → 0.46.3

package/runtime-desktop/crates/webview-control/src/embedded.rs

@@ -0,0 +1,121 @@
+//! Driving adapter (a): the in-process Rust API for EMBEDDED hosts (para-chat / unclaw-app).
+//!
+//! Same command surface as the control-channel adapter (bridge_mac.rs, driving adapter (b)) but
+//! with NO socket, NO JSON framing — a plain Rust object over the one `WebviewControl` contract.
+//! An embedded host that links this crate creates an in-app browser tab as `ChildOf(paneView)` and
+//! tears it out / docks it back with `set_mount` — the same live WKWebView, session + bridge intact.
+//!
+//! Threading: every method takes a `MainThreadMarker` and runs synchronously on the AppKit main
+//! thread. The facade deliberately has NO built-in `run_on_main_thread` — the host owns marshalling
+//! (Tauri's `run_on_main_thread`, or being called from the main runloop). WKWebView/NSView are not
+//! thread-safe, and the crate must not assume a Tauri `AppHandle`.
+
+use objc2::rc::Retained;
+use objc2::MainThreadMarker;
+use objc2_web_kit::WKWebView;
+
+use crate::wkwebview_backend as backend;
+use crate::{CreateResult, CreateSpec, MessageSink, Mount, WebviewInfo};
+
+/// In-process facade over the webview primitive. Stateless — the webview registry is a crate-level
+/// static — so it is a zero-cost handle the host can construct freely.
+#[derive(Clone, Copy, Default)]
+pub struct Controller;
+
+impl Controller {
+    pub fn new() -> Self {
+        Controller
+    }
+
+    /// Create a webview mounted per `spec.mount` (`ChildOf(pane)` for an embedded tab). `on_message`
+    /// receives RAW page->host payloads (`webkit.messageHandlers.bridgeShim.postMessage`).
+    pub fn create_webview(
+        &self,
+        mtm: MainThreadMarker,
+        spec: CreateSpec,
+        on_message: MessageSink,
+    ) -> Result<CreateResult, String> {
+        backend::create_webview(mtm, spec, on_message)
+    }
+
+    /// Tear-off / dock: move the live webview between `TopLevel` and `ChildOf(pane)`. False if unknown.
+    pub fn set_mount(&self, mtm: MainThreadMarker, id: &str, mount: Mount) -> bool {
+        backend::set_mount(mtm, id, mount)
+    }
+
+    /// Navigate the webview `id` to `url`. Err if `id` is unknown/closed.
+    pub fn navigate(&self, _mtm: MainThreadMarker, id: &str, url: &str) -> Result<(), String> {
+        let wk = self.webview(id)?;
+        unsafe { backend::navigate(Retained::as_ptr(&wk) as *mut WKWebView, url) }
+    }
+
+    /// Navigate back in webview `id`'s history. Err if `id` is unknown/closed.
+    pub fn go_back(&self, _mtm: MainThreadMarker, id: &str) -> Result<(), String> {
+        let wk = self.webview(id)?;
+        unsafe { backend::go_back(Retained::as_ptr(&wk) as *mut WKWebView) };
+        Ok(())
+    }
+
+    /// Navigate forward in webview `id`'s history. Err if `id` is unknown/closed.
+    pub fn go_forward(&self, _mtm: MainThreadMarker, id: &str) -> Result<(), String> {
+        let wk = self.webview(id)?;
+        unsafe { backend::go_forward(Retained::as_ptr(&wk) as *mut WKWebView) };
+        Ok(())
+    }
+
+    /// Reload webview `id`. Err if `id` is unknown/closed.
+    pub fn reload(&self, _mtm: MainThreadMarker, id: &str) -> Result<(), String> {
+        let wk = self.webview(id)?;
+        unsafe { backend::reload(Retained::as_ptr(&wk) as *mut WKWebView) };
+        Ok(())
+    }
+
+    /// Fire-and-forget JS injection into webview `id`. Err if `id` is unknown/closed.
+    pub fn inject_script(&self, _mtm: MainThreadMarker, id: &str, js: &str) -> Result<(), String> {
+        let wk = self.webview(id)?;
+        unsafe { backend::inject_script(Retained::as_ptr(&wk) as *mut WKWebView, js) };
+        Ok(())
+    }
+
+    /// CSP-immune eval (callAsyncJavaScript, `js` is a function body). Delivers the RAW return
+    /// string via `on_done` on the main thread. Err (via `on_done`) if `id` is unknown/closed.
+    pub fn eval_async(
+        &self,
+        _mtm: MainThreadMarker,
+        id: &str,
+        js: String,
+        on_done: impl FnOnce(Result<String, String>) + 'static,
+    ) {
+        match self.webview(id) {
+            Ok(wk) => unsafe { backend::eval_async(Retained::as_ptr(&wk) as *mut WKWebView, js, on_done) },
+            Err(e) => on_done(Err(e)),
+        }
+    }
+
+    /// Snapshot webview `id` to PNG bytes via `on_done` on the main thread.
+    pub fn snapshot(
+        &self,
+        _mtm: MainThreadMarker,
+        id: &str,
+        on_done: impl FnOnce(Result<Vec<u8>, String>) + 'static,
+    ) {
+        match self.webview(id) {
+            Ok(wk) => unsafe { backend::snapshot(Retained::as_ptr(&wk) as *mut WKWebView, on_done) },
+            Err(e) => on_done(Err(e)),
+        }
+    }
+
+    /// Close + drop the webview `id` (releases its window + view). False if unknown.
+    pub fn close(&self, _mtm: MainThreadMarker, id: &str) -> bool {
+        backend::close(id)
+    }
+
+    /// Live (non-closed) webviews.
+    pub fn list_webviews(&self) -> Vec<WebviewInfo> {
+        backend::list_webviews()
+    }
+
+    fn webview(&self, id: &str) -> Result<Retained<WKWebView>, String> {
+        backend::profile_webview(id).ok_or_else(|| format!("no webview {id}"))
+    }
+}

package/runtime-desktop/crates/webview-control/src/lib.rs

@@ -0,0 +1,99 @@
+//! webview-control — appwrap's generalized, automation-agnostic native webview primitive.
+//!
+//! Carved out of `src-tauri/src/bridge_mac.rs` (Phase 1). It owns the parts that MUST be native +
+//! in-process + appwrap-owned because `WKWebsiteDataStore` is immutable post-webview-creation:
+//! per-profile persistent+isolated stores, manual NSWindow+WKWebView creation, CSP-immune eval,
+//! snapshot, the `bridgeShim` WKScriptMessageHandler, and the SSO-popup delegate.
+//!
+//! Seam purity: the primitive emits RAW page payloads (`MessageSink`) and RAW eval/snapshot results
+//! (per-call `on_done` callbacks). It holds NO bod-browser protocol, transport `Sender`, or
+//! `{type:"pageMsg"}` / `{id,result}` framing — those live in the control-channel adapter
+//! (`bridge_mac.rs`). The `WkWebViewBackend` is macOS-only; a `WebKitGtkBackend` is a future slot.
+//!
+//! Two driving adapters over ONE contract:
+//! - (a) [`embedded::Controller`] — in-process Rust API for EMBEDDED hosts (para-chat / unclaw-app);
+//!       creates tabs as [`Mount::ChildOf`] a host pane and tears off / docks with [`set_mount`].
+//! - (b) the control-channel socket (`bridge_mac.rs`) — standalone / MCP; only ever [`Mount::TopLevel`].
+//!
+//! Cross-repo consumption (R1, resolved Phase 2): external hosts pin this crate as a **git dependency
+//! on a tagged appwrap rev** — `webview-control = { git = ".../appwrap", tag = "webview-control-vX" }`
+//! (no crates.io publish). appwrap-generated apps (unclaw-app) already get it via the whole-tree
+//! `native-desktop` copy; para-chat's hand-maintained `src-tauri` adds the git dep directly. objc2*
+//! versions come pinned by the tagged rev so the `*mut WKWebView`/`*mut NSView` pointers that cross
+//! this boundary never hit an ABI mismatch.
+
+#[cfg(target_os = "macos")]
+pub mod embedded;
+#[cfg(target_os = "macos")]
+pub mod popup;
+#[cfg(target_os = "macos")]
+mod profiles;
+#[cfg(target_os = "macos")]
+mod wkwebview_backend;
+
+use std::ffi::c_void;
+
+/// Opaque handle to a host-owned `NSView` that a webview can be mounted inside (Phase 2).
+///
+/// # Safety contract
+/// The wrapped pointer MUST be a valid `NSView*` (or subclass) for the ENTIRE time a webview is
+/// mounted in it. The caller guarantees, and the crate relies on, all of:
+/// - **Validity:** a live `NSView` created and retained by the *host* (e.g. a Tauri pane's
+///   `ns_view()` / an AppKit container). Never a dangling, freed, or non-`NSView` pointer.
+/// - **Main-thread only:** the handle is created, passed, and dereferenced ONLY on the AppKit main
+///   thread. `ViewHandle` is intentionally `!Send`/`!Sync` — it must not cross threads.
+/// - **Host-owned lifetime:** the host owns the pane and MUST NOT drop/free it while a webview is
+///   mounted in it. Reparent the webview out (`set_mount(TopLevel)`) or `close` it BEFORE tearing
+///   down the pane. The crate holds only a borrow-strength AppKit subview link, not ownership of
+///   the host pane.
+/// - **Laid-out bounds (Phase-3 landmine a):** fetch the `NSView*` and mount `ChildOf` it only
+///   AFTER the pane has been laid out (non-zero `bounds`). The webview is framed to the pane's
+///   bounds at mount; a zero-bounds pane (handle taken before layout) renders BLANK until a resize.
+///   Take the handle post-layout, on the main thread.
+/// - **objc2 ABI match (Phase-3 landmine b):** a host with its OWN `wry`/`objc2` tree (e.g.
+///   para-chat's `src-tauri`) MUST resolve `objc2*` to the SAME `0.6.x` this crate is built against
+///   (pinned by the tagged rev). A divergent objc2 makes the `*mut NSView` pointer cast UB in the
+///   host's tree — pin/dedupe objc2 across the workspace, don't just add the git dep.
+#[derive(Clone, Copy)]
+pub struct ViewHandle(*mut c_void);
+
+impl ViewHandle {
+    /// Wrap a raw host `NSView*`. See the type-level safety contract — the caller upholds validity,
+    /// main-thread affinity, and host-owned lifetime.
+    ///
+    /// # Safety
+    /// `ptr` must be a valid `NSView*` per the [`ViewHandle`] contract.
+    pub unsafe fn from_ptr(ptr: *mut c_void) -> Self {
+        ViewHandle(ptr)
+    }
+
+    /// The raw `NSView*`. Main-thread only.
+    pub fn as_ptr(self) -> *mut c_void {
+        self.0
+    }
+}
+
+/// Where a webview lives in the AppKit view tree (Phase 2 tear-off / dock).
+/// - `TopLevel` — the webview owns/fills its own `NSWindow` content view (the standalone/MCP shape;
+///   the only mount the control-channel adapter ever requests, so its behavior is unchanged).
+/// - `ChildOf(handle)` — the webview is a subview of a host-owned pane `NSView`; the same live
+///   `WKWebView` (page + `WKWebsiteDataStore` session + bridge) survives moving between the two.
+#[derive(Clone, Copy)]
+pub enum Mount {
+    TopLevel,
+    ChildOf(ViewHandle),
+}
+
+// The Phase-1 primitive surface — a flat, transport-free command set the control-channel adapter
+// drives — plus the Phase-2 reparent op (`set_mount`) and the embedded facade (`embedded::Controller`).
+// See ARCHITECTURE.md for the full contract.
+#[cfg(target_os = "macos")]
+pub use wkwebview_backend::{
+    close, create_profile_window, create_webview, devtools_enabled, eval_async, go_back, go_forward,
+    inject_script, install_message_handler, list_webviews, navigate, profile_webview, reload,
+    set_inspectable, set_mount, snapshot, user_close, CreateResult, CreateSpec, MessageSink,
+    WebviewInfo,
+};
+
+#[cfg(target_os = "macos")]
+pub use profiles::list as list_profiles;