@livx.cc/appwrap 0.43.0 → 0.46.1

package/runtime-desktop/src-tauri/src/main.rs

@@ -16,6 +16,8 @@ use tauri::Manager;
 #[cfg(target_os = "macos")]
 mod biometrics_mac;
 #[cfg(target_os = "macos")]
+mod bridge_mac;
+#[cfg(target_os = "macos")]
 mod notifications_mac;
 #[cfg(target_os = "macos")]
 mod oauth_mac;
@@ -24,6 +26,8 @@ mod popup_mac;
 #[cfg(target_os = "macos")]
 mod push_mac;
 #[cfg(target_os = "macos")]
+mod server;
+#[cfg(target_os = "macos")]
 mod sidecar;
 
 static STORAGE: Mutex<Option<HashMap<String, String>>> = Mutex::new(None);
@@ -46,6 +50,26 @@ static OAUTH_IN_FLIGHT: AtomicBool = AtomicBool::new(false);
 struct DeepLinkState { handshaken: bool, pending: Option<String> }
 static DEEPLINK: Mutex<DeepLinkState> = Mutex::new(DeepLinkState { handshaken: false, pending: None });
 
+/// Server-mode (`desktop.server`) deep-link delivery. The page is a plain web app (not a native-kit
+/// consumer), so instead of the native `deeplink.open` handshake we deliver deep links to it directly:
+/// COLD (link arrived before the page loaded) → appended to the navigation URL as `?__appwrap_deeplink=`
+/// so the page reads it on first load; WARM (already loaded) → a `window` CustomEvent `appwrap:deeplink`.
+/// `loaded` flips true when the boot thread navigates to the server URL (drains `pending` atomically).
+struct ServerNav { loaded: bool, pending: Option<String> }
+static SERVER_NAV: Mutex<ServerNav> = Mutex::new(ServerNav { loaded: false, pending: None });
+
+/// Percent-encode a string for use as a URL query-param value (RFC3986 unreserved set kept verbatim).
+fn percent_encode(s: &str) -> String {
+    let mut out = String::new();
+    for b in s.bytes() {
+        match b {
+            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => out.push(b as char),
+            _ => out.push_str(&format!("%{b:02X}")),
+        }
+    }
+    out
+}
+
 /// App identity + window shape, stamped by `appwrap dev|build desktop` from the appwrap config into
 /// `shell_config.json` (embedded at compile time). De-hardcodes what the spike baked in. Mirrors
 /// `DesktopShellConfig` in packages/appwrap-cli/src/desktop.ts.
@@ -87,6 +111,40 @@ struct ShellConfig {
     /// actually succeed. Gates push.register and the handshake's push capability (adhoc → 'none').
     #[serde(default)]
     push_signed: bool,
+    /// Local-server mode: when present the shell boots this command, waits for its port, then
+    /// navigates the window to `http://localhost:<port>` (instead of loading the bundled dist), and
+    /// SIGTERMs its process group on close. Absent → bundled-PWA load. See server.rs.
+    #[serde(default)]
+    server: Option<ServerConfig>,
+}
+
+/// Resolved local-server config (mirrors `DesktopShellConfig.server` in desktop.ts; `command`/`cwd`/
+/// `path` are absolute, stamped by the CLI).
+#[derive(serde::Deserialize, Clone)]
+#[serde(rename_all = "camelCase")]
+struct ServerConfig {
+    command: String,
+    #[serde(default)]
+    args: Vec<String>,
+    #[serde(default)]
+    cwd: String,
+    /// Non-empty → capture the URL the server prints on the first stdout line containing this marker
+    /// (tracks a dynamic port). Empty → use the fixed `port` below.
+    #[serde(default)]
+    url_marker: String,
+    #[serde(default)]
+    port: u16,
+    /// Load over https (vs http) in fixed-`port` mode. True when the server serves TLS (e.g. vite + mkcert).
+    #[serde(default)]
+    https: bool,
+    /// Reserved: readiness currently uses a TCP-accept probe (sufficient for vite/preview), so the
+    /// path isn't hit yet — kept in the wire config for a future HTTP health probe.
+    #[serde(default)]
+    #[allow(dead_code)]
+    health_path: String,
+    ready_timeout_ms: u64,
+    #[serde(default)]
+    path: String,
 }
 
 fn default_true() -> bool { true }
@@ -108,6 +166,20 @@ const INIT_JS: &str = r#"
 })();
 "#;
 
