@livx.cc/appwrap 0.42.4 → 0.46.1

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

@@ -0,0 +1,879 @@
+// appwrap desktop shell (spike) — Tauri chassis, appwrap protocol v1 surface.
+//
+// The whole bridge is ONE generic command: the init script injects the same
+// `window.appwrapNative.postMessage(json)` transport the Android shell exposes,
+// so the unmodified @livx.cc/native-kit AppwrapAdapter detects it and speaks
+// v1 envelopes. Responses/events go back via `window.__appwrapDeliver(json)`,
+// same as mobile. Handlers below are the desktop analogue of runtime/app/shell/handlers.ts.
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+
+use serde_json::{json, Value};
+use std::collections::HashMap;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Mutex, OnceLock};
+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;
+#[cfg(target_os = "macos")]
+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);
+
+/// App handle, set once in setup() — lets off-main-thread handlers (e.g. `toast.show`) reach
+/// plugin APIs like tauri-plugin-notification, which need a `Manager` to resolve their state.
+static APP: OnceLock<tauri::AppHandle> = OnceLock::new();
+
+/// Single in-flight `oauth.authorize` guard (mirrors the mobile shells' one-session model): a second
+/// authorize while one is pending → NATIVE_ERROR. The ASWebAuthenticationSession completion handler
+/// (oauth_mac) resolves/cancels the flow and clears this.
+static OAUTH_IN_FLIGHT: AtomicBool = AtomicBool::new(false);
+
+/// Cold-vs-warm deep-link state, under ONE lock: `handshaken` flips on the first `app.handshake`
+/// (after which links are WARM → `deeplink.open` events); `pending` holds a link that arrived
+/// before it (cold launch FROM a link), carried back as `deepLink` in the handshake response
+/// (mobile parity) so the PWA can route before first paint. A single mutex — not an atomic flag
+/// beside a mutex — so the handshake's read-flag+drain and on_open_url's check-then-stash can't
+/// interleave and strand a link that arrives at the exact handshake instant.
+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.
+#[derive(serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+struct ShellConfig {
+    app_id: String,
+    name: String,
+    version: String,
+    title: String,
+    width: f64,
+    height: f64,
+    url_scheme: String,
+    identifier: String,
+    /// Persist + restore window size/position across launches (tauri-plugin-window-state). When
+    /// false the plugin isn't registered, so the configured width/height always apply.
+    #[serde(default = "default_true")]
+    restore_window_state: bool,
+    /// Append `prompt=select_account` to Google `signInWithPopup` OAuth popup URLs (see popup_mac).
+    #[serde(default)]
+    google_account_picker: bool,
+    /// Launch on login (tauri-plugin-autostart, macOS LaunchAgent). On setup the shell enables the
+    /// login item when true and explicitly disables it when false — so flipping the config off
+    /// removes the item on the next launch.
+    #[serde(default)]
+    autostart: bool,
+    /// Absolute path to the app's custom-handlers TS file (stamped by the CLI). When non-empty the shell
+    /// spawns a `bun <path>` sidecar at setup and routes methods the sidecar advertises to it (see
+    /// sidecar.rs). Empty/absent → the feature is fully inert (no sidecar).
+    #[serde(default)]
+    handlers: String,
+    /// Absolute path to the Bun binary to spawn the sidecar with (the CLI stamps its own
+    /// `process.execPath`). A GUI-launched .app inherits the launchd PATH (no ~/.bun/bin), so a
+    /// bare `bun` lookup would fail there; sidecar.rs falls back to `bun` when this is empty/gone.
+    #[serde(default)]
+    handlers_runtime: String,
+    /// True when the CLI resolved a real signing identity + macOS provisioning profile for this
+    /// build — i.e. the .app carries the aps-environment entitlement, so APNs registration can
+    /// 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 }
+
+fn shell() -> &'static ShellConfig {
+    static CFG: OnceLock<ShellConfig> = OnceLock::new();
+    CFG.get_or_init(|| {
+        serde_json::from_str(include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/shell_config.json")))
+            .expect("invalid shell_config.json")
+    })
+}
+
+const INIT_JS: &str = r#"
+(() => {
+  const invoke = window.__TAURI_INTERNALS__.invoke;
+  window.appwrapNative = {
+    postMessage: (json) => { invoke('appwrap_invoke', { envelope: json }); },
+  };
+})();
+"#;
+
+/// 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.
+fn spawn_reaped(mut cmd: std::process::Command) -> Result<(), (&'static str, String)> {
+    let mut child = cmd.spawn().map_err(|e| ("NATIVE_ERROR", e.to_string()))?;
+    std::thread::spawn(move || { let _ = child.wait(); });
+    Ok(())
+}
+
+/// Show a real OS notification (tauri-plugin-notification). Checks/asks permission first and errors
+/// (not panics) on a missing app handle, denied permission, or delivery failure — the caller decides
+/// how to degrade. On macOS the plugin routes through the app bundle's identity, so Notification
+/// Center attributes it to the shell; unbundled `cargo run` may fail to deliver (no bundle id) → logged.
+fn show_notification(title: &str, body: &str) -> Result<(), String> {
+    use tauri::plugin::PermissionState;
+    use tauri_plugin_notification::NotificationExt;
+    let app = APP.get().ok_or("app handle not ready")?;
+    let notifier = app.notification();
+    let state = match notifier.permission_state().map_err(|e| e.to_string())? {
+        PermissionState::Prompt | PermissionState::PromptWithRationale => {
+            notifier.request_permission().map_err(|e| e.to_string())?
+        }
+        s => s,
+    };
+    if state != PermissionState::Granted {
+        return Err(format!("permission not granted ({state:?})"));
+    }
+    notifier
+        .builder()
+        .title(title)
+        .body(body)
+        .show()
+        .map_err(|e| e.to_string())
+}
+
+/// Set (Some(n)) or clear (None) the Dock-icon badge on the main window. Resolves the window via the
+/// stashed app handle so the worker-thread handlers can reach it; the tauri call posts to the event
+/// loop, so it's safe off the main thread.
+fn set_badge(count: Option<i64>) -> Result<(), (&'static str, String)> {
+    let app = APP.get().ok_or(("NATIVE_ERROR", "app handle not ready".to_string()))?;
+    let window = app
+        .get_webview_window("main")
+        .ok_or(("NATIVE_ERROR", "no main window".to_string()))?;
+    window
+        .set_badge_count(count)
+        .map_err(|e| ("NATIVE_ERROR", e.to_string()))
+}
+
+/// Request user attention on the main window (macOS: bounce the Dock icon). `critical` bounces until
+/// the app gains focus; otherwise a single informational bounce. Like `set_badge`, the underlying
+/// `request_user_attention` posts to the event loop (send_user_message), so it's safe off the main
+/// thread — no `run_on_main_thread` needed.
+fn request_attention(critical: bool) -> Result<(), (&'static str, String)> {
+    let app = APP.get().ok_or(("NATIVE_ERROR", "app handle not ready".to_string()))?;
+    let window = app
+        .get_webview_window("main")
+        .ok_or(("NATIVE_ERROR", "no main window".to_string()))?;
+    let kind = if critical {
+        tauri::UserAttentionType::Critical
+    } else {
+        tauri::UserAttentionType::Informational
+    };
+    window
+        .request_user_attention(Some(kind))
+        .map_err(|e| ("NATIVE_ERROR", e.to_string()))
+}
+
+/// Method-namespace prefixes served by the built-in `handle()` below (kept next to it — add the
+/// prefix here when you add a new built-in family). sidecar::init REJECTS any sidecar claim under
+/// these, so an app handler can never shadow a built-in (e.g. a custom `storage.get`).
+pub const BUILTIN_METHOD_PREFIXES: &[&str] = &[
+    "app.", "biometrics.", "browser.", "clipboard.", "deeplink.", "device.", "network.",
+    "notifications.", "oauth.", "push.", "storage.", "toast.", "ui.",
+];
+
+fn handle(method: &str, params: &Value) -> HandlerResult {
+    match method {
+        "app.handshake" => {
+            // One critical section: flip to warm AND drain any cold link together (see DEEPLINK).
+            let cold_link = {
+                let mut dl = DEEPLINK.lock().unwrap();
+                dl.handshaken = true;
+                dl.pending.take()
+            };
+            let mut resp = json!({
+            "protocol": 1,
+            "platform": "desktop",
+            "app": {
+                "id": shell().app_id,
+                "name": shell().name,
+                "version": shell().version,
+                "loader": "app"
+            },
+            // Explicit 'none' = veto (kit will NOT web-upgrade it): things a desktop
+            // genuinely lacks. Keys OMITTED here degrade to the kit's WebAdapter
+            // (share, geo, speech, media, ...) per the hybrid-fallback merge.
+            "capabilities": {
+                "clipboard": "native",
+                "toast": "native",
+                "device": "native",
+                "storage": "native",
+                "app": "native",
+                "browser": "native",
+                "network": "native",
+                "ui": "native",
+                "deeplinks": "native",
+                "oauth": "native",
+                // Touch ID via LocalAuthentication. The kit's WebAdapter stub answers available:
+                // false / authenticate→UNSUPPORTED (web-adapter.ts), so OMITTING the key would peg
+                // the module to a permanent no-op. We DO have a real native lane, so 'native' is the
+                // honest value — and it stays honest whether or not THIS Mac has enrolled hardware
+                // (biometrics.available then returns available:false, a valid native response).
+                "biometrics": "native",
+                // Dock-icon badge is native (notifications.setBadge/clear → NSDockTile); this is the
+                // key `kit.app.badgeCapability` reads. `notifications` is 'native' too: schedule/
+                // pending/requestPermission are intercepted below and served by notifications_mac
+                // (UNUserNotificationCenter — the only lane whose tap callback can route a stamped
+                // deepLink; the web Notification API fallback never fires since these never return
+                // UNSUPPORTED).
+                "notifications": "native",
+                "badge": "native",
+                "haptics": "none",
+                // 'native' ONLY when the CLI stamped push_signed (signed .app with an embedded
+                // profile backing aps-environment) — an adhoc build can never get an APNs token.
+                "push": if shell().push_signed { "native" } else { "none" },
+                "motion": "none"
+            }
+            });
+            // Cold launch FROM a deep link: hand the launching URL back synchronously (mobile parity —
+            // see `deepLink` on the kit's Handshake type) so the PWA routes before first paint.
+            if let Some(link) = cold_link {
+                resp["deepLink"] = json!(link);
+            }
+            Ok(resp)
+        }
+        "app.environment" => Ok(json!({
+            "platform": "desktop",
+            "os": std::env::consts::OS,
+            "arch": std::env::consts::ARCH,
+            "debug": cfg!(debug_assertions)
+        })),
+        "app.canOpenUrl" => Ok(json!({ "ok": params["url"].as_str().is_some() })),
+        "app.openUrl" | "browser.open" => {
+            let url = params["url"].as_str().ok_or(("NATIVE_ERROR", "missing url".to_string()))?;
+            if !(url.starts_with("http://") || url.starts_with("https://") || url.starts_with("mailto:")) {
+                return Err(("DENIED", format!("scheme not allowed: {url}")));
+            }
+            let mut cmd = std::process::Command::new("open");
+            cmd.arg(url);
+            spawn_reaped(cmd)?;
+            Ok(json!({ "ok": true }))
+        }
+        // Bounce the Dock icon to request attention (macOS). `critical` (default false) bounces until
+        // the app regains focus; otherwise a single bounce. No kit capability key advertises this —
+        // apps call it directly via kit.invoke('app.requestAttention'). Routes to request_user_attention
+        // which posts to the event loop, so it's thread-safe from this worker thread.
+        "app.requestAttention" => {
+            let critical = params["critical"].as_bool().unwrap_or(false);
+            request_attention(critical)?;
+            Ok(json!({ "ok": true }))
+        }
+        "app.openSettings" => {
+            let mut cmd = std::process::Command::new("open");
+            cmd.arg("x-apple.systempreferences:");
+            spawn_reaped(cmd)?;
+            Ok(json!({ "ok": true }))
+        }
+        "network.status" => Ok(json!({ "online": true, "type": "wifi" })),
+        "ui.safeArea" => Ok(json!({ "top": 0, "right": 0, "bottom": 0, "left": 0 })),
+        "ui.alert" | "ui.confirm" => {
+            let message = params["message"].as_str().unwrap_or("").replace('"', "\\\"");
+            let title = params["title"].as_str().unwrap_or(&shell().name).replace('"', "\\\"");
+            let buttons = if method == "ui.confirm" { "{\"Cancel\", \"OK\"}" } else { "{\"OK\"}" };
+            let script = format!(
+                "display dialog \"{message}\" with title \"{title}\" buttons {buttons} default button -1"
+            );
+            let out = std::process::Command::new("osascript")
+                .args(["-e", &script])
+                .output()
+                .map_err(|e| ("NATIVE_ERROR", e.to_string()))?;
+            // osascript exits 1 on Cancel; that's a `false` confirm, not an error.
+            let confirmed = out.status.success();
+            Ok(json!({ "ok": true, "confirmed": confirmed }))
+        }
+        "device.info" => Ok(json!({
+            "platform": "desktop",
+            "os": std::env::consts::OS,
+            "arch": std::env::consts::ARCH,
+            "model": "mac",
+        })),
+        "clipboard.copy" => {
+            let text = params["text"].as_str().unwrap_or_default().to_string();
+            arboard::Clipboard::new()
+                .and_then(|mut c| c.set_text(text))
+                .map_err(|e| ("NATIVE_ERROR", e.to_string()))?;
+            Ok(json!({ "ok": true }))
+        }
+        "clipboard.read" => {
+            let text = arboard::Clipboard::new()
+                .and_then(|mut c| c.get_text())
+                .unwrap_or_default();
+            Ok(json!({ "text": text }))
+        }
+        "toast.show" => {
+            let message = params["message"]
+                .as_str()
+                .or_else(|| params["text"].as_str())
+                .unwrap_or("");
+            // Real OS notification via tauri-plugin-notification — proper Notification Center
+            // identity from the bundle id (no shell-escaping / osascript hop). Graceful degrade:
+            // a denied permission or delivery failure logs and still returns ok (a toast is
+            // best-effort UX, never a hard error to the caller).
+            if let Err(e) = show_notification(&shell().name, message) {
+                eprintln!("[bridge] toast.show notification skipped: {e}");
+            }
+            Ok(json!({ "ok": true }))
+        }
+        // Dock-icon badge via the tauri window badge API (macOS NSDockTile). setBadge with count>0
+        // shows the number; count 0 (and `clear`) removes it. schedule/pending/requestPermission are
+        // NOT implemented here → they return UNSUPPORTED below and the kit degrades them to its
+        // WebAdapter (Notification API). `set_badge_count` posts to the event loop (thread-safe from
+        // this worker thread). `clear` is badge-only on desktop (no delivered-notification store).
+        "notifications.setBadge" => {
+            let count = params["count"].as_i64().unwrap_or(0);
+            set_badge(if count > 0 { Some(count) } else { None })?;
+            Ok(json!({ "ok": true }))
+        }
+        "notifications.clear" => {
+            set_badge(None)?;
+            Ok(json!({ "ok": true }))
+        }
+        m if m.starts_with("storage.") => storage_handle(m, params),
+        _ => Err(("UNSUPPORTED", format!("{method} not implemented on desktop"))),
+    }
+}
+
+/// Persisted-store file: ~/Library/Application Support/<identifier>/storage.json (macOS app-data dir).
+fn storage_path() -> std::path::PathBuf {
+    let home = std::env::var("HOME").unwrap_or_default();
+    std::path::Path::new(&home)
+        .join("Library/Application Support")
+        .join(&shell().identifier)
+        .join("storage.json")
+}
+
+fn load_store() -> HashMap<String, String> {
+    std::fs::read_to_string(storage_path())
+        .ok()
+        .and_then(|s| serde_json::from_str(&s).ok())
+        .unwrap_or_default()
+}
+
+fn save_store(store: &HashMap<String, String>) -> Result<(), String> {
+    let path = storage_path();
+    if let Some(dir) = path.parent() {
+        std::fs::create_dir_all(dir).map_err(|e| e.to_string())?;
+    }
+    let data = serde_json::to_string(store).map_err(|e| e.to_string())?;
+    std::fs::write(&path, data).map_err(|e| e.to_string())
+}
+
+/// storage.* — persisted to a JSON file in the macOS app-data dir (write-through, in-memory cache).
+/// Note secure.* rides the SAME plaintext file: desktop parity is "persistent", not encrypted (a
+/// Keychain-backed secure lane is out of scope for phase-0).
+fn storage_handle(method: &str, params: &Value) -> HandlerResult {
+    let mut guard = STORAGE.lock().unwrap();
+    let store = guard.get_or_insert_with(load_store);
+    let key = params["key"].as_str().unwrap_or_default();
+    let persist = |store: &HashMap<String, String>| -> HandlerResult {
+        save_store(store).map_err(|e| ("NATIVE_ERROR", e))?;
+        Ok(json!({ "ok": true }))
+    };
+    match method {
+        "storage.get" | "storage.secure.get" => Ok(json!({ "value": store.get(key) })),
+        "storage.set" | "storage.secure.set" => {
+            let value = params["value"].as_str().unwrap_or_default().to_string();
+            store.insert(key.to_string(), value);
+            persist(store)
+        }
+        "storage.remove" | "storage.secure.remove" => {
+            store.remove(key);
+            persist(store)
+        }
+        "storage.clear" => {
+            store.clear();
+            persist(store)
+        }
+        _ => Err(("UNSUPPORTED", format!("{method} not implemented on desktop"))),
+    }
+}
+
+#[tauri::command]
+fn appwrap_invoke(window: tauri::WebviewWindow, envelope: String) {
+    let req: Value = match serde_json::from_str(&envelope) {
+        Ok(v) => v,
+        Err(_) => return,
+    };
+    if req["kind"] != "request" {
+        return;
+    }
+    let id = req["id"].as_str().unwrap_or_default().to_string();
+    let method = req["method"].as_str().unwrap_or_default().to_string();
+    eprintln!("[bridge] {id} {method}");
+    let params = req["params"].clone();
+    // oauth.authorize replies asynchronously from the ASWebAuthenticationSession completion handler
+    // (must start on the main thread; the sheet stays up for minutes) — not from the worker thread.
+    if method == "oauth.authorize" {
+        let url = params["url"].as_str().unwrap_or_default().to_string();
+        let scheme = params["callbackScheme"].as_str().unwrap_or_default().to_string();
+        let ephemeral = params["ephemeral"].as_bool().unwrap_or(false);
+        if url.is_empty() || scheme.is_empty() {
+            deliver_error(&window, &id, "NATIVE_ERROR", "oauth.authorize: empty url or callbackScheme");
+            return;
+        }
+        if OAUTH_IN_FLIGHT.swap(true, Ordering::SeqCst) {
+            deliver_error(&window, &id, "NATIVE_ERROR", "oauth.authorize: a flow is already in progress");
+            return;
+        }
+        #[cfg(target_os = "macos")]
+        oauth_mac::start(window, id, url, scheme, ephemeral);
+        #[cfg(not(target_os = "macos"))]
+        {
+            let _ = (url, scheme, ephemeral);
+            OAUTH_IN_FLIGHT.store(false, Ordering::SeqCst);
+            deliver_error(&window, &id, "UNSUPPORTED", "oauth.authorize not implemented on this desktop OS");
+        }
+        return;
+    }
+    // push.register/unregister reply asynchronously from the APNs delegate callbacks (main thread) —
+    // and are only honest on a signed build (push_signed): adhoc has no aps entitlement, so
+    // registerForRemoteNotifications would just fail. Mirrors the mobile shell's envelope.
+    if method == "push.register" || method == "push.unregister" {
+        if !shell().push_signed {
+            deliver_error(&window, &id, "UNSUPPORTED",
+                "push needs a signed desktop build (set teamId/APPWRAP_TEAM_ID with an installed macOS provisioning profile)");
+            return;
+        }
+        #[cfg(target_os = "macos")]
+        {
+            if method == "push.register" { push_mac::register(window, id); }
+            else { push_mac::unregister(window, id); }
+        }
+        #[cfg(not(target_os = "macos"))]
+        deliver_error(&window, &id, "UNSUPPORTED", "push not implemented on this desktop OS");
+        return;
+    }
+    // biometrics.* — LocalAuthentication. `available` is a synchronous query; `authenticate` shows the
+    // Touch ID sheet and replies asynchronously from the LA completion block (main thread). Both live
+    // here (not in handle()) so the sheet starts off-worker-thread and the reply rides the window.
+    if method.starts_with("biometrics.") {
+        #[cfg(target_os = "macos")]
+        {
+            match method.as_str() {
+                "biometrics.available" => {
+                    let resp = json!({ "v": 1, "id": id, "kind": "response", "result": biometrics_mac::available() });
+                    deliver(&window, &resp);
+                }
+                "biometrics.authenticate" => {
+                    let reason = params["reason"].as_str().unwrap_or_default().to_string();
+                    biometrics_mac::authenticate(window, id, reason);
+                }
+                _ => deliver_error(&window, &id, "UNSUPPORTED", &format!("{method} not implemented on desktop")),
+            }
+        }
+        #[cfg(not(target_os = "macos"))]
+        deliver_error(&window, &id, "UNSUPPORTED", "biometrics not implemented on this desktop OS");
+        return;
+    }
+    // notifications.requestPermission / .schedule / .pending reply asynchronously from
+    // UNUserNotificationCenter completion blocks (started on the main thread) — so they intercept here,
+    // like biometrics/oauth. setBadge/clear are synchronous and fall through to handle() below.
+    #[cfg(target_os = "macos")]
+    if matches!(method.as_str(), "notifications.requestPermission" | "notifications.schedule" | "notifications.pending") {
+        match method.as_str() {
+            "notifications.requestPermission" => notifications_mac::request_permission(window, id),
+            "notifications.schedule" => notifications_mac::schedule(window, id, params),
+            "notifications.pending" => notifications_mac::pending(window, id),
+            _ => unreachable!(),
+        }
+        return;
+    }
+    // Off the main thread: handlers may block (clipboard, subprocess).
+    std::thread::spawn(move || {
+        // The app's own url scheme is an INTERNAL deep link (mobile-shell parity):
+        // loop it back as a `deeplink.open` event instead of shelling out to `open`.
+        let scheme = shell().url_scheme.as_str();
+        if !scheme.is_empty()
+            && (method == "app.openUrl" || method == "browser.open")
+            && params["url"].as_str().is_some_and(|u| u.starts_with(&format!("{scheme}://")))
+        {
+            let event = json!({ "v": 1, "kind": "event", "event": "deeplink.open",
+                "payload": { "url": params["url"] } });
+            deliver(&window, &event);
+            let resp = json!({ "v": 1, "id": id, "kind": "response", "result": { "ok": true } });
+            deliver(&window, &resp);
+            return;
+        }
+        // App-custom methods: forward to the Bun sidecar (desktop.handlers) if it advertised this
+        // method. Built-in collisions are ENFORCED away: sidecar::init drops any claim under
+        // BUILTIN_METHOD_PREFIXES (below), so a custom `storage.get` can never shadow handle().
+        // The sidecar keeps its own (dynamic) error codes — so build the envelope here rather than
+        // routing through handle()'s &'static-str-coded HandlerResult.
+        #[cfg(target_os = "macos")]
+        if sidecar::claims(&method) {
+            let resp = match sidecar::request(&method, &params) {
+                Ok(result) => json!({ "v": 1, "id": id, "kind": "response", "result": result }),
+                Err((code, message)) => json!({
+                    "v": 1, "id": id, "kind": "response",
+                    "error": { "code": code, "message": message }
+                }),
+            };
+            deliver(&window, &resp);
+            return;
+        }
+        let resp = match handle(&method, &params) {
+            Ok(result) => json!({ "v": 1, "id": id, "kind": "response", "result": result }),
+            Err((code, message)) => json!({
+                "v": 1, "id": id, "kind": "response",
+                "error": { "code": code, "message": message }
+            }),
+        };
+        deliver(&window, &resp);
+    });
+}
+
+/// Error response envelope (same shape as the inline error json in appwrap_invoke).
+fn deliver_error(window: &tauri::WebviewWindow, id: &str, code: &str, message: &str) {
+    let resp = json!({
+        "v": 1, "id": id, "kind": "response",
+        "error": { "code": code, "message": message }
+    });
+    deliver(window, &resp);
+}
+
+/// Route an incoming deep link — from the OS (`on_open_url`) OR a tapped local notification carrying
+/// one (notifications_mac) — through the SAME warm/cold path: warm (post-handshake) → emit a
+/// `deeplink.open` event; pre-handshake → stash the FIRST url as `pending` (drained into the handshake
+/// 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() {
+            dl.pending = Some(url.to_string());
+        }
+        dl.handshaken
+    };
+    if warm {
+        if let Some(window) = APP.get().and_then(|app| app.get_webview_window("main")) {
+            let event = json!({ "v": 1, "kind": "event", "event": "deeplink.open",
+                "payload": { "url": url } });
+            deliver(&window, &event);
+        }
+    }
+}
+
+fn deliver(window: &tauri::WebviewWindow, envelope: &Value) {
+    let js = format!(
+        "window.__appwrapDeliver({})",
+        serde_json::to_string(&envelope.to_string()).unwrap()
+    );
+    let _ = window.eval(&js);
+}
+
+fn main() {
+    // No `.menu(...)` override: Tauri v2 installs the default macOS menu (App/Edit/Window),
+    // whose Edit item carries the Cut/Copy/Paste/Select-All shortcuts the WebView needs — so
+    // Cmd+C/V/X/A work in inputs with zero shell code. Suppressing it would break those bindings.
+    let mut builder = tauri::Builder::default()
+        .plugin(tauri_plugin_deep_link::init())
+        .plugin(tauri_plugin_notification::init())
+        // Launch-on-login. LaunchAgent (default) writes a per-user LaunchAgent plist — works for the
+        // adhoc-signed .app (no Developer ID needed). The setup hook below flips the item on/off to
+        // match the config so turning `autostart` off actually removes it.
+        .plugin(tauri_plugin_autostart::init(
+            tauri_plugin_autostart::MacosLauncher::LaunchAgent,
+            None,
+        ));
+    // Window size/position persistence across launches. The plugin auto-restores on window-ready
+    // and saves on close/move/resize; skipping registration (restoreWindowState:false) means the
+    // configured width/height always apply. Registered BEFORE the window is built so its
+    // on_window_ready restore hook fires for it.
+    if shell().restore_window_state {
+        builder = builder.plugin(tauri_plugin_window_state::Builder::default().build());
+    }
+    builder
+        .invoke_handler(tauri::generate_handler![appwrap_invoke])
+        // Popups are plain NSWindows tauri doesn't know about; with the main (only tauri) window
+        // closed, tauri exits the app — but tear popups down explicitly so no dangling windows or
+        // live child webviews outlive the shell during teardown (or if the exit is ever prevented).
+        .on_window_event(|_window, _event| {
+            #[cfg(target_os = "macos")]
+            if _window.label() == "main"
+                && matches!(_event, tauri::WindowEvent::CloseRequested { .. } | tauri::WindowEvent::Destroyed)
+            {
+                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
+            // methods must be claimable before the webview's first invoke can race them.
+            #[cfg(target_os = "macos")]
+            if !shell().handlers.is_empty() {
+                sidecar::init(&shell().handlers, &shell().handlers_runtime);
+            }
+            // Launch-on-login: reconcile the login item to the config every launch, so turning
+            // `autostart` off (or on) takes effect on the next run. Best-effort — a failure to
+            // enable/disable the LaunchAgent shouldn't abort startup.
+            {
+                use tauri_plugin_autostart::ManagerExt;
+                let al = app.autolaunch();
+                let r = if shell().autostart { al.enable() } else { al.disable() };
+                if let Err(e) = r {
+                    eprintln!("[bridge] autostart reconcile ({}) failed: {e}", shell().autostart);
+                }
+            }
+            let restore = shell().restore_window_state;
+            let win_builder = tauri::WebviewWindowBuilder::new(app, "main", tauri::WebviewUrl::App("index.html".into()))
+                .title(shell().title.as_str())
+                .inner_size(shell().width, shell().height)
+                .initialization_script(INIT_JS);
+            // With state restore on, the plugin repositions/resizes AFTER creation — build hidden so
+            // the restore lands before first paint (no visible jump), then show below.
+            let win_builder = if restore { win_builder.visible(false) } else { win_builder };
+            // Safari-normalized UA must be set at BUILD time — the first document snapshots
+            // navigator.userAgent before setup() runs (probe: install()-time setCustomUserAgent
+            // only applied from the next navigation).
+            #[cfg(target_os = "macos")]
+            let win_builder = win_builder.user_agent(popup_mac::SAFARI_UA);
+            win_builder.build()?;
+            // Popup-window support (window.open → real child NSWindow; Firebase signInWithPopup)
+            // + Safari UA normalization. with_webview runs its closure on the main thread.
+            #[cfg(target_os = "macos")]
+            if let Some(window) = app.get_webview_window("main") {
+                let picker = shell().google_account_picker;
+                window.with_webview(move |w| popup_mac::install(w.inner() as _, picker))?;
+            }
+            // Reveal after the state plugin's on_window_ready restore has applied (built hidden above).
+            if restore {
+                if let Some(window) = app.get_webview_window("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.
+            // (oauth does NOT flow through here — ASWebAuthenticationSession captures its own callback.)
+            use tauri_plugin_deep_link::DeepLinkExt;
+            app.deep_link().on_open_url(move |event| {
+                for url in event.urls() {
+                    let url = url.to_string();
+                    eprintln!("[bridge] deeplink.open ← {url}");
+                    // Warm-vs-cold decision + emit is shared with notification taps — see route_deeplink.
+                    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")]
+            if let Some(mtm) = objc2::MainThreadMarker::new() {
+                notifications_mac::ensure_delegate(mtm);
+            }
+            Ok(())
+        })
+        .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);
+                    }
+                }
+                _ => {}
+            }
+        });
+}