@livx.cc/appwrap 0.46.1 → 0.46.3

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

@@ -0,0 +1,540 @@
+// WKWebView adapter for the webview-control primitive (macOS). Lifted from bridge_mac.rs
+// (Phase 1 extraction) with the transport/protocol stripped OUT: this module emits RAW page
+// payloads via an `on_message` callback and RAW eval/snapshot results via per-call `on_done`
+// callbacks. It knows nothing of the bod-browser wire format, the TCP Sender, or the
+// {type:"pageMsg"} / {id,result} framing — those live in the control-channel adapter (bridge_mac.rs).
+use std::cell::RefCell;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Mutex;
+
+use objc2::rc::Retained;
+use objc2::runtime::AnyObject;
+use objc2::runtime::ProtocolObject;
+use objc2::{define_class, msg_send, AnyThread, DefinedClass, MainThreadMarker, MainThreadOnly};
+use objc2_app_kit::{
+    NSAutoresizingMaskOptions, NSBackingStoreType, NSBitmapImageFileType, NSBitmapImageRep, NSImage,
+    NSView, NSWindow, NSWindowDelegate, NSWindowStyleMask,
+};
+use objc2_foundation::{
+    NSDictionary, NSError, NSNotification, NSObject, NSObjectProtocol, NSPoint, NSRect, NSSize,
+    NSString, NSURL, NSURLRequest, NSUUID,
+};
+use objc2_web_kit::{
+    WKContentWorld, WKScriptMessage, WKScriptMessageHandler, WKUserContentController, WKUserScript,
+    WKUserScriptInjectionTime, WKWebView, WKWebViewConfiguration, WKWebsiteDataStore,
+};
+
+use crate::popup;
+use crate::profiles;
+use crate::Mount;
+
+/// True when webviews should be Safari-inspectable (Develop ▸ <app> ▸ Web Inspector). Debug builds
+/// are ALWAYS inspectable; a release build is inspectable ONLY when `APPWRAP_DEVTOOLS` is set to
+/// `1`/`true` — so production apps aren't inspectable by default. Self-contained in this crate (no
+/// shell-config dependency) so every webview creation site can gate uniformly.
+pub fn devtools_enabled() -> bool {
+    cfg!(debug_assertions)
+        || matches!(std::env::var("APPWRAP_DEVTOOLS").ok().as_deref(), Some("1") | Some("true"))
+}
+
+/// Flip a WKWebView's `inspectable` property ON when [`devtools_enabled`], making it attachable from
+/// Safari → Develop. The property lands in macOS 13.3+, so it's guarded by `respondsToSelector:` and
+/// no-ops on older systems. Set right after webview creation, on the main thread. `wk` must be a live
+/// `*mut WKWebView`.
+pub unsafe fn set_inspectable(wk: *mut WKWebView) {
+    if wk.is_null() || !devtools_enabled() {
+        return;
+    }
+    let wk = &*wk;
+    let sel = objc2::sel!(setInspectable:);
+    let responds: bool = msg_send![wk, respondsToSelector: sel];
+    if responds {
+        let _: () = msg_send![wk, setInspectable: true];
+    }
+}
+
+/// Autoresizing mask that pins a mounted webview to fill its superview on resize — the same
+/// width+height-sizable mask popup windows use, applied on every (re)mount.
+const FILL_MASK: NSAutoresizingMaskOptions =
+    NSAutoresizingMaskOptions(NSAutoresizingMaskOptions::ViewWidthSizable.0 | NSAutoresizingMaskOptions::ViewHeightSizable.0);
+
+/// Raw page->host message sink. Receives the UNWRAPPED WKScriptMessage body string (the page's
+/// `webkit.messageHandlers.bridgeShim.postMessage(...)` payload). The adapter wraps it into its
+/// transport envelope — the primitive stays framing-agnostic. `Send` (it crosses onto the main
+/// thread with the create op) but not `Sync` — the handler is MainThreadOnly and only ever invoked
+/// on the main thread, mirroring the original bare `Sender`.
+pub type MessageSink = Box<dyn Fn(String) + Send>;
+
+/// Result of creating a profile window — the store facts the harness asserts. The adapter builds
+/// the wire JSON from this; the primitive returns plain data.
+pub struct CreateResult {
+    pub persistent: bool,
+    pub store_uuid: String,
+}
+
+/// One profile window's public identity for `list_webviews`.
+pub struct WebviewInfo {
+    pub label: String,
+    pub profile_id: String,
+}
+
+/// Spec for creating a webview via the embedded facade (Phase 2). Mirrors the control-channel
+/// `createWindow` op fields plus the `mount` target (the adapter always builds `Mount::TopLevel`).
+pub struct CreateSpec {
+    pub label: String,
+    pub url: String,
+    pub profile_id: String,
+    pub init_js: String,
+    pub mount: Mount,
+}
+
+// ---------------------------------------------------------------------------
+// Page -> host transport: a native WKScriptMessageHandler ("bridgeShim").
+// WebKit blocks ws://127.0.0.1 (and http beacons) from https pages as mixed content — NO loopback
+// exemption like Chrome — so the content layer posts results via
+// webkit.messageHandlers.bridgeShim.postMessage(json) instead. We hand the RAW payload to the
+// on_message sink; the adapter does the framing.
+// ---------------------------------------------------------------------------
+pub struct MsgHandlerIvars {
+    on_message: MessageSink,
+}
+
+define_class!(
+    #[unsafe(super(NSObject))]
+    #[thread_kind = MainThreadOnly]
+    #[name = "AppwrapBridgeMsgHandler"]
+    #[ivars = MsgHandlerIvars]
+    struct MsgHandler;
+
+    unsafe impl NSObjectProtocol for MsgHandler {}
+
+    unsafe impl WKScriptMessageHandler for MsgHandler {
+        #[unsafe(method(userContentController:didReceiveScriptMessage:))]
+        fn did_receive(&self, _ucc: &WKUserContentController, message: &WKScriptMessage) {
+            let body = unsafe { message.body() };
+            if let Ok(s) = body.downcast::<NSString>() {
+                (self.ivars().on_message)(s.to_string());
+            }
+        }
+    }
+);
+
+/// Install the bridgeShim WKScriptMessageHandler on an arbitrary WKWebView (used by the adapter for
+/// the legacy tauri-window path — the profile-window path installs it on the config's UCC before
+/// creation). The UCC retains the handler, so no external retention is needed here. Main-thread only.
+pub unsafe fn install_message_handler(wk: *mut WKWebView, mtm: MainThreadMarker, on_message: MessageSink) {
+    let wk = &*wk;
+    let handler = MsgHandler::alloc(mtm).set_ivars(MsgHandlerIvars { on_message });
+    let handler: Retained<MsgHandler> = msg_send![super(handler), init];
+    let ucc = wk.configuration().userContentController();
+    ucc.addScriptMessageHandler_name(
+        ProtocolObject::from_ref(&*handler),
+        &NSString::from_str("bridgeShim"),
+    );
+}
+
+/// A manually-created profile window. Strong refs kept alive until close (or windowWillClose).
+/// Only touched on the main thread; the unsafe Send exists solely so the registry can be a static
+/// Mutex (same pattern as popup_mac).
+struct ProfileWindow {
+    label: String,
+    profile_id: String,
+    window: Retained<NSWindow>,
+    webview: Retained<WKWebView>,
+    /// Set true by the window-close delegate on a USER (red-button) close.
+    closed: AtomicBool,
+    _handler: Retained<MsgHandler>,
+    /// Per-window SSO-popup delegate (weak uiDelegate → held here). Opaque; lifetime only.
+    _popup_delegate: Retained<AnyObject>,
+    /// NSWindowDelegate that flags `closed` on a user close (weak setDelegate → held here).
+    _win_delegate: Retained<ProfileWinDelegate>,
+}
+unsafe impl Send for ProfileWindow {}
+static PROFILE_WINDOWS: Mutex<Vec<ProfileWindow>> = Mutex::new(Vec::new());
+
+// NSWindowDelegate for profile windows — flags the matching registry entry `closed` when the user
+// closes the window (red button), so it drops out of list_webviews. Matches by NSWindow identity
+// (the notification's object). Main-thread only.
+define_class!(
+    #[unsafe(super(NSObject))]
+    #[thread_kind = MainThreadOnly]
+    #[name = "AppwrapProfileWinDelegate"]
+    struct ProfileWinDelegate;
+
+    unsafe impl NSObjectProtocol for ProfileWinDelegate {}
+
+    unsafe impl NSWindowDelegate for ProfileWinDelegate {
+        #[unsafe(method(windowWillClose:))]
+        fn window_will_close(&self, notification: &NSNotification) {
+            let Some(obj) = notification.object() else { return };
+            let key = Retained::as_ptr(&obj) as usize;
+            let v = PROFILE_WINDOWS.lock().unwrap();
+            if let Some(p) = v.iter().find(|p| Retained::as_ptr(&p.window) as usize == key) {
+                eprintln!("[bridge-shim] profile window {} user-closed", p.label);
+                // Detach from the superview so a ChildOf-mounted webview isn't left as a zombie in
+                // the host pane once `reap_closed` drops the registry `Retained` (see `close`).
+                p.webview.removeFromSuperview();
+                p.closed.store(true, Ordering::Relaxed);
+            }
+        }
+    }
+);
+
+/// Retained clone of a profile window's WKWebView (op routing), or None if the label is unknown /
+/// already closed. The adapter uses this to decide whether an op targets a profile window (else it
+/// falls back to its legacy tauri path).
+pub fn profile_webview(label: &str) -> Option<Retained<WKWebView>> {
+    PROFILE_WINDOWS
+        .lock()
+        .unwrap()
+        .iter()
+        .find(|p| p.label == label && !p.closed.load(Ordering::Relaxed))
+        .map(|p| p.webview.clone())
+}
+
+/// Public identities of the live (non-closed) profile windows.
+pub fn list_webviews() -> Vec<WebviewInfo> {
+    PROFILE_WINDOWS
+        .lock()
+        .unwrap()
+        .iter()
+        .filter(|p| !p.closed.load(Ordering::Relaxed))
+        .map(|p| WebviewInfo { label: p.label.clone(), profile_id: p.profile_id.clone() })
+        .collect()
+}
+
+/// Drop entries flagged `closed` (user-closed windows). Called at safe points only — never from
+/// within a delegate callback, so the delegate isn't released mid-call.
+fn reap_closed() {
+    let mut v = PROFILE_WINDOWS.lock().unwrap();
+    v.retain(|p| !p.closed.load(Ordering::Relaxed));
+}
+
+/// Close + drop a profile window (releases its NSWindow + WKWebView). Main-thread only. Returns
+/// false if no such profile window (caller falls back to tauri). The removed entry is held on the
+/// stack across window.close() so its window delegate stays alive while AppKit fires windowWillClose.
+pub fn close(label: &str) -> bool {
+    let entry = {
+        let mut v = PROFILE_WINDOWS.lock().unwrap();
+        v.iter().position(|p| p.label == label).map(|i| v.remove(i))
+    };
+    match entry {
+        Some(p) => {
+            // Detach the WKWebView from its superview BEFORE dropping the registry `Retained`. In
+            // `Mount::ChildOf` (embedded) mode the webview is a subview of the HOST pane (retained
+            // by the host's subview array), NOT the home window's contentView — so `window.close()`
+            // alone leaves it alive and VISIBLE in the host pane (a zombie). Harmless for TopLevel
+            // (the webview IS the home window's contentView, released with the window anyway).
+            p.webview.removeFromSuperview();
+            p.window.close();
+            true
+        }
+        None => false,
+    }
+}
+
+/// Drive NSWindow performClose: (the red-button path) WITHOUT touching the registry, so the
+/// windowWillClose delegate is the sole remover — proves user-close hygiene headlessly. Returns
+/// false if no such profile window. Main-thread only.
+pub fn user_close(label: &str) -> bool {
+    let win = PROFILE_WINDOWS
+        .lock()
+        .unwrap()
+        .iter()
+        .find(|p| p.label == label)
+        .map(|p| p.window.clone());
+    match win {
+        Some(w) => {
+            w.performClose(None);
+            true
+        }
+        None => false,
+    }
+}
+
+/// Create a top-level profile window (the standalone/MCP shape — `Mount::TopLevel`). Thin wrapper
+/// over [`create_webview`]; kept as-is so the control-channel adapter (bridge_mac.rs) is unchanged
+/// and its behavior byte-identical. Main-thread only.
+pub fn create_profile_window(
+    mtm: MainThreadMarker,
+    label: &str,
+    url: &str,
+    profile_id: &str,
+    init_js: &str,
+    on_message: MessageSink,
+) -> Result<CreateResult, String> {
+    create_webview(
+        mtm,
+        CreateSpec {
+            label: label.to_string(),
+            url: url.to_string(),
+            profile_id: profile_id.to_string(),
+            init_js: init_js.to_string(),
+            mount: Mount::TopLevel,
+        },
+        on_message,
+    )
+}
+
+/// Create a manual NSWindow + WKWebView bound to `profile_id`'s persistent data store, inject the
+/// bridge content bundle + bridgeShim handler, mount it per `spec.mount`, and register it. Runs on
+/// the main thread (the adapter/host marshals it there). Returns the store facts.
+///
+/// The webview ALWAYS owns a hidden home `NSWindow` (the `TopLevel` target), created here with
+/// `setReleasedWhenClosed(false)` so a host-window close never frees the view. For `TopLevel` the
+/// window is shown and holds the webview as its content view (identical to the pre-Phase-2 path);
+/// for `ChildOf(handle)` the window stays unshown and the webview is added as a subview of the
+/// host-owned pane. `set_mount` later moves the same live `WKWebView` between the two.
+pub fn create_webview(
+    mtm: MainThreadMarker,
+    spec: CreateSpec,
+    on_message: MessageSink,
+) -> Result<CreateResult, String> {
+    let CreateSpec { label, url, profile_id, init_js, mount } = spec;
+    let (label, url, profile_id, init_js) = (label.as_str(), url.as_str(), profile_id.as_str(), init_js.as_str());
+    let uuid_str = profiles::uuid_for(profile_id);
+    let nsuuid = NSUUID::initWithUUIDString(NSUUID::alloc(), &NSString::from_str(&uuid_str))
+        .ok_or_else(|| format!("bad uuid for profile {profile_id}: {uuid_str}"))?;
+    let store = unsafe { WKWebsiteDataStore::dataStoreForIdentifier(&nsuuid, mtm) };
+    let persistent = unsafe { store.isPersistent() };
+
+    let cfg = unsafe { WKWebViewConfiguration::new(mtm) };
+    unsafe { cfg.setWebsiteDataStore(&store) };
+
+    // bridgeShim message handler + content bundle (documentStart) on this cfg's UCC.
+    let ucc = unsafe { cfg.userContentController() };
+    let handler = MsgHandler::alloc(mtm).set_ivars(MsgHandlerIvars { on_message });
+    let handler: Retained<MsgHandler> = unsafe { msg_send![super(handler), init] };
+    unsafe {
+        ucc.addScriptMessageHandler_name(
+            ProtocolObject::from_ref(&*handler),
+            &NSString::from_str("bridgeShim"),
+        );
+        let script = WKUserScript::initWithSource_injectionTime_forMainFrameOnly(
+            WKUserScript::alloc(mtm),
+            &NSString::from_str(init_js),
+            WKUserScriptInjectionTime::AtDocumentStart,
+            true,
+        );
+        ucc.addUserScript(&script);
+    }
+
+    let rect = NSRect::new(NSPoint::new(0.0, 0.0), NSSize::new(1100.0, 800.0));
+    let style = NSWindowStyleMask::Titled
+        | NSWindowStyleMask::Closable
+        | NSWindowStyleMask::Miniaturizable
+        | NSWindowStyleMask::Resizable;
+    let window = unsafe {
+        NSWindow::initWithContentRect_styleMask_backing_defer(
+            mtm.alloc::<NSWindow>(),
+            rect,
+            style,
+            NSBackingStoreType::Buffered,
+            false,
+        )
+    };
+    unsafe { window.setReleasedWhenClosed(false) };
+
+    let webview = unsafe {
+        WKWebView::initWithFrame_configuration(mtm.alloc::<WKWebView>(), window.frame(), &cfg)
+    };
+    unsafe {
+        webview.setCustomUserAgent(Some(&NSString::from_str(popup::SAFARI_UA)));
+        window.setTitle(&NSString::from_str(label));
+        // Safari Web Inspector (debug always; release only under APPWRAP_DEVTOOLS) for every
+        // bridge/profile/sub-window webview created through this primitive.
+        set_inspectable(Retained::as_ptr(&webview) as *mut WKWebView);
+    }
+
+    // Per-window SSO-popup delegate + window-close delegate. Both are weak refs on AppKit/WebKit →
+    // retained in the registry entry below.
+    let popup_delegate: Retained<AnyObject> =
+        popup::install_for_profile(Retained::as_ptr(&webview) as *mut std::ffi::c_void, mtm);
+    let win_delegate = ProfileWinDelegate::alloc(mtm).set_ivars(());
+    let win_delegate: Retained<ProfileWinDelegate> = unsafe { msg_send![super(win_delegate), init] };
+    window.setDelegate(Some(ProtocolObject::from_ref(&*win_delegate)));
+    window.center();
+
+    // Initial mount: TopLevel shows the home window with the webview as content view (the
+    // pre-Phase-2 behavior, byte-identical); ChildOf leaves the home window unshown and adds the
+    // webview into the host pane. Same reparent primitive as set_mount, applied at birth.
+    unsafe { mount_view(mtm, &webview, &window, mount) };
+
+    let nsurl = NSURL::URLWithString(&NSString::from_str(url))
+        .ok_or_else(|| format!("bad url: {url}"))?;
+    let req = NSURLRequest::requestWithURL(&nsurl);
+    let _ = unsafe { webview.loadRequest(&req) };
+
+    reap_closed();
+    PROFILE_WINDOWS.lock().unwrap().push(ProfileWindow {
+        label: label.to_string(),
+        profile_id: profile_id.to_string(),
+        window,
+        webview,
+        closed: AtomicBool::new(false),
+        _handler: handler,
+        _popup_delegate: popup_delegate,
+        _win_delegate: win_delegate,
+    });
+    eprintln!(
+        "[bridge-shim] profile window {label} profile={profile_id} store={uuid_str} persistent={persistent}"
+    );
+    Ok(CreateResult { persistent, store_uuid: uuid_str })
+}
+
+// ---------------------------------------------------------------------------
+// Phase 2: NSView-reparent (tear-off / dock). The SAME live WKWebView object is moved between its
+// home NSWindow (TopLevel) and a host-owned pane NSView (ChildOf) — page + WKWebsiteDataStore
+// session + WKScriptMessageHandler bridge + SSO uiDelegate all survive because it is never
+// re-created. Productionized from the Phase-0 spike. Main-thread only (WKWebView/NSView are not
+// thread-safe); zero-frame subviews render blank, so we always set frame = target bounds + a
+// fill autoresizing mask.
+// ---------------------------------------------------------------------------
+
+/// Reparent `webview` to `mount`, using `home_window` as the TopLevel target. Caller holds the
+/// main thread. `ChildOf` dereferences the host `NSView*` per the [`crate::ViewHandle`] contract.
+unsafe fn mount_view(
+    _mtm: MainThreadMarker,
+    webview: &WKWebView,
+    home_window: &NSWindow,
+    mount: Mount,
+) {
+    webview.removeFromSuperview();
+    match mount {
+        Mount::TopLevel => {
+            let size = home_window.frame().size;
+            webview.setFrame(NSRect::new(NSPoint::new(0.0, 0.0), size));
+            webview.setAutoresizingMask(FILL_MASK);
+            home_window.setContentView(Some(webview));
+            home_window.makeKeyAndOrderFront(None);
+        }
+        Mount::ChildOf(handle) => {
+            // The host owns this NSView; we only add a subview link (contract: valid, main-thread,
+            // host keeps it alive while mounted). Order the home window out so it isn't a stray.
+            let host = &*(handle.as_ptr() as *mut NSView);
+            let bounds = host.bounds();
+            webview.setFrame(bounds);
+            webview.setAutoresizingMask(FILL_MASK);
+            host.addSubview(webview);
+            home_window.orderOut(None);
+        }
+    }
+}
+
+/// Move a live profile webview between top-level and child-of-a-host-pane (tear-off / dock).
+/// Returns false if `label` is unknown or already closed. Main-thread only.
+pub fn set_mount(mtm: MainThreadMarker, label: &str, mount: Mount) -> bool {
+    let parts = PROFILE_WINDOWS
+        .lock()
+        .unwrap()
+        .iter()
+        .find(|p| p.label == label && !p.closed.load(Ordering::Relaxed))
+        .map(|p| (p.webview.clone(), p.window.clone()));
+    match parts {
+        Some((webview, window)) => {
+            unsafe { mount_view(mtm, &webview, &window, mount) };
+            true
+        }
+        None => false,
+    }
+}
+
+/// Navigate any WKWebView (profile or tauri) to `url`. Main-thread only.
+pub unsafe fn navigate(wk: *mut WKWebView, url: &str) -> Result<(), String> {
+    let wk = &*wk;
+    match NSURL::URLWithString(&NSString::from_str(url)) {
+        Some(nsurl) => {
+            let req = NSURLRequest::requestWithURL(&nsurl);
+            let _ = wk.loadRequest(&req);
+            Ok(())
+        }
+        None => Err(format!("bad url: {url}")),
+    }
+}
+
+/// Navigate back in the WKWebView's session history (no-op if none). Main-thread only.
+pub unsafe fn go_back(wk: *mut WKWebView) {
+    let _ = (&*wk).goBack();
+}
+
+/// Navigate forward in the WKWebView's session history (no-op if none). Main-thread only.
+pub unsafe fn go_forward(wk: *mut WKWebView) {
+    let _ = (&*wk).goForward();
+}
+
+/// Reload the current page. Main-thread only.
+pub unsafe fn reload(wk: *mut WKWebView) {
+    let _ = (&*wk).reload();
+}
+
+/// Fire-and-forget JS injection. Main-thread only.
+pub unsafe fn inject_script(wk: *mut WKWebView, js: &str) {
+    let wk = &*wk;
+    wk.evaluateJavaScript_completionHandler(&NSString::from_str(js), None);
+}
+
+/// callAsyncJavaScript on a raw WKWebView ptr — CSP-immune eval with an awaited return value.
+/// Delivers the RAW stringified JS return value ("null" or the NSString) via `on_done`; the adapter
+/// wraps it into the wire envelope. Main-thread only (the completion block also lands there).
+pub unsafe fn eval_async(
+    wk: *mut WKWebView,
+    js: String,
+    on_done: impl FnOnce(Result<String, String>) + 'static,
+) {
+    let wk = &*wk;
+    let mtm = MainThreadMarker::new().expect("eval_async runs on main");
+    let on_done = RefCell::new(Some(on_done));
+    let block = block2::RcBlock::new(move |result: *mut AnyObject, error: *mut NSError| {
+        let Some(cb) = on_done.borrow_mut().take() else { return };
+        if !error.is_null() {
+            cb(Err((*error).localizedDescription().to_string()));
+            return;
+        }
+        let out = if result.is_null() {
+            "null".to_string()
+        } else if let Ok(ns) = (&*result).downcast_ref::<NSString>().ok_or(()) {
+            ns.to_string()
+        } else {
+            "null".to_string()
+        };
+        cb(Ok(out));
+    });
+    wk.callAsyncJavaScript_arguments_inFrame_inContentWorld_completionHandler(
+        &NSString::from_str(&js),
+        None,
+        None,
+        &WKContentWorld::pageWorld(mtm),
+        Some(&block),
+    );
+}
+
+/// WKWebView takeSnapshot -> NSImage -> PNG bytes, delivered via `on_done`. The adapter base64s +
+/// frames it. Main-thread only (the completion block also lands there).
+pub unsafe fn snapshot(wk: *mut WKWebView, on_done: impl FnOnce(Result<Vec<u8>, String>) + 'static) {
+    let wk = &*wk;
+    let on_done = RefCell::new(Some(on_done));
+    let block = block2::RcBlock::new(move |image: *mut NSImage, error: *mut NSError| {
+        let Some(cb) = on_done.borrow_mut().take() else { return };
+        if image.is_null() {
+            let msg = if error.is_null() { "snapshot failed".to_string() } else { (*error).localizedDescription().to_string() };
+            cb(Err(msg));
+            return;
+        }
+        let img = &*image;
+        let Some(tiff) = img.TIFFRepresentation() else {
+            cb(Err("no TIFF representation".into()));
+            return;
+        };
+        let Some(rep) = NSBitmapImageRep::initWithData(NSBitmapImageRep::alloc(), &tiff) else {
+            cb(Err("bitmap rep failed".into()));
+            return;
+        };
+        let props = NSDictionary::new();
+        let Some(png) = rep.representationUsingType_properties(NSBitmapImageFileType::PNG, &props) else {
+            cb(Err("png encode failed".into()));
+            return;
+        };
+        cb(Ok(png.to_vec()));
+    });
+    wk.takeSnapshotWithConfiguration_completionHandler(None, &block);
+}

