@livx.cc/appwrap 0.51.1 → 0.51.3

package/package.json

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

package/runtime/app/shell/bridge.ts

@@ -56,6 +56,18 @@ export class Bridge {
     this.deliver(JSON.stringify({ v: 1, kind: 'event', event, payload }));
   }
 
+  /** Response-delivery retry cadence. iOS THROTTLES/freezes the WebContent renderer for ~30-45s while
+   * a native surface (permission alert, sheet, picker) sits over the WebView — `evaluateJavaScript`
+   * simply never runs — so we keep re-offering the response until the renderer wakes. The window is
+   * deliberately just under native-kit's 60s invoke watchdog: landing a real answer at 50s still beats
+   * the bogus TIMEOUT, and past that the caller has already given up. Static so tests can shrink them. */
+  static responseRetryMs = 2_000;
+  static responseRetryWindowMs = 50_000;
+  /** Per-ATTEMPT cap. A throttled WKWebView does not necessarily fail the eval — its completion
+   * handler may simply never fire, leaving the promise pending forever. Without this, a frozen
+   * renderer would silently stall the retry loop and we would be back to the 60s lie. */
+  static responseAttemptTimeoutMs = 3_000;
+
   private async onMessage(json: string): Promise<void> {
     let req: RequestEnvelope;
     try {
@@ -79,13 +91,60 @@ export class Bridge {
     }
   }
 
+  /**
+   * A response is the ONLY thing that settles the caller's promise. native-kit arms a per-invoke
+   * watchdog, so a response we fail to deliver does not surface as "delivery failed" — it surfaces to
+   * the USER as a bogus `<method> timed out after 60000ms`, i.e. a permission state or a real native
+   * error masquerading as a hang. That is exactly how geo.current's 15s `location timeout` became a
+   * silent 60s lie: the CoreLocation prompt froze the renderer, this eval no-op'd, and the old
+   * fire-and-forget `.catch(console.error)` swallowed it.
+   *
+   * So: retry until the renderer wakes, and if we truly give up, say so LOUDLY — never silently.
+   * Retry is RESPONSE-ONLY and safe: the adapter drops an id it has already settled (handleResponse
+   * `if (!p) return`), so a double-delivery is a no-op. Events are NOT idempotent → still one-shot.
+   */
   private respond(id: string, result?: unknown, error?: { code: string; message: string }): void {
-    this.deliver(JSON.stringify({ v: 1, id, kind: 'response', result, error }));
+    const json = JSON.stringify({ v: 1, id, kind: 'response', result, error });
+    void this.deliverResponse(json, id, error?.code);
+  }
+
+  private async deliverResponse(envelopeJson: string, id: string, code?: string): Promise<void> {
+    const deadline = Date.now() + Bridge.responseRetryWindowMs;
+    let attempt = 0;
+    let lastErr: unknown;
+    for (;;) {
+      try {
+        // Race the eval against a per-attempt cap: a frozen renderer may never call back at all.
+        await Promise.race([
+          this.deliverOnce(envelopeJson),
+          new Promise((_r, rej) =>
+            setTimeout(() => rej(new Error('eval did not complete (renderer throttled?)')),
+              Bridge.responseAttemptTimeoutMs)),
+        ]);
+        if (attempt > 0) console.log(`Bridge: response ${id} delivered after ${attempt} retries`);
+        return;
+      } catch (e) {
+        lastErr = e;
+        attempt++;
+        if (Date.now() + Bridge.responseRetryMs >= deadline) break;
+        await new Promise((r) => setTimeout(r, Bridge.responseRetryMs));
+      }
+    }
+    // Undeliverable. The caller WILL report a bogus timeout for this id — leave the real reason behind.
+    console.error(
+      `Bridge: response ${id}${code ? ` (${code})` : ''} UNDELIVERABLE after ${attempt} attempts ` +
+        `— the caller will report a false TIMEOUT. Last error:`,
+      lastErr
+    );
   }
 
   private deliver(envelopeJson: string): void {
+    this.deliverOnce(envelopeJson).catch((e) => console.error('Bridge: deliver failed', e));
+  }
+
+  private deliverOnce(envelopeJson: string): Promise<unknown> {
     const js = `window.__appwrapDeliver && window.__appwrapDeliver(${JSON.stringify(envelopeJson)})`;
-    this.evalJs(js).catch((e) => console.error('Bridge: deliver failed', e));
+    return this.evalJs(js);
   }
 
   /** Evaluate JS in the WebView and resolve its value (used by deliver + the dev-menu version probe). */

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

@@ -338,18 +338,18 @@ function createAssetServingClient(): android.webkit.WebViewClient {
   // In server mode (loader:'server') the page loads from a real https `serverUrl`: there are NO
   // https://appwrap.local requests and `backendOrigin` is same-origin, so the asset interceptor does
   // ZERO work — yet it is the ONLY off-main-thread callback, i.e. the only one exposed to that race.
-  // So OMIT it in server mode (the conditional spread expands to nothing): Android's default pure-Java
-  // interception runs, NS is never crossed into JS off-thread, and the crash is structurally impossible.
+  // So OMIT it in server mode (the server-mode literal below simply doesn't declare it): Android's default
+  // pure-Java interception runs, NS is never crossed into JS off-thread, and the crash is structurally
+  // impossible. This omission was originally written as a conditional spread — see the SBG warning below
+  // for why that shape silently broke the build and must not come back.
   // app/file loaders MUST serve bundled www/ assets, so they keep it (and retain the client for the
   // process lifetime — see CustomWebView.disposeNativeView — so a late in-flight call can't hit a dead peer).
   // NS runtime adds `.extend` on Java classes; it's not in the static typings, hence the cast.
-  assetClientClass = (android.webkit.WebViewClient as any).extend({
-    // Modern (API 21+) overload passes a WebResourceRequest; the legacy overload passed a string URL.
-    // We defensively handle both, so the param is the union.
-    ...(SHELL_CONFIG.loader === 'server' ? {} : { shouldInterceptRequest(
-      _view: android.webkit.WebView,
-      request: android.webkit.WebResourceRequest | string
-    ): android.webkit.WebResourceResponse | null {
+  // Modern (API 21+) overload passes a WebResourceRequest; the legacy overload passed a string URL.
+  // We defensively handle both, so the param is the union.
+  const interceptRequest = (
+    request: android.webkit.WebResourceRequest | string
+  ): android.webkit.WebResourceResponse | null => {
       const url: string = typeof request !== 'string' ? String(request.getUrl().toString()) : request;
       if (!url.startsWith(APP_ORIGIN)) return null; // external — let WebView handle it
 
@@ -378,16 +378,16 @@ function createAssetServingClient(): android.webkit.WebViewClient {
       return new android.webkit.WebResourceResponse(
         'text/plain', 'utf-8', 404, 'Not Found', new java.util.HashMap<string, string>(), emptyStream()
       );
-    } }),
+  };
 
-    // External URL schemes (mailto:/tel:/sms:/geo:/intent:/webcal:/market:/…) can't be rendered by the
-    // WebView — without this override it tries to LOAD them and dumps a full-page net::ERR_UNKNOWN_URL_SCHEME
-    // over the app. Hand every non-WebView scheme to the OS via ACTION_VIEW (intent: via parseUri) and
-    // return true so the WebView never navigates. http/https/file/about/blob/data/javascript stay in-WebView.
-    shouldOverrideUrlLoading(
-      view: android.webkit.WebView,
-      request: android.webkit.WebResourceRequest | string
-    ): boolean {
+  // External URL schemes (mailto:/tel:/sms:/geo:/intent:/webcal:/market:/…) can't be rendered by the
+  // WebView — without this override it tries to LOAD them and dumps a full-page net::ERR_UNKNOWN_URL_SCHEME
+  // over the app. Hand every non-WebView scheme to the OS via ACTION_VIEW (intent: via parseUri) and
+  // return true so the WebView never navigates. http/https/file/about/blob/data/javascript stay in-WebView.
+  const overrideUrlLoading = (
+    view: android.webkit.WebView,
+    request: android.webkit.WebResourceRequest | string
+  ): boolean => {
       const url: string = typeof request !== 'string' ? String(request.getUrl().toString()) : request;
       const scheme = (url.split(':')[0] || '').toLowerCase();
       if (['http', 'https', 'file', 'about', 'blob', 'data', 'javascript'].includes(scheme)) return false;
@@ -413,24 +413,23 @@ function createAssetServingClient(): android.webkit.WebViewClient {
         console.warn('[appwrap] no OS handler for external URL: ' + url + ' (' + e + ')');
       }
       return true;
-    },
+  };
 
-    onPageStarted(view: android.webkit.WebView, _url: string, _favicon: android.graphics.Bitmap): void {
+  const pageStarted = (view: android.webkit.WebView): void => {
       // Fallback injection — no-op when the document-start scripts already ran
       view.evaluateJavascript(buildBootstrapJs(), null as unknown as android.webkit.ValueCallback<string>);
-    },
+  };
 
-    // 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 {
+  // 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).
+  const receivedSslError = (
+    handler: android.webkit.SslErrorHandler,
+    error: android.net.http.SslError
+  ): void => {
       // 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.
       // Host WITHOUT port, mirroring the iOS DevCertNavDelegate (a dev server on :3000 and its HMR sub-
@@ -444,7 +443,48 @@ function createAssetServingClient(): android.webkit.WebViewClient {
       } else {
         handler.cancel();
       }
-    },
-  });
+  };
+
+  // TWO literals, selected by loader — NOT one literal with a conditional spread. Both the omission and
+  // this shape are load-bearing:
+  //   * The OMISSION (see the comment above) is what makes the off-thread race structurally impossible in
+  //     server mode. Do not "simplify" this to one literal that always defines shouldInterceptRequest and
+  //     early-returns null in server mode — the JS peer would still be crossed off-thread and the
+  //     `Cannot find runtime for instance` crash returns.
+  //   * The SHAPE must stay a spread-free object LITERAL of method shorthands. NativeScript's static
+  //     binding generator parses every `X.extend({...})` literal and reads `prop.key.name` for each
+  //     property: a SpreadElement has no `key`, so `...(cond ? {} : {...})` throws inside its js_parser,
+  //     which then ABANDONS THE WHOLE FILE and still exits 0 — silently dropping every @JavaProxy binding
+  //     declared later in the bundle (this cost us a FATAL `LookedUpClassNotFound:
+  //     cc.livx.appwrap.AppwrapMessagingService` boot crash that built green). For the same reason don't
+  //     hoist the object into a variable and pass `.extend(methods)`: SBG requires an ObjectExpression at
+  //     the call site and silently skips anything else. `appwrap doctor:bindings` (run by the android
+  //     build) now fails the build if a @JavaProxy ever loses its binding again.
+  assetClientClass = SHELL_CONFIG.loader === 'server'
+    ? (android.webkit.WebViewClient as any).extend({
+      shouldOverrideUrlLoading(view: android.webkit.WebView, request: android.webkit.WebResourceRequest | string): boolean {
+        return overrideUrlLoading(view, request);
+      },
+      onPageStarted(view: android.webkit.WebView, _url: string, _favicon: android.graphics.Bitmap): void {
+        pageStarted(view);
+      },
+      onReceivedSslError(_view: android.webkit.WebView, handler: android.webkit.SslErrorHandler, error: android.net.http.SslError): void {
+        receivedSslError(handler, error);
+      },
+    })
+    : (android.webkit.WebViewClient as any).extend({
+      shouldInterceptRequest(_view: android.webkit.WebView, request: android.webkit.WebResourceRequest | string): android.webkit.WebResourceResponse | null {
+        return interceptRequest(request);
+      },
+      shouldOverrideUrlLoading(view: android.webkit.WebView, request: android.webkit.WebResourceRequest | string): boolean {
+        return overrideUrlLoading(view, request);
+      },
+      onPageStarted(view: android.webkit.WebView, _url: string, _favicon: android.graphics.Bitmap): void {
+        pageStarted(view);
+      },
+      onReceivedSslError(_view: android.webkit.WebView, handler: android.webkit.SslErrorHandler, error: android.net.http.SslError): void {
+        receivedSslError(handler, error);
+      },
+    });
   return new assetClientClass();
 }

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

@@ -39,6 +39,12 @@ class AppwrapScriptHandler extends NSObject implements WKScriptMessageHandler {
     // Envelopes always travel as JSON strings (protocol v1)
     if (view?.onAppwrapMessage && typeof body === 'string') {
       view.onAppwrapMessage(body);
+    } else {
+      // Nothing to dispatch to (bridge detached / view gone) or a non-string body ⇒ this request is
+      // DROPPED and can never be answered — the caller's watchdog will report a false TIMEOUT for it.
+      // We cannot respond (there is no bridge here), so at least never drop it in silence.
+      appendWebLog('[native] appwrap request DROPPED (no bridge attached) — caller will see a false TIMEOUT');
+      console.error('AppWrap: request dropped — no bridge attached; caller will report a false TIMEOUT');
     }
   }
 }

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