+/// Build a JS snippet that swaps the boot splash into an error state with `msg` (server mode). Escapes
+/// the message for a single-quoted JS string literal.
+fn splash_error_js(msg: &str) -> String {
+    let esc = msg
+        .replace('\\', "\\\\")
+        .replace('\'', "\\'")
+        .replace(['\n', '\r'], " ");
+    format!(
+        "(function(){{var s=document.getElementById('spin');if(s)s.remove();\
+var m=document.getElementById('m');if(m)m.textContent='Server didn\\'t start';\
+var e=document.getElementById('e');if(e)e.textContent='{esc}';}})()"
+    )
+}
+
 type HandlerResult = Result<Value, (&'static str, String)>;
 
 /// spawn() without wait() leaks a zombie per call; reap in a detached thread.
@@ -548,6 +620,28 @@ fn deliver_error(window: &tauri::WebviewWindow, id: &str, code: &str, message: &
 /// response so the PWA routes before first paint). Reaches the main window via the stashed AppHandle,
 /// so it's safe to call from any thread. DRY single source for both entry points.
 pub fn route_deeplink(url: &str) {
+    // Server-mode apps get direct web delivery (see ServerNav), not the native-kit handshake path.
+    #[cfg(target_os = "macos")]
+    if shell().server.is_some() {
+        let deliver_now = {
+            let mut nav = SERVER_NAV.lock().unwrap();
+            if nav.loaded {
+                true
+            } else {
+                nav.pending = Some(url.to_string()); // cold → boot thread appends to the nav URL
+                false
+            }
+        };
+        if deliver_now {
+            if let Some(window) = APP.get().and_then(|app| app.get_webview_window("main")) {
+                let esc = url.replace('\\', "\\\\").replace('\'', "\\'");
+                let _ = window.eval(&format!(
+                    "window.dispatchEvent(new CustomEvent('appwrap:deeplink',{{detail:'{esc}'}}))"
+                ));
+            }
+        }
+        return;
+    }
     let warm = {
         let mut dl = DEEPLINK.lock().unwrap();
         if !dl.handshaken && dl.pending.is_none() {
@@ -606,11 +700,16 @@ fn main() {
                 popup_mac::close_all();
                 // Kill the handlers sidecar so the Bun process never outlives the shell.
                 sidecar::shutdown();
+                // NB: server teardown runs on RunEvent::Exit (below), NOT here — a blocking kill in
+                // this close handler would starve tauri-plugin-window-state's own save-on-close.
             }
         })
         .setup(|app| {
             // Stash the app handle so off-main-thread handlers can reach plugin state (notifications).
             let _ = APP.set(app.handle().clone());
+            // SPIKE: browser-bridge window-ops backend — inert unless APPWRAP_BRIDGE_JS is set.
+            #[cfg(target_os = "macos")]
+            bridge_mac::init(app.handle().clone());
             // Per-app custom handlers: spawn the Bun sidecar when configured (absolute path stamped by
             // the CLI). No-op / degrades to inert when empty, on spawn failure, or on a missing `ready`.
             // NOTE: init blocks setup for up to READY_TIMEOUT (5s, bounded) — intentional: sidecar
@@ -657,6 +756,64 @@ fn main() {
                     let _ = window.show();
                 }
             }
+            // Local-server mode: boot the server child now (the window shows the bundled splash), then a
+            // background thread polls its port and navigates the window to it — or, on timeout/spawn
+            // failure, writes the reason into the splash. Absent `server` → the bundled dist just loads.
+            #[cfg(target_os = "macos")]
+            if let Some(sc) = shell().server.clone() {
+                match server::spawn(&server::ServerCfg {
+                    command: &sc.command,
+                    args: &sc.args,
+                    cwd: &sc.cwd,
+                    path: &sc.path,
+                    url_marker: &sc.url_marker,
+                }) {
+                    Ok(url_rx) => {
+                        let app_handle = app.handle().clone();
+                        std::thread::spawn(move || {
+                            let timeout = std::time::Duration::from_millis(sc.ready_timeout_ms);
+                            // urlMarker mode → the captured URL (dynamic port); else TCP-poll the fixed port.
+                            let url = match url_rx {
+                                Some(rx) => rx.recv_timeout(timeout).ok(),
+                                None => server::wait_for_port(sc.port, sc.ready_timeout_ms)
+                                    .then(|| format!("{}://localhost:{}", if sc.https { "https" } else { "http" }, sc.port)),
+                            };
+                            let Some(win) = app_handle.get_webview_window("main") else { return };
+                            match url {
+                                Some(u) => {
+                                    // Flip to loaded + drain any cold deep link together, so a link
+                                    // arriving now either lands in this URL or takes the warm path.
+                                    let cold = {
+                                        let mut nav = SERVER_NAV.lock().unwrap();
+                                        nav.loaded = true;
+                                        nav.pending.take()
+                                    };
+                                    let target = match cold {
+                                        Some(dl) => {
+                                            let sep = if u.contains('?') { '&' } else { '?' };
+                                            format!("{u}{sep}__appwrap_deeplink={}", percent_encode(&dl))
+                                        }
+                                        None => u,
+                                    };
+                                    let _ = win.eval(&format!("location.replace('{target}')"));
+                                }
+                                None => {
+                                    let _ = win.eval(&splash_error_js(&format!(
+                                        "Server didn't come up within {}s.",
+                                        sc.ready_timeout_ms / 1000
+                                    )));
+                                }
+                            }
+                        });
+                    }
+                    Err(e) => {
+                        eprintln!("[server] spawn `{}` failed: {e} — server mode inert", sc.command);
+                        if let Some(win) = app.get_webview_window("main") {
+                            let _ = win.eval(&splash_error_js(&format!("Failed to start server: {e}")));
+                        }
+                    }
+                }
+            }
             // OS deep links (<urlScheme>://…, registered via the .app's CFBundleURLTypes). Warm →
             // emit `deeplink.open` (same envelope as the internal loopback in appwrap_invoke);
             // pre-handshake → stash the FIRST url, carried back in the handshake response.
@@ -670,6 +827,16 @@ fn main() {
                     route_deeplink(&url);
                 }
             });
+            // Cold launch: the URL that LAUNCHED the app (open para://…) can be missed by on_open_url on
+            // macOS — retrieve it explicitly so a link that starts the app is honored too. Stashed as a
+            // cold deep link (server mode → drained into the boot navigation; see route_deeplink/ServerNav).
+            if let Ok(Some(urls)) = app.deep_link().get_current() {
+                for url in urls {
+                    let url = url.to_string();
+                    eprintln!("[bridge] deeplink.open (launch) ← {url}");
+                    route_deeplink(&url);
+                }
+            }
             // Install the UNUserNotificationCenter delegate now (main thread) so a notification tapped
             // right after a cold launch is captured. Idempotent with the schedule-time call.
             #[cfg(target_os = "macos")]
@@ -678,6 +845,35 @@ fn main() {
             }
             Ok(())
         })
