@livx.cc/appwrap 0.46.1 → 0.46.2

package/runtime-desktop/crates/webview-control/examples/host_harness.rs

@@ -0,0 +1,245 @@
+//! Phase-2 host harness — proves a live WKWebView tears off (ChildOf pane -> TopLevel window) and
+//! docks back (-> ChildOf pane) with page + WKWebsiteDataStore session (localStorage marker) +
+//! WKScriptMessageHandler bridge all intact, driven THROUGH the embedded in-process API
+//! (`webview_control::embedded::Controller`) — driving-adapter (a), no socket.
+//!
+//! Run: `cargo run --example host_harness`  (macOS; add `-- --hold` to keep windows up for a look).
+//!
+//! It is a minimal bare-AppKit host: it owns a pane NSView inside a plain NSWindow (mirroring what a
+//! Tauri pane / unclaw-app pane provides), serves a loopback page from an in-process HTTP server
+//! (opaque about:/data: origins can't use localStorage), then runs the assertion sequence and exits
+//! non-zero on any failure. The AppKit main runloop is pumped manually so each async step
+//! (callAsyncJavaScript / page load / bridge post) completes before the next.
+
+use std::cell::RefCell;
+use std::ffi::c_void;
+use std::io::{Read, Write};
+use std::net::TcpListener;
+use std::rc::Rc;
+use std::sync::mpsc::{channel, Receiver};
+use std::time::{Duration, Instant};
+
+use objc2::rc::Retained;
+use objc2::MainThreadMarker;
+use objc2_app_kit::{
+    NSApplication, NSApplicationActivationPolicy, NSBackingStoreType, NSView, NSWindow,
+    NSWindowStyleMask,
+};
+use objc2_foundation::{
+    NSDate, NSDefaultRunLoopMode, NSPoint, NSRect, NSRunLoop, NSSize, NSString,
+};
+
+use webview_control::embedded::Controller;
+use webview_control::{CreateSpec, Mount, ViewHandle};
+
+/// Pump the AppKit main runloop for up to `secs`, returning early once `done()` is true.
+fn pump_until(secs: f64, mut done: impl FnMut() -> bool) {
+    let rl = NSRunLoop::currentRunLoop();
+    let deadline = Instant::now() + Duration::from_secs_f64(secs);
+    while Instant::now() < deadline {
+        if done() {
+            return;
+        }
+        let until = NSDate::dateWithTimeIntervalSinceNow(0.05);
+        unsafe { rl.runMode_beforeDate(NSDefaultRunLoopMode, &until) };
+    }
+}
+
+fn pump(secs: f64) {
+    pump_until(secs, || false);
+}
+
+/// Synchronous eval through the embedded Controller: fire callAsyncJavaScript and pump until the
+/// completion block lands (or timeout). Returns the RAW return string.
+fn eval(ctrl: &Controller, mtm: MainThreadMarker, id: &str, js: &str) -> Result<String, String> {
+    let slot: Rc<RefCell<Option<Result<String, String>>>> = Rc::new(RefCell::new(None));
+    let s2 = slot.clone();
+    ctrl.eval_async(mtm, id, js.to_string(), move |r| *s2.borrow_mut() = Some(r));
+    pump_until(8.0, || slot.borrow().is_some());
+    let out = slot.borrow_mut().take();
+    out.unwrap_or(Err("eval timed out".into()))
+}
+
+/// Start a throwaway loopback HTTP server; returns its `http://127.0.0.1:PORT/` URL. The page just
+/// carries a stable title — the session marker is written via localStorage by the harness.
+fn start_loopback() -> String {
+    let listener = TcpListener::bind("127.0.0.1:0").expect("bind loopback");
+    let addr = listener.local_addr().unwrap();
+    std::thread::spawn(move || {
+        let body = "<!doctype html><html><head><title>HOST-HARNESS-PAGE</title></head>\
+            <body style=\"margin:0;background:#0b5;color:#fff;font:700 40px system-ui;\
+            display:flex;align-items:center;justify-content:center;height:100vh\">\
+            <div id=\"tag\">HOST-HARNESS-LIVE</div></body></html>";
+        for stream in listener.incoming() {
+            let Ok(mut s) = stream else { continue };
+            let mut buf = [0u8; 1024];
+            let _ = s.read(&mut buf);
+            let resp = format!(
+                "HTTP/1.1 200 OK\r\nContent-Type: text/html\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",
+                body.len(),
+                body
+            );
+            let _ = s.write_all(resp.as_bytes());
+        }
+    });
+    format!("http://{addr}/")
+}
+
+fn main() {
+    let mtm = MainThreadMarker::new().expect("host_harness must run on the main thread");
+
+    // Scratch profile dir so we don't touch the real appwrap-desktop store.
+    let scratch = std::env::temp_dir().join(format!("webview-control-harness-{}", std::process::id()));
+    std::env::set_var("APPWRAP_PROFILE_DIR", &scratch);
+
+    // AppKit host app (accessory: no Dock icon; we pump the runloop manually rather than app.run()).
+    let app = NSApplication::sharedApplication(mtm);
+    app.setActivationPolicy(NSApplicationActivationPolicy::Accessory);
+    let _ = app.finishLaunching();
+
+    // The HOST-owned pane: a plain NSWindow whose content view is the container the tab docks into.
+    let pane_rect = NSRect::new(NSPoint::new(0.0, 0.0), NSSize::new(900.0, 640.0));
+    let style = NSWindowStyleMask::Titled | NSWindowStyleMask::Closable | NSWindowStyleMask::Resizable;
+    let pane_window = unsafe {
+        NSWindow::initWithContentRect_styleMask_backing_defer(
+            mtm.alloc::<NSWindow>(),
+            pane_rect,
+            style,
+            NSBackingStoreType::Buffered,
+            false,
+        )
+    };
+    unsafe {
+        pane_window.setReleasedWhenClosed(false);
+        pane_window.setTitle(&NSString::from_str("[host pane]"));
+    }
+    let pane = NSView::initWithFrame(mtm.alloc::<NSView>(), pane_rect);
+    pane_window.setContentView(Some(&pane));
+    pane_window.center();
+    pane_window.makeKeyAndOrderFront(None);
+    let pane_handle = unsafe { ViewHandle::from_ptr(Retained::as_ptr(&pane) as *mut c_void) };
+
+    let page_url = start_loopback();
+    let id = "harness-tab";
+    let ctrl = Controller::new();
+
+    // Bridge sink: the crate hands us RAW page->host payloads; capture them to prove the
+    // WKScriptMessageHandler survives reparenting.
+    let (tx, rx): (_, Receiver<String>) = channel();
+    let sink = Box::new(move |raw: String| {
+        let _ = tx.send(raw);
+    });
+
+    // (1) Create the tab as a CHILD of the host pane — an embedded in-app browser tab.
+    println!("== create_webview ChildOf(pane) id={id} url={page_url}");
+    let created = ctrl.create_webview(
+        mtm,
+        CreateSpec {
+            label: id.to_string(),
+            url: page_url.clone(),
+            profile_id: "harness".to_string(),
+            init_js: String::new(),
+            mount: Mount::ChildOf(pane_handle),
+        },
+        sink,
+    );
+    match &created {
+        Ok(c) => println!("   created: persistent={} store={}", c.persistent, c.store_uuid),
+        Err(e) => {
+            eprintln!("FAIL: create_webview: {e}");
+            std::process::exit(1);
+        }
+    }
+    pump(3.0); // let the page load
+
+    // (2) Write the session marker + capture page identity while CHILD.
+    let set = eval(
+        &ctrl,
+        mtm,
+        id,
+        "localStorage.setItem('marker','HOST-HARNESS-SESSION-77'); \
+         return JSON.stringify({href:location.href,title:document.title,marker:localStorage.getItem('marker')});",
+    );
+    println!("== child, marker set: {set:?}");
+
+    // (3) Bridge ping while CHILD.
+    let _ = eval(&ctrl, mtm, id, "webkit.messageHandlers.bridgeShim.postMessage('PING-CHILD'); return 'posted';");
+    pump(0.5);
+
+    // (4) TEAR OFF -> TopLevel window.
+    println!("== set_mount TopLevel (tear off)");
+    if !ctrl.set_mount(mtm, id, Mount::TopLevel) {
+        eprintln!("FAIL: set_mount TopLevel returned false");
+        std::process::exit(1);
+    }
+    pump(1.5);
+
+    // (5) DOCK BACK -> ChildOf(pane).
+    println!("== set_mount ChildOf(pane) (dock back)");
+    if !ctrl.set_mount(mtm, id, Mount::ChildOf(pane_handle)) {
+        eprintln!("FAIL: set_mount ChildOf returned false");
+        std::process::exit(1);
+    }
+    pump(1.5);
+
+    // (6) After child->toplevel->child: read page identity + marker back, and ping the bridge again.
+    let after = eval(
+        &ctrl,
+        mtm,
+        id,
+        "return JSON.stringify({href:location.href,title:document.title,marker:localStorage.getItem('marker')});",
+    );
+    println!("== after reparent cycle, read-back: {after:?}");
+    let _ = eval(&ctrl, mtm, id, "webkit.messageHandlers.bridgeShim.postMessage('PING-AFTER'); return 'posted';");
+    pump(0.5);
+
+    // ---- assertions ----
+    let after = match after {
+        Ok(s) => s,
+        Err(e) => {
+            eprintln!("FAIL: read-back eval error after reparent: {e}");
+            std::process::exit(1);
+        }
+    };
+    let page_ok = after.contains("HOST-HARNESS-PAGE"); // document.title preserved (page not reloaded/lost)
+    let session_ok = after.contains("HOST-HARNESS-SESSION-77"); // localStorage marker survived
+    let pings: Vec<String> = rx.try_iter().collect();
+    let bridge_ok = pings.iter().any(|p| p == "PING-CHILD") && pings.iter().any(|p| p == "PING-AFTER");
+
+    println!("\n---- Phase-2 embedded-API reparent assertions ----");
+    println!("page   survived (title HOST-HARNESS-PAGE): {page_ok}");
+    println!("session survived (marker 77):             {session_ok}");
+    println!("bridge  survived (pings {:?}):             {bridge_ok}", pings);
+
+    if std::env::args().any(|a| a == "--hold") {
+        println!("(--hold) leaving windows up 20s for inspection…");
+        pump(20.0);
+    }
+    // ---- zombie-close gate ----
+    // The tab is currently docked ChildOf(pane) (step 5/6). BEFORE close it is a subview of the host
+    // pane; AFTER close() the pane MUST have ZERO subviews — i.e. the WKWebView is actually gone from
+    // the host view tree, not left alive+visible as a zombie. This machine-gates the Phase-2 HIGH bug
+    // where close() only called window.close() and never removeFromSuperview() on the embedded webview.
+    let before_close = pane.subviews().count();
+    println!("\n== host pane subview count BEFORE close: {before_close} (expect 1: the docked tab)");
+    let _ = ctrl.close(mtm, id);
+    pump(0.5); // let AppKit settle the view-tree mutation
+    let after_close = pane.subviews().count();
+    println!("== host pane subview count AFTER close:  {after_close} (expect 0: tab detached)");
+    let pane_empty_ok = after_close == 0;
+
+    println!("pane empty after close (no zombie webview):  {pane_empty_ok}");
+
+    if page_ok && session_ok && bridge_ok && pane_empty_ok {
+        println!("\nPASS: live webview reparented child->toplevel->child via EMBEDDED API; page+session+bridge intact; host pane empty after close.");
+    } else {
+        if !pane_empty_ok {
+            eprintln!(
+                "\nFAIL: ZOMBIE WEBVIEW — host pane still has {after_close} subview(s) after close(); \
+                 the embedded WKWebView was not removed from the host view tree."
+            );
+        }
+        eprintln!("\nFAIL: one or more invariants did not survive reparent.");
+        std::process::exit(1);
+    }
+}

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

@@ -0,0 +1,100 @@
+//! 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) }
+    }
+
+    /// 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,95 @@
+//! 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, eval_async, inject_script,
+    install_message_handler, list_webviews, navigate, profile_webview, set_mount, snapshot,
+    user_close, CreateResult, CreateSpec, MessageSink, WebviewInfo,
+};