@livx.cc/appwrap 0.46.2 → 0.46.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.46.2",
+  "version": "0.46.3",
   "description": "Wrap any PWA into a native app with native capabilities (appwrap runtime + @livx.cc/native-kit).",
   "license": "MIT",
   "author": "Elya Livshitz",

package/runtime/app/shell/custom-webview.android.ts

@@ -93,6 +93,15 @@ export class CustomWebView extends WebView {
   /** Set by the bridge before load; receives raw envelope JSON. */
   onAppwrapMessage: ((json: string) => void) | null = null;
 
+  // STRONG JS references to the native clients. Chromium holds the Java WebViewClient /
+  // WebChromeClient, but NativeScript's mark-and-sweep does NOT treat that native hold as a
+  // GC root — so without a JS-side reference the JS peer gets collected under memory pressure
+  // (e.g. heavy scrolling), and the next background-thread shouldInterceptRequest crashes with
+  // "Cannot find runtime for instance". Retaining here (mirrors @nativescript/core's
+  // `nativeView.client = client`) keeps the peer alive for the WebView's lifetime.
+  private webViewClient: android.webkit.WebViewClient | null = null;
+  private webChromeClient: android.webkit.WebChromeClient | null = null;
+
   // Native-view → owning CustomWebView, keyed by the Java identity hash (stable per native
   // object, robust to NS re-wrapping the arg passed into the ChromeClient callback). WeakRef
   // so a destroyed view can be GC'd; entry pruned on dispose.
@@ -131,15 +140,23 @@ export class CustomWebView extends WebView {
     wv.setOverScrollMode(android.view.View.OVER_SCROLL_NEVER);
 
     this.installDocumentStartShim(wv);
-    wv.setWebViewClient(createAssetServingClient());
+    // Retain both clients in long-lived JS fields (see field docs) so their JS peers survive GC
+    // for the WebView's lifetime — otherwise a background-thread shouldInterceptRequest can fire
+    // after the peer is collected and crash with "Cannot find runtime for instance".
+    this.webViewClient = createAssetServingClient();
+    wv.setWebViewClient(this.webViewClient);
     // Bind THIS native view to THIS instance before wiring the (shared, extend-once) client.
     CustomWebView.registry.set(wv.hashCode(), new WeakRef<CustomWebView>(this));
-    wv.setWebChromeClient(new (getChromeClientClass())());
+    this.webChromeClient = new (getChromeClientClass())();
+    wv.setWebChromeClient(this.webChromeClient);
   }
 
   disposeNativeView(): void {
     const wv = this.android as android.webkit.WebView | undefined;
     if (wv) CustomWebView.registry.delete(wv.hashCode());
+    // Drop the retained clients now that the native view is going away, so their peers can be GC'd.
+    this.webViewClient = null;
+    this.webChromeClient = null;
     super.disposeNativeView();
   }
 

package/runtime-desktop/chrome/appwrap-browser-chrome.html

@@ -0,0 +1,120 @@
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Browser</title>
+<style>
+  :root {
+    --bar-h: 44px;
+    --bg: #f2f2f4; --fg: #1c1c1e; --border: #d0d0d5;
+    --field-bg: #ffffff; --field-border: #c4c4cc; --btn-hover: #e2e2e6;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #2a2a2e; --fg: #f2f2f4; --border: #444;
+      --field-bg: #1c1c1e; --field-border: #555; --btn-hover: #3a3a40;
+    }
+  }
+  * { box-sizing: border-box; }
+  html, body { margin: 0; height: 100%; overflow: hidden;
+    font: 13px -apple-system, system-ui, sans-serif; color: var(--fg); }
+  /* The controlled WKWebView is a native subview covering everything below the bar; the body below
+     the bar is never seen — only this top strip renders. */
+  #bar {
+    display: flex; align-items: center; gap: 6px;
+    height: var(--bar-h); padding: 0 8px;
+    background: var(--bg); border-bottom: 1px solid var(--border);
+    -webkit-user-select: none; user-select: none;
+  }
+  button.nav {
+    width: 30px; height: 28px; flex: none;
+    border: none; border-radius: 6px; background: transparent; color: var(--fg);
+    font-size: 16px; line-height: 1; cursor: default;
+  }
+  button.nav:hover { background: var(--btn-hover); }
+  button.nav:active { background: var(--field-border); }
+  #addr {
+    flex: 1 1 auto; height: 28px; padding: 0 10px;
+    border: 1px solid var(--field-border); border-radius: 7px;
+    background: var(--field-bg); color: var(--fg); font-size: 13px; outline: none;
+  }
+  #addr:focus { border-color: #4c8bf5; }
+  #profile {
+    flex: none; height: 28px; max-width: 160px;
+    border: 1px solid var(--field-border); border-radius: 7px;
+    background: var(--field-bg); color: var(--fg); font-size: 12px; padding: 0 4px;
+  }
+</style>
+</head>
+<body>
+  <div id="bar">
+    <button class="nav" id="back" title="Back">&#8249;</button>
+    <button class="nav" id="fwd" title="Forward">&#8250;</button>
+    <button class="nav" id="reload" title="Reload">&#8635;</button>
+    <input id="addr" type="text" spellcheck="false" autocomplete="off"
+           placeholder="Enter address (e.g. 127.0.0.1:3000)" />
+    <select id="profile" title="Profile"></select>
+  </div>
+<script>
+(function () {
+  var id = new URLSearchParams(location.search).get('id') || '';
+  function invoke(cmd, args) {
+    var core = window.__TAURI__ && window.__TAURI__.core;
+    if (!core) return Promise.reject(new Error('Tauri core unavailable'));
+    return core.invoke(cmd, args || {});
+  }
+
+  var addr = document.getElementById('addr');
+  var profileSel = document.getElementById('profile');
+
+  function normalizeUrl(raw) {
+    var s = (raw || '').trim();
+    if (!s) return '';
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(s) || /^about:/i.test(s)) return s;
+    return 'https://' + s;
+  }
+
+  document.getElementById('back').addEventListener('click', function () { invoke('browser_tab_back', { id: id }); });
+  document.getElementById('fwd').addEventListener('click', function () { invoke('browser_tab_forward', { id: id }); });
+  document.getElementById('reload').addEventListener('click', function () { invoke('browser_tab_reload', { id: id }); });
+
+  addr.addEventListener('keydown', function (e) {
+    if (e.key !== 'Enter') return;
+    var url = normalizeUrl(addr.value);
+    if (url) invoke('browser_tab_navigate', { id: id, url: url });
+  });
+
+  profileSel.addEventListener('change', function () {
+    invoke('browser_subwindow_switch_profile', { id: id, profileId: profileSel.value });
+  });
+
+  // Populate the profile dropdown.
+  invoke('browser_list_profiles').then(function (profiles) {
+    (profiles || ['default']).forEach(function (p) {
+      var opt = document.createElement('option');
+      opt.value = p; opt.textContent = p;
+      profileSel.appendChild(opt);
+    });
+  }).catch(function (e) { console.error('list profiles failed', e); });
+
+  // Keep the address bar in sync with the controlled webview (skip while the user is editing it).
+  var focused = false;
+  addr.addEventListener('focus', function () { focused = true; });
+  addr.addEventListener('blur', function () { focused = false; });
+  function poll() {
+    invoke('browser_tab_current_url', { id: id }).then(function (json) {
+      if (focused) return;
+      try {
+        var o = JSON.parse(json);
+        var href = o && o.href ? o.href : '';
+        if (href && href !== 'about:blank') addr.value = href;
+      } catch (_) {}
+    }).catch(function () {});
+  }
+  setInterval(poll, 1000);
+  poll();
+})();
+</script>
+</body>
+</html>

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