-        .run(tauri::generate_context!())
-        .expect("error while running appwrap desktop shell");
+        .build(tauri::generate_context!())
+        .expect("error while building appwrap desktop shell")
+        .run(|app_handle, event| {
+            #[cfg(target_os = "macos")]
+            match &event {
+                // ExitRequested fires while the window still EXISTS (⌘Q / Dock-quit / last-window-close),
+                // so persist geometry here — the window-state plugin's own save only fires on window
+                // CLOSE events, which those quit paths skip, so position/size wouldn't restore next run.
+                tauri::RunEvent::ExitRequested { .. } => {
+                    if shell().restore_window_state {
+                        use tauri_plugin_window_state::{AppHandleExt, StateFlags};
+                        let _ = app_handle.save_window_state(StateFlags::all());
+                    }
+                    server::shutdown();
+                }
+                // Belt-and-suspenders: also tear down on Exit (idempotent — shutdown() takes the child
+                // out of its slot, so this is a no-op after ExitRequested already ran).
+                tauri::RunEvent::Exit => server::shutdown(),
+                // macOS URL-scheme delivery for BOTH cold launch (app opened BY the link) and warm
+                // re-open — the canonical path; `on_open_url`/`get_current` miss the launch URL. Routed
+                // through the same handler (server mode → drained into the boot nav or dispatched warm).
+                tauri::RunEvent::Opened { urls } => {
+                    for url in urls {
+                        let u = url.to_string();
+                        eprintln!("[bridge] deeplink.open (opened) ← {u}");
+                        route_deeplink(&u);
+                    }
+                }
+                _ => {}
+            }
+        });
 }

package/runtime-desktop/src-tauri/src/popup_mac.rs

