@livx.cc/appwrap 0.51.0 → 0.51.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.51.0",
+  "version": "0.51.2",
   "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

@@ -107,6 +107,14 @@ export class CustomWebView extends WebView {
   // object, robust to NS re-wrapping the arg passed into the ChromeClient callback). WeakRef
   // so a destroyed view can be GC'd; entry pruned on dispose.
   private static registry = new Map<number, WeakRef<CustomWebView>>();
+  // Retired asset-serving WebViewClients (app/file loader ONLY — see disposeNativeView), kept
+  // process-alive so a shouldInterceptRequest already in flight on a background thread when the view is
+  // disposed can't fire against a GC'd JS peer → "Cannot find runtime for instance". Holding the (JS-peer)
+  // object here keeps NS's per-object runtime mapping resolvable. Server mode installs no interceptor, so
+  // its clients are NOT parked (all their callbacks are main-thread → safe to GC). Growth is bounded by
+  // the number of interceptor-bearing WebViews that dispose — note handlers-background can spin up an
+  // offscreen WebView per background task, so this is per-disposed-interceptor-view, not strictly one.
+  private static retiredClients = new Set<android.webkit.WebViewClient>();
   static forNative(view: android.webkit.WebView): CustomWebView | undefined {
     const owner = CustomWebView.registry.get(view.hashCode())?.deref();
     // identityHashCode is not unique: on a (rare) collision the map holds the LAST writer —
@@ -155,9 +163,20 @@ export class CustomWebView extends WebView {
   disposeNativeView(): void {
     const wv = this.android as android.webkit.WebView | undefined;
     if (wv) CustomWebView.registry.delete(wv.hashCode());
-    // Drop the retained clients now that the native view is going away, so their peers can be GC'd.
-    this.webViewClient = null;
+    // WebChromeClient (onJsPrompt) only fires on the main thread → safe to release for GC now.
     this.webChromeClient = null;
+    // WebViewClient is different: shouldInterceptRequest can be dispatched on a BACKGROUND thread, so a
+    // request already in flight when the view tears down would fire AFTER dispose. Releasing the client's
+    // JS peer here would let that late off-thread call crash with "Cannot find runtime for instance".
+    // Park it in a process-lived set so the peer stays registered for any straggler callback — but ONLY
+    // when the interceptor is actually installed (app/file loader). Server mode installs no
+    // shouldInterceptRequest (see createAssetServingClient), so its client has no off-thread callback to
+    // outlive dispose: parking it would be pure dead retention (an accumulating leak across background-
+    // task WebViews), so just release it for GC.
+    if (this.webViewClient) {
+      if (SHELL_CONFIG.loader !== 'server') CustomWebView.retiredClients.add(this.webViewClient);
+      this.webViewClient = null;
+    }
     super.disposeNativeView();
   }
 
@@ -307,14 +326,30 @@ function createAssetServingClient(): android.webkit.WebViewClient {
     return new android.webkit.WebResourceResponse(mimeFor(ext, rel), 'utf-8', 200, 'OK', outHeaders, pin);
   };
 
+  // WebViewClient callbacks. All are dispatched on the UI/main thread EXCEPT shouldInterceptRequest,
+  // which Android runs on a BACKGROUND thread (ShouldInterceptRequestMediator). NativeScript resolves
+  // the JS peer for a callback's instance via a per-object runtime lookup (Runtime.getObjectRuntime);
+  // if that peer is momentarily unregistered — freshly created and not yet mapped on boot, or disposed
+  // and GC'd on relaunch / RESTART-from-crash — the off-thread call throws
+  // `NativeScriptException: Cannot find runtime for instance` (the red NS crash screen). NS marshals a
+  // background-thread call to the main thread fine ONCE the peer is mapped, so this is a registration/
+  // lifetime race, not a plain GC one — which is why the earlier strong-JS-ref fix didn't cover the boot path.
+  //
+  // 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 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.
-    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
 
@@ -343,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;
@@ -378,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-
@@ -409,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/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/java/cc/livx/appwrap/AppwrapWidgetProvider.kt

@@ -5,7 +5,13 @@ import android.appwidget.AppWidgetManager
 import android.appwidget.AppWidgetProvider
 import android.content.Context
 import android.content.Intent
+import android.graphics.Bitmap
 import android.graphics.BitmapFactory
+import android.graphics.BitmapShader
+import android.graphics.Canvas
+import android.graphics.Paint
+import android.graphics.RectF
+import android.graphics.Shader
 import android.net.Uri
 import android.view.View
 import android.widget.RemoteViews
@@ -15,12 +21,14 @@ import java.io.File
 /**
  * Home-screen launcher widget (Android parity of the iOS WidgetKit launcher). Reads the payload the
  * `widget.publish` handler wrote into SharedPreferences ("appwrap.widget" / key "appwrap.widget") and
- * renders up to 4 icon-grid tiles; each tile deep-links back into the app via its entry's URL. Icons
- * are PNGs the handler saved into the app files dir. Resource ids are looked up by name so the module
- * needs no compile-time reference to the host app's R class.
+ * renders up to 12 icon-grid tiles across 4 columns; each tile deep-links back into the app via its
+ * entry's URL. Icons are PNGs the handler saved into the app files dir. Resource ids are looked up by
+ * name so the module needs no compile-time reference to the host app's R class.
  */
 class AppwrapWidgetProvider : AppWidgetProvider() {
-    private val tiles = listOf("tile0", "tile1", "tile2", "tile3")
+    private val columns = 4
+    private val tiles = (0 until 12).map { "tile$it" }
+    private val rows = (0 until 3).map { "row$it" }
 
     override fun onUpdate(ctx: Context, mgr: AppWidgetManager, ids: IntArray) {
         for (id in ids) render(ctx, mgr, id)
@@ -29,6 +37,27 @@ class AppwrapWidgetProvider : AppWidgetProvider() {
     private fun res(ctx: Context, type: String, name: String) =
         ctx.resources.getIdentifier(name, type, ctx.packageName)
 
+    /**
+     * Round an app icon to look native on the home screen (iOS-parity: iOS clips to a
+     * RoundedRectangle ~24% of the icon size). RemoteViews ImageViews can't clip via an outline, so we
+     * center-crop the source to a square and redraw it into a rounded bitmap at full source resolution
+     * — the widget host then downscales a crisp, antialiased image rather than a hard-edged square.
+     */
+    private fun rounded(src: Bitmap): Bitmap {
+        val size = minOf(src.width, src.height)
+        val sq = if (src.width != src.height)
+            Bitmap.createBitmap(src, (src.width - size) / 2, (src.height - size) / 2, size, size)
+        else src
+        val out = Bitmap.createBitmap(size, size, Bitmap.Config.ARGB_8888)
+        val canvas = Canvas(out)
+        val paint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+            shader = BitmapShader(sq, Shader.TileMode.CLAMP, Shader.TileMode.CLAMP)
+        }
+        val r = size * 0.22f
+        canvas.drawRoundRect(RectF(0f, 0f, size.toFloat(), size.toFloat()), r, r, paint)
+        return out
+    }
+
     private fun render(ctx: Context, mgr: AppWidgetManager, id: Int) {
         val rv = RemoteViews(ctx.packageName, res(ctx, "layout", "appwrap_widget"))
         val raw = ctx.getSharedPreferences("appwrap.widget", Context.MODE_PRIVATE)
@@ -39,10 +68,20 @@ class AppwrapWidgetProvider : AppWidgetProvider() {
         rv.setViewVisibility(res(ctx, "id", "appwrap_widget_title"),
             if (title.isEmpty()) View.GONE else View.VISIBLE)
         val entries = payload?.optJSONArray("entries")
+        val count = entries?.length() ?: 0
+
+        // A row with no entries at all is GONE so it contributes no height (the grid stays top-packed
+        // and leftover widget height falls to the bottom). A row that is only PARTLY filled stays
+        // VISIBLE and hides its trailing tiles as INVISIBLE, so a short final row keeps its tiles in
+        // the leading columns rather than centring them (iOS Grid's short-final-row behaviour).
+        for (r in rows.indices) {
+            rv.setViewVisibility(res(ctx, "id", rows[r]),
+                if (r * columns < count) View.VISIBLE else View.GONE)
+        }
 
         for (i in tiles.indices) {
             val tileId = res(ctx, "id", tiles[i])
-            val e = if (entries != null && i < entries.length()) entries.optJSONObject(i) else null
+            val e = if (entries != null && i < count) entries.optJSONObject(i) else null
             if (e == null) { rv.setViewVisibility(tileId, View.INVISIBLE); continue }
             rv.setViewVisibility(tileId, View.VISIBLE)
             rv.setTextViewText(res(ctx, "id", "${tiles[i]}_label"), e.optString("label"))
@@ -57,7 +96,7 @@ class AppwrapWidgetProvider : AppWidgetProvider() {
             if (icon.isNotEmpty()) {
                 val f = File(ctx.filesDir, icon)
                 if (f.exists()) BitmapFactory.decodeFile(f.absolutePath)
-                    ?.let { rv.setImageViewBitmap(res(ctx, "id", "${tiles[i]}_icon"), it) }
+                    ?.let { rv.setImageViewBitmap(res(ctx, "id", "${tiles[i]}_icon"), rounded(it)) }
             }
             val link = e.optString("deepLink", "")
             if (link.isNotEmpty()) {

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/modules-native/widget/App_Resources/Android/src/main/res/layout/appwrap_widget.xml

@@ -1,32 +1,36 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- AppWrap launcher widget: title + a 2×2 icon-grid of deep-linked tiles. Populated by
-     AppwrapWidgetProvider from the published payload; empty tiles are set INVISIBLE. Each icon can
-     carry an unread-count badge (tileN_badge) overlaid on its top-right corner. -->
+<!-- AppWrap launcher widget: title + a 4-column icon grid of deep-linked tiles (up to 3 rows / 12
+     tiles), populated by AppwrapWidgetProvider from the published payload.
+
+     LAYOUT CONTRACT (iOS parity — see AppwrapWidget.swift `gridView`):
+       * Rows are CONTENT-HEIGHT (wrap_content, NO layout_weight). The root is a vertical
+         LinearLayout at match_parent, so rows stack from the TOP and any leftover widget height
+         falls to the BOTTOM — the "app folder" feel. Giving rows `0dp + weight=1` (as this layout
+         once did) makes them greedily split the full height and float each icon to the centre of
+         its band, which strands the last row at the bottom behind a large dead gap on a
+         vertically-resized widget. Don't reintroduce weights here.
+       * A partially-filled row keeps its trailing tiles INVISIBLE (not GONE) so the short final row
+         stays aligned to the LEADING columns instead of centring. A fully-empty row is set GONE by
+         the provider so it consumes no height. -->
 <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
     android:orientation="vertical"
-    android:background="#F2FFFFFF"
+    android:background="@color/appwrap_widget_bg"
     android:padding="10dp">
 
     <TextView
         android:id="@+id/appwrap_widget_title"
         android:layout_width="wrap_content"
         android:layout_height="wrap_content"
-        android:textColor="#222222"
+        android:textColor="@color/appwrap_widget_title"
         android:textStyle="bold"
         android:textSize="12sp"
-        android:layout_marginBottom="6dp"
+        android:layout_marginBottom="8dp"
         android:maxLines="1"
         android:ellipsize="end" />
 
-    <LinearLayout
-        android:layout_width="match_parent"
-        android:layout_height="0dp"
-        android:layout_weight="1"
-        android:orientation="horizontal"
-        android:weightSum="2">
-
+    <LinearLayout android:id="@+id/row0" style="@style/AppwrapWidgetRow">
         <LinearLayout android:id="@+id/tile0" style="@style/AppwrapWidgetTile">
             <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
                 <ImageView android:id="@+id/tile0_icon" style="@style/AppwrapWidgetIcon" />
@@ -34,7 +38,6 @@
             </FrameLayout>
             <TextView android:id="@+id/tile0_label" style="@style/AppwrapWidgetLabel" />
         </LinearLayout>
-
         <LinearLayout android:id="@+id/tile1" style="@style/AppwrapWidgetTile">
             <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
                 <ImageView android:id="@+id/tile1_icon" style="@style/AppwrapWidgetIcon" />
@@ -42,15 +45,6 @@
             </FrameLayout>
             <TextView android:id="@+id/tile1_label" style="@style/AppwrapWidgetLabel" />
         </LinearLayout>
-    </LinearLayout>
-
-    <LinearLayout
-        android:layout_width="match_parent"
-        android:layout_height="0dp"
-        android:layout_weight="1"
-        android:orientation="horizontal"
-        android:weightSum="2">
-
         <LinearLayout android:id="@+id/tile2" style="@style/AppwrapWidgetTile">
             <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
                 <ImageView android:id="@+id/tile2_icon" style="@style/AppwrapWidgetIcon" />
@@ -58,7 +52,6 @@
             </FrameLayout>
             <TextView android:id="@+id/tile2_label" style="@style/AppwrapWidgetLabel" />
         </LinearLayout>
-
         <LinearLayout android:id="@+id/tile3" style="@style/AppwrapWidgetTile">
             <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
                 <ImageView android:id="@+id/tile3_icon" style="@style/AppwrapWidgetIcon" />
@@ -67,4 +60,64 @@
             <TextView android:id="@+id/tile3_label" style="@style/AppwrapWidgetLabel" />
         </LinearLayout>
     </LinearLayout>
+    <LinearLayout android:id="@+id/row1" style="@style/AppwrapWidgetRow">
+        <LinearLayout android:id="@+id/tile4" style="@style/AppwrapWidgetTile">
+            <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
+                <ImageView android:id="@+id/tile4_icon" style="@style/AppwrapWidgetIcon" />
+                <TextView android:id="@+id/tile4_badge" style="@style/AppwrapWidgetBadge" android:visibility="gone" />
+            </FrameLayout>
+            <TextView android:id="@+id/tile4_label" style="@style/AppwrapWidgetLabel" />
+        </LinearLayout>
+        <LinearLayout android:id="@+id/tile5" style="@style/AppwrapWidgetTile">
+            <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
+                <ImageView android:id="@+id/tile5_icon" style="@style/AppwrapWidgetIcon" />
+                <TextView android:id="@+id/tile5_badge" style="@style/AppwrapWidgetBadge" android:visibility="gone" />
+            </FrameLayout>
+            <TextView android:id="@+id/tile5_label" style="@style/AppwrapWidgetLabel" />
+        </LinearLayout>
+        <LinearLayout android:id="@+id/tile6" style="@style/AppwrapWidgetTile">
+            <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
+                <ImageView android:id="@+id/tile6_icon" style="@style/AppwrapWidgetIcon" />
+                <TextView android:id="@+id/tile6_badge" style="@style/AppwrapWidgetBadge" android:visibility="gone" />
+            </FrameLayout>
+            <TextView android:id="@+id/tile6_label" style="@style/AppwrapWidgetLabel" />
+        </LinearLayout>
+        <LinearLayout android:id="@+id/tile7" style="@style/AppwrapWidgetTile">
+            <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
+                <ImageView android:id="@+id/tile7_icon" style="@style/AppwrapWidgetIcon" />
+                <TextView android:id="@+id/tile7_badge" style="@style/AppwrapWidgetBadge" android:visibility="gone" />
+            </FrameLayout>
+            <TextView android:id="@+id/tile7_label" style="@style/AppwrapWidgetLabel" />
+        </LinearLayout>
+    </LinearLayout>
+    <LinearLayout android:id="@+id/row2" style="@style/AppwrapWidgetRow">
+        <LinearLayout android:id="@+id/tile8" style="@style/AppwrapWidgetTile">
+            <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
+                <ImageView android:id="@+id/tile8_icon" style="@style/AppwrapWidgetIcon" />
+                <TextView android:id="@+id/tile8_badge" style="@style/AppwrapWidgetBadge" android:visibility="gone" />
+            </FrameLayout>
+            <TextView android:id="@+id/tile8_label" style="@style/AppwrapWidgetLabel" />
+        </LinearLayout>
+        <LinearLayout android:id="@+id/tile9" style="@style/AppwrapWidgetTile">
+            <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
+                <ImageView android:id="@+id/tile9_icon" style="@style/AppwrapWidgetIcon" />
+                <TextView android:id="@+id/tile9_badge" style="@style/AppwrapWidgetBadge" android:visibility="gone" />
+            </FrameLayout>
+            <TextView android:id="@+id/tile9_label" style="@style/AppwrapWidgetLabel" />
+        </LinearLayout>
+        <LinearLayout android:id="@+id/tile10" style="@style/AppwrapWidgetTile">
+            <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
+                <ImageView android:id="@+id/tile10_icon" style="@style/AppwrapWidgetIcon" />
+                <TextView android:id="@+id/tile10_badge" style="@style/AppwrapWidgetBadge" android:visibility="gone" />
+            </FrameLayout>
+            <TextView android:id="@+id/tile10_label" style="@style/AppwrapWidgetLabel" />
+        </LinearLayout>
+        <LinearLayout android:id="@+id/tile11" style="@style/AppwrapWidgetTile">
+            <FrameLayout android:layout_width="wrap_content" android:layout_height="wrap_content" android:layout_marginBottom="4dp">
+                <ImageView android:id="@+id/tile11_icon" style="@style/AppwrapWidgetIcon" />
+                <TextView android:id="@+id/tile11_badge" style="@style/AppwrapWidgetBadge" android:visibility="gone" />
+            </FrameLayout>
+            <TextView android:id="@+id/tile11_label" style="@style/AppwrapWidgetLabel" />
+        </LinearLayout>
+    </LinearLayout>
 </LinearLayout>

package/runtime/modules-native/widget/App_Resources/Android/src/main/res/values/appwrap_widget_colors.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Widget chrome colors. Split into values/ + values-night/ so the tile follows the host's theme
+     (iOS parity: containerBackground(.fill.tertiary) + .primary label adapt automatically; a
+     hardcoded white slab with #333 text stayed stark-white on a dark home screen). The widget host
+     inflates RemoteViews with its own configuration, so -night resolves without any provider code. -->
+<resources>
+    <color name="appwrap_widget_bg">#F2FFFFFF</color>
+    <color name="appwrap_widget_title">#222222</color>
+    <color name="appwrap_widget_label">#333333</color>
+</resources>

package/runtime/modules-native/widget/App_Resources/Android/src/main/res/values/appwrap_widget_styles.xml

@@ -1,27 +1,54 @@
 <?xml version="1.0" encoding="utf-8"?>
 <resources>
-    <!-- One icon-grid tile: a centered icon over a single-line label, equal-weight in its row. -->
+    <!-- One grid row: 4 equal columns, CONTENT-HEIGHT. The absence of a layout_weight is load-bearing
+         (see the layout's contract comment) — a weighted row splits the widget height and floats its
+         icons mid-band, leaving a dead gap on a tall widget. -->
+    <style name="AppwrapWidgetRow">
+        <item name="android:layout_width">match_parent</item>
+        <item name="android:layout_height">wrap_content</item>
+        <item name="android:orientation">horizontal</item>
+        <item name="android:weightSum">4</item>
+        <item name="android:layout_marginBottom">10dp</item>
+    </style>
+    <!-- One icon-grid tile: a centered icon over a single-line label, equal-weight in its row.
+         Height is wrap_content so the row measures to content, not to the widget's full height. -->
     <style name="AppwrapWidgetTile">
         <item name="android:layout_width">0dp</item>
-        <item name="android:layout_height">match_parent</item>
+        <item name="android:layout_height">wrap_content</item>
         <item name="android:layout_weight">1</item>
         <item name="android:orientation">vertical</item>
-        <item name="android:gravity">center</item>
+        <item name="android:gravity">center_horizontal</item>
         <item name="android:padding">4dp</item>
     </style>
+    <!-- The provider rounds the bitmap itself (RemoteViews ImageView can't clip via outline), so the
+         source is drawn crisp at full res and just scaled to fit here — no fitCenter squashing. -->
+    <!-- The icon carries a top margin + SYMMETRIC start/end margins so the wrap_content badge-container
+         FrameLayout measures LARGER than the 44dp icon. The badge (pinned top|end of that padded
+         container) lands in the end-margin region — visually BEYOND the icon's top-right corner (iOS
+         offset(x:6,y:-6) parity) — yet stays WITHIN the container bounds, so RemoteViews' default
+         child-clipping never cuts it. marginStart mirrors marginEnd so the icon stays HORIZONTALLY
+         CENTERED within the FrameLayout (and thus under its label) — an end-only margin shifts the
+         icon left, leaving an asymmetric right gap.
+         SIZE: 44dp + 14dp of margins = 58dp, + 8dp tile padding = 66dp per column. At 4 columns that
+         needs ~284dp of widget width, which is why appwrap_widget_info declares minResizeWidth 280dp
+         — shrinking below that would start clipping the icons. -->
     <style name="AppwrapWidgetIcon">
-        <item name="android:layout_width">36dp</item>
-        <item name="android:layout_height">36dp</item>
-        <item name="android:scaleType">fitCenter</item>
+        <item name="android:layout_width">44dp</item>
+        <item name="android:layout_height">44dp</item>
+        <item name="android:layout_marginTop">7dp</item>
+        <item name="android:layout_marginStart">7dp</item>
+        <item name="android:layout_marginEnd">7dp</item>
+        <item name="android:scaleType">fitXY</item>
     </style>
-    <!-- Unread-count bubble overlaid on the icon's top-right corner. -->
+    <!-- Unread-count bubble overlapping the icon's top-right corner (iOS-parity: small, circular for
+         single digits, red fill, white ring, bold white number). ~40% of the 44dp icon. -->
     <style name="AppwrapWidgetBadge">
         <item name="android:layout_width">wrap_content</item>
-        <item name="android:layout_height">18dp</item>
+        <item name="android:layout_height">17dp</item>
         <item name="android:layout_gravity">top|end</item>
-        <item name="android:minWidth">18dp</item>
-        <item name="android:paddingLeft">5dp</item>
-        <item name="android:paddingRight">5dp</item>
+        <item name="android:minWidth">17dp</item>
+        <item name="android:paddingLeft">4dp</item>
+        <item name="android:paddingRight">4dp</item>
         <item name="android:background">@drawable/appwrap_badge_bg</item>
         <item name="android:gravity">center</item>
         <item name="android:textColor">#FFFFFF</item>
@@ -32,7 +59,7 @@
     <style name="AppwrapWidgetLabel">
         <item name="android:layout_width">wrap_content</item>
         <item name="android:layout_height">wrap_content</item>
-        <item name="android:textColor">#333333</item>
+        <item name="android:textColor">@color/appwrap_widget_label</item>
         <item name="android:textSize">11sp</item>
         <item name="android:maxLines">1</item>
         <item name="android:ellipsize">end</item>

package/runtime/modules-native/widget/App_Resources/Android/src/main/res/values-night/appwrap_widget_colors.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Dark-theme counterpart of values/appwrap_widget_colors.xml (same names, resolved by the host's
+     night configuration). Translucent near-black slab + light text, mirroring the light variant's
+     alpha so the tile reads as the same material on either theme. -->
+<resources>
+    <color name="appwrap_widget_bg">#E61C1C1E</color>
+    <color name="appwrap_widget_title">#FFFFFF</color>
+    <color name="appwrap_widget_label">#E6FFFFFF</color>
+</resources>

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

@@ -1,9 +1,13 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- Launcher widget: ~4×2 cells (medium), resizable, initial layout = the icon-grid. updatePeriodMillis
-     0 → the app drives refreshes itself via widget.publish (AppWidgetManager broadcast). -->
+     0 → the app drives refreshes itself via widget.publish (AppWidgetManager broadcast).
+     minResizeWidth 280dp: the grid is 4 fixed-width columns (~66dp each — see AppwrapWidgetIcon),
+     so ~284dp is the narrowest width that renders without clipping the icons. minWidth stays 250dp
+     (it only gates where the widget may be PLACED); minResizeWidth is what bounds a user drag. -->
 <appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
     android:minWidth="250dp"
     android:minHeight="110dp"
+    android:minResizeWidth="280dp"
     android:targetCellWidth="4"
     android:targetCellHeight="2"
     android:updatePeriodMillis="0"

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).`);