@livx.cc/appwrap 0.48.1 → 0.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.48.1",
+  "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/capabilities.manifest.ts

@@ -98,6 +98,16 @@ export const MODULES: ModuleManifest[] = [
     ios: { permissions: [{ key: 'NSLocationWhenInUseUsageDescription', domain: 'location', defaultUsage: 'Show your location.' }] },
     android: { permissions: ['android.permission.ACCESS_FINE_LOCATION', 'android.permission.ACCESS_COARSE_LOCATION'] },
   },
+  // heading (compass) — handlers live in the always-bundled parity/android groups (registerParity/
+  // AndroidHandlers). iOS CLHeading via CLLocationManager: trueHeading needs location auth, so it rides
+  // geo's SAME NSLocationWhenInUseUsageDescription (the CLI dedups when geo is also active; declared here
+  // for self-containment so a heading-only app still stamps it). Android uses TYPE_ROTATION_VECTOR — a
+  // motion sensor that needs NO runtime permission, so no android block (avoid an unused-permission flag).
+  {
+    name: 'heading', group: 'parity',
+    capabilities: { heading: 'native' },
+    ios: { permissions: [{ key: 'NSLocationWhenInUseUsageDescription', domain: 'location', defaultUsage: 'Show your compass heading.' }] },
+  },
   {
     name: 'photos', group: 'extended',
     capabilities: { photos: 'native' },
@@ -308,39 +318,11 @@ export const MODULES: ModuleManifest[] = [
   },
 
   // ── widget — home-screen presence via a native extension (iOS WidgetKit / Android AppWidget) ──
-  // Opt-in; ships its own extension target under modules-native/widget/. The host publishes tiles into
-  // an App Group container the extension reads at render; each tile deep-links back on tap. The App
-  // Group entitlement is app-specific (group.<appId>), so consumers supply it via appwrap.config
-  // `iosEntitlements` for now (Phase-2 templates `group.$APPID` in the CLI). Phase-1 spike ships a
-  // single static tile to prove the extension builds, provisions the group, renders, and deep-links.
-  {
-    name: 'widget', group: 'widget',
-    capabilities: { widget: { ios: true, android: true } },
-    // Android launcher widget = an AppWidgetProvider receiver (icon-grid) fed by the widget.publish
-    // handler via SharedPreferences; Kotlin source + res ship as nativeSrc. iOS side = the WidgetKit
-    // extension under nativeSrc's App_Resources/iOS/extensions/.
-    android: {
-      kotlin: true,
-      manifestApplication: `<receiver
-      android:name="cc.livx.appwrap.AppwrapWidgetProvider"
-      android:exported="true">
-      <intent-filter>
-        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
-      </intent-filter>
-      <meta-data
-        android:name="android.appwidget.provider"
-        android:resource="@xml/appwrap_widget_info" />
-    </receiver>`,
-    },
-    nativeSrc: 'widget',
-  },
-
-  // ── widget — home-screen presence via a native extension (iOS WidgetKit / Android AppWidget) ──
-  // Opt-in; ships its own extension target under modules-native/widget/. The host publishes tiles into
-  // an App Group container the extension reads at render; each tile deep-links back on tap. The App
-  // Group entitlement is app-specific (group.<appId>), so consumers supply it via appwrap.config
-  // `iosEntitlements` for now (Phase-2 templates `group.$APPID` in the CLI). Phase-1 spike ships a
-  // single static tile to prove the extension builds, provisions the group, renders, and deep-links.
+  // Opt-in; ships its own native surfaces under modules-native/widget/. The app publishes tiles/stats
+  // into a shared container (App Group on iOS, SharedPreferences on Android) via the `widget.publish`
+  // handler; the extension/provider reads it at render and each tile deep-links back on tap. Two kinds:
+  // a `launcher` icon-grid (the host's pinned apps) and a `data` widget (a mini-app's live stat/list).
+  // The App Group id is derived (`group.<appId>`) and templated into both targets by the CLI.
   {
     name: 'widget', group: 'widget',
     capabilities: { widget: { ios: true, android: true } },

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();
+}