@@ -24,8 +24,9 @@ use objc2::{define_class, msg_send, DefinedClass, MainThreadMarker, MainThreadOn
 use objc2_app_kit::{NSBackingStoreType, NSWindow, NSWindowDelegate, NSWindowStyleMask};
 use objc2_foundation::{NSNotification, NSPoint, NSRect, NSSize, NSString, NSURL, NSURLRequest};
 use objc2_web_kit::{
-    WKNavigationAction, WKNavigationActionPolicy, WKNavigationDelegate, WKUIDelegate, WKWebView,
-    WKWebViewConfiguration, WKWindowFeatures,
+    WKFrameInfo, WKMediaCaptureType, WKNavigationAction, WKNavigationActionPolicy, WKNavigationDelegate,
+    WKPermissionDecision, WKSecurityOrigin, WKUIDelegate, WKWebView, WKWebViewConfiguration,
+    WKWindowFeatures,
 };
 
 /// When true, Google `signInWithPopup` OAuth popups get `prompt=select_account` appended so a
@@ -111,6 +112,11 @@ struct Popup {
     /// param) would re-match and re-trigger a cancel+reload loop. Tied to the popup so it's dropped
     /// with the window.
     rewritten: AtomicBool,
+    /// The Delegate that created this popup (the opener's UI delegate — the global INSTALLED one for
+    /// the main shell window, or a per-profile-window delegate). It's the KVO `title` observer we
+    /// registered on `webview`, so teardown MUST remove the observer using THIS same object (not a
+    /// global) or KVO throws / leaks. Held strong so it outlives the observed webview.
+    observer: Retained<Delegate>,
 }
 unsafe impl Send for Popup {}
 static POPUPS: Mutex<Vec<Popup>> = Mutex::new(Vec::new());
@@ -143,10 +149,11 @@ fn cleanup_popup(pred: &dyn Fn(&Popup) -> bool, close_window: bool) {
         (p, descendants_of(&pairs, key))
     };
     // Stop observing `title` BEFORE releasing the webview (KVO throws if an observed object
-    // deallocates with observers attached). Registered unconditionally in create_web_view.
-    if let Some(observer) = installed_delegate() {
+    // deallocates with observers attached). Registered in create_web_view with p.observer as the
+    // observer — remove with the SAME object (per-window delegates make a global lookup wrong).
+    {
         let key = NSString::from_str("title");
-        let _: () = unsafe { msg_send![&*p.webview, removeObserver: &*observer, forKeyPath: &*key] };
+        let _: () = unsafe { msg_send![&*p.webview, removeObserver: &*p.observer, forKeyPath: &*key] };
     }
     if close_window {
         p.window.close();
@@ -192,11 +199,6 @@ pub fn close_all() {
     }
 }
 
-/// Strong ref to our installed Delegate (the KVO observer), if install() ran.
-fn installed_delegate() -> Option<Retained<Delegate>> {
-    INSTALLED.lock().unwrap().0.as_ref().map(|(d, _)| d.clone())
-}
-
 /// Strong refs to our delegate + wry's original (uiDelegate is weak on WKWebView).
 struct Installed(Option<(Retained<Delegate>, Retained<AnyObject>)>);
 unsafe impl Send for Installed {}
@@ -231,6 +233,20 @@ define_class!(
                 .map(|s| s.to_string())
                 .unwrap_or_default();
 
+            // Verification #4 proof: the SSO popup inherits the opener's data store (its profile's
+            // cookie jar). WebKit hands us a configuration derived from the opener, so its
+            // websiteDataStore is the SAME object as the opener's — log the pointer identity.
+            unsafe {
+                let opener_store = opener.configuration().websiteDataStore();
+                let child_store = configuration.websiteDataStore();
+                eprintln!(
+                    "[popup] shared-store check: opener={:p} child={:p} shared={}",
+                    Retained::as_ptr(&opener_store),
+                    Retained::as_ptr(&child_store),
+                    Retained::as_ptr(&opener_store) == Retained::as_ptr(&child_store),
+                );
+            }
+
             let width = unsafe { features.width() }.map(|n| n.doubleValue()).unwrap_or(720.0).max(200.0);
             let height = unsafe { features.height() }.map(|n| n.doubleValue()).unwrap_or(640.0).max(200.0);
             let rect = NSRect::new(NSPoint::new(0.0, 0.0), NSSize::new(width, height));
@@ -305,6 +321,7 @@ define_class!(
                 webview: child.clone(),
                 parent: opener as *const WKWebView as usize,
                 rewritten: AtomicBool::new(false),
+                observer: self.retain(),
             });
             // Returning the webview makes WebKit load the navigation action's request itself.
             Some(child)
@@ -317,6 +334,24 @@ define_class!(
             // fires but finds no entry → no-op).
             cleanup_popup(&|p: &Popup| &*p.webview == webview, true);
         }
+
+        // getUserMedia (mic/camera — e.g. voice mode): without this WKUIDelegate method the WebView
+        // DENIES capture by default, so `navigator.mediaDevices.getUserMedia` rejects. We GRANT it —
+        // the page is our own trusted (local/first-party) content. macOS still gates the actual device
+        // behind TCC, which needs the app's Info.plist usage string (NSMicrophoneUsageDescription, added
+        // when the `media` module is declared) + the user's one-time consent; this only lifts the
+        // WebKit-layer denial so that TCC prompt can appear at all.
+        #[unsafe(method(webView:requestMediaCapturePermissionForOrigin:initiatedByFrame:type:decisionHandler:))]
+        fn request_media_capture(
+            &self,
+            _web_view: &WKWebView,
+            _origin: &WKSecurityOrigin,
+            _frame: &WKFrameInfo,
+            _capture_type: WKMediaCaptureType,
+            decision_handler: &block2::DynBlock<dyn Fn(WKPermissionDecision)>,
+        ) {
+            decision_handler.call((WKPermissionDecision::Grant,));
+        }
     }
 
     // Child-popup navigation policy — only consulted when GOOGLE_ACCOUNT_PICKER wired the child's
@@ -464,3 +499,21 @@ pub fn install(webview_ptr: *mut std::ffi::c_void, google_account_picker: bool)
         }),
     ));
 }
