@livx.cc/appwrap 0.26.0 → 0.28.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.26.0",
+  "version": "0.28.1",
   "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_Resources/Android/src/main/AndroidManifest.xml

@@ -19,6 +19,9 @@
 	<!-- appwrap:permissions -->
 	<!-- /appwrap:permissions -->
 
+	<!-- appwrap:queries -->
+	<!-- /appwrap:queries -->
+
 	<application
 		android:name="com.tns.NativeScriptApplication"
 		android:allowBackup="true"

package/runtime/app/app.ts

@@ -1,8 +1,9 @@
 import { Application, isIOS } from '@nativescript/core';
-import { onDeepLink } from './shell/events';
+import { onDeepLink, onShortcut } from './shell/events';
 import { iosOrientationMask } from './shell/orientation';
 import { installForegroundNotificationDelegate } from './shell/handlers-extended';
 import { onApnsToken, onApnsError, onRemoteMessage } from './shell/handlers-push';
+import { registerBackgroundLaunchHandlers } from './shell/background-bootstrap.generated';
 
 /** APNs device token (NSData) → lowercase hex string the push backend expects. */
 function apnsTokenToHex(deviceToken: NSData): string {
@@ -15,44 +16,61 @@ function apnsTokenToHex(deviceToken: NSData): string {
 if (isIOS) {
   // Custom delegate for URL-scheme opens. NativeScript tracks lifecycle via
   // UIApplication notifications, so adding a delegate only extends behavior.
-  const DelegateClass = (UIResponder as any).extend(
-    {
-      applicationDidFinishLaunchingWithOptions(_app: UIApplication, launchOptions: NSDictionary<string, any>) {
-        // Set the notification delegate NOW so a cold-launch tap's deep link is delivered.
-        installForegroundNotificationDelegate();
-        const url = launchOptions?.objectForKey(UIApplicationLaunchOptionsURLKey);
-        if (url) onDeepLink(url.absoluteString ?? String(url));
-        return true;
-      },
-      applicationOpenURLOptions(_app: UIApplication, url: NSURL, _options: NSDictionary<string, any>) {
-        console.log('AppWrap: openURL', url.absoluteString);
-        onDeepLink(url.absoluteString);
-        return true;
-      },
-      // Drives `kit.screen.orientation.lock` — UIKit reads this on every rotation.
-      applicationSupportedInterfaceOrientationsForWindow(_app: UIApplication, _window: any) {
-        return iosOrientationMask();
-      },
-      // ── Remote push (APNs) — delivered to the AppDelegate, bridged to kit.push. ──
-      applicationDidRegisterForRemoteNotificationsWithDeviceToken(_app: UIApplication, deviceToken: NSData) {
-        onApnsToken(apnsTokenToHex(deviceToken));
-      },
-      applicationDidFailToRegisterForRemoteNotificationsWithError(_app: UIApplication, error: NSError) {
-        onApnsError(error?.localizedDescription ?? 'APNs registration failed');
-      },
-      // Background/silent + content-available pushes (a tapped alert routes via the UN delegate).
-      applicationDidReceiveRemoteNotificationFetchCompletionHandler(
-        _app: UIApplication,
-        userInfo: NSDictionary<any, any>,
-        completionHandler: (result: UIBackgroundFetchResult) => void
-      ) {
-        onRemoteMessage(userInfo, false);
-        completionHandler(UIBackgroundFetchResult.NewData);
-      },
-    },
-    { protocols: [UIApplicationDelegate] }
-  );
-  Application.ios.delegate = DelegateClass;
+  @NativeClass()
+  class AppWrapAppDelegate extends UIResponder implements UIApplicationDelegate {
+    static ObjCProtocols = [UIApplicationDelegate];
+
+    applicationDidFinishLaunchingWithOptions(_app: UIApplication, launchOptions: NSDictionary<string, any>): boolean {
+      // Set the notification delegate NOW so a cold-launch tap's deep link is delivered.
+      installForegroundNotificationDelegate();
+      // BGTaskScheduler launch handlers MUST be registered here (Apple's rule) — no-op unless the
+      // backgroundTask module is active (the CLI wires the generated bootstrap to the real impl).
+      registerBackgroundLaunchHandlers();
+      const url = launchOptions?.objectForKey(UIApplicationLaunchOptionsURLKey) as NSURL | null;
+      if (url) onDeepLink(url.absoluteString ?? String(url));
+      // Cold-launch from a home-screen quick action — Apple delivers it ONLY here in launchOptions
+      // (performActionForShortcutItem is NOT called for the launch action). Buffered until handshake.
+      const shortcut = launchOptions?.objectForKey(UIApplicationLaunchOptionsShortcutItemKey) as UIApplicationShortcutItem | null;
+      if (shortcut) onShortcut(String(shortcut.type));
+      return true;
+    }
+    // Warm activation of a quick action (app already running/backgrounded).
+    applicationPerformActionForShortcutItemCompletionHandler(
+      _app: UIApplication,
+      shortcutItem: UIApplicationShortcutItem,
+      completionHandler: (done: boolean) => void
+    ): void {
+      onShortcut(String(shortcutItem.type));
+      completionHandler(true);
+    }
+    applicationOpenURLOptions(_app: UIApplication, url: NSURL, _options: NSDictionary<string, any>): boolean {
+      console.log('AppWrap: openURL', url.absoluteString);
+      onDeepLink(url.absoluteString);
+      return true;
+    }
+    // Drives `kit.screen.orientation.lock` — UIKit reads this on every rotation.
+    applicationSupportedInterfaceOrientationsForWindow(_app: UIApplication, _window: UIWindow): UIInterfaceOrientationMask {
+      // iosOrientationMask() returns the raw bitmask as a number; the protocol types it as the enum.
+      return iosOrientationMask() as UIInterfaceOrientationMask;
+    }
+    // ── Remote push (APNs) — delivered to the AppDelegate, bridged to kit.push. ──
+    applicationDidRegisterForRemoteNotificationsWithDeviceToken(_app: UIApplication, deviceToken: NSData): void {
+      onApnsToken(apnsTokenToHex(deviceToken));
+    }
+    applicationDidFailToRegisterForRemoteNotificationsWithError(_app: UIApplication, error: NSError): void {
+      onApnsError(error?.localizedDescription ?? 'APNs registration failed');
+    }
+    // Background/silent + content-available pushes (a tapped alert routes via the UN delegate).
+    applicationDidReceiveRemoteNotificationFetchCompletionHandler(
+      _app: UIApplication,
+      userInfo: NSDictionary<any, any>,
+      completionHandler: (result: UIBackgroundFetchResult) => void
+    ): void {
+      onRemoteMessage(userInfo, false);
+      completionHandler(UIBackgroundFetchResult.NewData);
+    }
+  }
+  Application.ios.delegate = AppWrapAppDelegate;
 }
 
 Application.run({ moduleName: 'main-page' });

package/runtime/app/shell/android-helpers.ts

@@ -1,10 +1,8 @@
 import { Application, Utils } from '@nativescript/core';
 
-declare const android: any, java: any;
-
 let nextCode = 7300;
 
-function foregroundActivity(): any {
+function foregroundActivity() {
   return Application.android.foregroundActivity ?? Application.android.startActivity;
 }
 
@@ -20,6 +18,7 @@ export function requestPermissions(permissions: string[]): Promise<boolean> {
 
   const code = nextCode++;
   return new Promise((resolve) => {
+    // interop: NS activity-event payload is dispatched untyped via Application.android.on
     const onResult = (args: any) => {
       if (args.requestCode !== code) return;
       Application.android.off(Application.android.activityRequestPermissionsEvent as any, onResult);
@@ -32,7 +31,7 @@ export function requestPermissions(permissions: string[]): Promise<boolean> {
 }
 
 /** Decode a content Uri (downscaled to `maxSize` longest edge) into a JPEG data URL. */
-export function uriToDataUrl(uri: any, maxSize: number): string | null {
+export function uriToDataUrl(uri: android.net.Uri, maxSize: number): string | null {
   const cr = Utils.android.getApplicationContext().getContentResolver();
   const bounds = new android.graphics.BitmapFactory.Options();
   bounds.inJustDecodeBounds = true;
@@ -51,7 +50,7 @@ export function uriToDataUrl(uri: any, maxSize: number): string | null {
 }
 
 /** Compress an Android Bitmap to a JPEG data URL. */
-export function bitmapToDataUrl(bmp: any): string {
+export function bitmapToDataUrl(bmp: android.graphics.Bitmap): string {
   const baos = new java.io.ByteArrayOutputStream();
   bmp.compress(android.graphics.Bitmap.CompressFormat.JPEG, 85, baos);
   const b64 = android.util.Base64.encodeToString(baos.toByteArray(), android.util.Base64.NO_WRAP);
@@ -59,12 +58,13 @@ export function bitmapToDataUrl(bmp: any): string {
 }
 
 /** Launch an intent and resolve with its activity result. */
-export function startActivityForResult(intent: any): Promise<{ resultCode: number; intent: any }> {
+export function startActivityForResult(intent: android.content.Intent): Promise<{ resultCode: number; intent: android.content.Intent }> {
   const activity = foregroundActivity();
   if (!activity) return Promise.reject(Object.assign(new Error('no foreground activity'), { code: 'NOT_READY' }));
 
   const code = nextCode++;
   return new Promise((resolve) => {
+    // interop: NS activity-event payload is dispatched untyped via Application.android.on
     const onResult = (args: any) => {
       if (args.requestCode !== code) return;
       Application.android.off(Application.android.activityResultEvent as any, onResult);

package/runtime/app/shell/background-bootstrap.generated.ts

@@ -0,0 +1,8 @@
+/**
+ * Generated by `appwrap init`/`sync`. iOS BGTaskScheduler launch handlers MUST be registered at
+ * `applicationDidFinishLaunchingWithOptions` (Apple's rule) — too early for the page-load handler
+ * barrel. The AppDelegate calls {@link registerBackgroundLaunchHandlers} from didFinishLaunching; the
+ * CLI rewrites this to import the real implementation ONLY when the `backgroundTask` module is active
+ * (so a build without it never references BGTaskScheduler). Default = no-op. Do not edit.
+ */
+export function registerBackgroundLaunchHandlers(): void {}

package/runtime/app/shell/background-context.ts

@@ -0,0 +1,20 @@
+/**
+ * Background-launch context seam — a tiny always-bundled module so the (always-on) `app.handshake`
+ * handler can report a wake id WITHOUT importing the strippable `handlers-background` file (which only
+ * lands when the `backgroundTask` module is active). The headless runner sets the id before loading
+ * the offscreen WebView; the handshake reads it ONCE (so a foreground handshake later in the same
+ * process never re-reports a stale wake). No NativeScript globals → also unit-testable.
+ */
+let pendingBackgroundTaskId: string | null = null;
+
+/** Set by the headless background runner before it loads the offscreen WebView for `id`. */
+export function setPendingBackgroundTaskId(id: string | null): void {
+  pendingBackgroundTaskId = id;
+}
+
+/** Read-and-clear the pending wake id (called by the handshake handler). */
+export function consumePendingBackgroundTaskId(): string | null {
+  const id = pendingBackgroundTaskId;
+  pendingBackgroundTaskId = null;
+  return id;
+}

package/runtime/app/shell/banner.ts

@@ -9,7 +9,7 @@ import { bridge } from './bridge';
 
 let currentId: string | null = null;
 let iosBanner: UIView | null = null;
-let iosTapHandler: any = null;
+let iosTapHandler: any = null; // runtime-built ObjC gesture target (see iosGestureHandlerClass)
 let androidBanner: android.view.View | null = null;
 
 function onTap(): void {
@@ -41,8 +41,13 @@ export function dismissBanner(): void {
 }
 
 // ── iOS ──────────────────────────────────────────────────────────────
-// Built lazily (and only on iOS) — `NSObject`/`interop` don't exist on Android, and this file is
-// imported on both platforms via handlers.ts, so a top-level `.extend` would crash the Android shell.
+// Target/action handler for the banner's tap + swipe-down gestures (bare selectors exposed via
+// `exposedMethods`, no ObjC protocol). Built lazily INSIDE this iOS-only path — `interop` and
+// `NSObject` don't exist on Android, and this file is imported on both platforms via handlers.ts, so
+// a top-level `@NativeClass` with a `static ObjCExposedMethods = { … interop.types.void }` initializer
+// would touch `interop` at module load and crash the Android shell (same reason handlers-scanner keeps
+// its `exposedMethods` cancel-button target as a runtime `.extend` inside its iOS-only registrar).
+// any — runtime-built ObjC subclass; an exposedMethods (non-protocol) target has no static type.
 let IOSGestureHandler: any = null;
 function iosGestureHandlerClass(): any {
   if (!IOSGestureHandler) {
@@ -117,7 +122,7 @@ function showAndroidBanner(message: string): void {
   const SWIPE = 40 * density;
   let downX = 0, downY = 0, downT = 0;
   tv.setOnTouchListener(new android.view.View.OnTouchListener({
-    onTouch(_v: any, e: any) {
+    onTouch(_v: android.view.View, e: android.view.MotionEvent) {
       switch (e.getActionMasked()) {
         case android.view.MotionEvent.ACTION_DOWN:
           downX = e.getRawX(); downY = e.getRawY(); downT = e.getEventTime();

package/runtime/app/shell/bridge.ts

@@ -1,6 +1,8 @@
 import { isAndroid, isIOS } from '@nativescript/core';
 import { CustomWebView } from './custom-webview';
 
+// params: any — the bridge payload is an untyped JSON object decoded from the WebView; each handler
+// narrows it to its own param shape at the call site.
 export type HandlerFn = (params: any) => unknown | Promise<unknown>;
 
 interface RequestEnvelope {

package/runtime/app/shell/capabilities.manifest.ts

@@ -76,10 +76,13 @@ export const MODULES: ModuleManifest[] = [
   { name: 'device', core: true, group: 'extended', capabilities: { device: 'native' } },
   { name: 'clipboard', core: true, group: 'extended', capabilities: { clipboard: 'native' } },
   { name: 'network', core: true, group: 'extended', capabilities: { network: 'native' } },
-  { name: 'screen', core: true, group: 'extended', capabilities: { screen: 'native', dialogs: 'native', orientation: 'native', keyboard: 'native' } },
+  // privacyScreen: hide content in the app-switcher / block screenshots — permission-free, cheap → core.
+  { name: 'screen', core: true, group: 'extended', capabilities: { screen: 'native', dialogs: 'native', orientation: 'native', keyboard: 'native', privacyScreen: { ios: true, android: true } } },
   // badge: app-icon badge via the always-bundled notifications.setBadge handler — iOS sets the
   // springboard badge; Android is an honest no-op (launchers own badges) → ios:true / android:false.
-  { name: 'app', core: true, group: 'system', capabilities: { app: 'native', browser: 'native', badge: { ios: true, android: false } } },
+  // app.canOpenUrl rides the always-native `app` cap (no new key). shortcuts: home-screen quick
+  // actions — iOS UIApplicationShortcutItem / Android dynamic shortcuts (API 25+).
+  { name: 'app', core: true, group: 'system', capabilities: { app: 'native', browser: 'native', badge: { ios: true, android: false }, shortcuts: { ios: true, android: true } } },
 
   // ── opt-in: permission / dependency / weight-bearing ───────────────────
   // POST_NOTIFICATIONS / VIBRATE / USE_BIOMETRIC etc. are in the template's baseline manifest already.
@@ -246,11 +249,27 @@ export const MODULES: ModuleManifest[] = [
     },
     nativeSrc: 'health',
   },
+
+  // ── backgroundTask — headless background execution (HEADLESS JS HANDLER) — opt-in, STRIPPABLE ──
+  // The OS wakes the app (possibly cold, no visible WebView) for a permitted task id; the shell builds
+  // an OFFSCREEN WebView, loads the app conveying the id (the handshake reports it), awaits the JS
+  // handler's `backgroundTask.finish`, then completes + reschedules the OS task. iOS: BGTaskScheduler
+  // (BGAppRefreshTaskRequest / BGProcessingTaskRequest) — NO gradle dep, but Info.plist MUST declare
+  // the permitted identifiers (`appwrap.json.backgroundTasks`, stamped by the CLI) + the fetch/processing
+  // background modes. Android: WorkManager periodic work (the work-runtime dep rides via this module),
+  // self-initialized by its androidx startup provider — nothing mandatory to stamp.
+  // DEVICE-UNVERIFIED: the native background-wake path (offscreen WebView under BGTask / WorkManager)
+  // compiles only; it has NOT been run on a device. See handlers-background.ts.
+  {
+    name: 'backgroundTask', group: 'backgroundTask',
+    capabilities: { backgroundTask: { ios: true, android: true } },
+    android: { gradleDeps: ['androidx.work:work-runtime:2.9.1'] },
+  },
 ];
 
 /** Opt-in registration groups that own their own NS handler file (strippable when inactive). Core
  * groups (core/extended/parity/system/media/billing) are always bundled; only these are CLI-gated. */
-export const OPTIONAL_GROUPS = ['health', 'oauth', 'reviews', 'scanner', 'speech'] as const;
+export const OPTIONAL_GROUPS = ['health', 'oauth', 'reviews', 'scanner', 'speech', 'backgroundTask'] as const;
 
 /** Resolve the active capability map for the handshake from a set of active capability names. */
 export function buildCapabilityMap(

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

@@ -5,7 +5,8 @@ import { APPWRAP_GLOBALS_JS, NATIVE_FEEL_JS, serviceWorkerGuardJs, externalNavGu
 import { envGlobalsJs } from './env';
 import { requestPermissions } from './android-helpers';
 
-declare const android: any, java: any, androidx: any;
+// `android` + `java` resolve to the real types-android namespaces (no declare needed).
+declare const androidx: any; // no NS types: androidx.webkit.* (WebViewFeature/WebViewCompat) not in the android-32 platform typings
 
 /** Stable in-app origin — secure context, ES modules work (file:// blocks them). */
 export const APP_ORIGIN = 'https://appwrap.local';
@@ -42,7 +43,8 @@ export class CustomWebView extends WebView {
 
   initNativeView(): void {
     super.initNativeView();
-    const wv = this.android;
+    // NS core types the `.android` getter as `any`; narrow to the real WebView for this scope.
+    const wv = this.android as android.webkit.WebView;
     if (!wv) return;
 
     // Debug mode only: debuggable via chrome://inspect (full console + network) + keep the screen
@@ -77,7 +79,7 @@ export class CustomWebView extends WebView {
    * is process-wide but harmless with our single WebView. iOS suspends rAF on its own (no-op there).
    */
   setRenderingActive(active: boolean): void {
-    const wv = this.android;
+    const wv = this.android as android.webkit.WebView;
     if (!wv) return;
     try {
       if (active) { wv.onResume(); wv.resumeTimers(); }
@@ -87,11 +89,11 @@ export class CustomWebView extends WebView {
     }
   }
 
-  private installDocumentStartShim(wv: any): void {
+  private installDocumentStartShim(wv: android.webkit.WebView): void {
     try {
       const wkt = androidx.webkit;
       if (wkt.WebViewFeature.isFeatureSupported(wkt.WebViewFeature.DOCUMENT_START_SCRIPT)) {
-        const rules = new java.util.HashSet();
+        const rules = new java.util.HashSet<string>();
         rules.add(APP_ORIGIN);
         wkt.WebViewCompat.addDocumentStartJavaScript(wv, buildBootstrapJs(), rules);
         return;
@@ -102,13 +104,20 @@ export class CustomWebView extends WebView {
     }
   }
 
-  private createTransportChromeClient(): any {
+  private createTransportChromeClient(): android.webkit.WebChromeClient {
     const owner = new WeakRef<CustomWebView>(this);
+    // NS runtime adds `.extend` on Java classes; it's not in the static typings, hence the cast.
     const ChromeClient = (android.webkit.WebChromeClient as any).extend({
-      onJsPrompt(_view: any, _url: string, message: string, _defaultValue: string, result: any): boolean {
+      onJsPrompt(
+        _view: android.webkit.WebView,
+        _url: string,
+        message: string,
+        _defaultValue: string,
+        result: android.webkit.JsPromptResult
+      ): boolean {
         if (typeof message === 'string' && message.startsWith(PROMPT_PREFIX)) {
           result.confirm('');
-          const view = owner.get ? owner.get() : (owner as any).deref();
+          const view = owner.get ? owner.get() : (owner as { deref(): CustomWebView }).deref();
           view?.onAppwrapMessage?.(message.slice(PROMPT_PREFIX.length));
           return true;
         }
@@ -117,7 +126,7 @@ export class CustomWebView extends WebView {
 
       // getUserMedia: grant the WebView's per-origin capture after ensuring the
       // app holds the matching OS runtime permission (CAMERA / RECORD_AUDIO).
-      onPermissionRequest(request: any): void {
+      onPermissionRequest(request: android.webkit.PermissionRequest): void {
         const PR = android.webkit.PermissionRequest;
         const resources: string[] = Array.from(request.getResources());
         const perms = new Set<string>();
@@ -139,14 +148,15 @@ export class CustomWebView extends WebView {
 }
 
 /** https://appwrap.local/<path> → file under www/; SPA fallback to the entry for extension-less misses. */
-function createAssetServingClient(): any {
+function createAssetServingClient(): android.webkit.WebViewClient {
   const wwwPath = nsPath.join(knownFolders.currentApp().path, 'www');
 
-  const respond = (filePath: string, ext: string) => {
+  const respond = (filePath: string, ext: string): android.webkit.WebResourceResponse => {
     const stream = new java.io.FileInputStream(filePath);
     return new android.webkit.WebResourceResponse(mimeFor(ext, filePath), 'utf-8', stream);
   };
 
+  // (Array as any).create is the NS interop helper for native byte[]; not in lib typings.
   const emptyStream = () => new java.io.ByteArrayInputStream((Array as any).create('byte', 0));
 
   /**
@@ -164,10 +174,16 @@ function createAssetServingClient(): any {
    * (GET/HEAD) are proxied — POST/PUT/PATCH return 501 rather than silently sending an empty body.
    * (BodDB writes ride the WS, not HTTP POST, so this is rarely hit.)
    */
-  const proxyToBackend = (rel: string, query: string, ext: string, method: string, headers: any): any => {
+  const proxyToBackend = (
+    rel: string,
+    query: string,
+    ext: string,
+    method: string,
+    headers: java.util.Map<string, string> | null
+  ): android.webkit.WebResourceResponse => {
     if (method !== 'GET' && method !== 'HEAD') {
       return new android.webkit.WebResourceResponse(
-        'text/plain', 'utf-8', 501, 'Not Implemented', new java.util.HashMap(),
+        'text/plain', 'utf-8', 501, 'Not Implemented', new java.util.HashMap<string, string>(),
         new java.io.ByteArrayInputStream(new java.lang.String(
           'appwrap Android shell cannot proxy request bodies (shouldInterceptRequest limitation)'
         ).getBytes('UTF-8'))
@@ -178,9 +194,10 @@ function createAssetServingClient(): any {
     const target = `${SHELL_CONFIG.backendOrigin.replace(/\/+$/, '')}/${rel}${query}`;
     const pump = new java.lang.Runnable({
       run() {
-        let is: any = null;
+        let is: java.io.InputStream | null = null;
         try {
-          const conn = new java.net.URL(target).openConnection();
+          // openConnection() statically returns URLConnection; for http(s) it's an HttpURLConnection.
+          const conn = new java.net.URL(target).openConnection() as java.net.HttpURLConnection;
           conn.setRequestMethod(method);
           conn.setInstanceFollowRedirects(true);
           conn.setConnectTimeout(15000);
@@ -209,17 +226,22 @@ function createAssetServingClient(): any {
       },
     });
     new java.lang.Thread(pump).start();
-    const outHeaders = new java.util.HashMap();
+    const outHeaders = new java.util.HashMap<string, string>();
     outHeaders.put('Access-Control-Allow-Origin', '*');
     outHeaders.put('Cache-Control', 'no-cache');
     // mime/charset best-effort from the path; status 200 (real status is unknown until the bg read).
     return new android.webkit.WebResourceResponse(mimeFor(ext, rel), 'utf-8', 200, 'OK', outHeaders, pin);
   };
 
+  // NS runtime adds `.extend` on Java classes; it's not in the static typings, hence the cast.
   const Client = (android.webkit.WebViewClient as any).extend({
-    shouldInterceptRequest(_view: any, request: any): any {
-      const isObj = typeof request !== 'string';
-      const url: string = isObj ? String(request.getUrl().toString()) : request;
+    // 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 {
+      const url: string = typeof request !== 'string' ? String(request.getUrl().toString()) : request;
       if (!url.startsWith(APP_ORIGIN)) return null; // external — let WebView handle it
 
       const tail = url.slice(APP_ORIGIN.length);
@@ -239,25 +261,30 @@ function createAssetServingClient(): any {
       // Not a local asset → proxy to the backend (mirror of iOS), making relative
       // backend/vendor requests same-origin under app://appwrap.local.
       if (SHELL_CONFIG.backendOrigin) {
+        const isObj = typeof request !== 'string';
         const method = (isObj && request.getMethod && String(request.getMethod())) || 'GET';
         const headers = isObj && request.getRequestHeaders ? request.getRequestHeaders() : null;
         return proxyToBackend(rel, query, ext, method.toUpperCase(), headers);
       }
       return new android.webkit.WebResourceResponse(
-        'text/plain', 'utf-8', 404, 'Not Found', new java.util.HashMap(), emptyStream()
+        'text/plain', 'utf-8', 404, 'Not Found', new java.util.HashMap<string, string>(), emptyStream()
       );
     },
 
-    onPageStarted(view: any, _url: string, _favicon: any): void {
+    onPageStarted(view: android.webkit.WebView, _url: string, _favicon: android.graphics.Bitmap): void {
       // Fallback injection — no-op when the document-start scripts already ran
-      view.evaluateJavascript(buildBootstrapJs(), null);
+      view.evaluateJavascript(buildBootstrapJs(), null as unknown as android.webkit.ValueCallback<string>);
     },
 
     // `appwrap dev` points at a LAN dev server that almost always uses a self-signed / mkcert TLS
     // cert the device's trust store doesn't know — the WebView would otherwise hard-fail with
     // ERR_CERT_AUTHORITY_INVALID. Proceed past it ONLY in a debug build AND only when actually in
     // server-loader (dev) mode. Production app:// builds never reach this (local assets, no TLS).
-    onReceivedSslError(_view: any, handler: any, error: any): void {
+    onReceivedSslError(
+      _view: android.webkit.WebView,
+      handler: android.webkit.SslErrorHandler,
+      error: android.net.http.SslError
+    ): void {
       if (SHELL_CONFIG.debug && SHELL_CONFIG.loader === 'server') {
         console.warn('AppWrap: proceeding past dev-server SSL error (debug+server only):', String(error));
         handler.proceed();