@@ -63,13 +63,21 @@ fn eval(ctrl: &Controller, mtm: MainThreadMarker, id: &str, js: &str) -> Result<
 /// Start a throwaway loopback HTTP server; returns its `http://127.0.0.1:PORT/` URL. The page just
 /// carries a stable title — the session marker is written via localStorage by the harness.
 fn start_loopback() -> String {
+    start_loopback_titled("HOST-HARNESS-PAGE")
+}
+
+/// Start a throwaway loopback HTTP server carrying `title` as its `<title>`; returns its URL.
+fn start_loopback_titled(title: &str) -> String {
     let listener = TcpListener::bind("127.0.0.1:0").expect("bind loopback");
     let addr = listener.local_addr().unwrap();
+    let title = title.to_string();
     std::thread::spawn(move || {
-        let body = "<!doctype html><html><head><title>HOST-HARNESS-PAGE</title></head>\
+        let body = format!(
+            "<!doctype html><html><head><title>{title}</title></head>\
             <body style=\"margin:0;background:#0b5;color:#fff;font:700 40px system-ui;\
             display:flex;align-items:center;justify-content:center;height:100vh\">\
-            <div id=\"tag\">HOST-HARNESS-LIVE</div></body></html>";
+            <div id=\"tag\">HOST-HARNESS-LIVE</div></body></html>"
+        );
         for stream in listener.incoming() {
             let Ok(mut s) = stream else { continue };
             let mut buf = [0u8; 1024];
@@ -85,6 +93,35 @@ fn start_loopback() -> String {
     format!("http://{addr}/")
 }
 
+/// Read `location.href` once (pumping until the eval completes).
+fn href(ctrl: &Controller, mtm: MainThreadMarker, id: &str) -> String {
+    eval(ctrl, mtm, id, "return location.href;").unwrap_or_default()
+}
+
+/// Issue a nav op (idempotent — navigate/go_back/go_forward/reload can all be safely re-issued) and
+/// poll `location.href` until it contains `needle` or the deadline elapses. Re-issuing each iteration
+/// makes it robust to a WKWebView dropping a single async load request. Returns the last href.
+fn nav_settle(
+    ctrl: &Controller,
+    mtm: MainThreadMarker,
+    id: &str,
+    needle: &str,
+    secs: f64,
+    mut issue: impl FnMut(),
+) -> String {
+    let deadline = Instant::now() + Duration::from_secs_f64(secs);
+    let mut last = String::new();
+    while Instant::now() < deadline {
+        issue();
+        pump(0.4);
+        last = href(ctrl, mtm, id);
+        if last.contains(needle) {
+            return last;
+        }
+    }
+    last
+}
+
 fn main() {
     let mtm = MainThreadMarker::new().expect("host_harness must run on the main thread");
 
@@ -211,6 +248,60 @@ fn main() {
     println!("session survived (marker 77):             {session_ok}");
     println!("bridge  survived (pings {:?}):             {bridge_ok}", pings);
 
+    // ---- 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);
+    let page2_url = start_loopback_titled("HOST-HARNESS-PAGE-2");
+    println!("\n== NAV: navigate -> page2 {page2_url}");
+    let at2 = nav_settle(&ctrl, mtm, id, &page2_url, 10.0, || { let _ = ctrl.navigate(mtm, id, &page2_url); });
+    let nav_fwd_ok = at2.contains(&page2_url);
+    println!("   at page2: {at2:?} (ok={nav_fwd_ok})");
+
+    println!("== NAV: go_back -> page1");
+    let back1 = nav_settle(&ctrl, mtm, id, &page1_href, 10.0, || { let _ = ctrl.go_back(mtm, id); });
+    let nav_back_ok = back1 == page1_href && !page1_href.is_empty();
+    println!("   back at page1: {back1:?} (ok={nav_back_ok})");
+
+    println!("== NAV: go_forward -> page2");
+    let fwd2 = nav_settle(&ctrl, mtm, id, &page2_url, 10.0, || { let _ = ctrl.go_forward(mtm, id); });
+    let nav_fwd2_ok = fwd2.contains(&page2_url);
+    println!("   forward at page2: {fwd2:?} (ok={nav_fwd2_ok})");
+
+    println!("== NAV: reload (still page2, title present)");
+    let reloaded = nav_settle(&ctrl, mtm, id, &page2_url, 10.0, || { let _ = ctrl.reload(mtm, id); });
+    let title2 = eval(&ctrl, mtm, id, "return document.title;").unwrap_or_default();
+    let reload_ok = reloaded.contains(&page2_url) && title2.contains("HOST-HARNESS-PAGE-2");
+    println!("   after reload: href={reloaded:?} title={title2:?} (ok={reload_ok})");
+    let nav_ok = nav_fwd_ok && nav_back_ok && nav_fwd2_ok && reload_ok;
+
+    // ---- PROFILE SWAP: a second webview on a DIFFERENT profile → different store uuid ----
+    let first_store = created.as_ref().map(|c| c.store_uuid.clone()).unwrap_or_default();
+    let id_b = "harness-tab-b";
+    println!("\n== PROFILE SWAP: create id={id_b} profile=harnessB ChildOf(same pane)");
+    let created_b = ctrl.create_webview(
+        mtm,
+        CreateSpec {
+            label: id_b.to_string(),
+            url: page_url.clone(),
+            profile_id: "harnessB".to_string(),
+            init_js: String::new(),
+            mount: Mount::ChildOf(pane_handle),
+        },
+        Box::new(|_raw| {}),
+    );
+    let store_b = match &created_b {
+        Ok(c) => { println!("   harnessB store={}", c.store_uuid); c.store_uuid.clone() }
+        Err(e) => { eprintln!("FAIL: create harnessB: {e}"); std::process::exit(1); }
+    };
+    let profile_swap_ok = !first_store.is_empty() && store_b != first_store;
+    println!("   store isolation: harness={first_store} harnessB={store_b} (differ={profile_swap_ok})");
+    let _ = ctrl.close(mtm, id_b);
+    pump(0.3);
+
+    println!("\n---- nav + profile-swap assertions ----");
+    println!("nav ops (fwd/back/fwd/reload):               {nav_ok}");
+    println!("profile swap (distinct store uuid):          {profile_swap_ok}");
+
     if std::env::args().any(|a| a == "--hold") {
         println!("(--hold) leaving windows up 20s for inspection…");
         pump(20.0);
@@ -230,9 +321,11 @@ fn main() {
 
     println!("pane empty after close (no zombie webview):  {pane_empty_ok}");
 
-    if page_ok && session_ok && bridge_ok && pane_empty_ok {
-        println!("\nPASS: live webview reparented child->toplevel->child via EMBEDDED API; page+session+bridge intact; host pane empty after close.");
+    if page_ok && session_ok && bridge_ok && pane_empty_ok && nav_ok && profile_swap_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."); }
+        if !profile_swap_ok { eprintln!("\nFAIL: profile swap did not yield a distinct store uuid."); }
         if !pane_empty_ok {
             eprintln!(
                 "\nFAIL: ZOMBIE WEBVIEW — host pane still has {after_close} subview(s) after close(); \

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

@@ -49,6 +49,27 @@ impl Controller {
         unsafe { backend::navigate(Retained::as_ptr(&wk) as *mut WKWebView, url) }
     }
 
+    /// Navigate back in webview `id`'s history. Err if `id` is unknown/closed.
+    pub fn go_back(&self, _mtm: MainThreadMarker, id: &str) -> Result<(), String> {
+        let wk = self.webview(id)?;
+        unsafe { backend::go_back(Retained::as_ptr(&wk) as *mut WKWebView) };
+        Ok(())
+    }
+
+    /// Navigate forward in webview `id`'s history. Err if `id` is unknown/closed.
+    pub fn go_forward(&self, _mtm: MainThreadMarker, id: &str) -> Result<(), String> {
+        let wk = self.webview(id)?;
+        unsafe { backend::go_forward(Retained::as_ptr(&wk) as *mut WKWebView) };
+        Ok(())
+    }
+
+    /// Reload webview `id`. Err if `id` is unknown/closed.
+    pub fn reload(&self, _mtm: MainThreadMarker, id: &str) -> Result<(), String> {
+        let wk = self.webview(id)?;
+        unsafe { backend::reload(Retained::as_ptr(&wk) as *mut WKWebView) };
+        Ok(())
+    }
+
     /// Fire-and-forget JS injection into webview `id`. Err if `id` is unknown/closed.
     pub fn inject_script(&self, _mtm: MainThreadMarker, id: &str, js: &str) -> Result<(), String> {
         let wk = self.webview(id)?;

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

@@ -89,7 +89,11 @@ pub enum Mount {
 // See ARCHITECTURE.md for the full contract.
 #[cfg(target_os = "macos")]
 pub use wkwebview_backend::{
-    close, create_profile_window, create_webview, eval_async, inject_script,
-    install_message_handler, list_webviews, navigate, profile_webview, set_mount, snapshot,
-    user_close, CreateResult, CreateSpec, MessageSink, WebviewInfo,
+    close, create_profile_window, create_webview, devtools_enabled, eval_async, go_back, go_forward,
+    inject_script, install_message_handler, list_webviews, navigate, profile_webview, reload,
+    set_inspectable, set_mount, snapshot, user_close, CreateResult, CreateSpec, MessageSink,
+    WebviewInfo,
 };
+
+#[cfg(target_os = "macos")]
+pub use profiles::list as list_profiles;

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

@@ -278,6 +278,9 @@ define_class!(
             };
             unsafe {
                 child.setCustomUserAgent(Some(&NSString::from_str(SAFARI_UA)));
+                // Safari Web Inspector on window.open() child popups too (SSO flows etc.) —
+                // gated identically (debug always; release only under APPWRAP_DEVTOOLS).
+                crate::wkwebview_backend::set_inspectable(Retained::as_ptr(&child) as *mut WKWebView);
                 // Route the child's own UI-delegate messages (window.close(), nested
                 // window.open) back through us.
                 child.setUIDelegate(Some(ProtocolObject::from_ref(self)));

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

@@ -27,6 +27,18 @@ fn load() -> HashMap<String, String> {
         .unwrap_or_default()
 }
 
+/// Sorted list of known profile ids from the on-disk map (the dropdown source). Always includes
+/// "default" so the chrome always has at least one selectable profile, even on a fresh install.
+pub fn list() -> Vec<String> {
+    let mut ids: Vec<String> = load().into_keys().collect();
+    if !ids.iter().any(|k| k == "default") {
+        ids.push("default".to_string());
+    }
+    ids.sort();
+    ids.dedup();
+    ids
+}
+
 /// Stable UUID string for a profile id — generated once and persisted so the
 /// same on-disk data store is reattached on every subsequent launch.
 pub fn uuid_for(profile_id: &str) -> String {

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

@@ -28,6 +28,31 @@ use crate::popup;
 use crate::profiles;
 use crate::Mount;
 
+/// True when webviews should be Safari-inspectable (Develop ▸ <app> ▸ Web Inspector). Debug builds
+/// are ALWAYS inspectable; a release build is inspectable ONLY when `APPWRAP_DEVTOOLS` is set to
+/// `1`/`true` — so production apps aren't inspectable by default. Self-contained in this crate (no
+/// shell-config dependency) so every webview creation site can gate uniformly.
+pub fn devtools_enabled() -> bool {
+    cfg!(debug_assertions)
+        || matches!(std::env::var("APPWRAP_DEVTOOLS").ok().as_deref(), Some("1") | Some("true"))
+}
+
+/// Flip a WKWebView's `inspectable` property ON when [`devtools_enabled`], making it attachable from
+/// Safari → Develop. The property lands in macOS 13.3+, so it's guarded by `respondsToSelector:` and
+/// no-ops on older systems. Set right after webview creation, on the main thread. `wk` must be a live
+/// `*mut WKWebView`.
+pub unsafe fn set_inspectable(wk: *mut WKWebView) {
+    if wk.is_null() || !devtools_enabled() {
+        return;
+    }
+    let wk = &*wk;
+    let sel = objc2::sel!(setInspectable:);
+    let responds: bool = msg_send![wk, respondsToSelector: sel];
+    if responds {
+        let _: () = msg_send![wk, setInspectable: true];
+    }
+}
+
 /// Autoresizing mask that pins a mounted webview to fill its superview on resize — the same
 /// width+height-sizable mask popup windows use, applied on every (re)mount.
 const FILL_MASK: NSAutoresizingMaskOptions =
@@ -316,6 +341,9 @@ pub fn create_webview(
     unsafe {
         webview.setCustomUserAgent(Some(&NSString::from_str(popup::SAFARI_UA)));
         window.setTitle(&NSString::from_str(label));
+        // Safari Web Inspector (debug always; release only under APPWRAP_DEVTOOLS) for every
+        // bridge/profile/sub-window webview created through this primitive.
+        set_inspectable(Retained::as_ptr(&webview) as *mut WKWebView);
     }
 
     // Per-window SSO-popup delegate + window-close delegate. Both are weak refs on AppKit/WebKit →
@@ -424,6 +452,21 @@ pub unsafe fn navigate(wk: *mut WKWebView, url: &str) -> Result<(), String> {
     }
 }
 
+/// Navigate back in the WKWebView's session history (no-op if none). Main-thread only.
+pub unsafe fn go_back(wk: *mut WKWebView) {
+    let _ = (&*wk).goBack();
+}
+
+/// Navigate forward in the WKWebView's session history (no-op if none). Main-thread only.
+pub unsafe fn go_forward(wk: *mut WKWebView) {
+    let _ = (&*wk).goForward();
+}
+
+/// Reload the current page. Main-thread only.
+pub unsafe fn reload(wk: *mut WKWebView) {
+    let _ = (&*wk).reload();
+}
+
 /// Fire-and-forget JS injection. Main-thread only.
 pub unsafe fn inject_script(wk: *mut WKWebView, js: &str) {
     let wk = &*wk;

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

@@ -7,7 +7,9 @@ edition = "2021"
 tauri-build = { version = "2", features = [] }
 
 [dependencies]
-tauri = { version = "2", features = [] }
+# `devtools` feature so `open_devtools()`/`close_devtools()` compile in RELEASE too (in debug they're
+# always available); the ⌥⌘I toggle is still gated at runtime by webview_control::devtools_enabled().
+tauri = { version = "2", features = ["devtools"] }
 tauri-plugin-deep-link = "2"
 tauri-plugin-window-state = "2"
 tauri-plugin-notification = "2"

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

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

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

@@ -14,6 +14,7 @@ use serde_json::{json, Value};
 use std::io::{Read, Write};
 use std::net::TcpStream;
 use std::sync::mpsc::{channel, Sender};
+use std::sync::Mutex;
 use std::time::Duration;
 use tauri::{AppHandle, Manager};
 
@@ -37,6 +38,50 @@ fn page_sink(tx: Sender<String>) -> wv::MessageSink {
 fn page_port() -> u16 {
     std::env::var("APPWRAP_BRIDGE_PAGE_PORT").ok().and_then(|s| s.parse().ok()).unwrap_or(9236)
 }
+
+/// The live control-channel page->shim sender, set for the duration of a connected `run()`. Lets a
+/// webview created OUTSIDE the createWindow op (e.g. a browser sub-window in browser_tab.rs) route
+/// its page beacons to the SAME shim, so it registers as a bod-browser tab. None when disconnected.
+static PAGE_TX: Mutex<Option<Sender<String>>> = Mutex::new(None);
+
+/// Clears PAGE_TX on drop, so every `run()` return path (normal or error) leaves it None.
+struct PageTxGuard;
+impl Drop for PageTxGuard {
+    fn drop(&mut self) {
+        *PAGE_TX.lock().unwrap() = None;
+    }
+}
+
+/// Page->shim sink for a webview created outside `createWindow` (browser sub-windows). Unlike a
+/// snapshot of the CURRENT PAGE_TX, this sink reads the LIVE control connection at send-time: a
+/// sub-window opened while the shim is disconnected (PAGE_TX == None) installs this ONE sink and its
+/// beacons are dropped for now, but the moment a later `run()` publishes a PAGE_TX the SAME installed
+/// sink starts delivering — so the window SELF-HEALS into agent-exposure on shim (re)connect, with no
+/// re-injection of the message handler. Framing stays identical to `page_sink`.
+pub fn bridge_sink() -> wv::MessageSink {
+    Box::new(move |raw: String| {
+        if let Some(tx) = PAGE_TX.lock().unwrap().as_ref() {
+            let _ = tx.send(json!({ "type": "pageMsg", "payload": raw }).to_string());
+        }
+    })
+}
+
+/// Build the SAME framed init-JS `createWindow` injects, for a webview created elsewhere. Reads the
+/// content bundle from `APPWRAP_BRIDGE_JS`; None when the feature is off (unset/empty) or the read
+/// fails (logged). `label` becomes `window.__BRIDGE_LABEL` so the shim registers this webview by id.
+pub fn bridge_init_js(label: &str) -> Option<String> {
+    let path = match std::env::var("APPWRAP_BRIDGE_JS") {
+        Ok(p) if !p.is_empty() => p,
+        _ => return None,
+    };
+    match std::fs::read_to_string(&path) {
+        Ok(bundle) => Some(format!(
+            "window.__BRIDGE_LABEL={};window.__BRIDGE_PORT={};\n{}",
+            serde_json::to_string(&label).unwrap(), page_port(), bundle
+        )),
+        Err(e) => { eprintln!("[bridge-shim] bridge_init_js read {path}: {e}"); None }
+    }
+}
 fn rust_port() -> u16 {
     std::env::var("APPWRAP_BRIDGE_RUST_PORT").ok().and_then(|s| s.parse().ok()).unwrap_or(9237)
 }
@@ -62,6 +107,14 @@ pub fn init(app: AppHandle) {
 fn run(app: &AppHandle, mut stream: TcpStream, js_path: &str) {
     let _ = stream.set_read_timeout(Some(Duration::from_millis(50)));
     let (tx, rx) = channel::<String>();
+    // Publish this connection's sender so sub-window webviews (created outside createWindow) can route
+    // their page beacons here; the guard clears it on ANY return below (disconnect/error).
+    *PAGE_TX.lock().unwrap() = Some(tx.clone());
+    let _tx_guard = PageTxGuard;
+    // Self-heal sub-windows opened BEFORE this connect: their dynamic sink can now deliver, but a
+    // document already loaded won't re-fire its `register` beacon on its own. Nudge every open
+    // sub-window webview to re-post `register` so it (re)appears as a bod-browser tab on this shim.
+    crate::browser_tab::reregister_subwindows(app);
     let mut acc = String::new();
     let mut buf = [0u8; 65536];
     loop {

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

@@ -13,19 +13,39 @@
 mod imp {
     use std::collections::HashMap;
     use std::ffi::c_void;
+    use std::sync::mpsc::channel;
     use std::sync::{Mutex, OnceLock};
+    use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
     use objc2::rc::Retained;
     use objc2::{MainThreadMarker, MainThreadOnly};
-    use objc2_app_kit::{NSView, NSWindow};
+    use objc2_app_kit::{NSAutoresizingMaskOptions, NSView, NSWindow};
     use objc2_foundation::{NSPoint, NSRect, NSSize};
     use objc2_web_kit::WKWebView;
     use serde::Deserialize;
-    use tauri::Manager;
+    use tauri::{Manager, WebviewUrl, WebviewWindowBuilder};
 
     use webview_control::embedded::Controller;
     use webview_control::{CreateSpec, Mount, ViewHandle};
 
+    /// Fixed height (points) of the sub-window chrome strip (‹ › ⟳ + address bar + profile▾). The
+    /// controlled WKWebView pane is pinned BELOW this within the sub-window's contentView.
+    pub const CHROME_H: f64 = 44.0;
+
+    /// Autoresizing mask keeping the controlled-webview container pinned below the chrome bar while it
+    /// tracks window resize: both margins fixed (44pt top gap, 0 bottom), width+height flexible.
+    fn container_mask() -> NSAutoresizingMaskOptions {
+        NSAutoresizingMaskOptions(
+            NSAutoresizingMaskOptions::ViewWidthSizable.0 | NSAutoresizingMaskOptions::ViewHeightSizable.0,
+        )
+    }
+
+    /// A unique sub-window id / bridge tab label.
+    fn new_subwin_id() -> String {
+        let ms = SystemTime::now().duration_since(UNIX_EPOCH).map(|d| d.as_millis()).unwrap_or(0);
+        format!("subwin-{ms}")
+    }
+
     /// Web-DOM pane rect the front-end reserves (top-left origin, CSS px == points here since the
     /// shell runs at the window's backing scale). We flip Y to AppKit's bottom-left origin at mount.
     #[derive(Deserialize, Clone, Copy)]
@@ -160,6 +180,189 @@ mod imp {
         .map_err(|e| e.to_string())?;
         rx.recv().map_err(|e| e.to_string())?
     }
+
+    // ---- Sub-window: a standalone Tauri chrome window + a controlled WKWebView pane below the bar ----
+
+    /// Bridge init-JS + page sink for a sub-window webview, so it registers as a bod-browser tab when
+    /// the shim is running, and is inert-but-functional otherwise (empty init, no-op sink).
+    fn bridge_wiring(id: &str) -> (String, webview_control::MessageSink) {
+        let init_js = crate::bridge_mac::bridge_init_js(id).unwrap_or_default();
+        // Live self-healing sink: delivers to whichever shim is connected at send-time (None-safe),
+        // so a sub-window created while the shim is down becomes agent-exposed on a later connect.
+        let sink = crate::bridge_mac::bridge_sink();
+        (init_js, sink)
+    }
+
+    /// Mount a controlled WKWebView `ChildOf` a pane pinned below the chrome bar in `win`'s content
+    /// view, wiring the bridge for agent-exposure. Runs on the main thread (via `with_webview`).
+    fn mount_pane(win: &tauri::WebviewWindow, id: &str, profile_id: &str, url: &str) -> Result<(), String> {
+        let (tx, rx) = channel();
+        let (id, profile_id, url) = (id.to_string(), profile_id.to_string(), url.to_string());
+        win.with_webview(move |w| {
+            let res = (|| -> Result<(), String> {
+                let mtm = MainThreadMarker::new().ok_or("not main thread")?;
+                unsafe {
+                    let wk = &*(w.inner() as *mut WKWebView);
+                    let ns_win = wk.window().ok_or("chrome webview has no window")?;
+                    let content = content_view(&ns_win);
+                    let b = content.bounds().size;
+                    let rect = PaneRect { x: 0.0, y: CHROME_H, width: b.width, height: (b.height - CHROME_H).max(0.0) };
+                    let frame = appkit_rect(&content, rect);
+                    let container = NSView::initWithFrame(NSView::alloc(mtm), frame);
+                    container.setAutoresizingMask(container_mask());
+                    content.addSubview(&container);
+                    let cptr = Retained::as_ptr(&container) as *mut c_void;
+                    let handle = ViewHandle::from_ptr(cptr);
+                    let (init_js, sink) = bridge_wiring(&id);
+                    let spec = CreateSpec {
+                        label: id.clone(),
+                        url: url.clone(),
+                        profile_id: profile_id.clone(),
+                        init_js,
+                        mount: Mount::ChildOf(handle),
+                    };
+                    Controller::new().create_webview(mtm, spec, sink)?;
+                    containers().lock().unwrap().insert(id.clone(), cptr as usize);
+                }
+                Ok(())
+            })();
+            let _ = tx.send(res);
+        })
+        .map_err(|e| e.to_string())?;
+        rx.recv().map_err(|e| e.to_string())?
+    }
+
+    /// Clean up a sub-window's controlled webview + container. Main-thread only (called from the
+    /// window's Destroyed event, which fires on the main thread).
+    fn teardown(id: &str, mtm: MainThreadMarker) {
+        Controller::new().close(mtm, id);
+        if let Some(ptr) = containers().lock().unwrap().remove(id) {
+            unsafe { (*(ptr as *mut NSView)).removeFromSuperview() };
+        }
+    }
+
+    /// Open a sub-window: build the Tauri chrome window (loads the bundled chrome HTML asset, `?id=`
+    /// stamped so it binds to this webview), then mount the controlled webview below the chrome bar.
+    pub fn open(app: tauri::AppHandle, profile_id: String) -> Result<String, String> {
+        // Two DISTINCT labels: the Tauri chrome window (`win_id`) and the controlled WKWebView it
+        // hosts (`view_id = <win_id>-view`). Sharing one label double-listed it in `listWindows`
+        // (once from `app.webview_windows()`, once from the crate registry). The chrome HTML, its
+        // invokes, the container/registry key, the bridge `__BRIDGE_LABEL`, and what agents drive all
+        // key on `view_id`; only the OS window keeps `win_id`.
+        let win_id = new_subwin_id();
+        let view_id = format!("{win_id}-view");
+        let chrome_url = format!("appwrap-browser-chrome.html?id={view_id}");
+        let win = WebviewWindowBuilder::new(&app, &win_id, WebviewUrl::App(chrome_url.into()))
+            .title("Browser")
+            .inner_size(1100.0, 800.0)
+            .build()
+            .map_err(|e| e.to_string())?;
+        // Tear the controlled webview down when the sub-window closes, so it doesn't linger as a
+        // registry zombie / stray bod-browser tab.
+        let idc = view_id.clone();
+        win.on_window_event(move |ev| {
+            if matches!(ev, tauri::WindowEvent::Destroyed) {
+                if let Some(mtm) = MainThreadMarker::new() {
+                    teardown(&idc, mtm);
+                }
+            }
+        });
+        mount_pane(&win, &view_id, &profile_id, "about:blank")?;
+        Ok(view_id)
+    }
+
+    /// Re-fire the `register` beacon on every open sub-window controlled webview. Called when the
+    /// shim (re)connects: their live sink can now deliver, but an already-loaded document won't
+    /// re-run its init-JS `register()`, so nudge each via the bridgeShim handler to re-post it.
+    /// Idempotent + inert when the bridge feature is off (no bridgeShim handler → the try/catch eats
+    /// it) and when there are no sub-windows.
+    pub fn reregister_all(app: &tauri::AppHandle) {
+        let ids: Vec<String> = containers().lock().unwrap().keys().cloned().collect();
+        if ids.is_empty() {
+            return;
+        }
+        let _ = app.run_on_main_thread(move || {
+            if let Some(mtm) = MainThreadMarker::new() {
+                let c = Controller::new();
+                for id in &ids {
+                    let js = "try{if(window.__BRIDGE_LABEL){webkit.messageHandlers.bridgeShim.postMessage(JSON.stringify({label:window.__BRIDGE_LABEL,type:'register',url:location.href,title:document.title}))}}catch(e){}".to_string();
+                    let _ = c.inject_script(mtm, id, &js);
+                }
+            }
+        });
+    }
+
+    /// Swap the sub-window's controlled webview to another profile: profile is immutable per-webview,
+    /// so close the current one (keeps the pane container) and recreate `ChildOf` the SAME container
+    /// with the new profile. The Tauri chrome window is untouched.
+    pub fn switch_profile(app: tauri::AppHandle, id: String, profile_id: String) -> Result<(), String> {
+        let win = app.get_webview_window("main").ok_or("no main window")?;
+        let (tx, rx) = channel();
+        win.run_on_main_thread(move || {
+            let res = (|| -> Result<(), String> {
+                let mtm = MainThreadMarker::new().ok_or("not main thread")?;
+                let ptr = *containers().lock().unwrap().get(&id).ok_or("no pane for id")?;
+                Controller::new().close(mtm, &id);
+                unsafe {
+                    let handle = ViewHandle::from_ptr(ptr as *mut c_void);
+                    let (init_js, sink) = bridge_wiring(&id);
+                    let spec = CreateSpec {
+                        label: id.clone(),
+                        url: "about:blank".to_string(),
+                        profile_id: profile_id.clone(),
+                        init_js,
+                        mount: Mount::ChildOf(handle),
+                    };
+                    Controller::new().create_webview(mtm, spec, sink)?;
+                }
+                Ok(())
+            })();
+            let _ = tx.send(res);
+        })
+        .map_err(|e| e.to_string())?;
+        rx.recv().map_err(|e| e.to_string())?
+    }
+
+    /// Route a nav op (`back`/`forward`/`reload`) to the controlled webview `id` on the main thread.
+    pub fn nav_op(app: tauri::AppHandle, id: String, op: &'static str) -> Result<(), String> {
+        let win = app.get_webview_window("main").ok_or("no main window")?;
+        let (tx, rx) = channel();
+        win.run_on_main_thread(move || {
+            let res = (|| -> Result<(), String> {
+                let mtm = MainThreadMarker::new().ok_or("not main thread")?;
+                let c = Controller::new();
+                match op {
+                    "back" => c.go_back(mtm, &id),
+                    "forward" => c.go_forward(mtm, &id),
+                    "reload" => c.reload(mtm, &id),
+                    other => Err(format!("bad nav op: {other}")),
+                }
+            })();
+            let _ = tx.send(res);
+        })
+        .map_err(|e| e.to_string())?;
+        rx.recv().map_err(|e| e.to_string())?
+    }
+
+    /// Read the controlled webview `id`'s current `{href,title}` as a JSON string (for the address bar).
+    pub fn current_url(app: tauri::AppHandle, id: String) -> Result<String, String> {
+        let win = app.get_webview_window("main").ok_or("no main window")?;
+        let (tx, rx) = channel();
+        win.run_on_main_thread(move || {
+            let mtm = match MainThreadMarker::new() {
+                Some(m) => m,
+                None => { let _ = tx.send(Err("not main thread".to_string())); return; }
+            };
+            Controller::new().eval_async(
+                mtm,
+                &id,
+                "return JSON.stringify({href:location.href,title:document.title});".to_string(),
+                move |r| { let _ = tx.send(r); },
+            );
+        })
+        .map_err(|e| e.to_string())?;
+        rx.recv_timeout(Duration::from_secs(5)).map_err(|e| e.to_string())?
+    }
 }
 
 #[cfg(target_os = "macos")]
@@ -191,3 +394,52 @@ pub fn browser_tab_navigate(app: tauri::AppHandle, id: String, url: String) -> R
 pub fn browser_tab_close(app: tauri::AppHandle, id: String) -> Result<(), String> {
     imp::close(app, id)
 }
+
+#[cfg(target_os = "macos")]
+#[tauri::command]
+pub fn browser_subwindow_open(app: tauri::AppHandle, profile_id: Option<String>) -> Result<String, String> {
+    imp::open(app, profile_id.unwrap_or_else(|| "default".to_string()))
+}
+
+#[cfg(target_os = "macos")]
+#[tauri::command]
+pub fn browser_subwindow_switch_profile(app: tauri::AppHandle, id: String, profile_id: String) -> Result<(), String> {
+    imp::switch_profile(app, id, profile_id)
+}
+
+#[cfg(target_os = "macos")]
+#[tauri::command]
+pub fn browser_tab_back(app: tauri::AppHandle, id: String) -> Result<(), String> {
+    imp::nav_op(app, id, "back")
+}
+
+#[cfg(target_os = "macos")]
+#[tauri::command]
+pub fn browser_tab_forward(app: tauri::AppHandle, id: String) -> Result<(), String> {
+    imp::nav_op(app, id, "forward")
+}
+
+#[cfg(target_os = "macos")]
+#[tauri::command]
+pub fn browser_tab_reload(app: tauri::AppHandle, id: String) -> Result<(), String> {
+    imp::nav_op(app, id, "reload")
+}
+
+#[cfg(target_os = "macos")]
+#[tauri::command]
+pub fn browser_tab_current_url(app: tauri::AppHandle, id: String) -> Result<String, String> {
+    imp::current_url(app, id)
+}
+
+#[cfg(target_os = "macos")]
+#[tauri::command]
+pub fn browser_list_profiles() -> Result<Vec<String>, String> {
+    Ok(webview_control::list_profiles())
+}
+
+/// Nudge every open browser sub-window to re-post its `register` beacon (called by the bridge control
+/// channel when a shim (re)connects, so pre-existing sub-windows self-heal into agent-exposure).
+#[cfg(target_os = "macos")]
+pub fn reregister_subwindows(app: &tauri::AppHandle) {
+    imp::reregister_all(app);
+}

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

@@ -695,6 +695,13 @@ fn main() {
             browser_tab::browser_tab_set_mount,
             browser_tab::browser_tab_navigate,
             browser_tab::browser_tab_close,
+            browser_tab::browser_subwindow_open,
+            browser_tab::browser_subwindow_switch_profile,
+            browser_tab::browser_tab_back,
+            browser_tab::browser_tab_forward,
+            browser_tab::browser_tab_reload,
+            browser_tab::browser_tab_current_url,
+            browser_tab::browser_list_profiles,
         ])
         // 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
@@ -714,6 +721,75 @@ fn main() {
         .setup(|app| {
             // Stash the app handle so off-main-thread handlers can reach plugin state (notifications).
             let _ = APP.set(app.handle().clone());
+            // Native "Browser ▸ New Browser Window" menu — every appwrap desktop app gets the
+            // app-owned browser sub-window affordance. We APPEND to the DEFAULT macOS menu (built via
+            // Menu::default) so Edit's Cut/Copy/Paste/Select-All stay intact; suppressing them would
+            // break Cmd+C/V in inputs. The menu event opens a sub-window for the "default" profile.
+            {
+                use tauri::menu::{Menu, MenuItem, Submenu};
+                let handle = app.handle();
+                match Menu::default(handle).and_then(|menu| {
+                    let new_win = MenuItem::with_id(
+                        handle, "browser_new_window", "New Browser Window", true,
+                        Some("CmdOrCtrl+Shift+N"),
+                    )?;
+                    let browser = Submenu::with_id_and_items(
+                        handle, "browser_menu", "Browser", true, &[&new_win],
+                    )?;
+                    menu.append(&browser)?;
+                    // View ▸ Toggle DevTools (⌥⌘I). Opens/closes Tauri's devtools on the focused
+                    // window; the handler no-ops in release unless APPWRAP_DEVTOOLS is set
+                    // (devtools_enabled), matching the Safari-inspectable gate.
+                    let toggle_devtools = MenuItem::with_id(
+                        handle, "toggle_devtools", "Toggle DevTools", true,
+                        Some("Alt+CmdOrCtrl+I"),
+                    )?;
+                    let view = Submenu::with_id_and_items(
+                        handle, "view_menu", "View", true, &[&toggle_devtools],
+                    )?;
+                    menu.append(&view)?;
+                    Ok(menu)
+                }) {
+                    Ok(menu) => {
+                        if let Err(e) = app.set_menu(menu) {
+                            eprintln!("[browser] set_menu failed: {e}");
+                        }
+                    }
+                    Err(e) => eprintln!("[browser] build Browser menu failed: {e}"),
+                }
+                app.on_menu_event(|app, event| {
+                    match event.id().as_ref() {
+                        "browser_new_window" => {
+                            if let Err(e) = browser_tab::browser_subwindow_open(app.clone(), Some("default".to_string())) {
+                                eprintln!("[browser] open sub-window (menu) failed: {e}");
+                            }
+                        }
+                        "toggle_devtools" => {
+                            // Gate at runtime: inert in a release build unless APPWRAP_DEVTOOLS is set
+                            // (same policy as Safari-inspectable); always on in debug.
+                            #[cfg(target_os = "macos")]
+                            if !webview_control::devtools_enabled() {
+                                eprintln!("[devtools] toggle ignored (set APPWRAP_DEVTOOLS=1 to enable in release)");
+                                return;
+                            }
+                            // Toggle on the focused webview window (sub-windows are their own
+                            // WebviewWindows), falling back to main.
+                            let win = app.webview_windows()
+                                .into_values()
+                                .find(|w| w.is_focused().unwrap_or(false))
+                                .or_else(|| app.get_webview_window("main"));
+                            if let Some(win) = win {
+                                if win.is_devtools_open() {
+                                    win.close_devtools();
+                                } else {
+                                    win.open_devtools();
+                                }
+                            }
+                        }
+                        _ => {}
+                    }
+                });
+            }
             // SPIKE: browser-bridge window-ops backend — inert unless APPWRAP_BRIDGE_JS is set.
             #[cfg(target_os = "macos")]
             bridge_mac::init(app.handle().clone());
@@ -755,7 +831,12 @@ fn main() {
             #[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))?;
+                window.with_webview(move |w| {
+                    popup_mac::install(w.inner() as _, picker);
+                    // Safari Web Inspector on the main Tauri window's WKWebView (debug always;
+                    // release only under APPWRAP_DEVTOOLS). Runs on the main thread (with_webview).
+                    unsafe { webview_control::set_inspectable(w.inner() as *mut _) };
+                })?;
             }
             // Reveal after the state plugin's on_window_ready restore has applied (built hidden above).
             if restore {

package/src/cli.ts

@@ -10,7 +10,7 @@
  */
 import { execFileSync, spawn } from 'child_process';
 import { createHash } from 'crypto';
-import { cpSync, existsSync, mkdirSync, openSync, closeSync, readdirSync, readFileSync, readSync, rmSync, statSync, writeFileSync, writeSync } from 'fs';
+import { copyFileSync, cpSync, existsSync, mkdirSync, openSync, closeSync, readdirSync, readFileSync, readSync, rmSync, statSync, writeFileSync, writeSync } from 'fs';
 import { networkInterfaces, tmpdir } from 'os';
 import { delimiter as pathDelimiter, dirname, join, resolve } from 'path';
 import { pathToFileURL } from 'url';
@@ -2052,6 +2052,15 @@ function regenerateDesktop(cwd: string, cfg: AppwrapConfig, outDir: string, push
     cpSync(dist, stagedDist, { recursive: true, force: true });
   }
 
+  // Stage the app-owned browser sub-window chrome (‹ › ⟳ + address bar + profile▾) INTO the dist so
+  // `WebviewUrl::App("appwrap-browser-chrome.html")` resolves it (browser_tab::browser_subwindow_open).
+  const chromeSrc = join(DESKTOP_TEMPLATE_DIR, 'chrome', 'appwrap-browser-chrome.html');
+  if (existsSync(chromeSrc)) {
+    copyFileSync(chromeSrc, join(stagedDist, 'appwrap-browser-chrome.html'));
+  } else {
+    console.warn(`⚠ browser chrome not found at ${chromeSrc} — sub-window chrome will 404.`);
+  }
+
   // Local-server mode: resolve `command` (bare name → PATH lookup) and `cwd` to ABSOLUTE, and stamp
   // the build-time PATH — a GUI-launched .app inherits the minimal launchd PATH (no ~/.bun/bin), so
   // a bare-name spawn (or a child that itself shells out to `bun`/`node`) would fail there.