@livx.cc/appwrap 0.26.0 → 0.28.1

package/runtime/app/shell/ios-ui-delegate.ts

@@ -12,118 +12,122 @@ import { Utils } from '@nativescript/core';
  *
  * Returns a retained delegate instance (the WKWebView holds uiDelegate weakly).
  */
-export function createUiDelegate(): any {
-  const DelegateClass = (NSObject as any).extend(
-    {
-      // iOS 15+: WKUIDelegate media capture permission.
-      webViewRequestMediaCapturePermissionForOriginInitiatedByFrameTypeDecisionHandler(
-        _webView: WKWebView,
-        _origin: any,
-        _frame: any,
-        _type: any,
-        decisionHandler: (decision: number) => void
-      ): void {
-        // WKPermissionDecision.Grant === 1 — silently grant (the app already holds the
-        // OS-level mic/camera permission; media.ensurePermission established TCC).
-        // NOTE: this only ever sees capabilities the build DECLARED — a request for an
-        // UNDECLARED capability is rejected upstream in JS (mediaCaptureGuardJs), because
-        // WebKit asks TCC to authorize the device AROUND this callback and a missing usage
-        // string is a hard process-kill a native `deny` here cannot prevent. So denying
-        // here is pointless for the crash; the real guard must be (and is) at the JS layer.
-        decisionHandler(1);
-      },
+@NativeClass()
+class AppwrapUiDelegate extends NSObject implements WKUIDelegate {
+  static ObjCProtocols = [WKUIDelegate];
+  static new(): AppwrapUiDelegate {
+    return <AppwrapUiDelegate>super.new();
+  }
 
-      // Preserve the behavior NS's own UIDelegate gave us (we fully replace it):
-      // target=_blank / window.open has no new window in a shell → load it in place.
-      webViewCreateWebViewWithConfigurationForNavigationActionWindowFeatures(
-        webView: WKWebView,
-        _configuration: any,
-        navigationAction: WKNavigationAction,
-        _windowFeatures: any
-      ): WKWebView | null {
-        const frame = navigationAction.targetFrame;
-        if (!frame || !frame.mainFrame) webView.loadRequest(navigationAction.request);
-        return null;
-      },
+  // iOS 15+: WKUIDelegate media capture permission.
+  webViewRequestMediaCapturePermissionForOriginInitiatedByFrameTypeDecisionHandler(
+    _webView: WKWebView,
+    _origin: WKSecurityOrigin,
+    _frame: WKFrameInfo,
+    _type: WKMediaCaptureType,
+    decisionHandler: (decision: WKPermissionDecision) => void
+  ): void {
+    // WKPermissionDecision.Grant === 1 — silently grant (the app already holds the
+    // OS-level mic/camera permission; media.ensurePermission established TCC).
+    // NOTE: this only ever sees capabilities the build DECLARED — a request for an
+    // UNDECLARED capability is rejected upstream in JS (mediaCaptureGuardJs), because
+    // WebKit asks TCC to authorize the device AROUND this callback and a missing usage
+    // string is a hard process-kill a native `deny` here cannot prevent. So denying
+    // here is pointless for the crash; the real guard must be (and is) at the JS layer.
+    decisionHandler(WKPermissionDecision.Grant);
+  }
 
-      webViewRunJavaScriptAlertPanelWithMessageInitiatedByFrameCompletionHandler(
-        _webView: WKWebView,
-        message: string,
-        _frame: any,
-        completionHandler: () => void
-      ): void {
-        Utils.dispatchToMainThread(() => {
-          const alert = UIAlertController.alertControllerWithTitleMessagePreferredStyle(
-            null as any,
-            String(message ?? ''),
-            UIAlertControllerStyle.Alert
-          );
-          alert.addAction(
-            UIAlertAction.actionWithTitleStyleHandler('OK', UIAlertActionStyle.Default, () => completionHandler())
-          );
-          present(alert);
-        });
-      },
+  // Preserve the behavior NS's own UIDelegate gave us (we fully replace it):
+  // target=_blank / window.open has no new window in a shell → load it in place.
+  webViewCreateWebViewWithConfigurationForNavigationActionWindowFeatures(
+    webView: WKWebView,
+    _configuration: WKWebViewConfiguration,
+    navigationAction: WKNavigationAction,
+    _windowFeatures: WKWindowFeatures
+  ): WKWebView {
+    const frame = navigationAction.targetFrame;
+    if (!frame || !frame.mainFrame) webView.loadRequest(navigationAction.request);
+    return null as unknown as WKWebView;
+  }
 
-      webViewRunJavaScriptConfirmPanelWithMessageInitiatedByFrameCompletionHandler(
-        _webView: WKWebView,
-        message: string,
-        _frame: any,
-        completionHandler: (ok: boolean) => void
-      ): void {
-        Utils.dispatchToMainThread(() => {
-          const alert = UIAlertController.alertControllerWithTitleMessagePreferredStyle(
-            null as any,
-            String(message ?? ''),
-            UIAlertControllerStyle.Alert
-          );
-          alert.addAction(
-            UIAlertAction.actionWithTitleStyleHandler('Cancel', UIAlertActionStyle.Cancel, () =>
-              completionHandler(false)
-            )
-          );
-          alert.addAction(
-            UIAlertAction.actionWithTitleStyleHandler('OK', UIAlertActionStyle.Default, () => completionHandler(true))
-          );
-          present(alert);
-        });
-      },
+  webViewRunJavaScriptAlertPanelWithMessageInitiatedByFrameCompletionHandler(
+    _webView: WKWebView,
+    message: string,
+    _frame: WKFrameInfo,
+    completionHandler: () => void
+  ): void {
+    Utils.dispatchToMainThread(() => {
+      const alert = UIAlertController.alertControllerWithTitleMessagePreferredStyle(
+        null as unknown as string,
+        String(message ?? ''),
+        UIAlertControllerStyle.Alert
+      );
+      alert.addAction(
+        UIAlertAction.actionWithTitleStyleHandler('OK', UIAlertActionStyle.Default, () => completionHandler())
+      );
+      present(alert);
+    });
+  }
 
-      webViewRunJavaScriptTextInputPanelWithPromptDefaultTextInitiatedByFrameCompletionHandler(
-        _webView: WKWebView,
-        prompt: string,
-        defaultText: string,
-        _frame: any,
-        completionHandler: (text: string | null) => void
-      ): void {
-        Utils.dispatchToMainThread(() => {
-          const alert = UIAlertController.alertControllerWithTitleMessagePreferredStyle(
-            null as any,
-            String(prompt ?? ''),
-            UIAlertControllerStyle.Alert
-          );
-          let field: UITextField | null = null;
-          alert.addTextFieldWithConfigurationHandler((tf: UITextField) => {
-            tf.text = String(defaultText ?? '');
-            field = tf;
-          });
-          alert.addAction(
-            UIAlertAction.actionWithTitleStyleHandler('Cancel', UIAlertActionStyle.Cancel, () =>
-              completionHandler(null)
-            )
-          );
-          alert.addAction(
-            UIAlertAction.actionWithTitleStyleHandler('OK', UIAlertActionStyle.Default, () =>
-              completionHandler(field ? String(field.text ?? '') : '')
-            )
-          );
-          present(alert);
-        });
-      },
-    },
-    { protocols: [WKUIDelegate] }
-  );
-  return DelegateClass.new();
+  webViewRunJavaScriptConfirmPanelWithMessageInitiatedByFrameCompletionHandler(
+    _webView: WKWebView,
+    message: string,
+    _frame: WKFrameInfo,
+    completionHandler: (ok: boolean) => void
+  ): void {
+    Utils.dispatchToMainThread(() => {
+      const alert = UIAlertController.alertControllerWithTitleMessagePreferredStyle(
+        null as unknown as string,
+        String(message ?? ''),
+        UIAlertControllerStyle.Alert
+      );
+      alert.addAction(
+        UIAlertAction.actionWithTitleStyleHandler('Cancel', UIAlertActionStyle.Cancel, () =>
+          completionHandler(false)
+        )
+      );
+      alert.addAction(
+        UIAlertAction.actionWithTitleStyleHandler('OK', UIAlertActionStyle.Default, () => completionHandler(true))
+      );
+      present(alert);
+    });
+  }
+
+  webViewRunJavaScriptTextInputPanelWithPromptDefaultTextInitiatedByFrameCompletionHandler(
+    _webView: WKWebView,
+    prompt: string,
+    defaultText: string,
+    _frame: WKFrameInfo,
+    completionHandler: (text: string) => void
+  ): void {
+    Utils.dispatchToMainThread(() => {
+      const alert = UIAlertController.alertControllerWithTitleMessagePreferredStyle(
+        null as unknown as string,
+        String(prompt ?? ''),
+        UIAlertControllerStyle.Alert
+      );
+      let field: UITextField | null = null;
+      alert.addTextFieldWithConfigurationHandler((tf: UITextField) => {
+        tf.text = String(defaultText ?? '');
+        field = tf;
+      });
+      alert.addAction(
+        UIAlertAction.actionWithTitleStyleHandler('Cancel', UIAlertActionStyle.Cancel, () =>
+          completionHandler(null as unknown as string)
+        )
+      );
+      alert.addAction(
+        UIAlertAction.actionWithTitleStyleHandler('OK', UIAlertActionStyle.Default, () =>
+          completionHandler(field ? String(field.text ?? '') : '')
+        )
+      );
+      present(alert);
+    });
+  }
+}
+
+export function createUiDelegate(): WKUIDelegate {
+  return AppwrapUiDelegate.new();
 }
 
 function present(alert: UIAlertController): void {

package/runtime/app/shell/native-log.ts

@@ -1,7 +1,5 @@
 import { knownFolders, path as nsPath } from '@nativescript/core';
 
-declare const NSString: any;
-
 /**
  * Single debug log sink → Documents/appwrap-web.log. Both the forwarded WebView console
  * (custom-webview) and native shell diagnostics (handlers) write here, because NativeScript's
@@ -15,7 +13,7 @@ export function appwrapNativeLog(line: string): void {
     _log += line + '\n';
     if (_log.length > 160000) _log = _log.slice(-120000);
     const p = nsPath.join(knownFolders.documents().path, 'appwrap-web.log');
-    NSString.stringWithString(_log).writeToFileAtomicallyEncodingError(p, true, 4 /*NSUTF8*/, null as any);
+    NSString.stringWithString(_log).writeToFileAtomicallyEncodingError(p, true, 4 /*NSUTF8*/);
   } catch {
     /* best-effort */
   }

