@livx.cc/appwrap 0.46.4 → 0.47.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.46.4",
+  "version": "0.47.1",
   "description": "Wrap any PWA into a native app with native capabilities (appwrap runtime + @livx.cc/native-kit).",
   "license": "MIT",
   "author": "Elya Livshitz",
@@ -31,6 +31,7 @@
     ".": "./src/config.ts",
     "./config": "./src/config.ts",
     "./handlers": "./src/handlers.ts",
+    "./plugin": "./src/plugin/index.ts",
     "./cli": "./src/cli.ts"
   },
   "files": [

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

@@ -248,6 +248,25 @@ fn main() {
     println!("session survived (marker 77):             {session_ok}");
     println!("bridge  survived (pings {:?}):             {bridge_ok}", pings);
 
+    // ---- IDEMPOTENT DOUBLE-INSTALL (bridgeShim) ----
+    // Simulate a SECOND plugin attaching onMessage to the SAME window. Before the fix, a second
+    // addScriptMessageHandler(name:"bridgeShim") on the same UCC threw NSInvalidArgumentException =
+    // hard crash. install_message_handler now does remove-then-add, so this must NOT crash and the
+    // bridge must still route to the newly-installed sink. Runs AFTER the original-sink assertions
+    // above (re-install replaces the sink, which is fine from here on).
+    println!("\n== IDEMPOTENCY: re-install bridgeShim on the live webview (second-plugin attach)");
+    let (tx2, rx2): (_, Receiver<String>) = channel();
+    let sink2 = Box::new(move |raw: String| { let _ = tx2.send(raw); });
+    if let Err(e) = ctrl.reinstall_message_handler(mtm, id, sink2) {
+        eprintln!("FAIL: reinstall_message_handler errored: {e}");
+        std::process::exit(1);
+    }
+    let _ = eval(&ctrl, mtm, id, "webkit.messageHandlers.bridgeShim.postMessage('PING-REINSTALL'); return 'posted';");
+    pump(0.5);
+    let reinstall_pings: Vec<String> = rx2.try_iter().collect();
+    let idempotent_ok = reinstall_pings.iter().any(|p| p == "PING-REINSTALL");
+    println!("   no crash on double-install; post-reinstall pings {reinstall_pings:?} (routed={idempotent_ok})");
+
     // ---- NAV ops (go_back / go_forward / reload via Controller) ----
     // The tab is docked ChildOf(pane) on page 1. Navigate to a distinct page 2, then walk history.
     let page1_href = href(&ctrl, mtm, id);
@@ -321,7 +340,12 @@ fn main() {
 
     println!("pane empty after close (no zombie webview):  {pane_empty_ok}");
 
-    if page_ok && session_ok && bridge_ok && pane_empty_ok && nav_ok && profile_swap_ok {
+    println!("bridge idempotent re-install (no crash, routes):  {idempotent_ok}");
+    if !idempotent_ok {
+        eprintln!("\nFAIL: bridge did not route after idempotent double-install of bridgeShim.");
+    }
+
+    if page_ok && session_ok && bridge_ok && pane_empty_ok && nav_ok && profile_swap_ok && idempotent_ok {
         println!("\nPASS: live webview reparented child->toplevel->child via EMBEDDED API; page+session+bridge intact; nav ops (back/forward/reload) + profile-swap (distinct store) verified; host pane empty after close.");
     } else {
         if !nav_ok { eprintln!("\nFAIL: nav ops (go_back/go_forward/reload) did not land as expected."); }

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

@@ -115,6 +115,23 @@ impl Controller {
         backend::list_webviews()
     }
 
+    /// Re-install the bridgeShim message handler on an existing webview's UCC. Mirrors a second
+    /// plugin attaching `onMessage` to the same window. Idempotent (remove-then-add) — proves the
+    /// double-install crash (NSInvalidArgumentException) is gone. Test/harness surface only.
+    #[doc(hidden)]
+    pub fn reinstall_message_handler(
+        &self,
+        mtm: MainThreadMarker,
+        id: &str,
+        on_message: crate::MessageSink,
+    ) -> Result<(), String> {
+        let wk = self.webview(id)?;
+        unsafe {
+            backend::install_message_handler(Retained::as_ptr(&wk) as *mut WKWebView, mtm, on_message)
+        };
+        Ok(())
+    }
+
     fn webview(&self, id: &str) -> Result<Retained<WKWebView>, String> {
         backend::profile_webview(id).ok_or_else(|| format!("no webview {id}"))
     }

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

@@ -127,6 +127,11 @@ pub unsafe fn install_message_handler(wk: *mut WKWebView, mtm: MainThreadMarker,
     let handler = MsgHandler::alloc(mtm).set_ivars(MsgHandlerIvars { on_message });
     let handler: Retained<MsgHandler> = msg_send![super(handler), init];
     let ucc = wk.configuration().userContentController();
+    // Idempotent per UCC: WKUserContentController throws NSInvalidArgumentException if a handler is
+    // already registered for a name. A window can already carry `bridgeShim` (a second plugin
+    // attaching onMessage, a browser tab, or the env-gated bridge). removeScriptMessageHandlerForName
+    // is safe when none is present, so remove-then-add makes re-install a no-op instead of a crash.
+    ucc.removeScriptMessageHandlerForName(&NSString::from_str("bridgeShim"));
     ucc.addScriptMessageHandler_name(
         ProtocolObject::from_ref(&*handler),
         &NSString::from_str("bridgeShim"),

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

@@ -23,6 +23,8 @@ mod notifications_mac;
 #[cfg(target_os = "macos")]
 mod oauth_mac;
 #[cfg(target_os = "macos")]
+mod plugin_host;
+#[cfg(target_os = "macos")]
 mod popup_mac;
 #[cfg(target_os = "macos")]
 mod push_mac;
@@ -107,6 +109,14 @@ struct ShellConfig {
     /// bare `bun` lookup would fail there; sidecar.rs falls back to `bun` when this is empty/gone.
     #[serde(default)]
     handlers_runtime: String,
+    /// Absolute path to the bun-built multiplexed plugin-host bundle (src/plugin/host.ts). Empty →
+    /// no plugins configured; the shell skips spawning the host. Stamped by `regeneratePlugins`.
+    #[serde(default)]
+    plugin_host: String,
+    /// Resolved + bun-built plugins the host loads at boot (`[{namespace, attachTo, bundlePath}]`),
+    /// passed through to the host process verbatim. Empty when none.
+    #[serde(default)]
+    plugins: Vec<serde_json::Value>,
     /// 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').
@@ -595,6 +605,20 @@ fn appwrap_invoke(window: tauri::WebviewWindow, envelope: String) {
             deliver(&window, &resp);
             return;
         }
+        // Plugin handler methods (cfg.plugins): the sidecar-compatible RPC path, routed AFTER the
+        // sidecar so a `desktop.handlers` claim always wins for the same name. Same envelope shape.
+        #[cfg(target_os = "macos")]
+        if plugin_host::claims(&method) {
+            let resp = match plugin_host::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!({
@@ -714,6 +738,9 @@ fn main() {
                 popup_mac::close_all();
                 // Kill the handlers sidecar so the Bun process never outlives the shell.
                 sidecar::shutdown();
+                // Tell plugins the main window is gone, then kill the plugin host (never outlives the shell).
+                plugin_host::on_window_closed("main");
+                plugin_host::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.
             }
@@ -801,6 +828,20 @@ fn main() {
             if !shell().handlers.is_empty() {
                 sidecar::init(&shell().handlers, &shell().handlers_runtime);
             }
+            // Multiplexed plugin host (cfg.plugins): spawn the Bun host over a Unix socket and block
+            // (≤5s) on its `ready` before the window's first invoke can race a plugin handler. Additive
+            // to the sidecar — inert when no plugins are configured. Reuses handlersRuntime (the same
+            // stamped bun binary). See plugin_host.rs.
+            #[cfg(target_os = "macos")]
+            if !shell().plugin_host.is_empty() && !shell().plugins.is_empty() {
+                let plugins_json = serde_json::to_string(&shell().plugins).unwrap_or_else(|_| "[]".into());
+                plugin_host::init(
+                    app.handle().clone(),
+                    &shell().plugin_host,
+                    &shell().handlers_runtime,
+                    &plugins_json,
+                );
+            }
             // 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.
@@ -844,6 +885,10 @@ fn main() {
                     let _ = window.show();
                 }
             }
+            // Per-window plugin attach: fan out `window-created` to the plugin host so plugins whose
+            // `attachTo` matches "main" run their `onWindow(ctx)`. No-op when no host is running.
+            #[cfg(target_os = "macos")]
+            plugin_host::on_window_created("main", "index.html");
             // 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.

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

@@ -0,0 +1,522 @@
+//! Multiplexed PLUGIN HOST — the bidirectional generalization of `sidecar.rs`.
+//!
+//! Where the sidecar is a ONE-WAY method-RPC to a single Bun process (shell→sidecar request/response,
+//! no window reference), the plugin host is a BIDIRECTIONAL, per-window channel to a single Bun host
+//! process that loads ALL configured plugins (Elya decision: one multiplexed host):
+//!   - the shell EMITS window/page lifecycle EVENTS to the host (window-created, message, closed),
+//!   - the host CALLS native `webview-control` OPS back (a plugin's `WindowCtx` methods) — routed by
+//!     `pluginId × windowId`, dispatched on the main thread, answered with a `result`,
+//!   - handler RPC (`call`/`result`) preserves the sidecar's back-compat path: a plugin's `handlers`
+//!     route exactly like `defineHandlers`.
+//!
+//! Transport = a Unix domain socket (design decision: no port, filesystem-perm'd). The shell BINDS +
+//! listens, spawns `bun <host> --socket <path> --plugins <json>`, and the host connects. Wire = the
+//! same proven line-JSON model as `bridge_mac.rs`, generalized to the plugin envelope. This module is
+//! ADDITIVE — the `desktop.handlers` sidecar (sidecar.rs) is untouched, so `defineHandlers` is unbroken.
+
+use serde_json::{json, Value};
+use std::collections::{HashMap, HashSet};
+use std::io::{BufRead, BufReader, Write};
+use std::os::unix::net::{UnixListener, UnixStream};
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::mpsc::{self, Receiver, Sender, SyncSender};
+use std::sync::{Arc, Mutex, OnceLock};
+use std::time::Duration;
+
+use objc2::rc::Retained;
+use objc2::MainThreadMarker;
+use objc2_web_kit::WKWebView;
+use tauri::{AppHandle, Manager};
+
+use webview_control as wv;
+
+const READY_TIMEOUT: Duration = Duration::from_secs(5);
+const CALL_TIMEOUT: Duration = Duration::from_secs(30);
+
+pub type PluginResult = Result<Value, (String, String)>;
+
+struct PluginHost {
+    /// Handler methods the host advertised (sidecar-compatible RPC surface), builtin-filtered.
+    methods: HashSet<String>,
+    alive: Arc<AtomicBool>,
+    /// Outbound line sink (drained by the writer thread → the socket).
+    out: Sender<String>,
+    /// Pending handler `call`s awaiting a `result`, keyed by our minted id.
+    pending: Arc<Mutex<HashMap<String, Sender<Value>>>>,
+    next_id: AtomicU64,
+    child: Mutex<std::process::Child>,
+    socket_path: String,
+}
+
+static HOST: OnceLock<PluginHost> = OnceLock::new();
+/// Live outbound sink, published for the duration of a connection so `on_window_created` / message
+/// sinks (which fire outside a request/response) can reach the host. None when disconnected.
+static OUT: Mutex<Option<Sender<String>>> = Mutex::new(None);
+
+/// Parse one host line into a routable outcome. Pure — unit-tested.
+enum Line {
+    Ready(Vec<String>),
+    Op { env: Value },
+    Result { id: String, value: Value },
+    Other,
+}
+
+fn parse_line(line: &str) -> Line {
+    let v: Value = match serde_json::from_str(line) {
+        Ok(v) => v,
+        Err(_) => return Line::Other,
+    };
+    match v["kind"].as_str() {
+        Some("ready") => {
+            let methods = v["plugins"]
+                .as_array()
+                .map(|plugins| {
+                    plugins
+                        .iter()
+                        .flat_map(|p| p["methods"].as_array().cloned().unwrap_or_default())
+                        .filter_map(|m| m.as_str().map(str::to_string))
+                        .collect()
+                })
+                .unwrap_or_default();
+            Line::Ready(methods)
+        }
+        Some("op") => Line::Op { env: v },
+        Some("result") => match v["id"].as_str() {
+            Some(id) => Line::Result { id: id.to_string(), value: v },
+            None => Line::Other,
+        },
+        _ => Line::Other,
+    }
+}
+
+/// Drop any handler claim that shadows a built-in namespace (same guard as the sidecar). Pure.
+fn filter_claims(methods: Vec<String>) -> Vec<String> {
+    let (rejected, kept): (Vec<String>, Vec<String>) = methods
+        .into_iter()
+        .partition(|m| crate::BUILTIN_METHOD_PREFIXES.iter().any(|p| m.starts_with(p)));
+    if !rejected.is_empty() {
+        eprintln!("[plugin-host] rejecting handler method(s) that shadow built-ins: {rejected:?}");
+    }
+    kept
+}
+
+/// Resolve which Bun binary to spawn (same policy as the sidecar — stamped path wins, else `bun`).
+fn resolve_runtime(stamped: &str) -> String {
+    if !stamped.is_empty() && std::path::Path::new(stamped).exists() {
+        return stamped.to_string();
+    }
+    eprintln!("[plugin-host] stamped runtime missing/empty ({stamped}) — falling back to `bun` (PATH lookup)");
+    "bun".to_string()
+}
+
+/// Spawn the multiplexed plugin host over a fresh Unix socket and block (≤5s) on its `ready`.
+/// `plugins_json` is the stamped `[{namespace, attachTo, bundlePath}]` array. Degrades to inert on
+/// any failure (the shell runs without plugins). Idempotent (OnceLock).
+pub fn init(app: AppHandle, host_path: &str, runtime: &str, plugins_json: &str) {
+    if HOST.get().is_some() {
+        return;
+    }
+    let socket_path = std::env::temp_dir()
+        .join(format!("appwrap-plugins-{}.sock", std::process::id()))
+        .to_string_lossy()
+        .to_string();
+    let _ = std::fs::remove_file(&socket_path);
+    let listener = match UnixListener::bind(&socket_path) {
+        Ok(l) => l,
+        Err(e) => {
+            eprintln!("[plugin-host] bind {socket_path} failed: {e} — running without plugins");
+            return;
+        }
+    };
+
+    let bun = resolve_runtime(runtime);
+    let mut child = match std::process::Command::new(&bun)
+        .args([host_path, "--socket", &socket_path, "--plugins", plugins_json])
+        .stdin(std::process::Stdio::null())
+        .stdout(std::process::Stdio::piped())
+        .stderr(std::process::Stdio::piped())
+        .spawn()
+    {
+        Ok(c) => c,
+        Err(e) => {
+            eprintln!("[plugin-host] spawn `{bun} {host_path}` failed: {e} — running without plugins");
+            let _ = std::fs::remove_file(&socket_path);
+            return;
+        }
+    };
+    // host stdout/stderr → shell stderr (prefixed) for diagnostics.
+    if let Some(p) = child.stdout.take() {
+        std::thread::spawn(move || {
+            for line in BufReader::new(p).lines().map_while(Result::ok) {
+                eprintln!("[plugin-host:out] {line}");
+            }
+        });
+    }
+    if let Some(p) = child.stderr.take() {
+        std::thread::spawn(move || {
+            for line in BufReader::new(p).lines().map_while(Result::ok) {
+                eprintln!("[plugin-host:err] {line}");
+            }
+        });
+    }
+
+    // Accept the host's connection (bounded — the host connects immediately after spawn).
+    listener.set_nonblocking(false).ok();
+    let stream = match accept_with_timeout(&listener, READY_TIMEOUT) {
+        Some(s) => s,
+        None => {
+            eprintln!("[plugin-host] host did not connect within {READY_TIMEOUT:?} — killing, no plugins");
+            let _ = child.kill();
+            let _ = std::fs::remove_file(&socket_path);
+            return;
+        }
+    };
+    let writer = stream.try_clone().expect("clone unix stream");
+    let reader = stream;
+
+    // Writer thread: drain the outbound channel → the socket.
+    let (out_tx, out_rx): (Sender<String>, Receiver<String>) = mpsc::channel();
+    {
+        let mut w = writer;
+        std::thread::spawn(move || {
+            for line in out_rx {
+                if w.write_all(line.as_bytes()).and_then(|_| w.write_all(b"\n")).is_err() {
+                    break;
+                }
+            }
+        });
+    }
+    *OUT.lock().unwrap() = Some(out_tx.clone());
+
+    let alive = Arc::new(AtomicBool::new(true));
+    let pending: Arc<Mutex<HashMap<String, Sender<Value>>>> = Arc::new(Mutex::new(HashMap::new()));
+
+    // Reader thread: first `ready` unblocks init; then route ops (→ main thread) + resolve results.
+    let (ready_tx, ready_rx): (SyncSender<Option<Vec<String>>>, Receiver<Option<Vec<String>>>) =
+        mpsc::sync_channel(1);
+    let r_alive = alive.clone();
+    let r_pending = pending.clone();
+    let r_out = out_tx.clone();
+    let r_app = app.clone();
+    std::thread::spawn(move || {
+        let mut reader = BufReader::new(reader);
+        let mut got_ready = false;
+        let mut line = String::new();
+        loop {
+            line.clear();
+            match reader.read_line(&mut line) {
+                Ok(0) | Err(_) => break,
+                Ok(_) => {}
+            }
+            let trimmed = line.trim();
+            if trimmed.is_empty() {
+                continue;
+            }
+            match parse_line(trimmed) {
+                Line::Ready(methods) => {
+                    if !got_ready {
+                        got_ready = true;
+                        let _ = ready_tx.send(Some(methods));
+                    }
+                }
+                Line::Op { env } => dispatch_op(&r_app, &r_out, env),
+                Line::Result { id, value } => {
+                    if let Some(tx) = r_pending.lock().unwrap().remove(&id) {
+                        let _ = tx.send(value);
+                    }
+                }
+                Line::Other => eprintln!("[plugin-host] ignoring line: {trimmed}"),
+            }
+        }
+        r_alive.store(false, Ordering::SeqCst);
+        r_pending.lock().unwrap().clear();
+        *OUT.lock().unwrap() = None;
+        if !got_ready {
+            let _ = ready_tx.send(None);
+        }
+        eprintln!("[plugin-host] reader exited — host marked dead");
+    });
+
+    let methods = match ready_rx.recv_timeout(READY_TIMEOUT) {
+        Ok(Some(m)) => filter_claims(m),
+        _ => {
+            eprintln!("[plugin-host] no `ready` within {READY_TIMEOUT:?} — killing, no plugins");
+            let _ = child.kill();
+            let _ = std::fs::remove_file(&socket_path);
+            return;
+        }
+    };
+    eprintln!("[plugin-host] ready — {} handler method(s): {:?}", methods.len(), methods);
+    let _ = HOST.set(PluginHost {
+        methods: methods.into_iter().collect(),
+        alive,
+        out: out_tx,
+        pending,
+        next_id: AtomicU64::new(1),
+        child: Mutex::new(child),
+        socket_path,
+    });
+}
+
+/// Accept one connection, polling in non-blocking mode until `timeout`.
+fn accept_with_timeout(listener: &UnixListener, timeout: Duration) -> Option<UnixStream> {
+    listener.set_nonblocking(true).ok()?;
+    let deadline = std::time::Instant::now() + timeout;
+    loop {
+        match listener.accept() {
+            Ok((s, _)) => {
+                s.set_nonblocking(false).ok();
+                return Some(s);
+            }
+            Err(ref e) if e.kind() == std::io::ErrorKind::WouldBlock => {
+                if std::time::Instant::now() >= deadline {
+                    return None;
+                }
+                std::thread::sleep(Duration::from_millis(10));
+            }
+            Err(_) => return None,
+        }
+    }
+}
+
+// ── Events: shell → host (window/page lifecycle). Fire-and-forget via the live OUT sink. ──────────
+
+/// Emit a `window-created` event so the host can fan out to plugins whose `attachTo` matches. Called
+/// from main.rs once a window's webview exists.
+pub fn on_window_created(label: &str, url: &str) {
+    emit_event("window-created", label, json!({ "url": url }));
+}
+
+/// Emit a `window-closed` event (plugin `onClose` + attach teardown).
+pub fn on_window_closed(label: &str) {
+    emit_event("window-closed", label, json!({}));
+}
+
+fn emit_event(method: &str, window_id: &str, params: Value) {
+    if let Some(tx) = OUT.lock().unwrap().as_ref() {
+        let _ = tx.send(json!({ "kind": "event", "method": method, "windowId": window_id, "params": params }).to_string());
+    }
+}
+
+// ── Ops: host → shell (a plugin's WindowCtx call). Dispatched on the main thread, answered `result`. ──
+
+fn dispatch_op(app: &AppHandle, out: &Sender<String>, env: Value) {
+    let id = env["id"].as_str().unwrap_or_default().to_string();
+    let window_id = env["windowId"].as_str().unwrap_or_default().to_string();
+    let method = env["method"].as_str().unwrap_or_default().to_string();
+    let params = env["params"].clone();
+    let app = app.clone();
+    let out = out.clone();
+    let out_err = out.clone();
+    let id_err = id.clone();
+    let r = app.clone().run_on_main_thread(move || {
+        run_op_on_main(&app, &out, &id, &window_id, &method, &params);
+    });
+    if let Err(e) = r {
+        respond(&out_err, &id_err, Err(format!("dispatch failed: {e}")));
+    }
+}
+
+/// Resolve the target window's `*mut WKWebView` (profile window OR the main tauri window) and hand it
+/// to `f` on the main thread. Returns Err if the window is unknown. Mirrors bridge_mac's dual path.
+fn on_webview<F>(app: &AppHandle, label: &str, f: F) -> Result<(), String>
+where
+    F: FnOnce(*mut WKWebView) + Send + 'static,
+{
+    if let Some(wk) = wv::profile_webview(label) {
+        f(Retained::as_ptr(&wk) as *mut WKWebView);
+        return Ok(());
+    }
+    match app.get_webview_window(label) {
+        Some(w) => w
+            .with_webview(move |pw| f(pw.inner() as *mut WKWebView))
+            .map_err(|e| e.to_string()),
+        None => Err(format!("no window {label}")),
+    }
+}
+
+fn run_op_on_main(app: &AppHandle, out: &Sender<String>, id: &str, label: &str, method: &str, params: &Value) {
+    let js = params["js"].as_str().unwrap_or_default().to_string();
+    let url = params["url"].as_str().unwrap_or_default().to_string();
+    match method {
+        "injectScript" => {
+            let res = on_webview(app, label, move |wk| unsafe { wv::inject_script(wk, &js) });
+            respond(out, id, res.map(|_| json!({ "ok": true })));
+        }
+        "postMessage" => {
+            // plugin→page: deliver as a `window` `appwrap:plugin` CustomEvent whose detail is the msg.
+            let payload = serde_json::to_string(&params["msg"]).unwrap_or_else(|_| "null".into());
+            let script = format!(
+                "window.dispatchEvent(new CustomEvent('appwrap:plugin',{{detail:{payload}}}));"
+            );
+            let res = on_webview(app, label, move |wk| unsafe { wv::inject_script(wk, &script) });
+            respond(out, id, res.map(|_| json!({ "ok": true })));
+        }
+        "navigate" => {
+            let res = on_webview(app, label, move |wk| unsafe { let _ = wv::navigate(wk, &url); });
+            respond(out, id, res.map(|_| json!({ "ok": true })));
+        }
+        "back" => respond(out, id, on_webview(app, label, |wk| unsafe { wv::go_back(wk) }).map(|_| json!({ "ok": true }))),
+        "forward" => respond(out, id, on_webview(app, label, |wk| unsafe { wv::go_forward(wk) }).map(|_| json!({ "ok": true }))),
+        "reload" => respond(out, id, on_webview(app, label, |wk| unsafe { wv::reload(wk) }).map(|_| json!({ "ok": true }))),
+        "setInspectable" => respond(out, id, on_webview(app, label, |wk| unsafe { wv::set_inspectable(wk) }).map(|_| json!({ "ok": true }))),
+        "url" => {
+            let out2 = out.clone();
+            let id2 = id.to_string();
+            let res = on_webview(app, label, move |wk| unsafe {
+                wv::eval_async(wk, "return location.href".into(), move |r| {
+                    respond(&out2, &id2, r.map(Value::String).map_err(|e| e));
+                });
+            });
+            if let Err(e) = res { respond(out, id, Err(e)); }
+        }
+        "eval" => {
+            let out2 = out.clone();
+            let id2 = id.to_string();
+            let js2 = js.clone();
+            let res = on_webview(app, label, move |wk| unsafe {
+                wv::eval_async(wk, js2, move |r| {
+                    // The crate delivers a RAW JSON string; parse it so the plugin gets a real value.
+                    respond(&out2, &id2, r.map(|s| serde_json::from_str(&s).unwrap_or(Value::String(s))));
+                });
+            });
+            if let Err(e) = res { respond(out, id, Err(e)); }
+        }
+        "snapshot" => {
+            let out2 = out.clone();
+            let id2 = id.to_string();
+            let res = on_webview(app, label, move |wk| unsafe {
+                wv::snapshot(wk, move |r| {
+                    respond(&out2, &id2, r.map(|bytes| json!(bytes)));
+                });
+            });
+            if let Err(e) = res { respond(out, id, Err(e)); }
+        }
+        "close" => {
+            let ok = wv::close(label);
+            if ok {
+                respond(out, id, Ok(json!({ "ok": true })));
+            } else if let Some(w) = app.get_webview_window(label) {
+                respond(out, id, w.close().map(|_| json!({ "ok": true })).map_err(|e| e.to_string()));
+            } else {
+                respond(out, id, Err(format!("no window {label}")));
+            }
+        }
+        "subscribeMessages" => {
+            // Install the bridgeShim WKScriptMessageHandler → page beacons become `message` events.
+            let out2 = out.clone();
+            let label2 = label.to_string();
+            let res = on_webview(app, label, move |wk| {
+                let mtm = MainThreadMarker::new().expect("run_on_main_thread is main");
+                let sink_out = out2.clone();
+                let sink_label = label2.clone();
+                let sink: wv::MessageSink = Box::new(move |raw: String| {
+                    let _ = sink_out.send(
+                        json!({ "kind": "event", "method": "message", "windowId": sink_label, "params": { "raw": raw } }).to_string(),
+                    );
+                });
+                unsafe { wv::install_message_handler(wk, mtm, sink) };
+            });
+            respond(out, id, res.map(|_| json!({ "ok": true })));
+        }
+        _ => respond(out, id, Err(format!("unknown op: {method}"))),
+    }
+}
+
+fn respond(out: &Sender<String>, id: &str, result: Result<Value, String>) {
+    let msg = match result {
+        Ok(data) => json!({ "kind": "result", "id": id, "ok": true, "data": data }),
+        Err(e) => json!({ "kind": "result", "id": id, "ok": false, "error": { "code": "NATIVE_ERROR", "message": e } }),
+    };
+    let _ = out.send(msg.to_string());
+}
+
+// ── Handler RPC: shell → host (sidecar-compatible `call`/`result`). ───────────────────────────────
+
+/// True if the host advertised this handler method (routed AFTER the sidecar in appwrap_invoke).
+pub fn claims(method: &str) -> bool {
+    HOST.get().is_some_and(|h| h.methods.contains(method))
+}
+
+/// Forward a claimed handler method to the host and block on its response (≤30s).
+pub fn request(method: &str, params: &Value) -> PluginResult {
+    let h = HOST.get().ok_or_else(|| ("NATIVE_ERROR".to_string(), "no plugin host".to_string()))?;
+    if !h.alive.load(Ordering::SeqCst) {
+        return Err(("NATIVE_ERROR".into(), format!("plugin host is not running ({method})")));
+    }
+    let id = format!("ph-{}", h.next_id.fetch_add(1, Ordering::SeqCst));
+    let (tx, rx) = mpsc::channel::<Value>();
+    h.pending.lock().unwrap().insert(id.clone(), tx);
+    let env = json!({ "kind": "call", "id": id, "method": method, "params": params });
+    if h.out.send(env.to_string()).is_err() {
+        h.pending.lock().unwrap().remove(&id);
+        return Err(("NATIVE_ERROR".into(), "plugin host write failed".into()));
+    }
+    match rx.recv_timeout(CALL_TIMEOUT) {
+        Ok(resp) => {
+            if resp["ok"].as_bool() == Some(true) {
+                Ok(resp.get("data").cloned().unwrap_or(Value::Null))
+            } else {
+                let code = resp["error"]["code"].as_str().unwrap_or("NATIVE_ERROR").to_string();
+                let message = resp["error"]["message"].as_str().unwrap_or("handler error").to_string();
+                Err((code, message))
+            }
+        }
+        Err(mpsc::RecvTimeoutError::Timeout) => {
+            h.pending.lock().unwrap().remove(&id);
+            Err(("NATIVE_ERROR".into(), format!("plugin host timeout ({method})")))
+        }
+        Err(mpsc::RecvTimeoutError::Disconnected) => {
+            Err(("NATIVE_ERROR".into(), format!("plugin host died during call ({method})")))
+        }
+    }
+}
+
+/// Kill the host child + remove the socket file (idempotent). Called on main-window teardown.
+pub fn shutdown() {
+    if let Some(h) = HOST.get() {
+        let _ = h.child.lock().unwrap().kill();
+        let _ = std::fs::remove_file(&h.socket_path);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_ready_flattens_all_plugin_methods() {
+        match parse_line(r#"{"kind":"ready","plugins":[{"pluginId":"a","methods":["a.x"]},{"pluginId":"b","methods":["b.y","b.z"]}]}"#) {
+            Line::Ready(m) => assert_eq!(m, vec!["a.x".to_string(), "b.y".into(), "b.z".into()]),
+            _ => panic!("expected Ready"),
+        }
+    }
+
+    #[test]
+    fn parse_op_and_result() {
+        assert!(matches!(parse_line(r#"{"kind":"op","id":"op-1","method":"url"}"#), Line::Op { .. }));
+        match parse_line(r#"{"kind":"result","id":"ph-1","ok":true,"data":5}"#) {
+            Line::Result { id, value } => { assert_eq!(id, "ph-1"); assert_eq!(value["data"], 5); }
+            _ => panic!("expected Result"),
+        }
+    }
+
+    #[test]
+    fn parse_malformed_is_other() {
+        assert!(matches!(parse_line("not json"), Line::Other));
+        assert!(matches!(parse_line(r#"{"kind":"result","ok":true}"#), Line::Other)); // no id
+    }
+
+    #[test]
+    fn filter_claims_rejects_builtin_shadowing() {
+        let kept = filter_claims(vec!["storage.get".into(), "myplugin.doThing".into()]);
+        assert_eq!(kept, vec!["myplugin.doThing".to_string()]);
+    }
+
+    #[test]
+    fn resolve_runtime_prefers_existing_stamped_path() {
+        assert_eq!(resolve_runtime("/bin/ls"), "/bin/ls");
+        assert_eq!(resolve_runtime("/nonexistent/bun-xyz"), "bun");
+        assert_eq!(resolve_runtime(""), "bun");
+    }
+}

package/src/cli.ts

@@ -685,6 +685,51 @@ function selectSigningProfile(
   return newest.name;
 }
 
+/** True if the persisted iOS project carries Manual / App-Store (match/fastlane) signing residue —
+ * `CODE_SIGN_STYLE = Manual` or a `PROVISIONING_PROFILE_SPECIFIER`. `appwrap release/publish`
+ * (fastlane `update_code_signing_settings`) writes these DIRECTLY into project.pbxproj, which NS
+ * PRESERVES across prepares and which OVERRIDES build.xcconfig — so a later device `deploy`/`dev`
+ * (auto lane) would inherit App-Store distribution signing and fail to install on a device. */
+export function pbxHasManualSigningResidue(pbxSrc: string): boolean {
+  return /^\s*CODE_SIGN_STYLE\s*=\s*Manual\s*;/m.test(pbxSrc)
+    || /^\s*PROVISIONING_PROFILE_SPECIFIER\s*=/m.test(pbxSrc);
+}
+
+/** Rewrite App-Store/manual signing residue in a project.pbxproj back to Xcode AUTOMATIC signing:
+ * Manual→Automatic, drop match/App-Store profile pins (PROVISIONING_PROFILE_SPECIFIER + UUID form),
+ * and Apple Distribution→Apple Development (plain + `[sdk=…]` variants). DEVELOPMENT_TEAM is left as
+ * is (correct for the current app). Pure + idempotent — a clean project passes through unchanged. */
+export function resetPbxToAutomaticSigning(pbxSrc: string): string {
+  let s = pbxSrc;
+  s = s.replace(/(^\s*CODE_SIGN_STYLE\s*=\s*)Manual(\s*;)/mg, '$1Automatic$2');
+  s = s.replace(/^[ \t]*PROVISIONING_PROFILE_SPECIFIER\s*=\s*[^;\n]*;[ \t]*\n?/mg, '');
+  s = s.replace(/^[ \t]*PROVISIONING_PROFILE\s*=\s*[^;\n]*;[ \t]*\n?/mg, '');
+  s = s.replace(/("?CODE_SIGN_IDENTITY(?:\[[^\]]*\])?"?\s*=\s*)"?Apple Distribution"?(\s*;)/mg, '$1"Apple Development"$2');
+  return s;
+}
+
+/** Self-heal for the auto lane (`deploy`/`dev`, signing≠manual): if a prior `release`/`publish` left
+ * Manual/App-Store signing in platforms/ios/project.pbxproj (fastlane `update_code_signing_settings`,
+ * which NS preserves across prepares + which OVERRIDES build.xcconfig), rewrite it back to automatic
+ * development signing IN PLACE. Surgical (no rebuild, deterministic — unlike wiping the platform dir,
+ * which fights the build-cache skip). Keeps device installs working across lane/app switches; a normal
+ * deploy with no residue is a no-op. */
+function resetStaleSigningForAutoLane(outDir: string, cfg: AppwrapConfig): void {
+  const mode = process.env.APPWRAP_SIGNING?.trim() || cfg.signing;
+  if (mode === 'manual') return;
+  const iosDir = join(outDir, 'platforms', 'ios');
+  if (!existsSync(iosDir)) return;
+  let proj: string | undefined;
+  try { proj = readdirSync(iosDir).find((d) => d.endsWith('.xcodeproj') && d !== 'Pods.xcodeproj'); } catch { return; }
+  if (!proj) return;
+  const pbx = join(iosDir, proj, 'project.pbxproj');
+  if (!existsSync(pbx)) return;
+  const src = readFileSync(pbx, 'utf8');
+  if (!pbxHasManualSigningResidue(src)) return;
+  writeFileSync(pbx, resetPbxToAutomaticSigning(src));
+  console.log('  ⚠ cleared stale manual/App-Store signing (from a prior `release`/`publish`) → automatic dev signing for this device build.');
+}
+
 /** Manual code-signing for device builds (`signing: 'manual'`). Resolves the app + each extension
  * target to an installed provisioning profile (by `<teamId>.<bundleId>`) and stamps Manual signing
  * into build.xcconfig (main app) + each extension's extension.json targetBuildConfigurationProperties.
@@ -2033,6 +2078,71 @@ flex-direction:column;gap:20px;background:#0b0b0f;color:#e5e5e5;font:14px -apple
 /** 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`). */
+/**
+ * Make `cfg.plugins` LIVE (A.1 loader): resolve each entry (path OR npm package), bun-build its
+ * entrypoint to a single embedded file under `native-desktop/plugins/`, bun-build the multiplexed
+ * plugin-host once, and stamp `{ pluginHost, plugins:[{bundleId, attachTo, bundlePath}] }` into the
+ * shell config. The Rust shell (plugin_host.rs) spawns the host with the stamped plugins at boot.
+ *
+ * A.1 scope: manifest/perms/native-deps merge is STUBBED (noted) — full `capabilities.manifest.ts`
+ * reuse (perms/entitlements union) lands later. `bundleId` here is the file/package basename (a
+ * pre-load build id for the bundle filename only); the authoritative routing/diagnostic identifier is
+ * the plugin def's `name`, which the host reads from the bundle after `import()`.
+ */
+export function regeneratePlugins(cwd: string, cfg: AppwrapConfig, outDir: string, shell: DesktopShellConfig): void {
+  const entries = cfg.plugins ?? [];
+  if (entries.length === 0) return;
+  const outPlugins = join(outDir, 'plugins');
+  mkdirSync(outPlugins, { recursive: true });
+  const bun = process.execPath; // the CLI runs under bun → the exact runtime to build/spawn with
+
+  const bunBuild = (entrypoint: string, outfile: string): boolean => {
+    try {
+      execFileSync(bun, ['build', entrypoint, '--target=bun', '--outfile', outfile], { stdio: 'pipe' });
+      return true;
+    } catch (e: unknown) {
+      console.warn(`⚠ plugin bun-build failed (${entrypoint}): ${e instanceof Error ? e.message : String(e)}`);
+      return false;
+    }
+  };
+
+  // Build the host bundle once (from THIS package's src/plugin/host.ts).
+  const hostSrc = resolve(import.meta.dir, 'plugin', 'host.ts');
+  const hostOut = join(outPlugins, 'host.js');
+  if (!bunBuild(hostSrc, hostOut)) {
+    console.warn('⚠ plugin host failed to build — plugins disabled for this build.');
+    return;
+  }
+
+  const stamped: DesktopShellConfig['plugins'] = [];
+  for (const raw of entries) {
+    const name = typeof raw === 'string' ? raw : raw.name;
+    const attachTo = typeof raw === 'string' ? undefined : raw.attachTo;
+    // Resolve: an existing path (relative to the app root) wins; else treat as an npm package name.
+    let entrypoint = resolve(cwd, name);
+    if (!existsSync(entrypoint)) {
+      try {
+        entrypoint = (Bun as unknown as { resolveSync(id: string, parent: string): string }).resolveSync(name, cwd);
+      } catch {
+        console.warn(`⚠ plugin "${name}" not found (no such path, not resolvable as an npm package) — skipping.`);
+        continue;
+      }
+    }
+    const bundleId = name.replace(/[^a-zA-Z0-9_-]/g, '_');
+    const bundlePath = join(outPlugins, `${bundleId}.js`);
+    if (!bunBuild(entrypoint, bundlePath)) continue;
+    stamped.push({ bundleId, attachTo, bundlePath });
+    console.log(`  plugin ← ${name}  (attachTo: ${attachTo ?? 'def-declared'})`);
+  }
+
+  if (stamped.length > 0) {
+    shell.pluginHost = hostOut;
+    shell.plugins = stamped;
+    // TODO(A.x): read each plugin's `manifest` and merge perms/entitlements/native-deps via
+    // generateModuleArtifacts + capabilities.manifest.ts (plugins are manifest-compatible with modules).
+  }
+}
+
 function regenerateDesktop(cwd: string, cfg: AppwrapConfig, outDir: string, pushSigned = false): void {
   if (!existsSync(DESKTOP_TEMPLATE_DIR)) {
     console.error(`✖ Desktop template not found at ${DESKTOP_TEMPLATE_DIR}`);
@@ -2104,6 +2214,10 @@ function regenerateDesktop(cwd: string, cfg: AppwrapConfig, outDir: string, push
     // the launchd PATH (no ~/.bun/bin), so the Rust shell can't rely on a bare `bun` lookup.
     shell.handlersRuntime = process.execPath;
   }
+  // Resolve + bun-build the configured plugins (make `cfg.plugins` LIVE). Runs BEFORE writing
+  // shell_config (and before applyOverrides, which happens after regenerateDesktop returns) so the
+  // stamped plugin bundles + host are embedded and the .app is self-contained.
+  regeneratePlugins(cwd, cfg, outDir, shell);
   writeFileSync(join(srcTauri, 'shell_config.json'), JSON.stringify(shell, null, 2) + '\n');
 
   const tauriConfPath = join(srcTauri, 'tauri.conf.json');
@@ -3204,6 +3318,9 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
   await sync(cwd, flags, cfgOverride); // re-stamp config + copy latest PWA dist (+ vendor backend assets)
   // Dev deploy → debug mode: keep-awake + WebView inspector for continuous troubleshooting.
   stampShellConfig(outDir, { ...cfg, debug: true });
+  // Self-heal: drop platforms/ios if a prior `release`/`publish` left App-Store/manual signing there
+  // (NS preserves it across prepares + it overrides build.xcconfig) → clean automatic dev signing.
+  resetStaleSigningForAutoLane(outDir, cfg);
 
   const ipaDir = join(outDir, 'platforms/ios/build/Debug-iphoneos');
 

package/src/config.ts

@@ -257,9 +257,13 @@ export interface AppwrapConfig {
    * OVER the generated wrapper after stamping — for legacy/custom native code the declarative config
    * can't express. Default `'appwrap.overrides'`; applied only if it exists. */
   overrides?: string;
-  /** Reserved — appwrap plugins (npm packages contributing a kit module + native handlers + config).
-   * Parsed today; full native composition lands with the plugin contract (see framework-extensibility). */
-  plugins?: string[];
+  /** appwrap TS plugins (`@livx.cc/appwrap/plugin`). Each entry is an npm package name or a path to a
+   * plugin entrypoint (that `export default definePlugin(...)`); the object form adds a config-level
+   * `attachTo` override (which windows it attaches to). `appwrap dev|build desktop` resolves + bun-builds
+   * each into a single embedded bundle and stamps it into the desktop shell (see `regeneratePlugins`),
+   * where the multiplexed plugin host loads them. A.1 skeleton: desktop-only; manifest/perms merge is
+   * stubbed (full module-manifest reuse lands later). */
+  plugins?: (string | { name: string; attachTo?: 'main' | 'all' | string; options?: unknown })[];
   /** Opt-in capability allow-list (built-in modules — see capabilities.manifest.ts). When PRESENT,
    * only the listed capabilities (plus always-on core) are advertised, permissioned, and — for
    * modules that own their handler file (e.g. health) — compiled into the shell. Their permissions,

package/src/desktop.ts

@@ -44,6 +44,11 @@ export interface DesktopShellConfig {
    * ~/.bun/bin, so a bare `bun` spawn fails. The Rust shell falls back to `bun` when this is
    * missing/nonexistent. */
   handlersRuntime: string;
+  /** Absolute path to the bun-built multiplexed plugin-host bundle (`src/plugin/host.ts`); '' when no
+   * plugins are configured (the Rust shell skips spawning the host). Stamped by `regeneratePlugins`. */
+  pluginHost: string;
+  /** Resolved + bun-built plugins the host loads at boot. Empty when none. Stamped by `regeneratePlugins`. */
+  plugins: { bundleId: string; attachTo?: string; bundlePath: string }[];
   /** True when `modules` includes 'media' → the .app carries an NSMicrophoneUsageDescription so
    * `getUserMedia` (voice mode) can pass macOS TCC. The WebKit-layer grant (popup_mac) is
    * unconditional; this only adds the OS usage string an app that actually uses the mic needs. */
@@ -90,6 +95,8 @@ export function deriveDesktopConfig(cfg: AppwrapConfig): DesktopShellConfig {
     handlers: d.handlers ?? '',
     pushSigned: false, // stamped by the CLI when a signing identity + macOS profile resolve — see buildDesktop
     handlersRuntime: '', // stamped by the CLI (process.execPath) when handlers is set — see regenerateDesktop
+    pluginHost: '', // stamped by regeneratePlugins (bun-built host bundle) when plugins are configured
+    plugins: [], // stamped by regeneratePlugins (resolved + bun-built plugin bundles)
     microphone: (cfg.modules ?? []).includes('media'),
     // `command`/`cwd`/`path` are resolved to absolute by the CLI (regenerateDesktop); carried as authored here.
     server: d.server

package/src/plugin/host.ts

@@ -0,0 +1,237 @@
+/**
+ * Multiplexed plugin host — ONE Bun process hosting all configured plugins (Elya decision: multiplexed
+ * for first-party). Generalizes `sidecar.rs`'s one-way NDJSON RPC to a BIDIRECTIONAL, per-window model.
+ *
+ * Boot: `bun host.ts --socket <path> --plugins <json>` — spawned by the Rust shell (plugin_host.rs).
+ * It connects to the shell's Unix domain socket, `import()`s each plugin bundle, and:
+ *   - announces `ready` (per-plugin handler methods, for the sidecar-compatible RPC path),
+ *   - on a `window-created` event, fans out to each plugin whose `attachTo` matches → `onWindow(ctx)`,
+ *   - marshals every `WindowCtx` call into an `op` envelope and awaits its `result`,
+ *   - routes page `message` events to that window's `onMessage` subscribers,
+ *   - answers `call` (handler RPC) exactly like the sidecar.
+ *
+ * The socket + framing live only in `main()`; `PluginHost` is transport-decoupled (a `send` sink) so
+ * the routing/attach logic is unit-testable with in-memory sinks (mirrors `runHandlers`).
+ */
+import type { Dispose, Envelope, PluginDef, StampedPlugin, WindowCtx, WindowIdentity } from './types';
+
+/** Reject an outstanding op after this long if the shell never sends its `result` (a native callback
+ * that never fires would otherwise leak the plugin's pending promise forever). Mirrors the Rust
+ * shell's CALL_TIMEOUT (plugin_host.rs, 30s) for the reverse op direction. */
+const OP_TIMEOUT_MS = 30_000;
+
+/** Resolve `attachTo` against a window identity. Config-string override wins over the def's own scope. */
+export function matchScope(def: PluginDef, override: string | undefined, win: WindowIdentity): boolean {
+  const scope = override ?? def.attachTo;
+  if (scope == null) return false; // handlers-only plugin — no per-window attach
+  if (typeof scope === 'function') return scope(win);
+  if (scope === 'all') return true;
+  if (scope === 'main') return win.id === 'main';
+  return scope === win.id;
+}
+
+interface Loaded {
+  entry: StampedPlugin;
+  def: PluginDef;
+}
+
+/** Per-(plugin,window) attach state: message subscribers + the onWindow disposer. */
+interface Attach {
+  subs: Set<(msg: string) => void>;
+  dispose?: Dispose;
+}
+
+export class PluginHost {
+  private pluginsRegistry: { pluginId: string; methods: string[] }[];
+  private ops = new Map<string, { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }>();
+  private attaches = new Map<string, Attach>(); // key: `${pluginId}\0${windowId}`
+  private opSeq = 0;
+
+  constructor(
+    private loaded: Loaded[],
+    private send: (env: Envelope) => void,
+  ) {
+    this.pluginsRegistry = loaded.map((l) => ({
+      pluginId: l.def.name,
+      methods: Object.keys(l.def.handlers ?? {}),
+    }));
+  }
+
+  /** Announce handler surfaces so the shell can route `call`s (the sidecar-compatible path). */
+  announceReady(): void {
+    this.send({ kind: 'ready', plugins: this.pluginsRegistry });
+  }
+
+  private key(pluginId: string, windowId: string): string {
+    return `${pluginId}\0${windowId}`;
+  }
+
+  /** Build the curated facade for one (plugin, window). Every method → an `op` awaiting a `result`. */
+  private makeCtx(pluginId: string, win: WindowIdentity): WindowCtx {
+    const call = <T>(method: string, params?: unknown): Promise<T> =>
+      new Promise<T>((resolve, reject) => {
+        const id = `op-${pluginId}-${++this.opSeq}`;
+        const timer = setTimeout(() => {
+          if (this.ops.delete(id)) reject(new Error(`op ${method} (${id}) timed out after ${OP_TIMEOUT_MS}ms`));
+        }, OP_TIMEOUT_MS);
+        // Don't keep the host process alive just for a pending op timer.
+        (timer as { unref?: () => void }).unref?.();
+        this.ops.set(id, { resolve: resolve as (v: unknown) => void, reject, timer });
+        this.send({ kind: 'op', id, pluginId, windowId: win.id, method, params });
+      });
+    const k = this.key(pluginId, win.id);
+    return {
+      id: win.id,
+      profileId: win.profileId,
+      url: () => call<string>('url'),
+      injectScript: (js) => call<void>('injectScript', { js }),
+      eval: <T = unknown>(js: string) => call<T>('eval', { js }),
+      navigate: (url) => call<void>('navigate', { url }),
+      back: () => call<void>('back'),
+      forward: () => call<void>('forward'),
+      reload: () => call<void>('reload'),
+      snapshot: async () => new Uint8Array(await call<number[]>('snapshot')),
+      close: () => call<void>('close'),
+      setInspectable: (on) => call<void>('setInspectable', { on }),
+      postMessage: (msg) => call<void>('postMessage', { msg }),
+      onMessage: (cb) => {
+        const a = this.attaches.get(k);
+        a?.subs.add(cb);
+        // First subscriber installs the native message handler on this window.
+        if (a && a.subs.size === 1) void call<void>('subscribeMessages');
+        return () => {
+          this.attaches.get(k)?.subs.delete(cb);
+        };
+      },
+    };
+  }
+
+  /** Dispatch one inbound envelope from the shell. */
+  async handle(env: Envelope): Promise<void> {
+    switch (env.kind) {
+      case 'result': {
+        const p = this.ops.get(env.id);
+        if (!p) return;
+        this.ops.delete(env.id);
+        clearTimeout(p.timer);
+        if (env.ok) p.resolve(env.data);
+        else p.reject(new Error(env.error?.message ?? 'op failed'));
+        return;
+      }
+      case 'call': {
+        // Handler RPC — sidecar-compatible. Method is namespaced; find the owning plugin.
+        const owner = this.loaded.find((l) => l.def.handlers && env.method in l.def.handlers);
+        const fn = owner?.def.handlers?.[env.method];
+        if (!fn) {
+          this.send({ kind: 'result', id: env.id, ok: false, error: { code: 'UNSUPPORTED', message: `${env.method} not implemented` } });
+          return;
+        }
+        try {
+          const data = await fn(env.params);
+          this.send({ kind: 'result', id: env.id, ok: true, data: data ?? null });
+        } catch (e) {
+          this.send({ kind: 'result', id: env.id, ok: false, error: { code: 'NATIVE_ERROR', message: e instanceof Error ? e.message : String(e) } });
+        }
+        return;
+      }
+      case 'event': {
+        const win: WindowIdentity = { id: env.windowId, profileId: env.params?.profileId };
+        if (env.method === 'window-created') {
+          for (const l of this.loaded) {
+            if (!matchScope(l.def, l.entry.attachTo, win)) continue;
+            const k = this.key(l.def.name, win.id);
+            if (this.attaches.has(k)) continue; // already attached
+            const attach: Attach = { subs: new Set() };
+            this.attaches.set(k, attach);
+            try {
+              const d = await l.def.onWindow?.(this.makeCtx(l.def.name, win));
+              if (typeof d === 'function') attach.dispose = d;
+            } catch (e) {
+              console.error(`[plugin-host] ${l.def.name}.onWindow(${win.id}) threw:`, e);
+            }
+          }
+        } else if (env.method === 'message') {
+          const raw = String(env.params?.raw ?? '');
+          for (const l of this.loaded) {
+            const a = this.attaches.get(this.key(l.def.name, win.id));
+            a?.subs.forEach((cb) => {
+              try { cb(raw); } catch (e) { console.error(`[plugin-host] ${l.def.name} onMessage threw:`, e); }
+            });
+          }
+        } else if (env.method === 'window-closed') {
+          for (const l of this.loaded) {
+            const k = this.key(l.def.name, win.id);
+            const a = this.attaches.get(k);
+            if (!a) continue;
+            try { a.dispose?.(); l.def.onClose?.(win); } catch (e) { console.error(`[plugin-host] ${l.def.name} onClose threw:`, e); }
+            this.attaches.delete(k);
+          }
+        }
+        return;
+      }
+      default:
+        return;
+    }
+  }
+}
+
+/** Load each stamped plugin bundle → its default-exported def. */
+async function loadPlugins(entries: StampedPlugin[]): Promise<Loaded[]> {
+  const out: Loaded[] = [];
+  for (const entry of entries) {
+    try {
+      const mod = await import(entry.bundlePath);
+      const def: PluginDef | undefined = mod.default ?? mod.plugin;
+      if (!def?.name) {
+        console.error(`[plugin-host] ${entry.bundlePath} has no default-exported plugin def — skipping`);
+        continue;
+      }
+      out.push({ entry, def });
+    } catch (e) {
+      console.error(`[plugin-host] failed to load ${entry.bundlePath}:`, e);
+    }
+  }
+  return out;
+}
+
+/** CLI entrypoint: wire the Unix-socket transport around a `PluginHost`. */
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  const socketPath = args[args.indexOf('--socket') + 1];
+  const pluginsArg = args[args.indexOf('--plugins') + 1];
+  if (!socketPath || !pluginsArg) {
+    console.error('[plugin-host] missing --socket or --plugins');
+    process.exit(1);
+  }
+  const entries: StampedPlugin[] = JSON.parse(pluginsArg);
+  const loaded = await loadPlugins(entries);
+
+  const net = await import('node:net');
+  const sock = net.connect(socketPath);
+  let host: PluginHost;
+  const sendLine = (env: Envelope) => sock.write(JSON.stringify(env) + '\n');
+
+  sock.on('connect', () => {
+    host = new PluginHost(loaded, sendLine);
+    host.announceReady();
+  });
+  let buf = '';
+  sock.setEncoding('utf8');
+  sock.on('data', (chunk: string) => {
+    buf += chunk;
+    let nl: number;
+    while ((nl = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, nl).trim();
+      buf = buf.slice(nl + 1);
+      if (line) {
+        try { void host.handle(JSON.parse(line)); }
+        catch (e) { console.error('[plugin-host] bad line:', e); }
+      }
+    }
+  });
+  sock.on('error', (e: unknown) => console.error('[plugin-host] socket error:', e));
+  sock.on('close', () => process.exit(0));
+}
+
+// Run only as an entrypoint (not when imported by tests).
+if (import.meta.main) void main();

package/src/plugin/index.ts

@@ -0,0 +1,39 @@
+/**
+ * `definePlugin` — author an appwrap TS plugin (`@livx.cc/appwrap/plugin`).
+ *
+ *   // my-plugin.ts (referenced by `plugins` in appwrap.config.ts)
+ *   import { definePlugin } from '@livx.cc/appwrap/plugin';
+ *   export default definePlugin({
+ *     name: 'my-plugin',
+ *     attachTo: 'main',
+ *     onWindow(win) {
+ *       win.onMessage((m) => console.log('page said', m));
+ *       win.injectScript(`webkit.messageHandlers.bridgeShim.postMessage('hi')`);
+ *     },
+ *     handlers: { 'my-plugin.echo': (p) => ({ echoed: p }) }, // back-compat: == defineHandlers
+ *   });
+ *
+ * Types-first: `definePlugin` is an identity helper that validates + returns the def, which the plugin
+ * entrypoint `export default`s. The multiplexed host (`host.ts`) `import()`s the built bundle and reads
+ * `.default`. Nothing runs at import time (unlike `defineHandlers`, which starts a loop) — the host
+ * drives the lifecycle.
+ */
+import type { PluginDef } from './types';
+
+export function definePlugin(def: PluginDef): PluginDef {
+  if (!def || typeof def.name !== 'string' || !def.name) {
+    throw new Error('definePlugin: `name` is required');
+  }
+  return def;
+}
+
+export type {
+  PluginDef,
+  WindowCtx,
+  WindowScope,
+  WindowIdentity,
+  Dispose,
+  Envelope,
+  StampedPlugin,
+} from './types';
+export { WINDOW_CTX_VERSION } from './types';

package/src/plugin/types.ts

@@ -0,0 +1,109 @@
+/**
+ * appwrap plugin contract — the PORT (`@livx.cc/appwrap/plugin`).
+ *
+ * A TS plugin consumes a CURATED, VERSIONED facade over the native `webview-control` primitives
+ * ({@link WindowCtx}) — it never touches objc2 FFI. The plugin runs OUT-OF-WEBVIEW in the trusted
+ * multiplexed Bun host (see `host.ts`); the host speaks a bidirectional line-JSON protocol over a
+ * Unix domain socket to the Rust shell, which owns the primitives.
+ *
+ * IoC / Hollywood: the CORE calls the plugin — on window-created it fans out to each plugin whose
+ * `attachTo` matches, invoking `onWindow(ctx)`. Plugins never reach into core internals.
+ *
+ * A plugin with ONLY `handlers` behaves exactly like today's `defineHandlers` sidecar (back-compat):
+ * `desktop.handlers` is sugar for a local handlers-only plugin.
+ */
+
+/** The facade version this contract targets. Bump on a breaking WindowCtx change. */
+export const WINDOW_CTX_VERSION = 1 as const;
+
+/** Which windows a plugin attaches to (the OPT-IN gate — nothing is controllable unless configured).
+ * String forms are also expressible in `appwrap.config.ts` (stamped into shell_config); the predicate
+ * form is code-only (it lives in the host process). */
+export type WindowScope =
+  | 'main' // the app's main window
+  | 'all' // every window (incl. sub-windows)
+  | string // an explicit window label / id
+  | ((win: WindowIdentity) => boolean);
+
+/** The minimal identity the host matches `attachTo` against. */
+export interface WindowIdentity {
+  id: string;
+  /** Per-profile isolated store id, when the window was created for a profile; else undefined. */
+  profileId?: string;
+}
+
+/** Disposer returned by subscriptions / `onWindow` for teardown on detach/close. */
+export type Dispose = () => void;
+
+/**
+ * Curated, versioned facade over the native `webview-control` primitives, scoped to ONE window.
+ * NOT raw FFI — a deliberately small subset (design risk #4: avoid a god-interface). Every method
+ * marshals over the host↔shell socket as an `op` envelope and awaits a `result`.
+ */
+export interface WindowCtx extends WindowIdentity {
+  /** Current top-level URL of the window. */
+  url(): Promise<string>;
+  /** Inject JS that runs immediately in the page (fire-and-forget; no return value). */
+  injectScript(js: string): Promise<void>;
+  /** CSP-immune eval with an awaited return value (callAsyncJavaScript). `js` is a FUNCTION BODY
+   * (use `return`). Result is JSON-parsed. */
+  eval<T = unknown>(js: string): Promise<T>;
+  navigate(url: string): Promise<void>;
+  back(): Promise<void>;
+  forward(): Promise<void>;
+  reload(): Promise<void>;
+  /** PNG bytes of the current page. */
+  snapshot(): Promise<Uint8Array>;
+  close(): Promise<void>;
+  /** Toggle the Safari Web Inspector for this window (release builds gate on APPWRAP_DEVTOOLS). */
+  setInspectable(on: boolean): Promise<void>;
+  /** Subscribe to page→plugin beacons: the page calls
+   * `webkit.messageHandlers.bridgeShim.postMessage(json)`; `cb` receives the RAW string. */
+  onMessage(cb: (msg: string) => void): Dispose;
+  /** plugin→page: delivered as a `window` `appwrap:plugin` CustomEvent whose `detail` is `msg`. */
+  postMessage(msg: unknown): Promise<void>;
+}
+
+/** The plugin definition — authored with {@link definePlugin} and `export default`ed. */
+export interface PluginDef {
+  /** Namespace — guards against shadowing built-in method prefixes (like the sidecar's filter). */
+  name: string;
+  /** BACK-COMPAT: PWA→plugin RPC, identical semantics to `defineHandlers`. */
+  handlers?: Record<string, (params: any) => any | Promise<any>>;
+  /** OPT-IN: which windows this plugin attaches to. Omit → no per-window attach (handlers-only). */
+  attachTo?: WindowScope;
+  /** Per-window attach hook (the bidirectional part). Return a Dispose for detach cleanup. */
+  onWindow?(win: WindowCtx): void | Dispose | Promise<void | Dispose>;
+  /** Window closed. */
+  onClose?(win: WindowIdentity): void;
+}
+
+// ── Wire protocol (host ↔ shell, one JSON object per line over a Unix domain socket) ──────────────
+// Envelope: { pluginId?, windowId?, kind, method?, params?, id?, ... }. Route by pluginId × windowId.
+//   host → shell:  { kind:'ready',  plugins:[{ pluginId, methods:[…] }] }   (once, at boot)
+//   host → shell:  { kind:'op',     id, pluginId, windowId, method, params }  (a WindowCtx call)
+//   shell → host:  { kind:'result', id, ok, data|error }                     (op result)
+//   shell → host:  { kind:'event',  method, windowId, params }               (window/page lifecycle)
+//   shell → host:  { kind:'call',   id, method, params }                     (handler RPC, ==sidecar)
+//   host → shell:  { kind:'result', id, ok, data|error }                     (handler result)
+// `result` is bidirectional — each side keys its own pending map by the unique `id` it minted.
+
+export type Envelope =
+  | { kind: 'ready'; plugins: { pluginId: string; methods: string[] }[] }
+  | { kind: 'op'; id: string; pluginId: string; windowId: string; method: string; params?: unknown }
+  | { kind: 'result'; id: string; ok: boolean; data?: unknown; error?: { code: string; message: string } }
+  | { kind: 'event'; method: 'window-created' | 'window-closed' | 'message'; windowId: string; params?: any }
+  | { kind: 'call'; id: string; method: string; params?: unknown };
+
+/** One resolved plugin the host loads at boot (stamped into shell_config by `regeneratePlugins`). */
+export interface StampedPlugin {
+  /** Bundle/build id derived from the config source (sanitized filename or package name). This is a
+   * pre-bundle-load stamp — the plugin's real def `name` isn't known until the host `import()`s the
+   * bundle. It is NOT the routing/diagnostic identifier: routing (matchScope, registry) and all
+   * diagnostics key off the loaded def `name` (see host.ts). Used only for the bundle filename. */
+  bundleId: string;
+  /** Config-level attachTo OVERRIDE (string forms only). Falls back to the def's own `attachTo`. */
+  attachTo?: 'main' | 'all' | string;
+  /** Absolute path to the bun-built single-file plugin bundle. */
+  bundlePath: string;
+}