@livx.cc/appwrap 0.48.2 → 0.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.48.2",
+  "version": "0.49.0",
   "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/main-page.ts

@@ -1,5 +1,6 @@
 import { Application, AndroidApplication, EventData, Page, isAndroid, isIOS, knownFolders, path } from '@nativescript/core';
 import { bridge } from './shell/bridge';
+import { effectiveServerUrl } from './shell/server-url';
 import { registerHandlers } from './shell/handlers';
 import { registerExtendedHandlers } from './shell/handlers-extended';
 import { registerParityHandlers } from './shell/handlers-parity';
@@ -11,9 +12,11 @@ import { registerFsHandlers } from './shell/handlers-fs';
 import { registerPushHandlers } from './shell/handlers-push';
 import { registerAndroidHandlers } from './shell/handlers-android';
 import { registerOptionalHandlers } from './shell/optional-handlers.generated';
+import { registerPlugins } from './shell/plugins.generated';
 import './shell/fcm-bootstrap.generated'; // side-effect: registers the FCM service when push is wired
 import { startEventForwarding } from './shell/events';
 import { startDevMenu } from './shell/devmenu';
+import { showEnvBannerIfActive } from './shell/env-banner';
 import { SHELL_CONFIG } from './shell/config';
 import { bindStatusBarPage, setStatusBarStyle, applyThemeColor, enableAndroidEdgeToEdge, wireAndroidSafeArea } from './shell/status-bar';
 import { CustomWebView } from './shell/custom-webview';