+
+/// Install a DEDICATED popup delegate on a manually-created profile window's WKWebView, and return
+/// it so the caller retains it for that window's lifetime (uiDelegate is a WEAK property). Unlike
+/// install(), this does NOT touch the global INSTALLED — every concurrent profile window keeps its
+/// own delegate, so SSO popups work in all of them simultaneously (not last-writer-wins).
+///
+/// There is no wry delegate to forward to (the webview was built by us, not wry), so file-upload /
+/// media panels aren't forwarded — acceptable (trusted OS input is out of scope). The child popup is
+/// alloc'd with the PARENT's passed WKWebViewConfiguration (create_web_view), which carries the
+/// parent's websiteDataStore — so the popup shares the profile's cookie jar (verification #4).
+pub fn install_for_profile(webview_ptr: *mut std::ffi::c_void, mtm: MainThreadMarker) -> Retained<AnyObject> {
+    let webview: &WKWebView = unsafe { &*(webview_ptr as *const WKWebView) };
+    let delegate = Delegate::alloc(mtm).set_ivars(DelegateIvars { wry_delegate: None });
+    let delegate: Retained<Delegate> = unsafe { msg_send![super(delegate), init] };
+    unsafe { webview.setUIDelegate(Some(ProtocolObject::from_ref(&*delegate))) };
+    // Opaque to the caller (Delegate is private) — retained only for the window's lifetime.
+    unsafe { Retained::cast_unchecked::<AnyObject>(delegate) }
+}

package/runtime-desktop/src-tauri/src/server.rs