@@ -236,14 +236,22 @@ export async function handleEnvDeepLink(link: string): Promise<void> {
   }
 }
 
-/** Free-form URL entry, gated by `allowPattern` (default-deny). Rejects a non-matching URL. */
+/** Free-form URL entry, gated by `allowPattern` (default-deny). Rejects a non-matching URL.
+ *
+ * The field is deliberately EMPTY — do NOT re-add a `defaultText: 'https://'` prefill. A URL is the one
+ * input class users always PASTE, and a copied URL already carries its own scheme, so a prefill breaks
+ * exactly the case this field exists for: iOS pastes at the caret (which sits AFTER the prefill), giving
+ * `https://https://host` → rejected by `allowPattern` as "Not allowed". Typing masks the bug (you type the
+ * host after the prefix), which is why it reads as "paste doesn't work". An empty field is also where iOS
+ * offers Paste most readily — long-pressing a NON-empty field raises the cursor loupe, not the edit menu.
+ * The `https://` hint lives in `message` instead, where it can't contaminate the value.
+ */
 async function promptOther(): Promise<void> {
   const res = await Dialogs.prompt({
     title: 'Custom environment',
-    message: 'Enter an allowed URL (https://…).',
+    message: 'Enter or paste an allowed URL (https://…).',
     okButtonText: 'Next',
     cancelButtonText: 'Cancel',
-    defaultText: 'https://',
     inputType: 'text',
   });
   if (!res?.result || !res.text) return;

package/runtime/app/shell/geo-auth.ts

@@ -0,0 +1,48 @@
+/**
+ * PURE CoreLocation authorization-status → action mapping (no NativeScript imports; bun-tested).
+ * Mirrors notif-identity.ts: the decision lives here so the permission semantics are verifiable
+ * off-device, and handlers-extended.ts only does the CoreLocation plumbing.
+ *
+ * WHY this exists: a permission state must NEVER surface to the user as a timeout. `denied` and
+ * `restricted` are TERMINAL answers we already know — they must reject INSTANTLY with a distinct
+ * code, not sit until some watchdog gives up and reports a hang.
+ */
+
+/** CLAuthorizationStatus raw values (stable ObjC enum; hardcoded so this module stays iOS-global-free). */
+export const CL_AUTH = {
+  notDetermined: 0,
+  restricted: 1,
+  denied: 2,
+  authorizedAlways: 3,
+  authorizedWhenInUse: 4,
+} as const;
+
+export type GeoAuthAction =
+  /** Terminal: reject now with this KitError code — no surface, no waiting. */
+  | { kind: 'reject'; code: 'DENIED' | 'RESTRICTED'; message: string }
+  /** Authorized: start locating. The caller arms its location timer HERE (not before). */
+  | { kind: 'start' }
+  /** Not yet asked: present the system prompt and WAIT for the decision. The caller must NOT arm a
+   * timer — the prompt is dismiss-bound (the user may take as long as they like) and, worse, iOS
+   * THROTTLES the WebContent renderer while it is up, so a timer that fires now produces a response
+   * that cannot be delivered. See Bridge.respond. */
+  | { kind: 'request' };
+
+/** Map a CLAuthorizationStatus to what geo.current should do. Unknown/future values → request
+ * (asking is safe and self-correcting: the delegate re-enters here with the real status). */
+export function geoAuthAction(status: number): GeoAuthAction {
+  switch (status) {
+    case CL_AUTH.denied:
+      return { kind: 'reject', code: 'DENIED', message: 'location permission denied' };
+    case CL_AUTH.restricted:
+      // Parental controls / MDM / Screen Time. The user CANNOT grant it — asking is pointless and
+      // waiting is a lie. Distinct from DENIED: "denied" is fixable in Settings, "restricted" is not.
+      return { kind: 'reject', code: 'RESTRICTED', message: 'location access is restricted on this device' };
+    case CL_AUTH.authorizedAlways:
+    case CL_AUTH.authorizedWhenInUse:
+      return { kind: 'start' };
+    case CL_AUTH.notDetermined:
+    default:
+      return { kind: 'request' };
+  }
+}

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

@@ -1,6 +1,7 @@
 import { Application, ApplicationSettings, Connectivity, Device, Utils, isAndroid, isIOS } from '@nativescript/core';
 import { bridge } from './bridge';
 import { onDeepLink } from './events';
+import { geoAuthAction } from './geo-auth';
 import { onRemoteMessage } from './handlers-push';
 import { uiImageToDataUrl } from './ios-image';
 import { notifIdentity, type NotifIdentity } from './notif-identity';
@@ -24,6 +25,10 @@ function ensureIosDelegates(): void {
     onResult?: (r: GeoResult) => void;
     onError?: (e: Error) => void;
     onCleanup?: () => void;
+    /** Prompt answered (or never shown) → wake the throttled renderer so a response can be delivered. */
+    onAuthSettled?: () => void;
+    /** Authorized → arm the location timer NOW (never while the prompt is up). */
+    onLocating?: () => void;
     static new(): GeoDelegateImpl {
       return <GeoDelegateImpl>super.new();
     }
@@ -42,15 +47,24 @@ function ensureIosDelegates(): void {
       this.onCleanup?.();
       this.onError?.(Object.assign(new Error(error.localizedDescription), { code: 'DENIED' }));
     }
+    /** Called by CoreLocation on delegate creation AND on every auth change (i.e. when the system
+     * prompt is answered). This is the ONLY dismiss signal the permission alert gives us. */
     locationManagerDidChangeAuthorization(m: CLLocationManager): void {
-      const st = m.authorizationStatus;
-      if (st === CLAuthorizationStatus.kCLAuthorizationStatusAuthorizedWhenInUse ||
-          st === CLAuthorizationStatus.kCLAuthorizationStatusAuthorizedAlways) {
+      // The prompt is a native surface over the WebView: iOS leaves the WebContent renderer THROTTLED
+      // for ~30-45s after it, so any response we post would be undeliverable. Every other surface
+      // (OAuth/PHPicker/share/billing) already recovers here; geo never did — and the global
+      // UIWindowDidBecomeHidden observer is intentionally disarmed (see main-page.ts), so nothing
+      // covered it. That is the root of the 60s `geo.current timed out after 60000ms`.
+      this.onAuthSettled?.();
+      const action = geoAuthAction(m.authorizationStatus);
+      if (action.kind === 'start') {
+        this.onLocating?.();
         m.startUpdatingLocation();
-      } else if (st === CLAuthorizationStatus.kCLAuthorizationStatusDenied) {
+      } else if (action.kind === 'reject') {
         this.onCleanup?.();
-        this.onError?.(Object.assign(new Error('location permission denied'), { code: 'DENIED' }));
+        this.onError?.(Object.assign(new Error(action.message), { code: action.code }));
       }
+      // 'request' → the prompt is still up; wait for the user's answer (no timer, no surface churn).
     }
   }
   GeoDelegate = GeoDelegateImpl;
@@ -317,22 +331,30 @@ export function registerExtendedHandlers(): void {
   });
 
   // ── geolocation (CLLocationManager) ────────────────────────────────
+  // The 15s budget covers ACQUIRING A FIX only — it is armed once we are authorized and locating.
+  // It must never cover the permission prompt: the prompt is dismiss-bound (the user may take as long
+  // as they like) and it throttles the WebContent renderer, so a timer firing while it is up produces
+  // a rejection that CANNOT be delivered — which is precisely how this became a silent 60s hang.
   bridge.register('geo.current', () => {
     if (!isIOS) throw Object.assign(new Error('iOS only for now'), { code: 'UNSUPPORTED' });
     return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        cleanup();
-        reject(Object.assign(new Error('location timeout'), { code: 'TIMEOUT' }));
-      }, 15000);
-
       let manager: CLLocationManager | null = null;
       let delegate: any = null;
+      let timer: any = null;
       const cleanup = () => {
-        clearTimeout(timer);
+        if (timer) clearTimeout(timer);
+        timer = null;
         manager?.stopUpdatingLocation();
         manager = null;
         delegate = null;
       };
+      const armLocationTimer = () => {
+        if (timer) return;
+        timer = setTimeout(() => {
+          cleanup();
+          reject(Object.assign(new Error('location timeout'), { code: 'TIMEOUT' }));
+        }, 15000);
+      };
 
       Utils.dispatchToMainThread(() => {
         manager = CLLocationManager.new();
@@ -340,14 +362,18 @@ export function registerExtendedHandlers(): void {
         delegate.onResult = resolve;
         delegate.onError = reject;
         delegate.onCleanup = cleanup;
+        delegate.onLocating = armLocationTimer;
+        // Reuse the shared primitive every other native surface already uses (handlers-oauth /
+        // PHPicker / share / billing / apple-signin). Idempotent + coalesced ⇒ safe to call when no
+        // prompt was ever shown.
+        delegate.onAuthSettled = () => bridge.getWebView()?.recoverAfterNativeSurface();
         manager.delegate = delegate;
         manager.desiredAccuracy = kCLLocationAccuracyHundredMeters;
-        const st = manager.authorizationStatus;
-        if (st === CLAuthorizationStatus.kCLAuthorizationStatusNotDetermined) {
-          manager.requestWhenInUseAuthorization();
-        } else {
-          manager.startUpdatingLocation();
-        }
+        // Assigning the delegate makes CoreLocation invoke didChangeAuthorization immediately with the
+        // current status, which drives every case: denied/restricted reject NOW, authorized arms the
+        // timer + locates, notDetermined waits for the prompt below.
+        const action = geoAuthAction(manager.authorizationStatus);
+        if (action.kind === 'request') manager.requestWhenInUseAuthorization();
       });
     });
   });

