@livx.cc/appwrap 0.23.2 → 0.24.0

package/package.json

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

package/runtime/App_Resources/Android/src/main/res/xml/file_paths.xml

@@ -1,5 +1,11 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- Paths FileProvider may expose. kit.share.files writes into cacheDir/shared. -->
+<!-- Paths FileProvider may expose.
+     - cacheDir/shared: kit.share.files staging area (keep exact, share writes here).
+     - The three roots below back kit.fs.getUri() so content:// resolves for every FsDirectory:
+       cache→getCacheDir, data→getFilesDir, documents→getExternalFilesDir(null). -->
 <paths>
     <cache-path name="shared" path="shared/" />
+    <cache-path name="fs_cache" path="." />
+    <files-path name="fs_data" path="." />
+    <external-files-path name="fs_documents" path="." />
 </paths>

package/runtime/app/main-page.ts

@@ -6,6 +6,8 @@ import { registerParityHandlers } from './shell/handlers-parity';
 import { registerSystemHandlers } from './shell/handlers-system';
 import { registerBillingHandlers } from './shell/handlers-billing';
 import { registerMediaHandlers } from './shell/handlers-media';
+import { registerKeyboardHandlers } from './shell/keyboard';
+import { registerFsHandlers } from './shell/handlers-fs';
 import { registerPushHandlers } from './shell/handlers-push';
 import { registerAndroidHandlers } from './shell/handlers-android';
 import { registerOptionalHandlers } from './shell/optional-handlers.generated';