@@ -0,0 +1,156 @@
+//! `desktop.server` mode: boot a local server command, wait for its port, then the shell navigates the
+//! window to it (see main.rs setup). This is the desktop analogue of iOS/Android `loader:'server'`, but
+//! the URL is served by a child process THIS shell owns — so we also tear it down on window-close.
+//!
+//! Teardown correctness: the server (e.g. `para-chat`) itself spawns children (a backend + a vite
+//! preview). A plain SIGKILL of the direct child would orphan those grandchildren. So we `setsid()` the
+//! child into its OWN process group at spawn, then SIGTERM the WHOLE group on shutdown — every
+//! descendant gets the signal and the server's own exit-guard can reap cleanly.
+
+use std::io::{BufRead, BufReader};
+use std::net::TcpStream;
+use std::os::unix::process::CommandExt;
+use std::process::{Child, Command, Stdio};
+use std::sync::mpsc::{self, Receiver};
+use std::sync::{Mutex, OnceLock};
+use std::time::{Duration, Instant};
+
+/// The booted child + its process-group id (== pid after setsid). Recorded for teardown.
+struct Running {
+    child: Child,
+    pgid: i32,
+}
+
+static RUNNING: OnceLock<Mutex<Option<Running>>> = OnceLock::new();
+
+fn slot() -> &'static Mutex<Option<Running>> {
+    RUNNING.get_or_init(|| Mutex::new(None))
+}
+
+/// Resolved server config (mirrors `ServerConfig` in main.rs).
+pub struct ServerCfg<'a> {
+    pub command: &'a str,
+    pub args: &'a [String],
+    pub cwd: &'a str,
+    pub path: &'a str,
+    /// Non-empty → capture the printed URL from stdout (see `spawn`). Empty → caller uses wait_for_port.
+    pub url_marker: &'a str,
+}
+
+/// Extract the first `http://…`/`https://…` token from a line (up to the next whitespace). Pure.
+fn extract_url(line: &str) -> Option<String> {
+    let start = line.find("http://").or_else(|| line.find("https://"))?;
+    let rest = &line[start..];
+    let end = rest.find(char::is_whitespace).unwrap_or(rest.len());
+    Some(rest[..end].to_string())
+}
+
+/// Spawn the server command in its own process group (setsid), with the CLI-stamped PATH (a
+/// GUI-launched .app has a minimal launchd PATH). Records the child for teardown.
+///
+/// When `url_marker` is non-empty, stdout is piped and a reader thread tees each line to the shell's
+/// stderr AND, on the first line containing the marker, extracts the printed URL and sends it back —
+/// so the shell loads whatever port the server auto-picked (no hardcoded port). Returns that receiver.
+/// When `url_marker` is empty, stdout is inherited and `None` is returned (caller uses `wait_for_port`).
+pub fn spawn(cfg: &ServerCfg) -> std::io::Result<Option<Receiver<String>>> {
+    let capture = !cfg.url_marker.is_empty();
+    let mut cmd = Command::new(cfg.command);
+    cmd.args(cfg.args);
+    if !cfg.cwd.is_empty() {
+        cmd.current_dir(cfg.cwd);
+    }
+    if !cfg.path.is_empty() {
+        cmd.env("PATH", cfg.path);
+    }
+    cmd.stdin(Stdio::null()).stderr(Stdio::inherit());
+    cmd.stdout(if capture { Stdio::piped() } else { Stdio::inherit() });
+    // New session/process group so we can signal every descendant at teardown. setsid() also makes the
+    // child the group leader → its pgid equals its pid.
+    unsafe {
+        cmd.pre_exec(|| {
+            if libc::setsid() == -1 {
+                return Err(std::io::Error::last_os_error());
+            }
+            Ok(())
+        });
+    }
+    let mut child = cmd.spawn()?;
+    let pgid = child.id() as i32;
+
+    let rx = if capture {
+        let stdout = child.stdout.take().expect("piped stdout");
+        let marker = cfg.url_marker.to_string();
+        let (tx, rx) = mpsc::channel::<String>();
+        std::thread::spawn(move || {
+            let mut sent = false;
+            for line in BufReader::new(stdout).lines().map_while(Result::ok) {
+                eprintln!("[server] {line}");
+                if !sent && line.contains(&marker) {
+                    if let Some(url) = extract_url(&line) {
+                        let _ = tx.send(url);
+                        sent = true; // keep draining stdout so the child never blocks on a full pipe
+                    }
+                }
+            }
+        });
+        Some(rx)
+    } else {
+        None
+    };
+
+    *slot().lock().unwrap() = Some(Running { child, pgid });
+    Ok(rx)
+}
+
+/// Poll `127.0.0.1:port` with a TCP connect until it accepts (server is listening) or the timeout
+/// elapses. TCP-accept is a sufficient readiness signal — vite/preview binds the port only once it's
+/// ready to serve. Returns false on timeout.
+pub fn wait_for_port(port: u16, timeout_ms: u64) -> bool {
+    let deadline = Instant::now() + Duration::from_millis(timeout_ms);
+    let addr: std::net::SocketAddr = ([127, 0, 0, 1], port).into();
+    loop {
+        if TcpStream::connect_timeout(&addr, Duration::from_millis(500)).is_ok() {
+            return true;
+        }
+        if Instant::now() >= deadline {
+            return false;
+        }
+        std::thread::sleep(Duration::from_millis(300));
+    }
+}
+
+/// Signal the child's whole process group and reap (idempotent). Called on app exit so the local stack
+/// never outlives the shell. SIGTERM first (lets the server run its exit-guard + reap its own children),
+/// then a short grace, then SIGKILL as a backstop — the server may TRAP SIGTERM without exiting, and a
+/// blocking `wait()` on such a child would hang the exit forever, so we hard-kill the group and only
+/// `try_wait()` (non-blocking) to reap. The negative pgid targets every descendant.
+pub fn shutdown() {
+    if let Some(m) = RUNNING.get() {
+        if let Some(mut r) = m.lock().unwrap().take() {
+            unsafe { libc::kill(-r.pgid, libc::SIGTERM) };
+            std::thread::sleep(Duration::from_millis(1500));
+            unsafe { libc::kill(-r.pgid, libc::SIGKILL) };
+            let _ = r.child.try_wait();
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::extract_url;
+
+    #[test]
+    fn extracts_first_url_up_to_whitespace() {
+        assert_eq!(
+            extract_url("   Frontend:  https://localhost:5050  (ready)"),
+            Some("https://localhost:5050".to_string())
+        );
+        assert_eq!(extract_url("Backend: http://localhost:5051"), Some("http://localhost:5051".to_string()));
+    }
+
+    #[test]
+    fn none_when_no_url() {
+        assert_eq!(extract_url("Frontend ready on port 5050"), None);
+        assert_eq!(extract_url(""), None);
+    }
+}

package/src/cli.ts

@@ -1979,6 +1979,30 @@ function desktopCopyFilter(src: string): boolean {
   return !/(^|\/)(target|gen|node_modules)(\/|$)/.test(rel);
 }
 
+/** Resolve a `desktop.server.command` to an absolute path: an absolute/relative path is resolved
+ * against the app root; a bare name is looked up on `path` (build-time PATH). Falls back to the bare
+ * name (the Rust shell will surface the spawn ENOENT) when it's nowhere. */
+function resolveServerCommand(command: string, cwd: string, path: string): string {
+  if (command.includes('/')) return resolve(cwd, command);
+  for (const dir of path.split(pathDelimiter).filter(Boolean)) {
+    const abs = join(dir, command);
+    if (existsSync(abs)) return abs;
+  }
+  return command;
+}
+
+/** The bundled splash shown while a local-server app boots (before the shell navigates to the live
+ * server). A dependency-free, theme-neutral holding page. */
+function desktopSplashHtml(name: string): string {
+  const safe = name.replace(/</g, '&lt;').replace(/&/g, '&amp;');
+  return `<!doctype html><html><head><meta charset="utf-8"><title>${safe}</title>
+<style>html,body{height:100%;margin:0}body{display:flex;align-items:center;justify-content:center;
+flex-direction:column;gap:20px;background:#0b0b0f;color:#e5e5e5;font:14px -apple-system,system-ui,sans-serif}
+.s{width:34px;height:34px;border:3px solid #333;border-top-color:#888;border-radius:50%;animation:r .8s linear infinite}
+@keyframes r{to{transform:rotate(360deg)}}#e{color:#f87171;max-width:70%;text-align:center;line-height:1.5}</style>
+</head><body><div class="s" id="spin"></div><div id="m">Starting ${safe}…</div><div id="e"></div></body></html>`;
+}
+
 /** Copy the desktop template into `native-desktop/` and stamp it from the config: the Rust-read
  * `shell_config.json` (identity + window), `tauri.conf.json` (productName/version/identifier +
  * frontendDist), and the staged web dist (`native-desktop/dist`, referenced as `../dist`). */
@@ -1991,19 +2015,39 @@ function regenerateDesktop(cwd: string, cfg: AppwrapConfig, outDir: string, push
   mkdirSync(outDir, { recursive: true });
   cpSync(DESKTOP_TEMPLATE_DIR, outDir, { recursive: true, force: true, filter: desktopCopyFilter });
 
-  // Stage the built web dist INTO the wrapper (mirrors mobile copyPwa) so frontendDist is a stable
-  // relative path independent of where the app project sits.
-  const dist = resolve(cwd, cfg.pwaDist);
-  if (!existsSync(dist)) {
-    console.error(`✖ Web dist not found at ${dist} — build the PWA first (or check pwaDist).`);
-    process.exit(1);
-  }
-  const stagedDist = join(outDir, 'dist');
-  rmSync(stagedDist, { recursive: true, force: true });
-  cpSync(dist, stagedDist, { recursive: true, force: true });
-
   const shell = deriveDesktopConfig(cfg);
   shell.pushSigned = pushSigned;
+
+  // Stage the frontendDist INTO the wrapper (mirrors mobile copyPwa) so it's a stable relative path
+  // independent of where the app project sits. Local-server apps (`desktop.server`) have no meaningful
+  // web dist — the window loads the live server — so we stage a tiny bundled SPLASH instead (shown
+  // while the server boots, then the shell navigates away from it).
+  const stagedDist = join(outDir, 'dist');
+  rmSync(stagedDist, { recursive: true, force: true });
+  if (shell.server) {
+    mkdirSync(stagedDist, { recursive: true });
+    writeFileSync(join(stagedDist, 'index.html'), desktopSplashHtml(shell.name));
+  } else {
+    const dist = resolve(cwd, cfg.pwaDist);
+    if (!existsSync(dist)) {
+      console.error(`✖ Web dist not found at ${dist} — build the PWA first (or check pwaDist).`);
+      process.exit(1);
+    }
+    cpSync(dist, stagedDist, { recursive: true, force: true });
+  }
+
+  // Local-server mode: resolve `command` (bare name → PATH lookup) and `cwd` to ABSOLUTE, and stamp
+  // the build-time PATH — a GUI-launched .app inherits the minimal launchd PATH (no ~/.bun/bin), so
+  // a bare-name spawn (or a child that itself shells out to `bun`/`node`) would fail there.
+  if (shell.server) {
+    const s = shell.server;
+    s.cwd = s.cwd ? resolve(cwd, s.cwd) : cwd;
+    s.command = resolveServerCommand(s.command, cwd, process.env.PATH ?? '');
+    s.path = process.env.PATH ?? '';
+    if (!existsSync(s.command)) {
+      console.warn(`⚠ desktop.server.command not found (${s.command}) — the server will fail to spawn at launch.`);
+    }
+  }
   // Resolve the handlers path to ABSOLUTE (against the app root): the shell binary runs from a
   // different cwd, and for `build desktop` the .app runs from wherever it's installed — an absolute
   // path is the only one that stays valid. The handler file is NOT copied into the wrapper/.app; the
@@ -2347,7 +2391,9 @@ async function buildDesktop(cwd: string, flags: Record<string, string>): Promise
   ensureDesktopMacOS();
   const cfg = await loadConfig(cwd, flags);
   const outDir = resolve(cwd, flags.out ?? 'native-desktop');
-  buildWebIfBundled(cwd, cfg, flags);
+  // Local-server apps load the live server, not a bundled web build — skip it (regenerateDesktop
+  // stages a boot splash for them). Otherwise build/stage the PWA as usual.
+  if (!cfg.desktop?.server) buildWebIfBundled(cwd, cfg, flags);
   // Resolve the signing lane BEFORE regeneration: shell_config.json is embedded at compile time,
   // and the Rust shell's push capability must only claim 'native' when the .app really ships the
   // profile-backed aps-environment entitlement (signed lane + installed macOS profile).
@@ -3524,10 +3570,21 @@ async function logs(cwd: string, flags: Record<string, string>, positionals: str
   console.log(`▶ watching web logs from ${cfg.id} on ${device.name} (pull every 3s) — Ctrl-C to stop.`);
   console.log('  [appwrap-web] = forwarded WebView console/errors. (--once = snapshot, --native = OS firehose.)');
   let shown = 0;
+  // Self-terminate when orphaned: if our controlling session dies, macOS reparents us to launchd and
+  // this loop would otherwise poll `devicectl` FOREVER — every stale session stacking load until
+  // CoreDeviceService pins a core at 100%. NOTE: `process.ppid` is cached at startup and does NOT
+  // update on reparent, so probe the ORIGINAL parent's liveness with signal 0 (throws once it's gone);
+  // also stop on a broken stdout pipe (consumer gone).
+  const parentPid = process.ppid;
+  const orphaned = (): boolean => { try { process.kill(parentPid, 0); return false; } catch { return true; } };
   for (;;) {
+    if (orphaned()) break; // original parent gone → we've been reparented → stop
     const all = pull();
     if (all.length < shown) shown = 0; // app relaunched → file reset; reprint
-    if (all.length > shown) { process.stdout.write(all.slice(shown)); shown = all.length; }
+    if (all.length > shown) {
+      try { process.stdout.write(all.slice(shown)); } catch { break; } // pipe closed → consumer gone
+      shown = all.length;
+    }
     try { execFileSync('sleep', ['3']); } catch { break; }
   }
 }