package/runtime/modules-native/widget/App_Resources/Android/src/main/res/drawable/appwrap_badge_bg.xml

@@ -1,7 +1,9 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- Red pill background for the widget tile's unread-count badge. -->
+<!-- Red circular/pill background for the widget tile's unread-count badge (iOS-parity Capsule).
+     Large corner radius → a true circle for single digits, a pill for 2+. White ring lifts it off
+     the icon. -->
 <shape xmlns:android="http://schemas.android.com/apk/res/android" android:shape="rectangle">
     <solid android:color="#FF3B30" />
     <stroke android:width="1.5dp" android:color="#FFFFFF" />
-    <corners android:radius="9dp" />
+    <corners android:radius="100dp" />
 </shape>

package/runtime/tests/bridge-response-delivery.test.ts

@@ -0,0 +1,113 @@
+import { beforeEach, describe, expect, mock, test } from 'bun:test';
+
+// The shell imports NativeScript globals at module load; the bridge only needs isIOS/isAndroid.
+mock.module('@nativescript/core', () => ({ isIOS: false, isAndroid: false, WebView: class {} }));
+
+const { Bridge } = await import('../app/shell/bridge');
+
+/** Drive the bridge like the real WebView does: feed it a request envelope, capture what it evals. */
+function harness(evalImpl: (js: string) => Promise<unknown>) {
+  const b = new Bridge();
+  const view: any = { onAppwrapMessage: null };
+  b.attach(view);
+  b.evalJs = evalImpl;
+  const delivered: any[] = [];
+  const send = (method: string, id = 'k1') => view.onAppwrapMessage(JSON.stringify({ v: 1, id, kind: 'request', method }));
+  /** Parse an envelope back out of the `window.__appwrapDeliver("…")` script the bridge builds. */
+  const parse = (js: string) => JSON.parse(JSON.parse(js.slice(js.indexOf('(') + 1, js.lastIndexOf(')'))));
+  return { b, send, delivered, parse };
+}
+
+/** Comfortably longer than the (shrunken) retry window, so the give-up path has fully run. */
+const settle = () => new Promise((r) => setTimeout(r, 150));
+
+describe('Bridge response delivery — a lost response must never become a false TIMEOUT', () => {
+  beforeEach(() => {
+    Bridge.responseRetryMs = 1;
+    Bridge.responseRetryWindowMs = 30;
+    Bridge.responseAttemptTimeoutMs = 5;
+  });
+
+  test('REGRESSION (the user bug): a response failing while the renderer is throttled is RETRIED, not swallowed', async () => {
+    // iOS freezes the WebContent renderer for ~30-45s under a permission alert: evaluateJavaScript
+    // never runs. Old behaviour: one attempt, .catch(console.error) → the caller hung to its 60s watchdog.
+    let attempts = 0;
+    const { b, send, parse } = harness(async (js) => {
+      if (++attempts < 4) throw new Error('renderer throttled');
+      return parse(js);
+    });
+    const seen: any[] = [];
+    b.register('geo.current', () => { throw Object.assign(new Error('location timeout'), { code: 'TIMEOUT' }); });
+    b.evalJs = async (js: string) => {
+      if (attempts++ < 3) throw new Error('renderer throttled');
+      seen.push(parse(js));
+    };
+    send('geo.current');
+    await settle();
+
+    expect(attempts).toBeGreaterThan(3); // it kept trying while frozen
+    expect(seen).toHaveLength(1); // and the answer LANDED once the renderer woke
+    expect(seen[0].error.code).toBe('TIMEOUT');
+  });
+
+  test('an eval that NEVER completes (frozen renderer) still retries — it must not stall the loop', async () => {
+    // WKWebView under a system alert may never invoke the completion handler at all, so the eval
+    // promise stays pending forever. A retry loop that only reacts to REJECTION would hang here.
+    let attempts = 0;
+    const seen: any[] = [];
+    const { b, send, parse } = harness(() => new Promise(() => {})); // never settles
+    b.register('geo.current', () => { throw Object.assign(new Error('location timeout'), { code: 'TIMEOUT' }); });
+    b.evalJs = ((js: string) => {
+      if (++attempts < 3) return new Promise(() => {}); // renderer frozen: no callback, ever
+      seen.push(parse(js));
+      return Promise.resolve(undefined);
+    }) as any;
+    send('geo.current');
+    await settle();
+
+    expect(attempts).toBeGreaterThanOrEqual(3); // the per-attempt cap broke the stall
+    expect(seen).toHaveLength(1);
+    expect(seen[0].error.code).toBe('TIMEOUT'); // and the real answer finally landed
+  });
+
+  test('a permanently undeliverable response is reported LOUDLY, never in silence', async () => {
+    const errs: string[] = [];
+    const orig = console.error;
+    console.error = (...a: any[]) => { errs.push(a.map(String).join(' ')); };
+    try {
+      const { b, send } = harness(async () => { throw new Error('webview gone'); });
+      b.register('geo.current', () => { throw Object.assign(new Error('nope'), { code: 'DENIED' }); });
+      send('geo.current');
+      await settle();
+      const line = errs.find((e) => e.includes('UNDELIVERABLE'));
+      expect(line).toBeDefined();
+      expect(line).toContain('false TIMEOUT'); // names the exact user-visible consequence
+      expect(line).toContain('DENIED'); // and the real reason we failed to convey
+    } finally { console.error = orig; }
+  });
+
+  test('a rejecting handler still answers with ITS code — a permission never masquerades as a timeout', async () => {
+    const seen: any[] = [];
+    const { b, send, parse } = harness(async (js) => { seen.push(parse(js)); });
+    b.register('geo.current', () => { throw Object.assign(new Error('location permission denied'), { code: 'DENIED' }); });
+    send('geo.current');
+    await settle();
+    expect(seen[0].error).toEqual({ code: 'DENIED', message: 'location permission denied' });
+  });
+
+  test('an unknown method answers UNSUPPORTED fast (no silent drop → no false timeout)', async () => {
+    const seen: any[] = [];
+    const { b, send, parse } = harness(async (js) => { seen.push(parse(js)); });
+    send('geo.nope');
+    await settle();
+    expect(seen[0].error.code).toBe('UNSUPPORTED');
+  });
+
+  test('retry is response-only: events stay one-shot (they are not idempotent)', async () => {
+    let calls = 0;
+    const { b } = harness(async () => { calls++; throw new Error('down'); });
+    b.emit('geo.position', { lat: 1, lng: 2 });
+    await settle();
+    expect(calls).toBe(1);
+  });
+});