@@ -41,6 +43,8 @@ export function onPageLoaded(args: EventData): void {
   registerSystemHandlers();
   registerBillingHandlers();
   registerMediaHandlers();
+  registerKeyboardHandlers();
+  registerFsHandlers();
   registerPushHandlers();
   // Last on purpose: overrides the iOS-only placeholders with Android impls
   if (isAndroid) registerAndroidHandlers();

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

@@ -68,13 +68,18 @@ export const MODULES: ModuleManifest[] = [
   { name: 'haptics', core: true, group: 'core', capabilities: { haptics: 'native' } },
   { name: 'share', core: true, group: 'core', capabilities: { share: 'native', shareFiles: 'native' } },
   { name: 'storage', core: true, group: 'core', capabilities: { storage: 'native', secureStorage: 'native' } },
+  // fs: app-sandbox file I/O (documents/data/cache) + system document picker. Core — every root is
+  // inside the app sandbox and the picker returns user-chosen security-scoped URIs → zero perms.
+  { name: 'fs', core: true, group: 'core', capabilities: { fs: 'native' } },
   { name: 'toast', core: true, group: 'core', capabilities: { toast: 'native', banner: 'native', updates: 'native' } },
   { name: 'statusBar', core: true, group: 'core', capabilities: { statusBar: 'native', themeColor: 'native' } },
   { 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' } },
-  { name: 'app', core: true, group: 'system', capabilities: { app: 'native', browser: 'native' } },
+  { name: 'screen', core: true, group: 'extended', capabilities: { screen: 'native', dialogs: 'native', orientation: 'native', keyboard: 'native' } },
+  // 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 } } },
 
   // ── opt-in: permission / dependency / weight-bearing ───────────────────
   // POST_NOTIFICATIONS / VIBRATE / USE_BIOMETRIC etc. are in the template's baseline manifest already.
@@ -118,6 +123,7 @@ export const MODULES: ModuleManifest[] = [
   {
     name: 'contacts', group: 'parity',
     capabilities: { contacts: 'native' },
+    ios: { permissions: [{ key: 'NSContactsUsageDescription', domain: 'contacts', defaultUsage: 'Find which of your contacts already play, and invite the rest.' }] },
     android: { permissions: ['android.permission.READ_CONTACTS'] },
   },
   {

package/runtime/app/shell/config.ts

@@ -40,6 +40,11 @@ export const SHELL_CONFIG = {
    * fights the app:// handler / remote-update detection). On by default; set false to opt out and keep
    * the SW (e.g. for in-WebView web-push). See `serviceWorkerGuardJs`. */
   neutralizeServiceWorker: true,
+  /** Open external-origin navigations (`<a>` to another origin, incl. `target="_blank"`, and
+   * `window.open(...)`) in the OS default browser (Safari / Chrome) instead of inside the shell
+   * WebView — regular-native-app behavior. Same-origin SPA navigation is untouched. Off by default.
+   * See `externalNavGuardJs`. */
+  openNewWindowsInBrowser: false,
   /** Remote push configured, per platform (iOS aps-environment entitlement / Android FCM). Drives the
    * `push` capability flag at runtime by platform — off unless `appwrap.json.push` enables it, so an
    * un-provisioned build honestly reports 'none' (and a personal-team iOS build keeps `pushIos:false`). */

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

@@ -1,7 +1,7 @@
 import { WebView, Utils, knownFolders, path as nsPath, File } from '@nativescript/core';
 import { SHELL_CONFIG } from './config';
 import { mimeFor } from './mime';
-import { APPWRAP_GLOBALS_JS, NATIVE_FEEL_JS, serviceWorkerGuardJs } from './web-quirks';
+import { APPWRAP_GLOBALS_JS, NATIVE_FEEL_JS, serviceWorkerGuardJs, externalNavGuardJs } from './web-quirks';
 import { envGlobalsJs } from './env';
 import { requestPermissions } from './android-helpers';
 
@@ -27,7 +27,7 @@ const PROMPT_PREFIX = '__appwrap__:';
  * native-feel. Globals first so the page can read __APPWRAP__ / __APPWRAP_BACKEND_ORIGIN__ before its
  * own scripts run. Built lazily (not a const) so envGlobalsJs() detects against a live activity context. */
 function buildBootstrapJs(): string {
-  return `${envGlobalsJs()}\n${APPWRAP_GLOBALS_JS}\n${TRANSPORT_SHIM}\n${serviceWorkerGuardJs(SHELL_CONFIG.neutralizeServiceWorker)}\n${NATIVE_FEEL_JS}`;
+  return `${envGlobalsJs()}\n${APPWRAP_GLOBALS_JS}\n${TRANSPORT_SHIM}\n${serviceWorkerGuardJs(SHELL_CONFIG.neutralizeServiceWorker)}\n${externalNavGuardJs(SHELL_CONFIG.openNewWindowsInBrowser)}\n${NATIVE_FEEL_JS}`;
 }
 
 /**

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

@@ -1,7 +1,7 @@
 import { WebView, knownFolders, path as nsPath, File } from '@nativescript/core';
 import { SHELL_CONFIG } from './config';
 import { mimeFor } from './mime';
-import { APPWRAP_GLOBALS_JS, NATIVE_FEEL_JS, mediaCaptureGuardJs, serviceWorkerGuardJs } from './web-quirks';
+import { APPWRAP_GLOBALS_JS, NATIVE_FEEL_JS, mediaCaptureGuardJs, serviceWorkerGuardJs, externalNavGuardJs } from './web-quirks';
 import { envGlobalsJs } from './env';
 import { createUiDelegate } from './ios-ui-delegate';
 import { appwrapNativeLog } from './native-log';
@@ -56,7 +56,8 @@ export class CustomWebView extends WebView {
     const hasPlistKey = (k: string) => !!NSBundle.mainBundle.objectForInfoDictionaryKey(k);
     const mediaGuard = mediaCaptureGuardJs(hasPlistKey('NSCameraUsageDescription'), hasPlistKey('NSMicrophoneUsageDescription'));
     const swGuard = serviceWorkerGuardJs(SHELL_CONFIG.neutralizeServiceWorker);
-    for (const src of [envGlobalsJs(), APPWRAP_GLOBALS_JS, mediaGuard, swGuard, NATIVE_FEEL_JS]) {
+    const extNavGuard = externalNavGuardJs(SHELL_CONFIG.openNewWindowsInBrowser);
+    for (const src of [envGlobalsJs(), APPWRAP_GLOBALS_JS, mediaGuard, swGuard, extNavGuard, NATIVE_FEEL_JS]) {
       const script = WKUserScript.alloc().initWithSourceInjectionTimeForMainFrameOnly(
         src,
         WKUserScriptInjectionTime.AtDocumentStart,

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

@@ -320,6 +320,49 @@ export function registerAndroidHandlers(): void {
     };
   });
 
+  // ── contacts bulk read (ContactsContract query over all contacts) ──
+  bridge.register('contacts.getAll', async () => {
+    if (!(await requestPermissions(['android.permission.READ_CONTACTS']))) {
+      throw err('DENIED', 'contacts permission denied');
+    }
+    const CC = android.provider.ContactsContract;
+    const cr = context().getContentResolver();
+    const column = (uri: any, col: string, sel: string | null, args: string[] | null): string[] => {
+      const out: string[] = [];
+      const cursor = cr.query(uri, [col], sel, args, null);
+      if (cursor) {
+        const idx = cursor.getColumnIndex(col);
+        while (cursor.moveToNext()) out.push(String(cursor.getString(idx)));
+        cursor.close();
+      }
+      return out;
+    };
+
+    const contacts: Array<{ name: string; phones: string[]; emails: string[] }> = [];
+    const cursor = cr.query(
+      CC.Contacts.CONTENT_URI,
+      [CC.Contacts._ID, CC.Contacts.DISPLAY_NAME],
+      null, null, null
+    );
+    if (cursor) {
+      const idIdx = cursor.getColumnIndex(CC.Contacts._ID);
+      const nameIdx = cursor.getColumnIndex(CC.Contacts.DISPLAY_NAME);
+      while (cursor.moveToNext()) {
+        const contactId = String(cursor.getString(idIdx));
+        const name = cursor.getString(nameIdx) ?? '';
+        contacts.push({
+          name,
+          phones: column(CC.CommonDataKinds.Phone.CONTENT_URI, CC.CommonDataKinds.Phone.NUMBER,
+            CC.CommonDataKinds.Phone.CONTACT_ID + ' = ?', [contactId]),
+          emails: column(CC.CommonDataKinds.Email.CONTENT_URI, CC.CommonDataKinds.Email.ADDRESS,
+            CC.CommonDataKinds.Email.CONTACT_ID + ' = ?', [contactId]),
+        });
+      }
+      cursor.close();
+    }
+    return { contacts };
+  });
+
   // ── calendar (CalendarContract direct insert) ──────────────────────
   bridge.register('calendar.createEvent', async ({ title, start, durationMin, notes }: any) => {
     if (!(await requestPermissions(['android.permission.WRITE_CALENDAR', 'android.permission.READ_CALENDAR']))) {

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

@@ -0,0 +1,367 @@
+import { Utils, isAndroid, isIOS } from '@nativescript/core';
+import { bridge } from './bridge';
+import { startActivityForResult } from './android-helpers';
+
+declare const android: any, java: any;
+
+const err = (code: string, message: string) => Object.assign(new Error(message), { code });
+
+type Dir = 'documents' | 'data' | 'cache';
+
+/** Strip a leading slash and reject any `..` segment so a path can't escape its sandbox root. */
+function safeRelPath(path: string): string {
+  const rel = String(path).replace(/^\/+/, '');
+  if (rel.split('/').some((seg) => seg === '..')) throw err('NATIVE_ERROR', `Path traversal rejected: ${path}`);
+  return rel;
+}
+
+/**
+ * `kit.fs` shell handlers — app-sandbox file I/O + a system document picker, ONE API across iOS
+ * and Android. No runtime permission: every root is inside the app sandbox and the picker returns
+ * user-chosen security-scoped (iOS) / SAF (Android) URIs.
+ *
+ * iOS uses `FileManager` + `NSData`/`NSString`; dirs resolve via `NSSearchPathForDirectoriesInDomains`.
+ * Android uses `java.io.File` under `getFilesDir()`/`getCacheDir()`/`getExternalFilesDir()`, the
+ * existing share FileProvider for `getUri` content:// URIs, and `ACTION_OPEN_DOCUMENT` for the picker.
+ *
+ * DEVICE-GATED / UNVERIFIED this session: the iOS `UIDocumentPickerViewController` delegate and the
+ * Android `ACTION_OPEN_DOCUMENT` activity-result plumbing (both async, new to the repo).
+ */
+export function registerFsHandlers(): void {
+  if (isIOS) registerIosFs();
+  else if (isAndroid) registerAndroidFs();
+}
+
+// ─────────────────────────────── iOS ───────────────────────────────
+
+/** NSSearchPath domain index per dir; `documents`/`cache` are first-class, `data` → Application Support. */
+function iosBaseDir(dir: Dir): string {
+  // NSDocumentDirectory=9, NSCachesDirectory=13, NSApplicationSupportDirectory=14; NSUserDomainMask=1.
+  const which = dir === 'documents' ? 9 : dir === 'cache' ? 13 : 14;
+  const paths = NSSearchPathForDirectoriesInDomains(which as any, 1 as any, true);
+  const base = paths.objectAtIndex(0) as string;
+  // Application Support isn't auto-created; ensure it exists so `data` writes don't fail.
+  if (which === 14) NSFileManager.defaultManager.createDirectoryAtPathWithIntermediateDirectoriesAttributesError(base, true, null, null);
+  return base;
+}
+
+function iosResolve(path: string, dir: Dir): string {
+  return iosBaseDir(dir) + '/' + safeRelPath(path);
+}
+
+function registerIosFs(): void {
+  const fm = () => NSFileManager.defaultManager;
+
+  bridge.register('fs.read', ({ path, dir = 'data', encoding = 'utf8' }: any) => {
+    const full = iosResolve(path, dir);
+    if (!fm().fileExistsAtPath(full)) throw err('NATIVE_ERROR', `No such file: ${path}`);
+    const data = NSData.dataWithContentsOfFile(full);
+    if (!data) throw err('NATIVE_ERROR', `Read failed: ${path}`);
+    if (encoding === 'base64') return data.base64EncodedStringWithOptions(0 as unknown as NSDataBase64EncodingOptions);
+    return NSString.alloc().initWithDataEncoding(data, 4 /* NSUTF8StringEncoding */) as unknown as string;
+  });
+
+  bridge.register('fs.write', ({ path, data, dir = 'data', encoding = 'utf8', recursive }: any) => {
+    const full = iosResolve(path, dir);
+    if (recursive) ensureParentIos(full);
+    const blob = encoding === 'base64'
+      ? NSData.alloc().initWithBase64EncodedStringOptions(data, 0 as unknown as NSDataBase64DecodingOptions)
+      : (NSString.stringWithString(String(data ?? '')) as any).dataUsingEncoding(4);
+    if (!blob) throw err('NATIVE_ERROR', `Encode failed: ${path}`);
+    if (!blob.writeToFileAtomically(full, true)) throw err('NATIVE_ERROR', `Write failed: ${path}`);
+    return { uri: NSURL.fileURLWithPath(full).absoluteString };
+  });
+
+  bridge.register('fs.append', ({ path, data, dir = 'data', encoding = 'utf8' }: any) => {
+    const full = iosResolve(path, dir);
+    ensureParentIos(full);
+    const blob = encoding === 'base64'
+      ? NSData.alloc().initWithBase64EncodedStringOptions(data, 0 as unknown as NSDataBase64DecodingOptions)
+      : (NSString.stringWithString(String(data ?? '')) as any).dataUsingEncoding(4);
+    if (!blob) throw err('NATIVE_ERROR', `Encode failed: ${path}`);
+    if (!fm().fileExistsAtPath(full)) {
+      blob.writeToFileAtomically(full, true);
+      return;
+    }
+    const handle = NSFileHandle.fileHandleForWritingAtPath(full);
+    handle.seekToEndOfFile();
+    handle.writeData(blob);
+    handle.closeFile();
+  });
+
+  bridge.register('fs.delete', ({ path, dir = 'data' }: any) => {
+    fm().removeItemAtPathError(iosResolve(path, dir), null); // no-throw if absent
+  });
+
+  bridge.register('fs.list', ({ path, dir = 'data' }: any) => {
+    const full = iosResolve(path, dir);
+    const names = fm().contentsOfDirectoryAtPathError(full, null);
+    if (!names) throw err('NATIVE_ERROR', `No such dir: ${path}`);
+    const out: any[] = [];
+    for (let i = 0; i < names.count; i++) {
+      const name = names.objectAtIndex(i) as string;
+      out.push(iosStat(full + '/' + name, name));
+    }
+    return out;
+  });
+
+  bridge.register('fs.mkdir', ({ path, dir = 'data', recursive = true }: any) => {
+    const ok = fm().createDirectoryAtPathWithIntermediateDirectoriesAttributesError(
+      iosResolve(path, dir), recursive !== false, null, null
+    );
+    if (!ok) throw err('NATIVE_ERROR', `mkdir failed: ${path}`);
+  });
+
+  bridge.register('fs.stat', ({ path, dir = 'data' }: any) => {
+    const full = iosResolve(path, dir);
+    if (!fm().fileExistsAtPath(full)) throw err('NATIVE_ERROR', `No such path: ${path}`);
+    return iosStat(full, path);
+  });
+
+  bridge.register('fs.getUri', ({ path, dir = 'data' }: any) =>
+    NSURL.fileURLWithPath(iosResolve(path, dir)).absoluteString
+  );
+
+  bridge.register('fs.pickFile', ({ types, multiple }: any) => pickFileIos(types, !!multiple));
+}
+
+function ensureParentIos(full: string): void {
+  const parent = (NSString.stringWithString(full) as any).stringByDeletingLastPathComponent;
+  NSFileManager.defaultManager.createDirectoryAtPathWithIntermediateDirectoriesAttributesError(parent, true, null, null);
+}
+
+function iosStat(full: string, name: string): any {
+  const fm = NSFileManager.defaultManager;
+  const isDirRef = new interop.Reference<boolean>(interop.types.bool, false);
+  const exists = fm.fileExistsAtPathIsDirectory(full, isDirRef as any);
+  const isDir = !!isDirRef.value;
+  const attrs = exists ? fm.attributesOfItemAtPathError(full, null) : null;
+  const size = attrs && !isDir ? Number(attrs.objectForKey(NSFileSize) ?? 0) : undefined;
+  const modDate = attrs ? attrs.objectForKey(NSFileModificationDate) : null;
+  const mtime = modDate ? Math.round(modDate.timeIntervalSince1970 * 1000) : undefined;
+  return {
+    name,
+    type: isDir ? 'dir' : 'file',
+    size,
+    mtime,
+    uri: NSURL.fileURLWithPath(full).absoluteString,
+  };
+}
+
+/**
+ * iOS document picker via UIDocumentPickerViewController. Reads each chosen URL's bytes (under a
+ * security-scoped access window) and returns them base64-inline. DEVICE-GATED — the delegate
+ * callbacks (didPickDocumentsAtURLs / wasCancelled) are not exercised in this session.
+ */
+function pickFileIos(types: string[] | undefined, multiple: boolean): Promise<any[]> {
+  return new Promise((resolve, reject) => {
+    Utils.dispatchToMainThread(() => {
+      try {
+        const utis = NSMutableArray.new();
+        // Map common MIME/extension hints to UTTypes; default to "any item".
+        (types ?? []).forEach((t) => {
+          const ut = (UTType as any).typeWithMIMEType?.(t) ?? (UTType as any).typeWithFilenameExtension?.(t.replace(/^\./, ''));
+          if (ut) utis.addObject(ut);
+        });
+        if (utis.count === 0) utis.addObject(UTTypeItem);
+
+        const picker = UIDocumentPickerViewController.alloc().initForOpeningContentTypes(utis as any);
+        picker.allowsMultipleSelection = multiple;
+
+        const DelegateClass = (NSObject as any).extend(
+          {
+            documentPickerDidPickDocumentsAtURLs(_p: any, urls: any) {
+              const out: any[] = [];
+              for (let i = 0; i < urls.count; i++) {
+                const url = urls.objectAtIndex(i);
+                const scoped = url.startAccessingSecurityScopedResource?.();
+                try {
+                  const data = NSData.dataWithContentsOfURL(url);
+                  if (data) {
+                    out.push({
+                      name: url.lastPathComponent,
+                      mimeType: mimeForUrlIos(url),
+                      size: data.length,
+                      base64: data.base64EncodedStringWithOptions(0 as unknown as NSDataBase64EncodingOptions),
+                    });
+                  }
+                } finally {
+                  if (scoped) url.stopAccessingSecurityScopedResource?.();
+                }
+              }
+              resolve(out);
+            },
+            documentPickerWasCancelled() {
+              resolve([]);
+            },
+          },
+          { protocols: [UIDocumentPickerDelegate] }
+        );
+        const delegate = DelegateClass.new();
+        (picker as any)._appwrapDelegate = delegate; // retain past the present call
+        picker.delegate = delegate;
+        Utils.ios.getRootViewController().presentViewControllerAnimatedCompletion(picker, true, null);
+      } catch (e: any) {
+        reject(err('NATIVE_ERROR', e?.message ?? 'document picker failed'));
+      }
+    });
+  });
+}
+
+function mimeForUrlIos(url: any): string {
+  const ut = (UTType as any).typeWithFilenameExtension?.(url.pathExtension);
+  return ut?.preferredMIMEType ?? 'application/octet-stream';
+}
+
+// ───────────────────────────── Android ─────────────────────────────
+
+function androidBaseDir(dir: Dir): any {
+  const ctx = Utils.android.getApplicationContext();
+  if (dir === 'cache') return ctx.getCacheDir();
+  if (dir === 'documents') return ctx.getExternalFilesDir(null) ?? ctx.getFilesDir();
+  return ctx.getFilesDir(); // 'data'
+}
+
+function androidFile(path: string, dir: Dir): any {
+  return new java.io.File(androidBaseDir(dir), safeRelPath(path));
+}
+
+function readBytesAndroid(file: any): any {
+  const fis = new java.io.FileInputStream(file);
+  const baos = new java.io.ByteArrayOutputStream();
+  const buf = Array.create('byte', 8192);
+  let n: number;
+  while ((n = fis.read(buf)) !== -1) baos.write(buf, 0, n);
+  fis.close();
+  return baos.toByteArray();
+}
+
+function registerAndroidFs(): void {
+  bridge.register('fs.read', ({ path, dir = 'data', encoding = 'utf8' }: any) => {
+    const file = androidFile(path, dir);
+    if (!file.exists()) throw err('NATIVE_ERROR', `No such file: ${path}`);
+    const bytes = readBytesAndroid(file);
+    if (encoding === 'base64') return android.util.Base64.encodeToString(bytes, android.util.Base64.NO_WRAP);
+    return new java.lang.String(bytes, 'UTF-8').toString();
+  });
+
+  bridge.register('fs.write', ({ path, data, dir = 'data', encoding = 'utf8', recursive }: any) => {
+    const file = androidFile(path, dir);
+    if (recursive) file.getParentFile()?.mkdirs();
+    writeAndroid(file, data, encoding, false);
+    return { uri: android.net.Uri.fromFile(file).toString() };
+  });
+
+  bridge.register('fs.append', ({ path, data, dir = 'data', encoding = 'utf8' }: any) => {
+    const file = androidFile(path, dir);
+    file.getParentFile()?.mkdirs();
+    writeAndroid(file, data, encoding, true);
+  });
+
+  bridge.register('fs.delete', ({ path, dir = 'data' }: any) => {
+    androidFile(path, dir).delete(); // no-throw if absent
+  });
+
+  bridge.register('fs.list', ({ path, dir = 'data' }: any) => {
+    const file = androidFile(path, dir);
+    const children = file.listFiles();
+    if (!children) throw err('NATIVE_ERROR', `No such dir: ${path}`);
+    const out: any[] = [];
+    for (let i = 0; i < children.length; i++) out.push(androidStat(children[i], children[i].getName()));
+    return out;
+  });
+
+  bridge.register('fs.mkdir', ({ path, dir = 'data', recursive = true }: any) => {
+    const file = androidFile(path, dir);
+    const ok = recursive !== false ? file.mkdirs() : file.mkdir();
+    if (!ok && !file.isDirectory()) throw err('NATIVE_ERROR', `mkdir failed: ${path}`);
+  });
+
+  bridge.register('fs.stat', ({ path, dir = 'data' }: any) => {
+    const file = androidFile(path, dir);
+    if (!file.exists()) throw err('NATIVE_ERROR', `No such path: ${path}`);
+    return androidStat(file, path);
+  });
+
+  bridge.register('fs.getUri', ({ path, dir = 'data' }: any) => {
+    // Hand out a content:// via the existing share FileProvider so other apps (kit.share) can read it.
+    const ctx = Utils.android.getApplicationContext();
+    const authority = ctx.getPackageName() + '.fileprovider';
+    return androidx.core.content.FileProvider.getUriForFile(ctx, authority, androidFile(path, dir)).toString();
+  });
+
+  bridge.register('fs.pickFile', ({ types, multiple }: any) => pickFileAndroid(types, !!multiple));
+}
+
+function writeAndroid(file: any, data: string, encoding: string, append: boolean): void {
+  const bytes = encoding === 'base64'
+    ? android.util.Base64.decode(String(data ?? ''), android.util.Base64.DEFAULT)
+    : new java.lang.String(String(data ?? '')).getBytes('UTF-8');
+  const fos = new java.io.FileOutputStream(file, append);
+  fos.write(bytes);
+  fos.close();
+}
+
+function androidStat(file: any, name: string): any {
+  const isDir = file.isDirectory();
+  return {
+    name,
+    type: isDir ? 'dir' : 'file',
+    size: isDir ? undefined : file.length(),
+    mtime: file.lastModified(),
+    uri: android.net.Uri.fromFile(file).toString(),
+  };
+}
+
+/**
+ * Android document picker via ACTION_OPEN_DOCUMENT (reuses the shared startActivityForResult).
+ * Reads each chosen content:// URI's bytes via the ContentResolver and returns them base64-inline.
+ * DEVICE-GATED — the activity-result plumbing is not exercised in this session.
+ */
+async function pickFileAndroid(types: string[] | undefined, multiple: boolean): Promise<any[]> {
+  const intent = new android.content.Intent(android.content.Intent.ACTION_OPEN_DOCUMENT);
+  intent.addCategory(android.content.Intent.CATEGORY_OPENABLE);
+  intent.setType((types && types.length === 1) ? types[0] : '*/*');
+  if (types && types.length > 1) {
+    // EXTRA_MIME_TYPES needs a Java String[]; NativeScript won't auto-marshal a JS array here.
+    const arr = Array.create('java.lang.String', types.length);
+    types.forEach((t, i) => { arr[i] = t; });
+    intent.putExtra(android.content.Intent.EXTRA_MIME_TYPES, arr);
+  }
+  if (multiple) intent.putExtra(android.content.Intent.EXTRA_ALLOW_MULTIPLE, true);
+
+  const { resultCode, intent: result } = await startActivityForResult(intent);
+  if (resultCode !== android.app.Activity.RESULT_OK || !result) return [];
+
+  const uris: any[] = [];
+  const clip = result.getClipData?.();
+  if (clip) for (let i = 0; i < clip.getItemCount(); i++) uris.push(clip.getItemAt(i).getUri());
+  else if (result.getData()) uris.push(result.getData());
+
+  const cr = Utils.android.getApplicationContext().getContentResolver();
+  return uris.map((uri) => {
+    const stream = cr.openInputStream(uri);
+    const baos = new java.io.ByteArrayOutputStream();
+    const buf = Array.create('byte', 8192);
+    let n: number;
+    while ((n = stream.read(buf)) !== -1) baos.write(buf, 0, n);
+    stream.close();
+    const bytes = baos.toByteArray();
+    return {
+      name: queryDisplayName(cr, uri),
+      mimeType: cr.getType(uri) ?? 'application/octet-stream',
+      size: bytes.length,
+      base64: android.util.Base64.encodeToString(bytes, android.util.Base64.NO_WRAP),
+    };
+  });
+}
+
+function queryDisplayName(cr: any, uri: any): string {
+  const cursor = cr.query(uri, [android.provider.OpenableColumns.DISPLAY_NAME], null, null, null);
+  let name = 'file';
+  if (cursor) {
+    if (cursor.moveToFirst()) name = String(cursor.getString(0) ?? 'file');
+    cursor.close();
+  }
+  return name;
+}

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

@@ -184,6 +184,44 @@ export function registerParityHandlers(): void {
     });
   });
 
+  // ── contacts bulk read (CNContactStore — requires permission) ──────
+  bridge.register('contacts.getAll', () => {
+    if (!isIOS) throw iosOnly();
+    const store = CNContactStore.new();
+    return new Promise((resolve, reject) => {
+      store.requestAccessForEntityTypeCompletionHandler(CNEntityType.Contacts, (granted: boolean, error: NSError | null) => {
+        if (!granted) {
+          return reject(err('DENIED', error?.localizedDescription ?? 'contacts access denied'));
+        }
+        try {
+          const collect = (labeled: NSArray<any>, map: (v: any) => string) => {
+            const out: string[] = [];
+            for (let i = 0; i < labeled.count; i++) out.push(map(labeled.objectAtIndex(i).value));
+            return out;
+          };
+          const keys = NSArray.arrayWithArray([
+            CNContactGivenNameKey,
+            CNContactFamilyNameKey,
+            CNContactPhoneNumbersKey,
+            CNContactEmailAddressesKey,
+          ] as any);
+          const request = CNContactFetchRequest.alloc().initWithKeysToFetch(keys);
+          const contacts: Array<{ name: string; phones: string[]; emails: string[] }> = [];
+          store.enumerateContactsWithFetchRequestErrorUsingBlock(request, null as any, (contact: any) => {
+            contacts.push({
+              name: `${contact.givenName ?? ''} ${contact.familyName ?? ''}`.trim(),
+              phones: collect(contact.phoneNumbers, (v) => String(v.stringValue)),
+              emails: collect(contact.emailAddresses, (v) => String(v)),
+            });
+          });
+          resolve({ contacts });
+        } catch (e: any) {
+          reject(err('NATIVE_ERROR', e.message));
+        }
+      });
+    });
+  });
+
   // ── calendar (EventKit) ────────────────────────────────────────────
   bridge.register('calendar.createEvent', ({ title, start, durationMin, notes }: any) => {
     if (!isIOS) throw iosOnly();

package/runtime/app/shell/ios-frameworks.d.ts

@@ -30,6 +30,14 @@ declare const HKStatisticsOptions: any;
 declare const HKUnit: any;
 declare const CNContactPickerViewController: any;
 declare const CNContactPickerDelegate: any;
+// Contacts framework (contacts.getAll bulk read — CNContactStore, vs the ContactsUI picker above)
+declare const CNContactStore: any;
+declare const CNEntityType: any;
+declare const CNContactFetchRequest: any;
+declare const CNContactGivenNameKey: any;
+declare const CNContactFamilyNameKey: any;
+declare const CNContactPhoneNumbersKey: any;
+declare const CNContactEmailAddressesKey: any;
 declare const EKEventStore: any;
 declare const EKEvent: any;
 declare const EKSpan: any;

package/runtime/app/shell/keyboard.ts

@@ -0,0 +1,85 @@
+import { Application, Utils, isAndroid, isIOS } from '@nativescript/core';
+import { bridge } from './bridge';
+
+declare const android: any;
+// iOS keyboard-notification globals (marshalled from UIKit at runtime).
+declare const NSNotificationCenter: any;
+declare const UIKeyboardWillShowNotification: string;
+declare const UIKeyboardWillHideNotification: string;
+declare const UIKeyboardFrameEndUserInfoKey: string;
+
+let observersArmed = false;
+
+/**
+ * `kit.keyboard` shell handlers: dismiss the software keyboard (`keyboard.hide`)
+ * and forward show/hide so the page can lift content above it.
+ *
+ * Heights are emitted in CSS px — iOS keyboard frames are in points (≈ CSS px in
+ * a WKWebView), Android raw pixels are divided by display density. iOS observes
+ * `UIKeyboardWillShow/Hide`; Android watches the decor view's visible frame.
+ */
+export function registerKeyboardHandlers(): void {
+  bridge.register('keyboard.hide', () => {
+    Utils.dispatchToMainThread(() => {
+      if (isIOS) {
+        // WKWebView is a UIView → endEditing resigns the active field's first responder.
+        (bridge.getWebView()?.ios as any)?.endEditing?.(true);
+      } else if (isAndroid) {
+        hideAndroidKeyboard();
+      }
+    });
+  });
+
+  if (observersArmed) return;
+  observersArmed = true;
+  if (isIOS) armIosKeyboardObservers();
+  else if (isAndroid) armAndroidKeyboardObserver();
+}
+
+/** iOS: NSNotificationCenter observers → emit keyboard.show {height} / keyboard.hide. */
+function armIosKeyboardObservers(): void {
+  const center = NSNotificationCenter.defaultCenter;
+  center.addObserverForNameObjectQueueUsingBlock(UIKeyboardWillShowNotification, null, null, (note: any) => {
+    const value = note?.userInfo?.objectForKey?.(UIKeyboardFrameEndUserInfoKey);
+    const height = value ? value.CGRectValue.size.height : 0; // points ≈ CSS px in WKWebView
+    bridge.emit('keyboard.show', { height: Math.round(height) });
+  });
+  center.addObserverForNameObjectQueueUsingBlock(UIKeyboardWillHideNotification, null, null, () => {
+    bridge.emit('keyboard.hide');
+  });
+}
+
+/** Android: a global-layout listener compares the decor view's visible frame to its full height. */
+function armAndroidKeyboardObserver(): void {
+  const activity = androidActivity();
+  if (!activity) return;
+  const rootView = activity.getWindow().getDecorView();
+  const density = Utils.android.getApplicationContext().getResources().getDisplayMetrics().density || 1;
+  let lastShown = false;
+  const listener = new android.view.ViewTreeObserver.OnGlobalLayoutListener({
+    onGlobalLayout() {
+      const rect = new android.graphics.Rect();
+      rootView.getWindowVisibleDisplayFrame(rect);
+      const screenHeight = rootView.getHeight();
+      const hiddenPx = screenHeight - rect.bottom; // band covered at the bottom
+      const shown = hiddenPx > screenHeight * 0.15; // >15% ≈ keyboard, not a nav/status bar
+      if (shown === lastShown) return;
+      lastShown = shown;
+      if (shown) bridge.emit('keyboard.show', { height: Math.round(hiddenPx / density) });
+      else bridge.emit('keyboard.hide');
+    },
+  });
+  rootView.getViewTreeObserver().addOnGlobalLayoutListener(listener);
+}
+
+function hideAndroidKeyboard(): void {
+  const activity = androidActivity();
+  if (!activity) return;
+  const imm = activity.getSystemService(android.content.Context.INPUT_METHOD_SERVICE);
+  const view = activity.getCurrentFocus() ?? activity.getWindow().getDecorView();
+  imm?.hideSoftInputFromWindow(view.getWindowToken(), 0);
+}
+
+function androidActivity(): any {
+  return Application.android.foregroundActivity ?? Application.android.startActivity;
+}

package/runtime/app/shell/web-quirks.ts

@@ -119,6 +119,64 @@ export function serviceWorkerGuardJs(enabled: boolean): string {
 })();`;
 }
 
+/**
+ * Make the shell behave like a regular native app when the web content tries to leave the app's own
+ * origin: hand external-origin navigations to the OS default browser (Safari / Chrome — via the core
+ * `app.openUrl` handler, which leaves the app) instead of replacing the shell WebView. Intercepts, at
+ * document-start (BEFORE the page wires its own handlers), two intents:
+ *   - a click on an `<a href>` resolving to a DIFFERENT origin (incl. `target="_blank"`), and
+ *   - `window.open(url, ...)` to a different origin.
+ * Same-origin links / SPA route changes pass straight through (the app keeps owning its own
+ * navigation), so this never ejects the user mid-flow inside their own app. Only runs in the top
+ * frame — embedded iframes (maps, video, ad frames) are left alone. Non-http(s) schemes
+ * (`tel:`/`mailto:`/`app:`) are ignored here and handled by the OS/WebView as usual.
+ *
+ * The request is dispatched fire-and-forget over the same raw transport the bridge listens on (iOS
+ * `webkit.messageHandlers.appwrap`, Android `appwrapNative.postMessage`) — independent of the
+ * consumer's native-kit, so it works even on an unmodified remotely-loaded (loader:'server') webapp.
+ *
+ * `enabled` = SHELL_CONFIG.openNewWindowsInBrowser (default false). Idempotent via a window guard.
+ */
+export function externalNavGuardJs(enabled: boolean): string {
+  if (!enabled) return '';
+  return `(function(){
+  if (window.top !== window.self || window.__appwrapExtNavGuard) return;
+  window.__appwrapExtNavGuard = true;
+  function send(url){
+    try {
+      var json = JSON.stringify({ v:1, id:'extnav-'+Date.now()+'-'+Math.random().toString(36).slice(2),
+        kind:'request', method:'app.openUrl', params:{ url:url } });
+      if (window.webkit && window.webkit.messageHandlers && window.webkit.messageHandlers.appwrap) {
+        window.webkit.messageHandlers.appwrap.postMessage(json); return true; }
+      if (window.appwrapNative && window.appwrapNative.postMessage) {
+        window.appwrapNative.postMessage(json); return true; }
+    } catch (e) {}
+    return false;
+  }
+  // Resolve to an absolute http(s) URL that is on a DIFFERENT origin than the app shell; else null.
+  function external(href){
+    try {
+      var u = new URL(href, location.href);
+      if (u.protocol !== 'http:' && u.protocol !== 'https:') return null; // tel:/mailto:/app:/blob: → OS/WebView
+      return u.origin !== location.origin ? u.href : null;
+    } catch (e) { return null; }
+  }
+  document.addEventListener('click', function(e){
+    if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+    var a = e.target && e.target.closest ? e.target.closest('a[href]') : null;
+    if (!a) return;
+    var url = external(a.getAttribute('href'));
+    if (url && send(url)) { e.preventDefault(); e.stopPropagation(); }
+  }, true);
+  var open = window.open;
+  window.open = function(url){
+    var ext = url != null ? external(String(url)) : null;
+    if (ext && send(ext)) return null;
+    return open ? open.apply(window, arguments) : null;
+  };
+})();`;
+}
+
 /**
  * Native-feel injection shared by both CustomWebViews. Suppresses the "it's a
  * web page" tells: pinch / double-tap zoom, long-press callout & selection,

package/runtime/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appwrap-shell",
   "main": "app/app.ts",
-  "version": "0.18.0",
+  "version": "0.21.0",
   "private": true,
   "scripts": {
     "dev:ios": "ns run ios",

package/src/cli.ts

@@ -363,6 +363,7 @@ export const SHELL_CONFIG = {
   debugLog: ${JSON.stringify(cfg.debugLog ?? '*')},
   devMenu: ${JSON.stringify(cfg.devMenu ?? true)},
   neutralizeServiceWorker: ${JSON.stringify(cfg.neutralizeServiceWorker ?? true)},
+  openNewWindowsInBrowser: ${JSON.stringify(cfg.openNewWindowsInBrowser ?? false)},
   pushIos: ${JSON.stringify(!!cfg.push?.enabled && cfg.push?.ios !== false)},
   pushAndroid: ${JSON.stringify(!!cfg.push?.enabled && cfg.push?.android !== false)},
 };

package/src/config.ts

@@ -79,6 +79,13 @@ export interface AppwrapConfig {
    * for in-WebView web-push as a fallback. NOTE: keeping the SW is the only way to get web push; native
    * push is the separate `push` lane (APNs/FCM) and does NOT need a SW. */
   neutralizeServiceWorker?: boolean;
+  /** Hand navigations that LEAVE the app's own origin to the OS default browser (Safari / Chrome)
+   * instead of replacing the shell WebView — so external links and `window.open(...)`/`target="_blank"`
+   * behave like a regular native app (open in the system browser) rather than navigating away inside
+   * the shell. Covers external-origin `<a>` clicks (including `target="_blank"`) and `window.open()`;
+   * same-origin SPA navigation, subframes/iframes and `tel:`/`mailto:` are left untouched. Default
+   * `false` (unchanged in-WebView navigation). See `externalNavGuardJs`. */
+  openNewWindowsInBrowser?: boolean;
   /** Apple Development Team ID for device builds (Xcode → Settings → Accounts). */
   teamId?: string;
   /** Path (relative to the PWA project) to a StoreKit configuration file for LOCAL IAP