@livx.cc/appwrap 0.48.2 → 0.50.0

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

@@ -0,0 +1,229 @@
+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;
+  }
+}
+
+// ── Deep-link entry (`<scheme>://env?url=<encoded-url>`) ──────────────────────────────────────────
+// A PR-preview link can be SHARED and auto-open the app on that env. Same security model as "Other":
+// the decoded target must pass `isUrlAllowed` (anchored allowPattern, default-deny) and a confirm
+// prompt, then applies via the EXACT SAME `applySwitch` path as a manual switch. events.ts owns the
+// WebView-ready timing (warm: now; cold launch: buffered, replayed after the PWA handshake).
+
+export type EnvDeepLinkDecision =
+  | { action: 'switch'; url: string }
+  | { action: 'rejected'; url: string }
+  | { action: 'ignored' };
+
+/** Decode the `url` query param from a `<scheme>://env?url=<encoded>` link. Null if absent/undecodable. */
+function parseEnvTargetUrl(link: string): string | null {
+  const q = String(link || '').indexOf('?');
+  if (q < 0) return null;
+  for (const part of link.slice(q + 1).split('&')) {
+    const eq = part.indexOf('=');
+    if ((eq < 0 ? part : part.slice(0, eq)) !== 'url') continue;
+    try {
+      const decoded = decodeURIComponent((eq < 0 ? '' : part.slice(eq + 1)).replace(/\+/g, '%20')).trim();
+      return decoded || null;
+    } catch {
+      return null; // malformed percent-encoding
+    }
+  }
+  return null;
+}
+
+/** Structurally an env-switch deep link (`<scheme>://env…`) AND the switcher is enabled — the signal
+ * events.ts uses to CONSUME the link (never forward an env link to the PWA). Inert (false) when the
+ * feature is disabled/absent, so such a link simply falls through to the normal PWA deep-link path. */
+export function isEnvDeepLink(link: string): boolean {
+  return isEnvSwitcherEnabled() && hostOf(link) === 'env';
+}
+
+/**
+ * PURE decision for an inbound `<scheme>://env?url=…` deep link — no dialogs, no side effects (unit-
+ * testable, mirrors env-switcher-security.test.ts). SECURITY: the decoded target MUST pass the SAME
+ * `isUrlAllowed` gate as the "Other" custom URL (anchored allowPattern, default-deny). Disabled feature
+ * / non-env link / malformed (no decodable `url`) → `ignored` (silently dropped); target present but not
+ * allowlisted → `rejected` (NEVER switch); allowlisted → `switch`.
+ */
+export function decideEnvDeepLink(link: string): EnvDeepLinkDecision {
+  if (!isEnvSwitcherEnabled() || hostOf(link) !== 'env') return { action: 'ignored' };
+  const target = parseEnvTargetUrl(link);
+  if (!target) return { action: 'ignored' };
+  if (!isUrlAllowed(target)) return { action: 'rejected', url: target };
+  return { action: 'switch', url: target };
+}
+
+/**
+ * Handle an env-switch deep link end-to-end: confirm + apply via the SAME `applySwitch` path as a manual
+ * switch (persist override → reload the WebView → refresh the banner, incl. the host-equals-default →
+ * RESET semantics). A disallowed target shows a brief alert and NEVER switches; a malformed/disabled link
+ * is ignored silently. Callers gate the WebView-ready timing (warm now / cold at handshake).
+ */
+export async function handleEnvDeepLink(link: string): Promise<void> {
+  const decision = decideEnvDeepLink(link);
+  if (decision.action === 'switch') {
+    const preset = (SHELL_CONFIG.envSwitcher?.envs ?? []).find((e) => e.url === decision.url);
+    await applySwitch(decision.url, preset ? preset.label : 'Shared link');
+  } else if (decision.action === 'rejected') {
+    await Dialogs.alert({ title: 'Not allowed', message: 'That environment link is not allowed for this app.', okButtonText: 'OK' });
+  }
+}
+
+/** 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/events.ts

@@ -2,8 +2,13 @@ import { Application, Connectivity, isAndroid } from '@nativescript/core';
 import type { AndroidActivityNewIntentEventData, OrientationChangedEventData } from '@nativescript/core';
 import { bridge } from './bridge';
 import { connectivityStatus } from './handlers-extended';
+import { isEnvDeepLink, handleEnvDeepLink } from './env-switcher';
 
 let pendingDeepLink: string | null = null;
+// A cold-launch env-switch deep link (`<scheme>://env?url=…`). Buffered like `pendingDeepLink` until the
+// PWA handshake, so the confirm dialog + WebView reload run when the shell is actually ready (not during
+// iOS didFinishLaunching / the Android launch-intent read, when no WebView exists yet).
+let pendingEnvDeepLink: string | null = null;
 let pendingPushTap: { data: Record<string, string> } | null = null;
 let pendingShortcut: string | null = null;
 // True only once the PWA's JS has handshaked — i.e. the WebView is actually
@@ -25,6 +30,14 @@ export function onDeepLink(url: string): void {
   // Give a native consumer (OAuth callback) first refusal — a matched OAuth redirect is internal
   // plumbing, not an app deep link, so it's swallowed here and never forwarded to the PWA.
   if (deepLinkInterceptor?.(url)) return;
+  // Env-switch deep link (config-gated): a shared PR-preview link that re-points the shell. CONSUMED
+  // here — never forwarded to the PWA (it's a shell command, not an app route). The allowlist + confirm
+  // gate lives in handleEnvDeepLink; disabled/absent switcher → isEnvDeepLink is false → normal path.
+  if (isEnvDeepLink(url)) {
+    if (pwaReady) void handleEnvDeepLink(url);
+    else pendingEnvDeepLink = url; // cold launch — replay after the handshake, when the WebView is ready
+    return;
+  }
   if (pwaReady) bridge.emit('deeplink.open', { url });
   else pendingDeepLink = url; // buffer until the PWA handshakes — delivered IN the handshake response
 }
@@ -77,6 +90,12 @@ export function onPwaHandshake(): void {
     pendingShortcut = null;
     setTimeout(() => bridge.emit('app.shortcut', { id }), 500);
   }
+  if (pendingEnvDeepLink) {
+    const link = pendingEnvDeepLink;
+    pendingEnvDeepLink = null;
+    // Small beat so the just-handshaked WebView is fully attached before the confirm/reload.
+    setTimeout(() => void handleEnvDeepLink(link), 500);
+  }
 }
 
 /** Wire lifecycle + connectivity event forwarding (the PWA subscribes to these). */

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