package/runtime/tests/geo-auth.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from 'bun:test';
+import { CL_AUTH, geoAuthAction } from '../app/shell/geo-auth';
+
+describe('geoAuthAction', () => {
+  test('denied → rejects INSTANTLY with DENIED (never a timeout)', () => {
+    expect(geoAuthAction(CL_AUTH.denied)).toEqual({
+      kind: 'reject', code: 'DENIED', message: 'location permission denied',
+    });
+  });
+
+  test('restricted → rejects with RESTRICTED, distinct from DENIED (was: burned 15s → TIMEOUT)', () => {
+    const r = geoAuthAction(CL_AUTH.restricted);
+    expect(r.kind).toBe('reject');
+    expect((r as any).code).toBe('RESTRICTED');
+  });
+
+  test('a permission state NEVER maps to waiting/starting — the headline invariant', () => {
+    for (const st of [CL_AUTH.denied, CL_AUTH.restricted]) {
+      expect(geoAuthAction(st).kind).toBe('reject');
+    }
+  });
+
+  test('authorized (whenInUse + always) → start locating', () => {
+    expect(geoAuthAction(CL_AUTH.authorizedWhenInUse)).toEqual({ kind: 'start' });
+    expect(geoAuthAction(CL_AUTH.authorizedAlways)).toEqual({ kind: 'start' });
+  });
+
+  test('notDetermined → request the prompt (and, per contract, arm no timer)', () => {
+    expect(geoAuthAction(CL_AUTH.notDetermined)).toEqual({ kind: 'request' });
+  });
+
+  test('unknown/future status → request (safe + self-correcting), never a silent hang', () => {
+    expect(geoAuthAction(99).kind).toBe('request');
+  });
+});