package/runtime/app/shell/status-bar.ts

@@ -28,7 +28,7 @@ export function enableAndroidEdgeToEdge(): void {
     try {
       // Explicit transparent status-bar colors (light + dark) so the page background — not the NS
       // page backgroundColor — shows under the status bar. Nav bar keeps NS's default subtle scrim.
-      (Utils as any).android.enableEdgeToEdge(activity, {
+      Utils.android.enableEdgeToEdge(activity, {
         statusBarLightColor: transparent,
         statusBarDarkColor: transparent,
       });
@@ -55,6 +55,7 @@ export function wireAndroidSafeArea(webView: View): void {
   // Un-box the layout that wraps the WebView so it (and its child WebView) fills the window UNDER the
   // bars. 'dont-apply' = NS won't pad it with the system-bar insets.
   const layout = (webView.parent as View) ?? webView;
+  // androidOverflowEdge: not in the public View typings — an NS edge-to-edge layout hint set dynamically.
   (layout as any).androidOverflowEdge = 'dont-apply';
 
   const density = Screen.mainScreen.scale || 1; // physical px per dp
@@ -65,7 +66,8 @@ export function wireAndroidSafeArea(webView: View): void {
       `s.setProperty('--saie-right','${r}px');s.setProperty('--saie-bottom','${b}px');` +
       `})(document.documentElement.style);`;
     try {
-      (webView as any).android?.evaluateJavascript(js, null);
+      // webView.android is typed `any` by NS core; on Android it's an android.webkit.WebView.
+      webView.android?.evaluateJavascript(js, null);
     } catch (e) {
       console.warn('AppWrap: safe-area inject failed', e);
     }
@@ -82,7 +84,7 @@ export function wireAndroidSafeArea(webView: View): void {
       const decor = Application.android?.startActivity?.getWindow()?.getDecorView();
       const wi = decor?.getRootWindowInsets?.();
       if (!wi) return false;
-      const Type = (global as any).android.view.WindowInsets.Type;
+      const Type = android.view.WindowInsets.Type;
       const ins = wi.getInsets(Type.systemBars() | Type.displayCutout());
       inject(dp(ins.left), dp(ins.top), dp(ins.right), dp(ins.bottom));
       return ins.top + ins.bottom + ins.left + ins.right > 0;
@@ -132,12 +134,13 @@ export function applyThemeColor(color: string): void {
 /** 'light' = white icons/text (for dark backgrounds), 'dark' = black. */
 export function setStatusBarStyle(style: 'light' | 'dark'): void {
   if (isIOS) {
+    // statusBarStyle is a CSS-backed Page property, not on the public Page type — set dynamically.
     if (currentPage) (currentPage as any).statusBarStyle = style;
   } else if (isAndroid) {
     const window = Application.android?.startActivity?.getWindow();
     if (!window) return;
     const decorView = window.getDecorView();
-    const controller = (decorView as any).getWindowInsetsController?.();
+    const controller = decorView.getWindowInsetsController?.();
     if (controller) {
       const APPEARANCE_LIGHT_STATUS_BARS = 8; // WindowInsetsController.APPEARANCE_LIGHT_STATUS_BARS
       // Android "light status bar" = dark icons; invert from our naming

package/runtime/app/shell/toast.ts

@@ -4,7 +4,7 @@ import { Utils, isAndroid, isIOS } from '@nativescript/core';
 export function showToast(message: string, duration: 'short' | 'long' = 'short'): void {
   const ms = duration === 'long' ? 3500 : 2000;
   if (isAndroid) {
-    const Toast = (android as any).widget.Toast;
+    const Toast = android.widget.Toast;
     Toast.makeText(
       Utils.android.getApplicationContext(),
       message,

package/runtime/references.d.ts

@@ -1,2 +1,23 @@
 /// <reference path="./node_modules/@nativescript/types-ios/index.d.ts" />
 /// <reference path="./node_modules/@nativescript/types-android/lib/android-32.d.ts" />
+
+// Opt-in iOS framework typings the shell's native handlers use. @nativescript/types-ios ships the FULL
+// SDK but its default index references only a curated subset (for IDE/compile speed); reference the
+// extras here so handlers get real types + autocomplete instead of `any`. (NativeScript-documented:
+// blog.nativescript.org/where-did-my-types-go) Path arch ('objc-x86_64') is where they were generated;
+// the API surface is arch-independent for type-checking.
+/// <reference path="./node_modules/@nativescript/types-ios/lib/ios/objc-x86_64/objc!Contacts.d.ts" />
+/// <reference path="./node_modules/@nativescript/types-ios/lib/ios/objc-x86_64/objc!ContactsUI.d.ts" />
+/// <reference path="./node_modules/@nativescript/types-ios/lib/ios/objc-x86_64/objc!HealthKit.d.ts" />
+/// <reference path="./node_modules/@nativescript/types-ios/lib/ios/objc-x86_64/objc!EventKit.d.ts" />
+/// <reference path="./node_modules/@nativescript/types-ios/lib/ios/objc-x86_64/objc!CoreMotion.d.ts" />
+/// <reference path="./node_modules/@nativescript/types-ios/lib/ios/objc-x86_64/objc!StoreKit.d.ts" />
+/// <reference path="./node_modules/@nativescript/types-ios/lib/ios/objc-x86_64/objc!LocalAuthentication.d.ts" />
+/// <reference path="./node_modules/@nativescript/types-ios/lib/ios/objc-x86_64/objc!PhotosUI.d.ts" />
+/// <reference path="./node_modules/@nativescript/types-ios/lib/ios/objc-x86_64/objc!_LocationEssentials.d.ts" />
+/// <reference path="./node_modules/@nativescript/types-ios/lib/ios/objc-x86_64/objc!CoreLocation.d.ts" />
+/// <reference path="./node_modules/@nativescript/types-ios/lib/ios/objc-x86_64/objc!AVFoundation.d.ts" />
+/// <reference path="./node_modules/@nativescript/types-ios/lib/ios/objc-x86_64/objc!Speech.d.ts" />
+/// <reference path="./node_modules/@nativescript/types-ios/lib/ios/objc-x86_64/objc!BackgroundTasks.d.ts" />
+/// <reference path="./node_modules/@nativescript/types-ios/lib/ios/objc-x86_64/objc!AuthenticationServices.d.ts" />
+/// <reference path="./node_modules/@nativescript/types-ios/lib/ios/objc-x86_64/objc!Photos.d.ts" />

package/runtime/tsconfig.json

@@ -5,6 +5,7 @@
     "moduleResolution": "bundler",
     "lib": ["es2021", "dom"],
     "experimentalDecorators": true,
+    "noImplicitAny": true,
     "removeComments": false,
     "noEmitHelpers": true,
     "noEmitOnError": true,

package/src/cli.ts

@@ -25,8 +25,25 @@ import {
   iosOrientations,
   mergeManifest,
   stampAndroidOrientation,
+  stampAndroidQueries,
+  stampPlistBackgroundTasks,
   stampPlistOrientations,
 } from './derive';
+import type { WebManifest } from './derive';
+
+/** What `child_process.execFileSync` attaches to the Error it throws on a non-zero exit
+ * (stdout/stderr are Buffer with the default encoding, string when `encoding` is set). */
+interface ExecError extends Error {
+  stdout?: string | Buffer;
+  stderr?: string | Buffer;
+  status?: number | null;
+}
+const asExecError = (e: unknown): ExecError => (e ?? {}) as ExecError;
+/** Combined stdout+stderr captured on an exec failure (empty string when none). */
+const execErrText = (e: unknown): string => {
+  const err = asExecError(e);
+  return `${err.stdout ?? ''}${err.stderr ?? ''}`;
+};
 
 /** Marketing version → a monotonic integer build (0.2.1 → 201; 1.4.12 → 10412). Stable & increasing
  * across semver bumps so store re-uploads are always accepted without a manual bump. */
@@ -175,6 +192,7 @@ const OPTIONAL_GROUP_HANDLERS: Record<string, { file: string; fn: string }> = {
   reviews: { file: './handlers-reviews', fn: 'registerReviewsHandlers' },
   scanner: { file: './handlers-scanner', fn: 'registerScannerHandlers' },
   speech: { file: './handlers-speech', fn: 'registerSpeechHandlers' },
+  backgroundTask: { file: './handlers-background', fn: 'registerBackgroundTaskHandlers' },
 };
 
 /** Generate the two composition artifacts in the wrapper: the active capability list (drives the
@@ -195,6 +213,18 @@ function generateModuleArtifacts(outDir: string, req: NativeReqs): void {
     `/** Generated by \`appwrap\` — only the active strippable modules are imported. Do not edit. */\n` +
       `${imports}${imports ? '\n' : ''}\nexport function registerOptionalHandlers(): void {\n${calls}\n}\n`
   );
+
+  // iOS BGTaskScheduler launch handlers must register at didFinishLaunching (the AppDelegate calls
+  // registerBackgroundLaunchHandlers) — too early for the page-load barrel. Wire the real impl ONLY
+  // when backgroundTask is active, so a build without it never references BGTaskScheduler. No-op default.
+  const bgActive = req.activeOptionalGroups.includes('backgroundTask');
+  writeFileSync(
+    join(shell, 'background-bootstrap.generated.ts'),
+    `/** Generated by \`appwrap\` — wires the iOS BGTask launch handlers only when backgroundTask is active. Do not edit. */\n` +
+      (bgActive
+        ? `export { registerBackgroundTaskLaunchHandlers as registerBackgroundLaunchHandlers } from './handlers-background';\n`
+        : `export function registerBackgroundLaunchHandlers(): void {}\n`)
+  );
 }
 
 /** Stamp the active modules' gradle dependencies into Android app.gradle. Idempotent marker block. */
@@ -286,15 +316,15 @@ function parseArgs(argv: string[]) {
 }
 
 /** Parse the PWA's web manifest (manifest.json / .webmanifest) from the dist dir, or null. */
-function loadManifest(cwd: string, cfg: AppwrapConfig): Record<string, any> | null {
+function loadManifest(cwd: string, cfg: AppwrapConfig): WebManifest | null {
   const dist = resolve(cwd, cfg.pwaDist);
   for (const name of ['manifest.json', 'manifest.webmanifest']) {
     const mf = join(dist, name);
     if (!existsSync(mf)) continue;
     try {
       return JSON.parse(readFileSync(mf, 'utf8'));
-    } catch (e: any) {
-      console.warn(`⚠ Could not parse ${name}: ${e.message}`);
+    } catch (e: unknown) {
+      console.warn(`⚠ Could not parse ${name}: ${e instanceof Error ? e.message : String(e)}`);
     }
   }
   return null;
@@ -398,6 +428,12 @@ function stampIOSDisplayName(outDir: string, cfg: AppwrapConfig, req: NativeReqs
   // arrays (iPhone + ~ipad). Skipped when unset → keep the template's free-rotation default.
   if (cfg.orientation) src = stampPlistOrientations(src, iosOrientations(cfg.orientation));
 
+  // Headless background tasks (backgroundTask module): stamp BGTaskSchedulerPermittedIdentifiers +
+  // fetch/processing background modes from `backgroundTasks`. Idempotent both ways — passing []/undefined
+  // strips the block — so it no-ops (and cleans up) when the module is inactive or the field is absent.
+  const bgActive = req.activeOptionalGroups.includes('backgroundTask');
+  src = stampPlistBackgroundTasks(src, bgActive ? cfg.backgroundTasks : undefined);
+
   // Permission usage strings + URL scheme + export-compliance — idempotent: strip stamped block, re-add
   src = src.replace(/\s*<!-- appwrap:begin -->[\s\S]*?<!-- appwrap:end -->/g, '');
   const extras: string[] = [];
@@ -412,6 +448,12 @@ function stampIOSDisplayName(outDir: string, cfg: AppwrapConfig, req: NativeReqs
       `  <key>CFBundleURLTypes</key>\n  <array>\n    <dict>\n      <key>CFBundleTypeRole</key>\n      <string>Editor</string>\n      <key>CFBundleURLName</key>\n      <string>${cfg.id}</string>\n      <key>CFBundleURLSchemes</key>\n      <array>\n        <string>${cfg.urlScheme}</string>\n      </array>\n    </dict>\n  </array>`
     );
   }
+  // Schemes kit.app.canOpenUrl() may probe → LSApplicationQueriesSchemes (iOS 9+ requires declaration
+  // for custom schemes). No-op when absent.
+  if (cfg.queryUrlSchemes?.length) {
+    const items = cfg.queryUrlSchemes.map((s) => `    <string>${s}</string>`).join('\n');
+    extras.push(`  <key>LSApplicationQueriesSchemes</key>\n  <array>\n${items}\n  </array>`);
+  }
   if (extras.length) {
     src = src.replace(
       /<\/dict>\s*<\/plist>\s*$/,
@@ -644,6 +686,10 @@ function stampAndroidAppName(outDir: string, cfg: AppwrapConfig, req: NativeReqs
       /<!-- appwrap:application -->[\s\S]*?<!-- \/appwrap:application -->/,
       `<!-- appwrap:application -->\n\t\t${req.androidManifestApp.join('\n\t\t')}\n\t\t<!-- /appwrap:application -->`
     );
+    // <queries> for kit.app.canOpenUrl() visibility probes (API 30+) — idempotent marker. queryPackages
+    // → explicit <package>; queryUrlSchemes → a VIEW <intent> per scheme (symmetric with iOS's
+    // LSApplicationQueriesSchemes). See stampAndroidQueries.
+    src = stampAndroidQueries(src, cfg.queryPackages, cfg.queryUrlSchemes);
     writeFileSync(manifest, src);
   }
 }
@@ -845,13 +891,13 @@ function vendorBackendAssets(www: string, cfg: AppwrapConfig): void {
     // Retry a couple times (the backend can briefly reset under deploy/cold-start), and on total
     // failure fall back to the cached copy if one exists rather than breaking the whole sync.
     let ok = false;
-    let lastErr: any;
+    let lastErr: unknown;
     for (let attempt = 0; attempt < 3 && !ok; attempt++) {
       try {
         execFileSync('curl', ['-fsSL', '--retry', '2', url, '-o', tmp], { stdio: 'pipe' });
         cpSync(tmp, dest);
         ok = true;
-      } catch (e: any) {
+      } catch (e: unknown) {
         lastErr = e;
       }
     }
@@ -860,10 +906,12 @@ function vendorBackendAssets(www: string, cfg: AppwrapConfig): void {
       console.log(`  vendor ← ${url}`);
     } else if (existsSync(dest) && readFileSync(dest).length > 0) {
       console.warn(`⚠ vendor fetch failed: ${url} — using cached copy (backend unreachable).`);
-      if (lastErr?.stderr) console.warn(`  ${String(lastErr.stderr).trim()}`);
+      const err = execErrText(lastErr);
+      if (err) console.warn(`  ${err.trim()}`);
     } else {
       console.error(`✖ vendor fetch failed: ${url} (backend reachable? path correct?) — no cached copy to fall back to`);
-      if (lastErr?.stderr) console.error(String(lastErr.stderr).trim());
+      const err = execErrText(lastErr);
+      if (err) console.error(err.trim());
       process.exit(1);
     }
   }
@@ -1090,19 +1138,27 @@ async function build(cwd: string, flags: Record<string, string>, positionals: st
 
 interface DeviceInfo { id: string; name: string; model: string; transport: string }
 
+/** The subset of a `xcrun devicectl list devices --json-output` device entry appwrap reads. */
+interface DevicectlDevice {
+  identifier?: string;
+  deviceProperties?: { name?: string };
+  hardwareProperties?: { platform?: string; marketingName?: string; productType?: string };
+  connectionProperties?: { tunnelState?: string; transportType?: string };
+}
+
 /** Discover usable physical iOS devices via devicectl (USB + network). Excludes 'unavailable'
  * tunnels and non-iOS (watch). Returns [] if none. */
 function listIosDevices(): DeviceInfo[] {
   const out = join(tmpdir(), `appwrap-devices-${process.pid}.json`);
   try {
     execFileSync('xcrun', ['devicectl', 'list', 'devices', '--json-output', out], { stdio: 'pipe' });
-    const j = JSON.parse(readFileSync(out, 'utf8'));
+    const j = JSON.parse(readFileSync(out, 'utf8')) as { result?: { devices?: DevicectlDevice[] } };
     rmSync(out, { force: true });
     return (j?.result?.devices ?? [])
-      .filter((d: any) => d?.hardwareProperties?.platform === 'iOS'
+      .filter((d) => d?.hardwareProperties?.platform === 'iOS'
         && d?.connectionProperties?.tunnelState !== 'unavailable')
-      .map((d: any) => ({
-        id: d.identifier,
+      .map((d) => ({
+        id: d.identifier ?? '',
         name: d?.deviceProperties?.name ?? '(unknown)',
         model: d?.hardwareProperties?.marketingName ?? d?.hardwareProperties?.productType ?? '',
         transport: d?.connectionProperties?.transportType ?? '',
@@ -1129,7 +1185,7 @@ function pickDevice(devices: DeviceInfo[], explicitId?: string): DeviceInfo {
   }
   console.log('Multiple devices connected:');
   devices.forEach((d, i) => console.log(`  ${i + 1}) ${d.name} — ${d.model || 'iPhone'} [${d.transport}]`));
-  const ans = (globalThis as any).prompt(`Select device [1-${devices.length}]: `);
+  const ans = (globalThis as { prompt(msg?: string): string | null }).prompt(`Select device [1-${devices.length}]: `);
   const idx = Number(ans) - 1;
   if (!Number.isInteger(idx) || idx < 0 || idx >= devices.length) {
     console.error('✖ Invalid selection.'); process.exit(1);
@@ -1192,8 +1248,8 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
       execFileSync('xcrun', ['devicectl', 'device', 'install', 'app', '--timeout', '25', '--device', device.id, ipaPath], { encoding: 'utf8', stdio: ['inherit', 'pipe', 'pipe'] })
     );
     process.stdout.write(out);
-  } catch (e: any) {
-    const log = `${e?.stdout ?? ''}${e?.stderr ?? ''}`;
+  } catch (e: unknown) {
+    const log = execErrText(e);
     process.stderr.write(log);
     if (/maximum number of installed apps|MIInstallerErrorDomain error 13|ApplicationVerificationFailed/.test(log)) {
       // Free Apple developer profile caps a device at 3 app IDs — a sibling appwrap/WDA build often eats a slot.
@@ -1255,8 +1311,8 @@ function usbmuxInstall(ipaPath: string): boolean {
     const out = execFileSync('ideviceinstaller', ['install', ipaPath], { encoding: 'utf8', stdio: ['inherit', 'pipe', 'pipe'] });
     process.stdout.write(out);
     return /Complete|Installed/i.test(out);
-  } catch (e: any) {
-    process.stderr.write(`${e?.stdout ?? ''}${e?.stderr ?? ''}`);
+  } catch (e: unknown) {
+    process.stderr.write(execErrText(e));
     return false;
   }
 }
@@ -1269,8 +1325,8 @@ function withUnlockRetry<T>(label: string, run: () => T, tries = 40, delayMs = 3
   for (let i = 0; ; i++) {
     try {
       return run();
-    } catch (e: any) {
-      const log = `${e?.stdout ?? ''}${e?.stderr ?? ''}`;
+    } catch (e: unknown) {
+      const log = execErrText(e);
       if (/maximum number of installed apps|MIInstallerErrorDomain error 13|ApplicationVerificationFailed/.test(log)) throw e;
       // devicectl/CoreDevice tunnel STUCK (it switches to a [wired] path and hangs) is NOT a lock —
       // retrying as "waiting for unlock" is pointless + misleading. Re-throw so the caller can fall back.

package/src/config.ts

@@ -43,6 +43,19 @@ export interface AppwrapConfig {
   pwaDist: string;
   /** Custom URL scheme for deep links (e.g. "hellowrap" → hellowrap://...). */
   urlScheme?: string;
+  /** Custom URL schemes `kit.app.canOpenUrl()` may probe (e.g. `['whatsapp', 'tg']`) — covers BOTH
+   * platforms with a single declaration. Since iOS 9 / Android API 30+ a probe of an undeclared custom
+   * scheme returns false for privacy. These stamp into iOS Info.plist `LSApplicationQueriesSchemes` AND
+   * Android `<queries>` as a VIEW `<intent>` per scheme — so scheme-based `canOpenUrl` is symmetric
+   * without hand-mapping each scheme to a package. Common schemes (http/https/tel/mailto/sms) need no
+   * declaration on either platform. No-op when absent. */
+  queryUrlSchemes?: string[];
+  /** Android-only explicit package visibility for `kit.app.canOpenUrl()` (e.g. `['com.whatsapp']`) —
+   * for probing a specific package directly. Under API 30+ package visibility, `resolveActivity`
+   * returns null for undeclared packages — these stamp into AndroidManifest `<queries>` as
+   * `<package android:name="..."/>`. For scheme probes prefer `queryUrlSchemes` (cross-platform).
+   * No-op when absent. */
+  queryPackages?: string[];
   /** App icon source (≥512px square png). Defaults to the largest icon in the PWA manifest. */
   icon?: string;
   /** Loader: 'app' (default — app:// scheme, ES modules OK), 'file' (debug fallback), or 'server'
@@ -120,6 +133,13 @@ export interface AppwrapConfig {
    * (the per-app `permissions{}` map only OVERRIDES the default usage copy). When ABSENT, every
    * capability is active and permissions come solely from `permissions{}` (pre-modules behavior). */
   modules?: string[];
+  /** Permitted headless background-task identifiers (for the `backgroundTask` module). iOS REQUIRES
+   * these declared at build time — they stamp into Info.plist `BGTaskSchedulerPermittedIdentifiers`
+   * (without them `BGTaskScheduler.register` throws) plus `fetch`+`processing` into UIBackgroundModes.
+   * Android self-initializes WorkManager via its androidx startup provider — nothing to stamp. The
+   * same ids are what `kit.backgroundTask.register(id, …)` / `.schedule({id})` use. No-op when absent
+   * or the module is inactive. */
+  backgroundTasks?: string[];
   /** Remote push (APNs/FCM). Off unless set — gating matters: an `aps-environment` entitlement on a
    * team that can't hold the Push capability (e.g. a personal team) BREAKS code signing, and the
    * handshake should honestly report `push: 'none'` on an un-provisioned build. The kit returns a raw