package/runtime-desktop/src-tauri/Cargo.lock

@@ -70,6 +70,7 @@ dependencies = [
  "tauri-plugin-deep-link",
  "tauri-plugin-notification",
  "tauri-plugin-window-state",
+ "webview-control",
 ]
 
 [[package]]
@@ -4626,6 +4627,18 @@ dependencies = [
  "system-deps",
 ]
 
+[[package]]
+name = "webview-control"
+version = "0.1.0"
+dependencies = [
+ "block2",
+ "objc2",
+ "objc2-app-kit",
+ "objc2-foundation",
+ "objc2-web-kit",
+ "serde_json",
+]
+
 [[package]]
 name = "webview2-com"
 version = "0.38.2"

package/runtime-desktop/src-tauri/Cargo.toml

@@ -7,7 +7,9 @@ edition = "2021"
 tauri-build = { version = "2", features = [] }
 
 [dependencies]
-tauri = { version = "2", features = [] }
+# `devtools` feature so `open_devtools()`/`close_devtools()` compile in RELEASE too (in debug they're
+# always available); the ⌥⌘I toggle is still gated at runtime by webview_control::devtools_enabled().
+tauri = { version = "2", features = ["devtools"] }
 tauri-plugin-deep-link = "2"
 tauri-plugin-window-state = "2"
 tauri-plugin-notification = "2"
@@ -20,6 +22,9 @@ libc = "0.2"  # desktop.server: setsid the local-server child + SIGTERM its whol
 # macOS oauth.authorize — ASWebAuthenticationSession (system-browser auth sheet, exact parity with the
 # iOS shell path in runtime/app/shell/handlers-oauth.ts: auto-close on redirect, user-cancel signal).
 [target.'cfg(target_os = "macos")'.dependencies]
+# The generalized native webview primitive (per-profile store, eval, snapshot, popup, bridgeShim).
+# objc2* versions MUST stay identical to those below — the WKWebView pointer crosses the boundary.
+webview-control = { path = "../crates/webview-control" }
 base64 = "0.22"  # SPIKE: bridge_mac screenshot PNG encoding
 objc2 = "0.6"
 objc2-foundation = "0.3"

package/runtime-desktop/src-tauri/capabilities/default.json

@@ -1,6 +1,6 @@
 {
   "$schema": "../gen/schemas/desktop-schema.json",
   "identifier": "default",
-  "windows": ["main"],
+  "windows": ["main", "subwin-*"],
   "permissions": ["core:default", "notification:default"]
 }