@@ -111,6 +114,9 @@ export function onPageLoaded(args: EventData): void {
   if (isAndroid) registerAndroidHandlers();
   // Opt-in modules that own their own handler file (health, …) — generated to only the active set.
   registerOptionalHandlers();
+  // Config-gated TS plugins (appwrap.config `plugins`) — registers each plugin's bridge handlers.
+  // No-op default when no plugins are configured (generated barrel is empty → no plugin glue compiled).
+  registerPlugins();
   // Shake-to-open developer menu (App Info / Reload). On by default, incl. prod.
   if (SHELL_CONFIG.devMenu) startDevMenu();
 
@@ -129,6 +135,9 @@ export function onPageLoaded(args: EventData): void {
   if (isAndroid) wireAndroidSafeArea(webView); // experimental edge-to-edge (no-op unless config on)
   startEventForwarding();
   loadBundle(webView);
+  // Env indicator banner: shown in the bottom safe area on relaunch when a non-default env override is
+  // active (env-switcher only). Bottom-safe-area, auto-shrinks to a pill after 3s. No-op otherwise.
+  showEnvBannerIfActive();
 
   // Halt the WebView render + JS-timer pipeline while backgrounded so a page running a continuous
   // animation (Android doesn't auto-pause rAF off-screen) stops burning CPU/battery. No-op on iOS.
@@ -172,8 +181,8 @@ function loadBundle(webView: CustomWebView): void {
         return;
       }
       if (SHELL_CONFIG.loader === 'server' && SHELL_CONFIG.serverUrl) {
-        // Live URL (dev HMR / deployed). Bridge (WKUserScript + message handler) still injects.
-        const url = NSURL.URLWithString(SHELL_CONFIG.serverUrl);
+        // Live URL (dev HMR / deployed), or a persisted debug override. Bridge still injects.
+        const url = NSURL.URLWithString(effectiveServerUrl());
         wk.loadRequest(NSURLRequest.requestWithURL(url));
       } else if (SHELL_CONFIG.loader === 'file') {
         const entryURL = NSURL.fileURLWithPath(entryPath);
@@ -194,7 +203,7 @@ function loadBundle(webView: CustomWebView): void {
         return;
       }
       webView.src = SHELL_CONFIG.loader === 'server' && SHELL_CONFIG.serverUrl
-        ? SHELL_CONFIG.serverUrl
+        ? effectiveServerUrl()
         : SHELL_CONFIG.loader === 'file'
           ? `file://${entryPath}`
           : `https://appwrap.local/${SHELL_CONFIG.entry}`;

package/runtime/app/shell/bridge.ts

@@ -26,6 +26,12 @@ export class Bridge {
     this.handlers.set(method, handler);
   }
 
+  /** Whether a handler is already registered for `method` (used by the plugin host to refuse a
+   * namespaced key that would clobber a core handler). */
+  has(method: string): boolean {
+    return this.handlers.has(method);
+  }
+
   /**
    * Both platforms push envelopes in: iOS via WKScriptMessageHandler 'appwrap',
    * Android via the prompt() tunnel intercepted in WebChromeClient.onJsPrompt

package/runtime/app/shell/config.ts

@@ -65,4 +65,9 @@ export const SHELL_CONFIG = {
    * Lifting extra makes the page cover that strip (the keyboard hides the thin bottom row of content).
    * Default 82. Set 0 for NO extra lift (input sits flush at the reported height; the strip may show). */
   iosKeyboardExtraLift: 82,
+  /** Runtime env-switcher (loader:'server'). `enabled` is the resolved kill-switch (config block
+   * present AND not `enabled:false`); when false the menu action, banner, and boot override are all
+   * inert. `envs` = declared presets; `allowPattern` = anchored regex gating "Other" (default-deny
+   * when ''). Stamped by `appwrap init`/`sync` — see `stampShellConfig`. */
+  envSwitcher: { enabled: false, envs: [] as { label: string; url: string }[], allowPattern: '' },
 };

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

@@ -5,6 +5,13 @@ import { APPWRAP_GLOBALS_JS, NATIVE_FEEL_JS, serviceWorkerGuardJs, externalNavGu
 import { envGlobalsJs } from './env';
 import { requestPermissions } from './android-helpers';
 
+/** Host[:port] of a URL, lowercased; '' if unparseable (scheme/path/userinfo stripped). */
+function hostOfUrl(url: string): string {
+  const afterScheme = String(url || '').replace(/^[a-z][a-z0-9+.-]*:\/\//i, '');
+  const authority = afterScheme.split(/[/?#]/)[0];
+  return (authority.split('@').pop() || authority).toLowerCase();
+}
+
 // `android` + `java` resolve to the real types-android namespaces (no declare needed).
 declare const androidx: any; // no NS types: androidx.webkit.* (WebViewFeature/WebViewCompat) not in the android-32 platform typings
 
@@ -384,17 +391,23 @@ function createAssetServingClient(): android.webkit.WebViewClient {
       view.evaluateJavascript(buildBootstrapJs(), null as unknown as android.webkit.ValueCallback<string>);
     },
 
-    // `appwrap dev` points at a LAN dev server that almost always uses a self-signed / mkcert TLS
-    // cert the device's trust store doesn't know — the WebView would otherwise hard-fail with
-    // ERR_CERT_AUTHORITY_INVALID. Proceed past it ONLY in a debug build AND only when actually in
-    // server-loader (dev) mode. Production app:// builds never reach this (local assets, no TLS).
+    // DEBUG-ONLY dev-server cert trust (Android parity with the iOS WKNavigationDelegate). `appwrap dev`
+    // points at a LAN dev server that almost always uses a self-signed / mkcert TLS cert the device's
+    // trust store doesn't know — the WebView would otherwise hard-fail with ERR_CERT_AUTHORITY_INVALID.
+    // Proceed past it ONLY in a debug build, only in server-loader mode, AND only for the ONE host the
+    // build-time host (`SHELL_CONFIG.serverUrl`, NOT the switchable override) — never blanket-trust every host. Production app:// builds
+    // never reach this (local assets, no TLS). NEVER active in a store build (SHELL_CONFIG.debug false).
     onReceivedSslError(
       _view: android.webkit.WebView,
       handler: android.webkit.SslErrorHandler,
       error: android.net.http.SslError
     ): void {
-      if (SHELL_CONFIG.debug && SHELL_CONFIG.loader === 'server') {
-        console.warn('AppWrap: proceeding past dev-server SSL error (debug+server only):', String(error));
+      // BUILD-TIME serverUrl host ONLY — never the switchable `effectiveServerUrl()` override (would let a
+      // switched host's self-signed cert be trusted → MITM). The dev server is always the build-time URL.
+      const allowedHost = hostOfUrl(SHELL_CONFIG.serverUrl);
+      const errHost = hostOfUrl(String(error?.getUrl?.() ?? ''));
+      if (SHELL_CONFIG.debug && SHELL_CONFIG.loader === 'server' && !!allowedHost && errHost === allowedHost) {
+        console.warn('AppWrap: trusting self-signed dev-server cert (debug + host-scoped):', errHost);
         handler.proceed();
       } else {
         handler.cancel();

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

@@ -57,6 +57,103 @@ class AppwrapLogHandler extends NSObject implements WKScriptMessageHandler {
   }
 }
 
+/** Host[:port] of a URL, lowercased; '' if unparseable (scheme/path/userinfo stripped). */
+function hostOfUrl(url: string): string {
+  const afterScheme = String(url || '').replace(/^[a-z][a-z0-9+.-]*:\/\//i, '');
+  const authority = afterScheme.split(/[/?#]/)[0];
+  return (authority.split('@').pop() || authority).toLowerCase();
+}
+
+/**
+ * DEBUG-ONLY dev-server cert trust. A `WKNavigationDelegate` that accepts the server-trust challenge for
+ * the ONE build-time host (`SHELL_CONFIG.serverUrl`, NOT the switchable override) and ONLY in a debug build — so `appwrap dev`
+ * against a local vite HTTPS server with a self-signed cert loads on-device with NO per-device CA install
+ * (and getUserMedia/mic works — a secure context). NEVER in a store build (gated on `SHELL_CONFIG.debug`,
+ * which `appwrap build` never sets), and scoped to exactly one host so it can't blanket-trust the internet.
+ *
+ * It WRAPS NativeScript's own navigation delegate: every other selector is forwarded to the original via
+ * ObjC message forwarding (`forwardingTargetForSelector:` + a `respondsToSelector:` that also consults the
+ * fallback), so NS's load-lifecycle events keep firing. This is a DISTINCT gate from the env-switcher
+ * (which is allowlist+enabled-gated and runs in all builds); cert trust stays debug-only + host-scoped.
+ */
+@NativeClass()
+class DevCertNavDelegate extends NSObject implements WKNavigationDelegate {
+  static ObjCProtocols = [WKNavigationDelegate];
+  fallback: WKNavigationDelegate | null = null;
+  static withFallback(fb: WKNavigationDelegate | null): DevCertNavDelegate {
+    const d = <DevCertNavDelegate>DevCertNavDelegate.new();
+    d.fallback = fb;
+    return d;
+  }
+  private fbResponds(sel: string): boolean {
+    const f = this.fallback as any;
+    return !!(f && f.respondsToSelector && f.respondsToSelector(sel));
+  }
+
+  // The reason this delegate exists: trust a self-signed cert for the build-time serverUrl host, debug
+  // only. Host WITHOUT port (protectionSpace.host has no port; serverUrl may, e.g. a :3000 dev server).
+  // Scoped to the BUILD-TIME host, never the switchable override (would enable MITM on a switched host).
+  webViewDidReceiveAuthenticationChallengeCompletionHandler(
+    webView: WKWebView,
+    challenge: NSURLAuthenticationChallenge,
+    completionHandler: (d: NSURLSessionAuthChallengeDisposition, c: NSURLCredential | null) => void
+  ): void {
+    const space = challenge.protectionSpace;
+    const stripPort = (h: string) => h.replace(/:\d+$/, '');
+    const allowedHost = stripPort(hostOfUrl(SHELL_CONFIG.serverUrl));
+    if (
+      SHELL_CONFIG.debug && !!allowedHost &&
+      space.authenticationMethod === NSURLAuthenticationMethodServerTrust &&
+      stripPort(hostOfUrl(space.host)) === allowedHost && space.serverTrust
+    ) {
+      appendWebLog(`[native:devcert] trusting self-signed cert for ${space.host} (debug + host-scoped)`);
+      completionHandler(NSURLSessionAuthChallengeDisposition.UseCredential, NSURLCredential.credentialForTrust(space.serverTrust));
+      return;
+    }
+    if (this.fbResponds('webView:didReceiveAuthenticationChallenge:completionHandler:')) {
+      (this.fallback as any).webViewDidReceiveAuthenticationChallengeCompletionHandler(webView, challenge, completionHandler);
+      return;
+    }
+    completionHandler(NSURLSessionAuthChallengeDisposition.PerformDefaultHandling, null);
+  }
+
+  // We REPLACE NS's navigationDelegate, so we MUST re-implement every method NS relied on and forward it
+  // EXPLICITLY — ObjC message forwarding (forwardingTargetForSelector) is unreliable for a @NativeClass,
+  // and a decision method (below) whose `decisionHandler` is never called STALLS the navigation → blank.
+  webViewDecidePolicyForNavigationActionDecisionHandler(webView: WKWebView, navigationAction: any, decisionHandler: (p: number) => void): void {
+    if (this.fbResponds('webView:decidePolicyForNavigationAction:decisionHandler:')) {
+      (this.fallback as any).webViewDecidePolicyForNavigationActionDecisionHandler(webView, navigationAction, decisionHandler);
+    } else {
+      decisionHandler(1 /* WKNavigationActionPolicy.Allow */);
+    }
+  }
+  webViewDecidePolicyForNavigationResponseDecisionHandler(webView: WKWebView, navigationResponse: any, decisionHandler: (p: number) => void): void {
+    if (this.fbResponds('webView:decidePolicyForNavigationResponse:decisionHandler:')) {
+      (this.fallback as any).webViewDecidePolicyForNavigationResponseDecisionHandler(webView, navigationResponse, decisionHandler);
+    } else {
+      decisionHandler(1 /* WKNavigationResponsePolicy.Allow */);
+    }
+  }
+  webViewDidStartProvisionalNavigation(webView: WKWebView, navigation: any): void {
+    if (this.fbResponds('webView:didStartProvisionalNavigation:')) (this.fallback as any).webViewDidStartProvisionalNavigation(webView, navigation);
+  }
+  webViewDidCommitNavigation(webView: WKWebView, navigation: any): void {
+    if (this.fbResponds('webView:didCommitNavigation:')) (this.fallback as any).webViewDidCommitNavigation(webView, navigation);
+  }
+  webViewDidFinishNavigation(webView: WKWebView, navigation: any): void {
+    if (this.fbResponds('webView:didFinishNavigation:')) (this.fallback as any).webViewDidFinishNavigation(webView, navigation);
+  }
+  webViewDidFailNavigationWithError(webView: WKWebView, navigation: any, error: NSError): void {
+    if (this.fbResponds('webView:didFailNavigation:withError:')) (this.fallback as any).webViewDidFailNavigationWithError(webView, navigation, error);
+  }
+  webViewDidFailProvisionalNavigationWithError(webView: WKWebView, navigation: any, error: NSError): void {
+    if (this.fbResponds('webView:didFailProvisionalNavigation:withError:')) (this.fallback as any).webViewDidFailProvisionalNavigationWithError(webView, navigation, error);
+  }
+  webViewWebContentProcessDidTerminate(webView: WKWebView): void {
+    if (this.fbResponds('webViewWebContentProcessDidTerminate:')) (this.fallback as any).webViewWebContentProcessDidTerminate(webView);
+  }
+}
+
 export class CustomWebView extends WebView {
   /** Set by the bridge before load; receives raw envelope JSON. */
   onAppwrapMessage: ((json: string) => void) | null = null;
@@ -67,6 +164,7 @@ export class CustomWebView extends WebView {
   // TS `private` is compile-time only — sharing it let super.initNativeView() overwrite
   // our media-capture delegate with NS's, so getUserMedia re-prompted every call.
   private _appwrapUiDelegate!: WKUIDelegate; // retained — WKWebView holds uiDelegate weakly
+  private _navDelegate: DevCertNavDelegate | null = null; // retained — WKWebView holds navigationDelegate weakly
 
   /** No-op on iOS: WKWebView suspends rAF/timers itself when the app leaves the foreground.
    * Kept for parity with the Android impl (wired to suspend/resume in main-page). */
@@ -267,6 +365,14 @@ export class CustomWebView extends WebView {
     // the `.grant` sticks: iOS then prompts once (TCC), like a native app.
     const wk = this.nativeViewProtected as WKWebView;
     if (wk && this._appwrapUiDelegate) wk.UIDelegate = this._appwrapUiDelegate;
+    // DEBUG-ONLY dev-server cert trust: wrap NS's navigation delegate so a self-signed local dev server
+    // loads without a per-device CA install. Only in a debug server-loader build; forwards all other
+    // nav-delegate selectors to NS's original so load events keep firing. Never compiled-active in a
+    // store build (SHELL_CONFIG.debug is false there).
+    if (wk && SHELL_CONFIG.debug && SHELL_CONFIG.loader === 'server') {
+      this._navDelegate = DevCertNavDelegate.withFallback(wk.navigationDelegate);
+      wk.navigationDelegate = this._navDelegate;
+    }
     // Lightweight self-check surfaced via debug.webviewInfo (support diagnostics).
     (global as { __appwrapWebviewDiag?: string }).__appwrapWebviewDiag =
       `delegateIsMine=${!!wk && wk.UIDelegate === this._appwrapUiDelegate} ` +

package/runtime/app/shell/devmenu.ts

@@ -2,6 +2,8 @@ import { Device, Dialogs, Utils, isAndroid, isIOS } from '@nativescript/core';
 import { bridge } from './bridge';
 import { SHELL_CONFIG } from './config';
 import { SHELL_BUILD, reloadWebView, getReportedWebVersion } from './handlers';
+import { isEnvSwitcherEnabled, showEnvSwitcher } from './env-switcher';
+import { resetEnvBannerPosition } from './env-banner';
 
 /**
  * Shake-to-open developer menu (enabled in prod too, gated by `SHELL_CONFIG.devMenu`).
@@ -55,6 +57,7 @@ function onAccelMagnitude(g: number, dir: number): void {
     lastSpikeAt = 0;
     lastSpikeDir = 0;
     lastMenuAt = now;
+    resetEnvBannerPosition(); // a shake also recalls a stranded (freely-dragged) env pill to its default spot
     void showDevMenu();
   }
 }
@@ -117,15 +120,20 @@ async function showDevMenu(): Promise<void> {
   if (menuOpen) return; // sensor keeps firing while the sheet is up — don't stack dialogs
   menuOpen = true;
   try {
+    const actions = ['App Info', 'Reload', 'Toggle Debug'];
+    // "Switch Environment" — only when the env-switcher is configured + enabled (runs in ALL build types,
+    // not just debug; the gate is the config allowlist + confirm prompt, see env-switcher.ts).
+    if (isEnvSwitcherEnabled()) actions.push('Switch Environment');
     const action = await Dialogs.action({
       title: SHELL_CONFIG.name,
       message: 'Developer menu',
       cancelButtonText: 'Cancel',
-      actions: ['App Info', 'Reload', 'Toggle Debug'],
+      actions,
     });
     if (action === 'App Info') await showInfo();
     else if (action === 'Reload') reloadWebView();
     else if (action === 'Toggle Debug') toggleWebDebug();
+    else if (action === 'Switch Environment') await showEnvSwitcher();
   } finally {
     menuOpen = false;
   }

package/runtime/app/shell/env-banner.ts

@@ -0,0 +1,236 @@
+import { Application, Utils, isAndroid, isIOS } from '@nativescript/core';
+import { activeEnvLabel, currentOverride, hostOf, isEnvSwitcherEnabled, isNonDefaultOverride, showEnvSwitcher } from './env-switcher';
+
+/**
+ * Env indicator banner — a non-invasive marker pinned to the BOTTOM safe area, shown on every relaunch
+ * while a NON-DEFAULT env override is active (see `currentOverride`). It starts EXPANDED (label + host),
+ * auto-shrinks to a small PILL after 3s to stay out of the way; tapping the pill re-expands it, tapping
+ * the expanded banner opens the "Switch Environment" menu (`showEnvSwitcher`). Moved here from the AGF web
+ * app since env-switching is now a framework concern. Distinct from `banner.ts` (the update-prompt banner).
+ */
+
+const SHRINK_MS = 3000;
+type State = 'expanded' | 'pill';
+let state: State = 'expanded';
+let shrinkTimer: any = null;
+
+// iOS refs (built lazily inside the iOS path — `interop`/`NSObject` don't exist on Android).
+let iosContainer: UIView | null = null;
+let iosLabel: UILabel | null = null;
+let iosTapHandler: any = null;
+let IOSGestureHandler: any = null;
+let iosDraggedCenter: { x: number; y: number } | null = null; // where the user parked the pill (drag)
+let iosPanRecognizer: any = null; // read inside the (no-arg) pan handler to avoid a param-selector crash
+
+// Android refs.
+let androidView: android.widget.TextView | null = null;
+
+/** Show the banner if the switcher is enabled AND a NON-DEFAULT override is active. Idempotent. No-op
+ * otherwise (incl. when the override resolves to the build-time default host). */
+export function showEnvBannerIfActive(): void {
+  if (!isEnvSwitcherEnabled() || !isNonDefaultOverride()) return;
+  state = 'expanded';
+  if (isIOS) Utils.dispatchToMainThread(showIOSBanner);
+  else if (isAndroid) runOnAndroidUi(showAndroidBanner);
+}
+
+/**
+ * Reconcile the banner with the CURRENT override after an in-session switch/reset (the WebView reloads but
+ * this native overlay doesn't re-render on its own). Override active → ensure shown, reset to EXPANDED,
+ * re-render the new label/host, and re-arm the single shrink timer. Override cleared (reset) → hide it.
+ * Called from `applySwitch`; complements `showEnvBannerIfActive` (relaunch path).
+ */
+export function refreshEnvBanner(): void {
+  if (!isEnvSwitcherEnabled() || !isNonDefaultOverride()) { hideEnvBanner(); return; }
+  state = 'expanded';
+  if (isIOS) Utils.dispatchToMainThread(() => { if (iosContainer) { renderIOS(); armShrink(); } else showIOSBanner(); });
+  else if (isAndroid) runOnAndroidUi(() => { if (androidView) { renderAndroid(); armShrink(); } else showAndroidBanner(); });
+}
+
+/** Remove the banner and cancel its shrink timer. Idempotent. */
+export function hideEnvBanner(): void {
+  if (shrinkTimer) { clearTimeout(shrinkTimer); shrinkTimer = null; }
+  if (isIOS) Utils.dispatchToMainThread(hideIOSBanner);
+  else if (isAndroid) runOnAndroidUi(hideAndroidBanner);
+}
+
+/**
+ * Recall a stranded pill to its default spot: clear the parked/dragged position and re-render. No-op
+ * cleanly if the banner isn't shown. Wired to the shake handler (devmenu.ts) so a shake both opens the
+ * dev menu AND brings a dragged-away pill home — the recovery mechanism for the now-unclamped drag.
+ */
+export function resetEnvBannerPosition(): void {
+  iosDraggedCenter = null;
+  if (isIOS) { if (iosContainer) render(); }
+  else if (isAndroid) { if (androidView) render(); }
+}
+
+function bannerText(): string {
+  const label = activeEnvLabel() || 'Custom';
+  return state === 'pill' ? `⇄ ${label}` : `⇄ ${label} · ${hostOf(currentOverride())}`;
+}
+
+function armShrink(): void {
+  if (shrinkTimer) clearTimeout(shrinkTimer);
+  shrinkTimer = setTimeout(() => {
+    state = 'pill';
+    render();
+  }, SHRINK_MS);
+}
+
+function onTap(): void {
+  if (state === 'expanded') {
+    void showEnvSwitcher(); // tap expanded → open the switch menu
+  } else {
+    state = 'expanded'; // tap pill → re-expand, then re-arm the auto-shrink
+    render();
+    armShrink();
+  }
+}
+
+function render(): void {
+  if (isIOS) Utils.dispatchToMainThread(renderIOS);
+  else if (isAndroid) runOnAndroidUi(renderAndroid);
+}
+
+// ── iOS ──────────────────────────────────────────────────────────────
+function iosGestureHandlerClass(): any {
+  if (!IOSGestureHandler) {
+    IOSGestureHandler = (NSObject as any).extend(
+      {
+        bannerTapped() { onTap(); },
+        // Drag to reposition; remember where the user parked it so re-renders don't snap it back.
+        // No-arg (reads the module-level recognizer) — a param-selector target crashes with
+        // "unrecognized selector" on a runtime .extend, so we mirror the no-arg tap pattern.
+        bannerPanned() {
+          const gr = iosPanRecognizer, c = iosContainer;
+          if (!gr || !c || !c.superview) return;
+          const t = gr.translationInView(c.superview);
+          // FREELY draggable ANYWHERE — including the top safe-area / status bar / screen edges. No clamp:
+          // recovery is via shake (see resetEnvBannerPosition), not by fencing the drag.
+          const nx = c.center.x + t.x, ny = c.center.y + t.y;
+          c.center = CGPointMake(nx, ny);
+          gr.setTranslationInView(CGPointMake(0, 0), c.superview);
+          if (gr.state === 3 /* UIGestureRecognizerState.Ended */) iosDraggedCenter = { x: nx, y: ny };
+        },
+      },
+      {
+        exposedMethods: {
+          bannerTapped: { returns: interop.types.void },
+          bannerPanned: { returns: interop.types.void },
+        },
+      }
+    );
+  }
+  return IOSGestureHandler;
+}
+
+function showIOSBanner(): void {
+  if (iosContainer) return; // already shown
+  const rootVC = Utils.ios.getRootViewController();
+  if (!rootVC?.view) return;
+
+  const container = UIView.alloc().initWithFrame(CGRectMake(0, 0, 10, 10));
+  container.backgroundColor = UIColor.colorWithRedGreenBlueAlpha(0.72, 0.45, 0.02, 0.92); // amber = "not default"
+  container.layer.cornerRadius = 15;
+  container.clipsToBounds = true;
+  container.userInteractionEnabled = true;
+
+  const label = UILabel.alloc().initWithFrame(CGRectZero);
+  label.textColor = UIColor.whiteColor;
+  label.textAlignment = NSTextAlignment.Center;
+  label.font = UIFont.systemFontOfSizeWeight(13, UIFontWeightSemibold);
+  container.addSubview(label);
+
+  iosTapHandler = iosGestureHandlerClass().alloc().init();
+  container.addGestureRecognizer(UITapGestureRecognizer.alloc().initWithTargetAction(iosTapHandler, 'bannerTapped'));
+  iosPanRecognizer = UIPanGestureRecognizer.alloc().initWithTargetAction(iosTapHandler, 'bannerPanned');
+  container.addGestureRecognizer(iosPanRecognizer);
+
+  rootVC.view.addSubview(container);
+  iosContainer = container;
+  iosLabel = label;
+  renderIOS();
+  armShrink();
+}
+
+function renderIOS(): void {
+  const container = iosContainer, label = iosLabel;
+  if (!container || !label) return;
+  // Position in the SUPERVIEW's coordinate space (where container.center lives), NOT UIScreen: the root
+  // view can be inset/offset from the screen, which made the default land at the TOP. Fall back to the
+  // screen only if the container isn't in a hierarchy yet.
+  const sv = container.superview;
+  const bounds = sv ? sv.bounds : UIScreen.mainScreen.bounds;
+  const insets = sv ? sv.safeAreaInsets : null;
+  const safeBottom = insets ? insets.bottom : 0;
+  label.text = bannerText();
+  const height = 30;
+  const width = state === 'pill' ? 96 : Math.min(bounds.size.width - 24, 320);
+  container.alpha = state === 'pill' ? 0.6 : 1.0; // shrunk pill is semi-transparent but still readable
+  UIView.animateWithDurationAnimations(0.25, () => {
+    label.frame = CGRectMake(10, 0, width - 20, height);
+    container.frame = CGRectMake(0, 0, width, height);
+    if (state === 'pill' && iosDraggedCenter) {
+      container.center = CGPointMake(iosDraggedCenter.x, iosDraggedCenter.y); // where the user parked it
+    } else if (state === 'pill') {
+      // Parked default: inset from the left edge and RAISED well above the home-indicator zone, so a drag
+      // isn't stolen by iOS system edge gestures and it never sits under a bottom CTA. Draggable from there.
+      container.center = CGPointMake(20 + width / 2, bounds.size.height - safeBottom - height / 2 - 64);
+    } else {
+      // Expanded (transient): centered just above the safe area.
+      container.center = CGPointMake(bounds.size.width / 2, bounds.size.height - safeBottom - height / 2 - 6);
+    }
+  });
+}
+
+function hideIOSBanner(): void {
+  if (!iosContainer) return;
+  iosContainer.removeFromSuperview();
+  iosContainer = null;
+  iosLabel = null;
+}
+
+// ── Android ──────────────────────────────────────────────────────────
+function showAndroidBanner(): void {
+  if (androidView) return;
+  const activity = Application.android.foregroundActivity || Application.android.startActivity;
+  if (!activity) return;
+  const density = activity.getResources().getDisplayMetrics().density;
+  const padH = Math.round(14 * density), padV = Math.round(6 * density);
+
+  const tv = new android.widget.TextView(activity);
+  tv.setTextColor(android.graphics.Color.WHITE);
+  tv.setTextSize(13);
+  tv.setPadding(padH, padV, padH, padV);
+  const bg = new android.graphics.drawable.GradientDrawable();
+  bg.setColor(android.graphics.Color.argb(235, 184, 115, 5)); // amber
+  bg.setCornerRadius(15 * density);
+  tv.setBackground(bg);
+  tv.setOnClickListener(new android.view.View.OnClickListener({ onClick() { onTap(); } }));
+
+  const lp = new android.widget.FrameLayout.LayoutParams(-2, -2); // WRAP_CONTENT × WRAP_CONTENT
+  lp.gravity = android.view.Gravity.BOTTOM | android.view.Gravity.CENTER_HORIZONTAL;
+  lp.bottomMargin = Math.round(10 * density);
+  activity.addContentView(tv, lp);
+  androidView = tv;
+  renderAndroid();
+  armShrink();
+}
+
+function renderAndroid(): void {
+  if (androidView) androidView.setText(bannerText());
+}
+
+function hideAndroidBanner(): void {
+  if (!androidView) return;
+  const parent = androidView.getParent();
+  if (parent) (parent as android.view.ViewGroup).removeView(androidView);
+  androidView = null;
+}
+
+function runOnAndroidUi(fn: () => void): void {
+  const activity = Application.android.foregroundActivity || Application.android.startActivity;
+  if (activity) activity.runOnUiThread(new java.lang.Runnable({ run: fn }));
+  else fn();
+}

package/runtime/app/shell/env-switcher.ts

@@ -0,0 +1,163 @@
+import { ApplicationSettings, Dialogs, Utils, isAndroid, isIOS } from '@nativescript/core';
+import { SHELL_CONFIG } from './config';
+import { OVERRIDE_KEY, effectiveServerUrl, isUrlAllowed } from './server-url';
+import { bridge } from './bridge';
+import { refreshEnvBanner } from './env-banner';
+
+/**
+ * Runtime env-switcher — re-point a `loader:'server'` shell between declared environments (prod / lab /
+ * a preview URL) at runtime, surviving a cold start, with NO separate native build. First-party capability
+ * (not a plugin), opt-in via `SHELL_CONFIG.envSwitcher`. Inert unless the config block is present AND
+ * `enabled` (a prod fork can set `enabled:false` to hard-disable).
+ *
+ * SECURITY MODEL (distinct from the debug-only dev-server cert trust): this runs in ALL build types when
+ * configured. The gate is a REGEX ALLOWLIST + a CONFIRM prompt, not build-type. Declared presets (`envs`)
+ * are always trusted; a free-form "Other" URL must match `allowPattern` (anchored, full-string, compiled
+ * with try/catch — a throwing/absent pattern is treated as DEFAULT-DENY: "Other" disabled). The chosen URL
+ * is persisted through the same native-storage seam the boot loader reads (`kit:serverUrlOverride`).
+ */
+
+export function isEnvSwitcherEnabled(): boolean {
+  return SHELL_CONFIG.loader === 'server' && !!SHELL_CONFIG.envSwitcher?.enabled;
+}
+
+/** Host[:port] of a URL — scheme/path/query/fragment/userinfo stripped. '' if unparseable. */
+export function hostOf(url: string): string {
+  const afterScheme = String(url || '').replace(/^[a-z][a-z0-9+.-]*:\/\//i, '');
+  const authority = afterScheme.split(/[/?#]/)[0];
+  return (authority.split('@').pop() || authority).toLowerCase();
+}
+
+/** The currently persisted override URL, or '' when none / malformed / feature disabled. */
+export function currentOverride(): string {
+  if (!isEnvSwitcherEnabled()) return '';
+  try {
+    const raw = ApplicationSettings.getString(OVERRIDE_KEY, '');
+    if (!raw) return '';
+    const url = JSON.parse(raw);
+    return typeof url === 'string' ? url : '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * True when a persisted override is active AND resolves to a host that DIFFERS from the build-time default
+ * (`SHELL_CONFIG.serverUrl`). This — not raw `currentOverride()` — is the "you are NOT on the default env"
+ * signal the banner keys off: an override whose host equals the build default is not an off-default state
+ * (e.g. selecting the preset that equals the build default). Host-normalized via `hostOf` (host[:port],
+ * lowercased) — note `hostOf` KEEPS the port (unlike the dev-cert match, which strips it), so two envs that
+ * differ only by port compare as distinct; both sides use the same `hostOf`, so the equality test is sound.
+ */
+export function isNonDefaultOverride(): boolean {
+  const override = currentOverride();
+  if (!override) return false;
+  return hostOf(override) !== hostOf(SHELL_CONFIG.serverUrl);
+}
+
+/** Label for the active env: a matching preset's label, else 'Custom' when an override is set, else ''. */
+export function activeEnvLabel(): string {
+  const override = currentOverride();
+  if (!override) return '';
+  const preset = (SHELL_CONFIG.envSwitcher?.envs ?? []).find((e) => e.url === override);
+  return preset ? preset.label : 'Custom';
+}
+
+/** Persist an override (same encoding as `kit.storage.set` — JSON.stringify under the namespaced key). */
+function writeOverride(url: string): void {
+  ApplicationSettings.setString(OVERRIDE_KEY, JSON.stringify(url));
+}
+
+function clearOverride(): void {
+  ApplicationSettings.remove(OVERRIDE_KEY);
+}
+
+/** Load the current effective server URL into the live WebView (immediate switch — no wait for a cold
+ * start; the persisted override also makes it stick across relaunch via the boot loader). */
+function reloadToEffective(): void {
+  const wv = bridge.getWebView();
+  if (!wv) return;
+  const url = effectiveServerUrl();
+  Utils.dispatchToMainThread(() => {
+    if (isIOS && wv.ios) {
+      (wv.ios as WKWebView).loadRequest(NSURLRequest.requestWithURL(NSURL.URLWithString(url)));
+    } else if (isAndroid && wv.android) {
+      wv.android.clearCache(true);
+      wv.src = url;
+    }
+  });
+}
+
+/** Apply a switch after user confirmation: persist (or clear) then reload to the new effective URL. */
+async function applySwitch(url: string | null, label: string): Promise<void> {
+  const ok = await Dialogs.confirm({
+    title: 'Switch environment',
+    message: url ? `Load ${label}?\n${hostOf(url)}\n\nThe app will reload.` : 'Reset to the default environment?\nThe app will reload.',
+    okButtonText: url ? 'Switch' : 'Reset',
+    cancelButtonText: 'Cancel',
+  });
+  if (!ok) return;
+  // Switching to a URL whose host equals the build-time default is really a RESET: persisting it would be
+  // redundant state (the boot loader falls back to SHELL_CONFIG.serverUrl anyway) and would leave a
+  // relaunch-visible key. Clear instead, so both the banner gate and a cold start land on "default".
+  if (url && hostOf(url) !== hostOf(SHELL_CONFIG.serverUrl)) writeOverride(url);
+  else clearOverride();
+  reloadToEffective();
+  refreshEnvBanner(); // in-session: reflect the new env (switch) or hide (reset) — not just on relaunch
+}
+
+let menuOpen = false;
+
+/**
+ * Show the "Switch Environment" action sheet: pick a declared preset, enter a free-form "Other" URL
+ * (validated against `allowPattern`, default-deny), or reset to the build default. Every switch goes
+ * through a confirm prompt. No-op when the feature is disabled.
+ */
+export async function showEnvSwitcher(): Promise<void> {
+  if (!isEnvSwitcherEnabled() || menuOpen) return;
+  menuOpen = true;
+  try {
+    const envs = SHELL_CONFIG.envSwitcher?.envs ?? [];
+    const active = currentOverride();
+    const allowOther = !!SHELL_CONFIG.envSwitcher?.allowPattern;
+    const actions = envs.map((e) => (e.url === active ? `${e.label} ✓` : e.label));
+    if (allowOther) actions.push('Other…');
+    actions.push('Reset to default');
+
+    const choice = await Dialogs.action({
+      title: 'Switch Environment',
+      message: active ? `Current: ${activeEnvLabel()} (${hostOf(active)})` : 'Current: default',
+      cancelButtonText: 'Cancel',
+      actions,
+    });
+    if (!choice || choice === 'Cancel') return;
+
+    if (choice === 'Reset to default') return void (await applySwitch(null, 'default'));
+    if (choice === 'Other…') return void (await promptOther());
+
+    const label = choice.replace(/ ✓$/, '');
+    const env = envs.find((e) => e.label === label);
+    if (env) await applySwitch(env.url, env.label);
+  } finally {
+    menuOpen = false;
+  }
+}
+
+/** Free-form URL entry, gated by `allowPattern` (default-deny). Rejects a non-matching URL. */
+async function promptOther(): Promise<void> {
+  const res = await Dialogs.prompt({
+    title: 'Custom environment',
+    message: 'Enter an allowed URL (https://…).',
+    okButtonText: 'Next',
+    cancelButtonText: 'Cancel',
+    defaultText: 'https://',
+    inputType: 'text',
+  });
+  if (!res?.result || !res.text) return;
+  const url = res.text.trim();
+  if (!isUrlAllowed(url)) {
+    await Dialogs.alert({ title: 'Not allowed', message: 'That URL is not in the allowed pattern for this app.', okButtonText: 'OK' });
+    return;
+  }
+  await applySwitch(url, 'Custom');
+}

package/runtime/app/shell/handlers-background.ts

@@ -1,6 +1,7 @@
 import { Application, Utils, isAndroid, isIOS } from '@nativescript/core';
 import { bridge } from './bridge';
 import { SHELL_CONFIG } from './config';
+import { effectiveServerUrl } from './server-url';
 import { setPendingBackgroundTaskId } from './background-context';
 import { CustomWebView } from './custom-webview';
 // Android-only WorkManager Worker (@JavaProxy + `extends androidx.work.Worker`). Kept in a `.android.ts`
@@ -100,14 +101,14 @@ function loadAppInto(webView: CustomWebView, id: string, attempt = 0): void {
     const wk = webView.ios as WKWebView;
     if (retry(!wk)) return;
     if (SHELL_CONFIG.loader === 'server' && SHELL_CONFIG.serverUrl) {
-      wk.loadRequest(NSURLRequest.requestWithURL(NSURL.URLWithString(SHELL_CONFIG.serverUrl)));
+      wk.loadRequest(NSURLRequest.requestWithURL(NSURL.URLWithString(effectiveServerUrl())));
     } else {
       wk.loadRequest(NSURLRequest.requestWithURL(NSURL.URLWithString(`app://localhost/${SHELL_CONFIG.entry}`)));
     }
   } else {
     if (retry(!webView.android)) return;
     webView.src = SHELL_CONFIG.loader === 'server' && SHELL_CONFIG.serverUrl
-      ? SHELL_CONFIG.serverUrl
+      ? effectiveServerUrl()
       : `https://appwrap.local/${SHELL_CONFIG.entry}`;
   }
 }

package/runtime/app/shell/plugin-host.ts

@@ -0,0 +1,51 @@
+/**
+ * Mobile plugin host — the in-process analog of the desktop plugin host (`plugin/host.ts`).
+ *
+ * On desktop a plugin's `WindowCtx` ops marshal over a Unix socket to the Rust shell; that host does
+ * NOT apply on mobile — there is one WKWebView/WebView and the NS runtime IS the trusted host. So the
+ * mobile "host" is trivial: at boot it takes each configured plugin's def and registers its `handlers`
+ * directly onto the same {@link bridge} the built-in `handlers*.ts` groups use. A PWA then reaches a
+ * plugin handler exactly like any native method — `kit.invoke('<plugin>.<method>')`.
+ *
+ * This walking skeleton consumes ONLY `handlers` (the desktop types call a handlers-only plugin the
+ * base case). `attachTo`/`onWindow`/`WindowCtx` are desktop-only concepts (multi-window, out-of-webview
+ * control) with no mobile analog yet — a plugin that also declares them still works here; those fields
+ * are ignored. Deeper hooks (devmenu action, boot/deeplink) are a documented follow-up.
+ */
+import { bridge } from './bridge';
+
+/**
+ * The structural subset of the shared `PluginDef` (`@livx.cc/appwrap/plugin`) that the mobile host
+ * consumes. Kept as a local type so the NS runtime never imports the desktop socket/WindowCtx types.
+ * A plugin authored with `definePlugin({ name, handlers })` satisfies this by construction.
+ *
+ * Handler keys are BARE method names (`hello`, not `greeter.hello`); the host registers each on the
+ * bridge NAMESPACED under `plugin.name` → the PWA reaches it as `kit.invoke('<name>.<method>')`.
+ */
+export interface MobilePluginDef {
+  name: string;
+  handlers?: Record<string, (params: any) => unknown | Promise<unknown>>;
+}
+
+/** Register one plugin's bridge handlers, each NAMESPACED under `plugin.name` as `<name>.<method>`.
+ * This (a) matches the spec's `kit.invoke('<plugin>.<method>')` call shape and (b) confines a plugin
+ * to its own namespace so it cannot shadow a core handler (e.g. `app.reload`). As a belt-and-braces
+ * guard for the residual case where `name` itself collides with a core prefix, a namespaced key that
+ * is ALREADY registered (core handlers register first, at boot) is refused with a warning rather than
+ * clobbering the incumbent. */
+export function registerPluginHandlers(plugin: MobilePluginDef): void {
+  const name = plugin?.name;
+  const handlers = plugin?.handlers ?? {};
+  if (!name) {
+    console.warn('⚠ mobile plugin has no `name` — cannot namespace its handlers; skipping.');
+    return;
+  }
+  for (const method of Object.keys(handlers)) {
+    const key = `${name}.${method}`;
+    if (bridge.has(key)) {
+      console.warn(`⚠ mobile plugin "${name}" handler "${key}" collides with an already-registered method — refusing to override; skipping.`);
+      continue;
+    }
+    bridge.register(key, handlers[method]);
+  }
+}

package/runtime/app/shell/plugins.generated.ts

@@ -0,0 +1,8 @@
+/**
+ * Generated by `appwrap init`/`sync` from the appwrap config `plugins`. Do not edit.
+ * Committed DEFAULT registers NO plugins (parity with the module barrels): a build without `plugins`
+ * imports no plugin bundle and compiles no plugin glue. The CLI (`regenerateMobilePlugins`) rewrites
+ * this to import each configured plugin's bundle and register its handlers.
+ */
+export function registerPlugins(): void {
+}

package/runtime/app/shell/server-url.ts

@@ -0,0 +1,74 @@
+import { ApplicationSettings } from '@nativescript/core';
+import { SHELL_CONFIG } from './config';
+
+/**
+ * Persisted serverUrl override for `loader:'server'` shells.
+ *
+ * A web debug tool (e.g. an in-app env switcher) can point the WebView at a different origin at
+ * runtime. `window.location` only lasts the session — on a cold start the shell reloads its
+ * build-time `serverUrl`, and web `localStorage` is partitioned per-origin so it can't carry the
+ * choice across the switch. The fix lives in the shell: persist the chosen URL in native storage
+ * (survives restarts + origin changes) and read it HERE at every boot/reload site.
+ *
+ * The web writes it through the existing `kit.storage` seam — `kit.storage.set('serverUrlOverride',
+ * url)` — which stores `JSON.stringify(url)` under the namespaced key `kit:serverUrlOverride`
+ * (ApplicationSettings → NSUserDefaults / SharedPreferences). Clearing it (`kit.storage.remove`)
+ * reverts to the build-time `serverUrl` on the next load.
+ *
+ * SECURITY: honored ONLY when the env-switcher is configured + enabled (`SHELL_CONFIG.envSwitcher.enabled`
+ * — the config block is present and not `enabled:false`). An app that doesn't declare `envSwitcher`, or a
+ * prod fork that sets `enabled:false`, ignores the key entirely, so a compromised page can't persistently
+ * redirect the shell. The switcher's own gate (menu + allowPattern + confirm) governs what can be written;
+ * this is the read side. Runs in ALL build types when enabled — distinct from the debug-only cert trust.
+ */
+export const OVERRIDE_KEY = 'kit:serverUrlOverride';
+
+/**
+ * Full-string allowlist test for a candidate "Other"/override URL. DEFAULT-DENY: an empty or throwing
+ * `allowPattern` rejects everything. Enforces a FULL-STRING match (guards a non-anchored pattern that
+ * would otherwise match a substring). Bounded input length guards against pathological backtracking on a
+ * hostile pattern. Lives here (not env-switcher.ts) so the boot loader can reuse it without an import
+ * cycle — env-switcher.ts imports it back for the "Other" prompt.
+ */
+export function isUrlAllowed(url: string): boolean {
+  const pattern = SHELL_CONFIG.envSwitcher?.allowPattern;
+  if (!pattern) return false; // default-deny: no allowlist configured
+  if (!/^https?:\/\//i.test(url) || url.length > 2048) return false;
+  try {
+    const re = new RegExp(pattern);
+    const m = url.match(re);
+    return !!m && m[0] === url; // full-string match, regardless of author anchoring
+  } catch {
+    return false; // throwing pattern → default-deny
+  }
+}
+
+/** Is a stored/entered override URL trustworthy? A declared preset is implicitly allowed; otherwise it
+ * must match `allowPattern`. Used by BOTH the boot loader (re-validate the persisted override) and the
+ * switcher, so a compromised page that writes an arbitrary `serverUrlOverride` directly through the
+ * `kit.storage` bridge seam can't redirect the shell — the write is ignored at boot unless allowlisted. */
+export function isOverrideAllowed(url: string): boolean {
+  const presets = SHELL_CONFIG.envSwitcher?.envs ?? [];
+  if (presets.some((e) => e.url === url)) return true; // presets are implicitly trusted
+  return isUrlAllowed(url);
+}
+
+/** The URL a server-loader shell should load at boot/reload: a valid, ALLOWLISTED persisted override when
+ * the env-switcher is enabled, else the build-time `SHELL_CONFIG.serverUrl`. Re-validates the stored
+ * override against the same allowlist the switcher uses — the native menu isn't the only writer of the
+ * key (any page JS can write it via `kit.storage.set`), so the read side must not trust it blindly. */
+export function effectiveServerUrl(): string {
+  if (SHELL_CONFIG.loader !== 'server') return SHELL_CONFIG.serverUrl;
+  if (SHELL_CONFIG.envSwitcher?.enabled) {
+    try {
+      const raw = ApplicationSettings.getString(OVERRIDE_KEY, '');
+      if (raw) {
+        const url = JSON.parse(raw);
+        if (typeof url === 'string' && /^https?:\/\//i.test(url) && isOverrideAllowed(url)) return url;
+      }
+    } catch {
+      /* malformed override — fall back to the build-time serverUrl */
+    }
+  }
+  return SHELL_CONFIG.serverUrl;
+}

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

@@ -86,6 +86,71 @@ fn rust_port() -> u16 {
     std::env::var("APPWRAP_BRIDGE_RUST_PORT").ok().and_then(|s| s.parse().ok()).unwrap_or(9237)
 }
 
+// ---- Agent-browser-control gate ------------------------------------------------------------------
+// The bridge control channel can eval arbitrary JS in any embedded tab, so it is OPT-IN and OFF by
+// default. It is env-gated at process launch (APPWRAP_BRIDGE_JS), but an app's opt-in typically lives
+// in the FE and isn't known until after launch — a chicken-and-egg. Resolution: a PERSISTENT marker
+// file (survives relaunch, unlike per-launch web storage). The app writes/removes the marker (e.g. via
+// an `app.setAgentBrowserControl` handler) and asks the user to relaunch; on the next launch
+// `resolve_gate()` reads the marker and, if present, populates the bridge env BEFORE `init()` — so the
+// bridge comes up exactly when the user opted in, and stays fully inert otherwise. The marker path is
+// owned by the caller (main.rs, which knows the app identifier) so this module stays app-agnostic.
+
+/// Derive the built content bundle path from the running binary (dev + bundled layouts), so callers
+/// don't have to know it. Returns the first candidate that exists.
+fn resolve_content_js() -> Option<String> {
+    let exe = std::env::current_exe().ok()?;
+    let mut dir = exe.parent();
+    while let Some(d) = dir {
+        // Dev layout: …/runtime-desktop/… has the built bundle at bridge-shim/dist/content.js.
+        let cand = d.join("bridge-shim/dist/content.js");
+        if cand.exists() {
+            return Some(cand.to_string_lossy().into_owned());
+        }
+        // Bundled .app: content.js is staged into Contents/Resources.
+        let res = d.join("Resources/content.js");
+        if res.exists() {
+            return Some(res.to_string_lossy().into_owned());
+        }
+        dir = d.parent();
+    }
+    None
+}
+
+/// Launch-time gate resolution. The opt-in `marker` is the SINGLE source of truth for the
+/// browser-control bridge: it arms iff the marker is present, regardless of any inherited env.
+///
+/// A controlling daemon (mcp-desktop-browser) ALWAYS spawns us with `APPWRAP_BRIDGE_JS` set (it can't
+/// know the FE opt-in), so trusting an inherited env would let a daemon spawn arm the bridge with no
+/// marker — defeating the gate. Therefore: no marker → forcibly CLEAR the bridge env (`init()` then
+/// returns early, fully inert), no matter what we were spawned with. Marker present (opted in) → keep
+/// a daemon-provided env as-is (correct rendezvous ports), or populate it from the resolved content
+/// bundle + defaults when launched standalone. Must run before `init()` and before any embedded tab.
+pub fn resolve_gate(marker: &std::path::Path) {
+    if !marker.exists() {
+        // Not opted in — the bridge stays inert even if a spawner set the env. The marker, not the
+        // inherited env, is authoritative for the browser-control channel.
+        std::env::remove_var("APPWRAP_BRIDGE_JS");
+        return;
+    }
+    if std::env::var("APPWRAP_BRIDGE_JS").ok().filter(|s| !s.is_empty()).is_some() {
+        return; // opted in + env already provided (daemon-spawned) — respect its rendezvous ports
+    }
+    match resolve_content_js() {
+        Some(js) => {
+            std::env::set_var("APPWRAP_BRIDGE_JS", js);
+            if std::env::var("APPWRAP_BRIDGE_RUST_PORT").is_err() {
+                std::env::set_var("APPWRAP_BRIDGE_RUST_PORT", "3843");
+            }
+            if std::env::var("APPWRAP_BRIDGE_PAGE_PORT").is_err() {
+                std::env::set_var("APPWRAP_BRIDGE_PAGE_PORT", "3842");
+            }
+            eprintln!("[bridge-shim] agent browser control ENABLED via opt-in marker");
+        }
+        None => eprintln!("[bridge-shim] opt-in marker present but content.js not found — bridge stays off"),
+    }
+}
+
 pub fn init(app: AppHandle) {
     let js_path = match std::env::var("APPWRAP_BRIDGE_JS") {
         Ok(p) if !p.is_empty() => p,

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

@@ -365,6 +365,25 @@ fn handle(method: &str, params: &Value) -> HandlerResult {
             spawn_reaped(cmd)?;
             Ok(json!({ "ok": true }))
         }
+        // Persist the agent-browser-control opt-in (the security gate for the bridge control channel).
+        // Writes/removes the marker `bridge_mac::resolve_gate` reads at launch; takes effect on the
+        // next relaunch (the bridge env is read once at startup), so signal `requiresRelaunch`.
+        "app.setAgentBrowserControl" => {
+            let enabled = params["enabled"].as_bool().unwrap_or(false);
+            #[cfg(target_os = "macos")]
+            {
+                let path = agent_browser_control_marker();
+                if enabled {
+                    if let Some(parent) = path.parent() {
+                        std::fs::create_dir_all(parent).map_err(|e| ("NATIVE_ERROR", e.to_string()))?;
+                    }
+                    std::fs::write(&path, b"1").map_err(|e| ("NATIVE_ERROR", e.to_string()))?;
+                } else if path.exists() {
+                    std::fs::remove_file(&path).map_err(|e| ("NATIVE_ERROR", e.to_string()))?;
+                }
+            }
+            Ok(json!({ "ok": true, "enabled": enabled, "requiresRelaunch": true }))
+        }
         "network.status" => Ok(json!({ "online": true, "type": "wifi" })),
         "ui.safeArea" => Ok(json!({ "top": 0, "right": 0, "bottom": 0, "left": 0 })),
         "ui.alert" | "ui.confirm" => {
@@ -533,6 +552,17 @@ fn browser_window_handle(method: &str, params: &Value) -> HandlerResult {
     }
 }
 
+/// Opt-in marker for the agent-browser-control bridge gate: ~/Library/Application
+/// Support/<identifier>/agent-browser-control.enabled. Presence = enabled (read by
+/// bridge_mac::resolve_gate at launch; written/removed by `app.setAgentBrowserControl`).
+fn agent_browser_control_marker() -> std::path::PathBuf {
+    let home = std::env::var("HOME").unwrap_or_default();
+    std::path::Path::new(&home)
+        .join("Library/Application Support")
+        .join(&shell().identifier)
+        .join("agent-browser-control.enabled")
+}
+
 /// Persisted-store file: ~/Library/Application Support/<identifier>/storage.json (macOS app-data dir).
 fn storage_path() -> std::path::PathBuf {
     let home = std::env::var("HOME").unwrap_or_default();
@@ -965,6 +995,12 @@ fn main() {
                 });
             }
             // SPIKE: browser-bridge window-ops backend — inert unless APPWRAP_BRIDGE_JS is set.
+            // resolve_gate() first populates the bridge env from the persisted opt-in marker (an app's
+            // "agent browser control" toggle writes it via `app.setAgentBrowserControl`), so the
+            // channel comes up only when the user opted in; no marker → env stays unset → init()
+            // returns early (fully inert).
+            #[cfg(target_os = "macos")]
+            bridge_mac::resolve_gate(&agent_browser_control_marker());
             #[cfg(target_os = "macos")]
             bridge_mac::init(app.handle().clone());
             // Per-app custom handlers: spawn the Bun sidecar when configured (absolute path stamped by

package/src/cli.ts

@@ -11,8 +11,9 @@
 import { execFileSync, spawn } from 'child_process';
 import { createHash } from 'crypto';
 import { copyFileSync, cpSync, existsSync, mkdirSync, openSync, closeSync, readdirSync, readFileSync, readSync, rmSync, statSync, writeFileSync, writeSync } from 'fs';
+import { builtinModules } from 'module';
 import { networkInterfaces, tmpdir } from 'os';
-import { delimiter as pathDelimiter, dirname, join, resolve } from 'path';
+import { delimiter as pathDelimiter, dirname, extname, join, resolve } from 'path';
 import { pathToFileURL } from 'url';
 // PURE-DATA capability manifest (no NativeScript globals) — type-only import (erased at runtime);
 // the VALUES are loaded dynamically below from the resolved runtime so the CLI works both in the
@@ -247,6 +248,127 @@ function generateModuleArtifacts(outDir: string, req: NativeReqs): void {
   );
 }
 
+/** Make `cfg.plugins` LIVE for the MOBILE (NativeScript) shell — the in-process analog of the desktop
+ * `regeneratePlugins`. There is no separate host on mobile (one WebView, the NS runtime IS the trusted
+ * host), so a plugin's `handlers` register directly on the bridge at boot. For each configured plugin:
+ * resolve the entry (path or npm), bun-build it to a single ESM bundle under
+ * `native/app/shell/plugins/<id>.js` (definePlugin inlined; @nativescript/core externalized), emit a
+ * typed `.d.ts` shim so the barrel type-checks, and generate `app/shell/plugins.generated.ts` that
+ * imports + registers each. No plugins → rewrite the barrel to the committed no-op default and drop the
+ * plugins dir, so a non-plugin build compiles NO plugin glue (parity with the module barrels).
+ *
+ * SKELETON scope: only `handlers` are consumed on mobile. `attachTo`/`onWindow`/`WindowCtx` are
+ * desktop-only; a plugin declaring them still builds here (those fields are ignored).
+ *
+ * CROSS-LANE SKIP: a plugin that fails to resolve OR that pulls in a Node.js CORE module
+ * (`net`/`fs`/`child_process`/…, unavailable in the NativeScript runtime) is skipped with a warning,
+ * so a shared `plugins:[]` list genuinely builds on both lanes. The build alone is NOT enough to
+ * decide this: `bun build --target=node` treats node builtins as valid passthrough externals, so a
+ * desktop-only plugin importing `net` builds successfully and the incompatible `import "net"` lands
+ * in the emitted bundle — which then breaks the NS webpack build. We therefore SCAN the plugin's
+ * authored SOURCE for node-builtin imports/requires and skip on a hit (deterministic across import
+ * styles). We scan the source (not the emitted bundle) on purpose: a raw-text/bundle scan false-
+ * positives on (a) builtin specifiers that appear inside STRING LITERALS in a handler body, and (b)
+ * bun's own `import { createRequire } from "node:module"` interop shim, which it injects into the
+ * bundle for ANY CJS plugin — even one that only `require()`s the documented external
+ * `@nativescript/core`. The source reflects the author's real imports; bun's shims do not.
+ * KNOWN LIMITATION: only the ENTRY's own imports are scanned — a builtin pulled in TRANSITIVELY via a
+ * dependency slips through and fails the NS webpack build later (loud, not silent). Acceptable at this
+ * stage: it degrades in the right direction (a rare, self-announcing build error) vs the silent-drop a
+ * bundle scan caused, and such a plugin is desktop-only by construction. Revisit with a resolve-graph
+ * walk if transitive desktop deps become common. */
+/** Node.js core module names (bare + `node:` forms) — anything here is unavailable in the NS runtime. */
+const NODE_BUILTIN_SET = new Set(builtinModules.flatMap((m) => [m, `node:${m}`]));
+
+/** The distinct Node.js core modules a plugin's SOURCE actually imports/requires. Uses
+ * `Bun.Transpiler.scanImports`, which returns only real import/require STATEMENTS (never a specifier
+ * that merely appears inside a string literal), so a handler body containing `"x from 'fs'"` is not
+ * flagged. Subpaths like `fs/promises` and the `node:` prefix are normalised to the base module
+ * before the membership test. `loader` matches the source dialect (ts/tsx/js/jsx). */
+function nodeBuiltinImports(src: string, loader: 'ts' | 'tsx' | 'js' | 'jsx'): string[] {
+  const hits = new Set<string>();
+  for (const { path } of new Bun.Transpiler({ loader }).scanImports(src)) {
+    const base = path.replace(/^node:/, '').split('/')[0];
+    if (NODE_BUILTIN_SET.has(path) || NODE_BUILTIN_SET.has(base)) hits.add(path);
+  }
+  return [...hits];
+}
+
+/** Map a plugin entrypoint's extension to the Bun.Transpiler loader for its source dialect. */
+function loaderForEntry(entrypoint: string): 'ts' | 'tsx' | 'js' | 'jsx' {
+  const ext = extname(entrypoint).toLowerCase();
+  if (ext === '.tsx') return 'tsx';
+  if (ext === '.jsx') return 'jsx';
+  if (ext === '.ts' || ext === '.mts' || ext === '.cts') return 'ts';
+  return 'js';
+}
+
+export function regenerateMobilePlugins(cwd: string, cfg: AppwrapConfig, outDir: string): void {
+  const shellDir = join(outDir, 'app/shell');
+  const pluginsDir = join(shellDir, 'plugins');
+  // Start clean: stale bundles from a previous config must not linger in the disposable native/.
+  rmSync(pluginsDir, { recursive: true, force: true });
+
+  const barrelPath = join(shellDir, 'plugins.generated.ts');
+  const header = `/** Generated by \`appwrap\` from the appwrap config \`plugins\`. Do not edit. */\n`;
+  const writeNoop = () => writeFileSync(barrelPath, `${header}export function registerPlugins(): void {\n}\n`);
+
+  const entries = cfg.plugins ?? [];
+  if (entries.length === 0) { writeNoop(); return; }
+
+  mkdirSync(pluginsDir, { recursive: true });
+  const bun = process.execPath; // the CLI runs under bun → the exact runtime to build with
+  const imports: string[] = [];
+  const calls: string[] = [];
+  let idx = 0;
+  for (const raw of entries) {
+    const name = typeof raw === 'string' ? raw : raw.name;
+    // 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(`⚠ mobile 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 outfile = join(pluginsDir, `${bundleId}.js`);
+    // Cross-lane guard: a desktop-only plugin (importing net/fs/child_process/…) BUILDS fine here — node
+    // builtins pass through as valid externals — so scan the plugin's SOURCE for real builtin imports and
+    // skip on a hit, BEFORE building (no point bundling a plugin we'll drop).
+    const nodeBuiltins = nodeBuiltinImports(readFileSync(entrypoint, 'utf8'), loaderForEntry(entrypoint));
+    if (nodeBuiltins.length) {
+      console.warn(`⚠ mobile plugin "${name}" imports Node.js core module(s) [${nodeBuiltins.join(', ')}] unavailable in the NativeScript runtime (desktop-only plugin on the mobile lane) — skipping.`);
+      continue;
+    }
+    try {
+      // ESM single-file so NS webpack bundles it; @nativescript/core stays external (provided by the shell).
+      execFileSync(bun, ['build', entrypoint, '--format=esm', '--target=node', '--external=@nativescript/core', '--outfile', outfile], { stdio: 'pipe' });
+    } catch (e: unknown) {
+      console.warn(`⚠ mobile plugin bun-build failed (${name}): ${e instanceof Error ? e.message : String(e)} — skipping.`);
+      continue;
+    }
+    // Typed shim so the generated barrel resolves the JS bundle's default export under tsc.
+    writeFileSync(
+      join(pluginsDir, `${bundleId}.d.ts`),
+      `import type { MobilePluginDef } from '../plugin-host';\ndeclare const plugin: MobilePluginDef;\nexport default plugin;\n`
+    );
+    const ident = `plugin_${idx++}`;
+    imports.push(`import ${ident} from './plugins/${bundleId}.js';`);
+    calls.push(`  registerPluginHandlers(${ident});`);
+    console.log(`  plugin ← ${name}  (mobile: handlers)`);
+  }
+
+  if (imports.length === 0) { writeNoop(); return; }
+  writeFileSync(
+    barrelPath,
+    `${header}import { registerPluginHandlers } from './plugin-host';\n${imports.join('\n')}\n\n` +
+      `export function registerPlugins(): void {\n${calls.join('\n')}\n}\n`
+  );
+}
+
 /** Stamp the active modules' gradle dependencies into Android app.gradle. Idempotent marker block. */
 function stampAndroidGradleDeps(outDir: string, deps: string[]): void {
   const appGradle = join(outDir, 'App_Resources/Android/app.gradle');
@@ -482,6 +604,14 @@ async function loadConfig(cwd: string, flags: Record<string, string>): Promise<A
 }
 
 function stampShellConfig(outDir: string, cfg: AppwrapConfig): void {
+  // Resolve the env-switcher block. Absent block OR `enabled:false` → the whole feature is inert
+  // (the shell reads `envSwitcher.enabled`). `allowPattern`/`envs` default to empty (default-deny).
+  const es = cfg.envSwitcher;
+  const envSwitcher = {
+    enabled: !!es && es.enabled !== false,
+    envs: (es?.envs ?? []).map((e) => ({ label: String(e.label), url: String(e.url) })),
+    allowPattern: es?.allowPattern ?? '',
+  };
   const content = `/**
  * Shell config — stamped by \`appwrap init\`/\`sync\` from the appwrap config. Do not edit.
  */
@@ -508,6 +638,7 @@ export const SHELL_CONFIG = {
   pushAndroid: ${JSON.stringify(!!cfg.push?.enabled && cfg.push?.android !== false)},
   pushRegistrationUrl: ${JSON.stringify(cfg.push?.registrationUrl ?? '')},
   iosKeyboardExtraLift: ${JSON.stringify(cfg.iosKeyboardExtraLift ?? 82)},
+  envSwitcher: ${JSON.stringify(envSwitcher)} as { enabled: boolean; envs: { label: string; url: string }[]; allowPattern: string },
 };
 `;
   writeFileSync(join(outDir, 'app/shell/config.ts'), content);
@@ -1712,6 +1843,7 @@ function regenerateCore(cwd: string, outDir: string, cfg: AppwrapConfig, opts: {
   stampAndroidGradleDeps(outDir, req.androidGradleDeps);
   stampKotlin(outDir, req.androidKotlin);
   generateModuleArtifacts(outDir, req);
+  regenerateMobilePlugins(cwd, cfg, outDir); // config-gated TS plugins → bridge handlers (in-process)
   copyModuleNativeSrc(outDir, req); // module-owned native source (e.g. health's Kotlin shim)
   substituteModuleTokens(outDir, req); // stamp __APP_GROUP__ etc. into the copied extension source
   stampLaunchScreen(outDir, cfg);

package/src/config.ts

@@ -17,6 +17,29 @@
  * JSON still supported as a fallback). See `loadConfig` in cli.ts.
  */
 
+/** A single named environment shown in the switcher menu. */
+export interface EnvSwitcherEnv {
+  /** Human label shown in the menu + banner (e.g. 'Prod', 'Lab', 'PR #123'). */
+  label: string;
+  /** Absolute origin the WebView loads for this env (e.g. 'https://lab.example.com'). */
+  url: string;
+}
+
+/** Runtime env-switcher config (see `AppwrapConfig.envSwitcher`). */
+export interface EnvSwitcherConfig {
+  /** Kill-switch. Omitted → ON when the block is present. A prod config fork can set `false` to
+   * HARD-DISABLE the whole feature (menu action + banner + boot override all inert) even if `envs` /
+   * `allowPattern` are declared. Absent `envSwitcher` block entirely → also off (default for any app). */
+  enabled?: boolean;
+  /** Presets shown in the switch menu; always implicitly trusted (bypass `allowPattern`). */
+  envs?: EnvSwitcherEnv[];
+  /** Anchored regex (`^…$`) gating the free-form "Other" URL entry. DEFAULT-DENY: absent/invalid →
+   * "Other" is disabled (presets only). Compiled with try/catch; a throwing pattern → default-deny. */
+  allowPattern?: string;
+  /** Deeplink auto-switch (Phase 2 — not yet implemented). Opt-in. */
+  deeplink?: boolean;
+}
+
 export interface AppwrapConfig {
   id: string;
   name: string;
@@ -168,6 +191,13 @@ export interface AppwrapConfig {
   loader?: 'app' | 'file' | 'server';
   /** Live URL loaded when loader === 'server'. Set via config or `appwrap dev --url <url>`. */
   serverUrl?: string;
+  /** Runtime env-switcher (loader:'server' apps). Lets a build re-point the WebView between declared
+   * environments (prod / lab / a preview URL) at runtime — via the native dev-menu "Switch Environment"
+   * action + a bottom env-indicator banner — surviving a cold start, with NO separate native build.
+   * The chosen URL persists in native storage (`kit:serverUrlOverride`) and is honored by the shell's
+   * boot loader. Runs in ALL build types when configured (gate = `allowPattern` + `enabled`, NOT debug —
+   * distinct from the debug-only dev-server cert trust). Absent block → the whole feature is inert. */
+  envSwitcher?: EnvSwitcherConfig;
   /** Absolute backend origin for an offline (loader:'app') PWA whose API/WebSocket calls were
    * originally same-origin (e.g. "https://api.example.com"). Injected to the page as
    * `window.__APPWRAP_BACKEND_ORIGIN__`; a same-origin PWA reads it to make its calls absolute.
@@ -337,7 +367,7 @@ export function defineConfig(config: AppwrapConfig): AppwrapConfig {
 export const KNOWN_CONFIG_KEYS: ReadonlySet<string> = new Set([
   'androidAppLinks', 'appBoundDomains', 'backendOrigin', 'backgroundAudio', 'backgroundColor', 'backgroundTasks', 'buildNumber', 'debug',
   'debugLog', 'desktop', 'devMenu', 'edgeToEdge', 'entry', 'icon', 'id', 'iosKeyboardExtraLift', 'loader', 'modules', 'name',
-  'iosEntitlements', 'neutralizeServiceWorker', 'oauthRedirectSchemes', 'openNewWindowsInBrowser', 'orientation', 'overrides', 'permissions',
+  'envSwitcher', 'iosEntitlements', 'neutralizeServiceWorker', 'oauthRedirectSchemes', 'openNewWindowsInBrowser', 'orientation', 'overrides', 'permissions',
   'plugins', 'push', 'pwaDist', 'queryPackages', 'queryUrlSchemes', 'serverUrl', 'signing', 'signingProfiles', 'statusBarStyle',
   'splashIcon', 'storekitConfig', 'targetedDevices', 'teamId', 'themeColor', 'trackingDomains', 'urlScheme',
   'usesNonExemptEncryption', 'vendorPaths', 'version',