package/src/cli.ts

@@ -8,12 +8,12 @@
  * Config (TS preferred, JSON fallback) — probed in order: appwrap.config.ts → .js → appwrap.json.
  * Shape: { id, name, version, entry?, backgroundColor?, statusBarStyle?, pwaDist }. See config.ts.
  */
-import { execFileSync, spawn } from 'child_process';
+import { execFileSync, spawn, spawnSync } from 'child_process';
 import { createHash } from 'crypto';
 import { copyFileSync, cpSync, existsSync, mkdirSync, openSync, closeSync, readdirSync, readFileSync, readSync, rmSync, statSync, writeFileSync, writeSync } from 'fs';
 import { builtinModules } from 'module';
 import { networkInterfaces, tmpdir } from 'os';
-import { delimiter as pathDelimiter, dirname, extname, join, resolve } from 'path';
+import { basename, delimiter as pathDelimiter, dirname, extname, join, resolve } from 'path';
 import { pathToFileURL } from 'url';
 // PURE-DATA capability manifest (no NativeScript globals) — type-only import (erased at runtime);
 // the VALUES are loaded dynamically below from the resolved runtime so the CLI works both in the
@@ -1609,6 +1609,16 @@ export function applyOverrides(cwd: string, outDir: string, cfg: AppwrapConfig):
   // Files the template still provides must survive an override removal (regenerateCore ran first and
   // re-copied them) → protect them from the override prune.
   const templateFiles = existsSync(TEMPLATE_DIR) ? collectRelFiles(TEMPLATE_DIR, templateCopyFilter) : new Set<string>();
