@livx.cc/appwrap 0.48.1 → 0.49.0

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-android.ts

@@ -365,6 +365,44 @@ export function registerAndroidHandlers(): void {
     motionListener = null;
   });
 
+  // ── heading (SensorManager: rotation vector → compass azimuth) ─────
+  // TYPE_ROTATION_VECTOR fuses accelerometer+magnetometer(+gyro) into an orientation; getOrientation
+  // gives azimuth (rad, counter-clockwise from north), which we convert to a 0–360 compass heading.
+  // UNVERIFIED-ON-DEVICE.
+  let headingListener: android.hardware.SensorEventListener | null = null;
+
+  bridge.register('heading.start', (p: { hz?: number } = {}) => {
+    if (headingListener) return; // already streaming
+    const hz = Math.max(1, Math.min(60, p.hz || 10));
+    const minMs = 1000 / hz;
+    const sm = sensorManager();
+    const rot = sm.getDefaultSensor(android.hardware.Sensor.TYPE_ROTATION_VECTOR);
+    if (!rot) throw err('UNSUPPORTED', 'No rotation-vector sensor (compass) on this device');
+    const R = Array.create('float', 9);
+    const orientation = Array.create('float', 3);
+    let last = 0;
+    headingListener = new android.hardware.SensorEventListener({
+      onAccuracyChanged() {},
+      onSensorChanged(event: android.hardware.SensorEvent) {
+        const now = java.lang.System.currentTimeMillis();
+        if (now - last < minMs) return; // throttle emit to the requested Hz
+        last = now;
+        android.hardware.SensorManager.getRotationMatrixFromVector(R, event.values);
+        android.hardware.SensorManager.getOrientation(R, orientation);
+        // orientation[0] = azimuth in rad (−π..π), CCW from north. Convert to 0–360 compass degrees.
+        const deg = ((orientation[0] * 180) / Math.PI + 360) % 360;
+        bridge.emit('heading.data', { deg });
+      },
+    });
+    const periodUs = Math.max(5000, Math.round(1_000_000 / hz));
+    sm.registerListener(headingListener, rot, periodUs);
+  });
+
+  bridge.register('heading.stop', () => {
+    if (headingListener) sensorManager().unregisterListener(headingListener);
+    headingListener = null;
+  });
+
   // ── contacts (ACTION_PICK + ContactsContract query) ────────────────
   bridge.register('contacts.pick', async () => {
     if (!(await requestPermissions(['android.permission.READ_CONTACTS']))) {

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/handlers-parity.ts

@@ -24,7 +24,7 @@ function readContact(contact: CNContact): { name: string; phones: string[]; emai
 // shared module can instantiate on Android — NSObject/CL*/CN*/UIImagePicker* are iOS globals, and a
 // top-level `extends NSObject` would evaluate at ES-module load and crash the Android shell.
 // any: module-level holders for runtime-built ObjC subclasses; each class BODY stays fully typed.
-let GeoWatchDelegate: any, ContactPickerDelegate: any, CameraCaptureDelegate: any;
+let GeoWatchDelegate: any, HeadingDelegate: any, ContactPickerDelegate: any, CameraCaptureDelegate: any;
 function ensureIosDelegates(): void {
   if (!isIOS || GeoWatchDelegate) return;
 
@@ -58,6 +58,30 @@ function ensureIosDelegates(): void {
   }
   GeoWatchDelegate = GeoWatchDelegateImpl;
 
+  // CLLocationManager delegate for the compass heading stream (heading.watch). Emits a 0–360
+  // compass heading; prefers trueHeading (needs location auth) and falls back to magneticHeading.
+  // UNVERIFIED-ON-DEVICE.
+  @NativeClass()
+  class HeadingDelegateImpl extends NSObject implements CLLocationManagerDelegate {
+    static ObjCProtocols = [CLLocationManagerDelegate];
+    static new(): HeadingDelegateImpl {
+      return <HeadingDelegateImpl>super.new();
+    }
+    locationManagerDidUpdateHeading(_m: CLLocationManager, heading: CLHeading): void {
+      // trueHeading is negative when unavailable (no location auth / no recent fix) — magneticHeading
+      // is always valid once the magnetometer is calibrated.
+      const deg = heading.trueHeading >= 0 ? heading.trueHeading : heading.magneticHeading;
+      bridge.emit('heading.data', {
+        deg: ((deg % 360) + 360) % 360,
+        accuracy: heading.headingAccuracy >= 0 ? heading.headingAccuracy : undefined,
+      });
+    }
+    locationManagerDidFailWithError(_m: CLLocationManager, error: NSError): void {
+      console.warn('AppWrap: heading.watch error', error.localizedDescription);
+    }
+  }
+  HeadingDelegate = HeadingDelegateImpl;
+
   // CNContactPickerViewController delegate. The picker resolution callbacks are set as instance fields
   // after construction (replacing the old closure-captured `resolve`).
   @NativeClass()
@@ -220,6 +244,36 @@ export function registerParityHandlers(): void {
     motionManager = null;
   });
 
+  // ── heading (CLLocationManager compass) ────────────────────────────
+  // Compass heading via CLLocationManager.startUpdatingHeading (delegate-pushed, not polled — the
+  // heading callback is reliable, unlike CoreMotion's block). UNVERIFIED-ON-DEVICE.
+  let headingManager: CLLocationManager | null = null;
+  let headingDelegate: any = null;
+
+  bridge.register('heading.start', () => {
+    if (!isIOS) throw iosOnly();
+    if (headingManager) return; // already streaming
+    Utils.dispatchToMainThread(() => {
+      const mm = CLLocationManager.new();
+      if (!CLLocationManager.headingAvailable()) throw err('UNSUPPORTED', 'No compass on this device');
+      headingManager = mm;
+      headingDelegate = HeadingDelegate.new();
+      mm.delegate = headingDelegate;
+      mm.headingFilter = 1; // emit on ≥1° change
+      // trueHeading requires location auth; request it so we can report true (not just magnetic) north.
+      if (mm.authorizationStatus === CLAuthorizationStatus.kCLAuthorizationStatusNotDetermined) {
+        mm.requestWhenInUseAuthorization();
+      }
+      mm.startUpdatingHeading();
+    });
+  });
+
+  bridge.register('heading.stop', () => {
+    headingManager?.stopUpdatingHeading();
+    headingManager = null;
+    headingDelegate = null;
+  });
+
   // ── contacts (CNContactPickerViewController — no permission needed) ──
   bridge.register('contacts.pick', () => {
     if (!isIOS) throw iosOnly();

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