+  // ACTIVE modules' native source needs the SAME protection: copyModuleNativeSrc re-copied it into
+  // these exact relative paths, but it lives under runtime/modules-native/<name>/, which
+  // templateCopyFilter deliberately excludes — so it is absent from templateFiles above. Without this,
+  // dropping a consumer override that happened to shadow a module file prunes the MODULE's own copy
+  // too (the prune only sees "was in the overrides manifest, isn't in overrides now"), silently
+  // deleting e.g. res/xml/appwrap_widget_info.xml and failing the build at AAPT.
+  for (const name of nativeReqs(cfg).nativeSrc) {
+    const modDir = join(MODULES_NATIVE_DIR, name);
+    if (existsSync(modDir)) for (const rel of collectRelFiles(modDir)) templateFiles.add(rel);
+  }
   if (!existsSync(dir)) {
     // No overrides now: prune anything a PRIOR overrides run left behind (renamed/removed override files).
     pruneStale(outDir, OVERRIDES_MANIFEST, new Set(), templateFiles);
@@ -2132,6 +2142,122 @@ function runNs(outDir: string, args: string[]): void {
   const env = prepareNsEnv(outDir, args);
   console.log(`▶ ns ${args.join(' ')}  (cwd: ${outDir})`);
   execFileSync('ns', args, { cwd: outDir, stdio: 'inherit', env });
+  if (args.includes('android')) assertSbgParsedCleanly(outDir);
+}
+
+/** Fail an Android build when SBG's js_parser ABANDONED a bundled file.
+ *
+ * This is the root check; assertJavaProxyBindings() below is the outcome check. The parser catches errors
+ * PER FILE, drops that file's ENTIRE remaining AST, logs nothing unless JS_PARSER_ENABLE_LOGGING is set
+ * (runSbg.log stays empty), and the gradle task still exits 0 — so every binding declared after the throw
+ * silently vanishes from a green build. Measured blast radius when a spread in a `.extend({...})` literal
+ * threw ~1/3 of the way through bundle.js: bundle-sourced bindings went 24 -> 1. Gone were not just
+ * @JavaProxy('cc.livx.appwrap.AppwrapMessagingService') (a FATAL boot crash) but SensorEventListener x4,
+ * LocationListener, OnCompleteListener x2, RecognitionListener, ContentObserver, Runnable x5 and
+ * ValueCallback — i.e. sensors, geolocation, FCM token, speech and background threads, each failing later
+ * and far from the cause.
+ *
+ * Asserting only "@JavaProxy present" would miss all of that whenever the throw lands after the last
+ * @JavaProxy, so re-run the parser with logging and treat ANY abandoned file as a build failure. This is
+ * read-only w.r.t. the APK (gradle already generated the java); it only rewrites build-tools/sbg-*.txt with
+ * identical content, and those are not gradle inputs.
+ */
+function assertSbgParsedCleanly(outDir: string): void {
+  const buildTools = join(outDir, 'platforms/android/build-tools');
+  const parser = join(buildTools, 'jsparser/js_parser.js');
+  if (!existsSync(parser)) return assertJavaProxyBindings(outDir); // no parser here → nothing to re-run
+
+  // spawnSync, not execFileSync: the parser logs its fatal "Error processing" lines to STDERR, and
+  // execFileSync returns stdout ONLY — reading just stdout silently sees a clean log and passes.
+  const run = spawnSync('node', [parser, 'enableVerboseLogging'], {
+    cwd: buildTools,
+    encoding: 'utf8',
+    env: { ...process.env, JS_PARSER_ENABLE_LOGGING: 'true' },
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  // Couldn't re-run (no node on PATH, parser layout changed). Don't fail the build on the CHECK's own
+  // failure — fall back to the cheaper outcome assertion, which needs no subprocess.
+  if (run.error || run.status !== 0) return assertJavaProxyBindings(outDir);
+  const log = `${run.stdout ?? ''}\n${run.stderr ?? ''}`;
+
+  // "Error processing '<file>:' <err>" = that file was abandoned mid-AST. (Distinct from the parser's
+  // benign per-node "JSParser Error: Node type is not a call expression" chatter, which is not fatal.)
+  const abandoned = [...log.matchAll(/Error processing '([^']+):?'\s*(.*)/g)].map((m) => ({
+    file: basename(m[1].replace(/:$/, '')),
+    err: (m[2] || '').split('\n')[0].trim(),
+  }));
+  if (abandoned.length) {
+    console.error(
+      `\n✖ Android build is BROKEN: NativeScript's static-binding-generator ABANDONED ${abandoned.length} bundled\n` +
+        `  file(s) mid-parse. Every Java binding declared after the throw was silently dropped — the gradle\n` +
+        `  task still exited 0, so this APK/AAB is missing classes it needs:\n` +
+        abandoned.map((a) => `    • ${a.file}: ${a.err}`).join('\n') +
+        `\n\n  Symptoms this causes, all far from the cause: "LookedUpClassNotFound: <class>" FATAL at boot for a\n` +
+        `  @JavaProxy, or sensors/geolocation/speech/FCM-token/background-threads silently doing nothing.\n\n` +
+        `  The known offender is a SPREAD inside an \`X.extend({...})\` literal: the parser reads\n` +
+        `  \`prop.key.name\` for every property and a SpreadElement has no \`key\`. Keep .extend() literals\n` +
+        `  spread-free (select between two whole literals instead), and never pass a variable to .extend().\n\n` +
+        `  Full parse log:\n` +
+        `    cd ${buildTools} && JS_PARSER_ENABLE_LOGGING=true node jsparser/js_parser.js enableVerboseLogging\n`
+    );
+    process.exit(1);
+  }
+  assertJavaProxyBindings(outDir); // parse was clean — still assert the outcome
+}
+
+/** Fail an Android build when a `@JavaProxy` class silently lost its generated Java binding.
+ *
+ * NativeScript's static-binding-generator (SBG) reads the BUNDLED js and synthesizes the Java class each
+ * `@JavaProxy('a.b.C')` declares — the same class AndroidManifest entries and `new a.b.C()` reference. Its
+ * js_parser catches errors PER FILE: on an unsupported construct it abandons THE ENTIRE FILE, logs only
+ * under JS_PARSER_ENABLE_LOGGING (runSbg.log stays empty), and the gradle task still exits 0. So every
+ * @JavaProxy declared after that point in the bundle vanishes with a green build, and the app dies at boot
+ * on a device with `LookedUpClassNotFound: a.b.C` — the worst possible place to find out.
+ *
+ * This turns that silent, ship-to-prod failure into a build error. It is deliberately generic (assert the
+ * BINDING exists, not "no spreads"): it catches any future parser quirk, not just the one that bit us —
+ * a spread inside a `X.extend({...})` literal (a SpreadElement has no `.key`, so the parser threw on
+ * `prop.key.name` and dropped cc.livx.appwrap.AppwrapMessagingService, boot-crashing every server-loader
+ * app with push).
+ *
+ * Inputs are SBG's OWN records, so this checks exactly what SBG saw: sbg-js-parsed-files.txt (the files it
+ * parsed) and sbg-bindings.txt (what it decided to generate).
+ */
+function assertJavaProxyBindings(outDir: string): void {
+  const buildTools = join(outDir, 'platforms/android/build-tools');
+  const bindingsFile = join(buildTools, 'sbg-bindings.txt');
+  const parsedFile = join(buildTools, 'sbg-js-parsed-files.txt');
+  // Absent → SBG never ran for this invocation (e.g. `ns clean`, a prepare-only pass). Nothing to assert.
+  if (!existsSync(bindingsFile) || !existsSync(parsedFile)) return;
+
+  const bindings = readFileSync(bindingsFile, 'utf8');
+  const missing: Array<{ cls: string; file: string }> = [];
+  for (const jsFile of readFileSync(parsedFile, 'utf8').split('\n').map((l) => l.trim())) {
+    if (!jsFile || !existsSync(jsFile)) continue;
+    const js = readFileSync(jsFile, 'utf8');
+    // Only a real decorator call `JavaProxy('a.b.C')` matches — prose mentions like "(JavaProxy)" don't.
+    for (const m of js.matchAll(/JavaProxy\(\s*['"]([\w.$]+)['"]\s*\)/g)) {
+      const cls = m[1];
+      // sbg-bindings.txt is `*`-delimited; the proxy name is one field — a substring test is enough.
+      if (!bindings.includes(cls) && !missing.some((x) => x.cls === cls)) missing.push({ cls, file: basename(jsFile) });
+    }
+  }
+  if (!missing.length) return;
+
+  console.error(
+    `\n✖ Android build is BROKEN: ${missing.length} @JavaProxy class(es) got no Java binding from the\n` +
+      `  NativeScript static-binding-generator, so the APK/AAB is missing them. This build would install\n` +
+      `  and then CRASH AT BOOT with "LookedUpClassNotFound":\n` +
+      missing.map((m) => `    • ${m.cls}   (declared in ${m.file})`).join('\n') +
+      `\n\n  CAUSE: SBG's js_parser hit an unsupported construct, abandoned the whole file, and still exited 0,\n` +
+      `  dropping every @JavaProxy after that point. It does NOT report this itself.\n\n` +
+      `  The known offender is a SPREAD inside an \`X.extend({...})\` literal — the parser reads\n` +
+      `  \`prop.key.name\` for every property and a SpreadElement has no \`key\`. Keep .extend() literals\n` +
+      `  spread-free (select between two literals instead), and never pass a variable to .extend().\n\n` +
+      `  To see the real parse error:\n` +
+      `    cd ${buildTools} && JS_PARSER_ENABLE_LOGGING=true node jsparser/js_parser.js enableVerboseLogging\n`
+  );
+  process.exit(1);
 }
 
 /** Wipe the generated NativeScript state (`ns clean`: platforms/, hooks/, node_modules/) then restore
@@ -2841,6 +2967,9 @@ async function build(cwd: string, flags: Record<string, string>, positionals: st
 
   console.log(`▶ ns ${args.join(' ').replace(/(--key-store-password|--key-store-alias-password) [^ ]*/g, '$1 ****')}  (cwd: ${outDir})`);
   execFileSync('ns', args, { cwd: outDir, stdio: 'inherit' });
+  // This is the RELEASE path (CI's `build android --release --aab`) — the one whose output actually ships.
+  // It calls `ns` directly rather than via runNs, so it needs its own check. See assertSbgParsedCleanly.
+  if (platform === 'android') assertSbgParsedCleanly(outDir);
   if (platform === 'ios' && release) {
     const ipa = join(outDir, 'platforms/ios/build/Release-iphoneos');
     console.log(`ℹ Signed store .ipa in ${ipa} — upload via \`bunx @livx.cc/mcp-appstores apple-upload\` or the fastlane release lane (native/fastlane).`);