@livx.cc/appwrap 0.47.3 → 0.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.47.3",
+  "version": "0.48.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/AndroidManifest.xml

@@ -55,6 +55,9 @@
 			<data android:scheme="appwrap" />
 			<!-- appwrap:oauth-redirect-schemes --><!-- /appwrap:oauth-redirect-schemes -->
 		</intent-filter>
+		<!-- App Links (https) — autoVerify intent-filters stamped per host from config.androidAppLinks
+		     (or derived from iOS associated-domains applinks:). Needs assetlinks.json on the host. -->
+		<!-- appwrap:app-links --><!-- /appwrap:app-links -->
 	</activity>
 		<activity android:name="com.tns.ErrorReportActivity"/>
 

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

@@ -82,7 +82,7 @@ export const MODULES: ModuleManifest[] = [
   // springboard badge; Android is an honest no-op (launchers own badges) → 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 } } },
+  { name: 'app', core: true, group: 'system', capabilities: { app: 'native', browser: 'native', badge: { ios: true, android: false }, shortcuts: { ios: true, android: true }, pinShortcut: { ios: false, android: true } } },
 
   // ── opt-in: permission / dependency / weight-bearing ───────────────────
   // POST_NOTIFICATIONS / VIBRATE / USE_BIOMETRIC etc. are in the template's baseline manifest already.
@@ -298,13 +298,75 @@ export const MODULES: ModuleManifest[] = [
   {
     name: 'backgroundTask', group: 'backgroundTask',
     capabilities: { backgroundTask: { ios: true, android: true } },
-    android: { gradleDeps: ['androidx.work:work-runtime:2.9.1'] },
+    // work-runtime's Worker extends ListenableWorker, whose methods return guava's ListenableFuture;
+    // that type must be on the COMPILE classpath or javac fails with "cannot access ListenableFuture".
+    // The tiny listenablefuture:1.0 stub does NOT work here: other androidx deps transitively pull
+    // listenablefuture:9999.0-empty-to-avoid-conflict-with-guava (an EMPTY jar), which wins the
+    // version/capability conflict and evicts the real class. Full guava provides the listenablefuture
+    // capability and substitutes that empty stub, so it's the dep that actually resolves the class.
+    android: { gradleDeps: ['androidx.work:work-runtime:2.9.1', 'com.google.guava:guava:33.3.1-android'] },
+  },
+
+  // ── widget — home-screen presence via a native extension (iOS WidgetKit / Android AppWidget) ──
+  // Opt-in; ships its own extension target under modules-native/widget/. The host publishes tiles into
+  // an App Group container the extension reads at render; each tile deep-links back on tap. The App
+  // Group entitlement is app-specific (group.<appId>), so consumers supply it via appwrap.config
+  // `iosEntitlements` for now (Phase-2 templates `group.$APPID` in the CLI). Phase-1 spike ships a
+  // single static tile to prove the extension builds, provisions the group, renders, and deep-links.
+  {
+    name: 'widget', group: 'widget',
+    capabilities: { widget: { ios: true, android: true } },
+    // Android launcher widget = an AppWidgetProvider receiver (icon-grid) fed by the widget.publish
+    // handler via SharedPreferences; Kotlin source + res ship as nativeSrc. iOS side = the WidgetKit
+    // extension under nativeSrc's App_Resources/iOS/extensions/.
+    android: {
+      kotlin: true,
+      manifestApplication: `<receiver
+      android:name="cc.livx.appwrap.AppwrapWidgetProvider"
+      android:exported="true">
+      <intent-filter>
+        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
+      </intent-filter>
+      <meta-data
+        android:name="android.appwidget.provider"
+        android:resource="@xml/appwrap_widget_info" />
+    </receiver>`,
+    },
+    nativeSrc: 'widget',
+  },
+
+  // ── widget — home-screen presence via a native extension (iOS WidgetKit / Android AppWidget) ──
+  // Opt-in; ships its own extension target under modules-native/widget/. The host publishes tiles into
+  // an App Group container the extension reads at render; each tile deep-links back on tap. The App
+  // Group entitlement is app-specific (group.<appId>), so consumers supply it via appwrap.config
+  // `iosEntitlements` for now (Phase-2 templates `group.$APPID` in the CLI). Phase-1 spike ships a
+  // single static tile to prove the extension builds, provisions the group, renders, and deep-links.
+  {
+    name: 'widget', group: 'widget',
+    capabilities: { widget: { ios: true, android: true } },
+    // Android launcher widget = an AppWidgetProvider receiver (icon-grid) fed by the widget.publish
+    // handler via SharedPreferences; Kotlin source + res ship as nativeSrc. iOS side = the WidgetKit
+    // extension under nativeSrc's App_Resources/iOS/extensions/.
+    android: {
+      kotlin: true,
+      manifestApplication: `<receiver
+      android:name="cc.livx.appwrap.AppwrapWidgetProvider"
+      android:exported="true">
+      <intent-filter>
+        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
+      </intent-filter>
+      <meta-data
+        android:name="android.appwidget.provider"
+        android:resource="@xml/appwrap_widget_info" />
+    </receiver>`,
+    },
+    nativeSrc: 'widget',
   },
 ];
 
 /** 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', 'tracking', 'appleSignIn', 'backgroundTask'] as const;
+export const OPTIONAL_GROUPS = ['health', 'oauth', 'reviews', 'scanner', 'speech', 'tracking', 'appleSignIn', 'backgroundTask', 'widget'] 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

@@ -196,6 +196,15 @@ export class CustomWebView extends WebView {
       if (wkt.WebViewFeature.isFeatureSupported(wkt.WebViewFeature.DOCUMENT_START_SCRIPT)) {
         const rules = new java.util.HashSet<string>();
         rules.add(APP_ORIGIN);
+        // loader:'server' loads a REMOTE origin (serverUrl), not the app:// bundle. The document-start
+        // bridge shim must be allowed THERE too — otherwise it only lands via the onPageStarted
+        // fallback, which RACES the page's native-kit detect(): it sees no `window.appwrapNative`,
+        // falls back to the web adapter, and NO native capability works (share/widget/pin all report
+        // 'none'). Adding the server origin injects the bridge before any page script runs.
+        const serverOrigin = SHELL_CONFIG.loader === 'server'
+          ? (String(SHELL_CONFIG.serverUrl).match(/^https?:\/\/[^/]+/)?.[0] ?? '')
+          : '';
+        if (serverOrigin) rules.add(serverOrigin);
         wkt.WebViewCompat.addDocumentStartJavaScript(wv, buildBootstrapJs(), rules);
         return;
       }

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

@@ -1,6 +1,7 @@
 import { Application, Utils } from '@nativescript/core';
 import { bridge } from './bridge';
 import { requestPermissions, startActivityForResult, uriToDataUrl, bitmapToDataUrl } from './android-helpers';
+import { notifIdentity } from './notif-identity';
 
 // no NS types: android-32 typings omit ContactsContract/MediaStore column + ACTION_PICK_IMAGES constants this file reads
 declare const android: any, androidx: any;
@@ -23,12 +24,40 @@ export function registerAndroidHandlers(): void {
     context().getSystemService(android.content.Context.NOTIFICATION_SERVICE);
   const pendingTimers = new Map<number, any>();
 
-  const ensureChannel = () => {
+  const ensureChannel = (channelId: string = CHANNEL_ID, name: string = 'Notifications') => {
     if (android.os.Build.VERSION.SDK_INT < 26) return;
     const channel = new android.app.NotificationChannel(
-      CHANNEL_ID, 'Notifications', android.app.NotificationManager.IMPORTANCE_DEFAULT
+      channelId, name, android.app.NotificationManager.IMPORTANCE_DEFAULT
     );
-    notificationManager().createNotificationChannel(channel);
+    notificationManager().createNotificationChannel(channel); // idempotent; updates name in place
+  };
+
+  // Per-sender channel id — a stable, sanitized key so each mini-app gets its own row
+  // in Android's notification settings (real per-"app" mute/importance).
+  const senderChannelId = (sender: string) => 'sender-' + sender.replace(/[^a-zA-Z0-9]/g, '_').slice(0, 64);
+
+  /** Decode an icon (http(s) URL or data-URI) to a Bitmap for setLargeIcon; null on failure.
+   * Called on a background thread (URL fetch would throw NetworkOnMainThread otherwise). */
+  const loadBitmap = (icon: string): android.graphics.Bitmap | null => {
+    try {
+      if (icon.startsWith('data:')) {
+        const comma = icon.indexOf(',');
+        const b64 = comma >= 0 ? icon.slice(comma + 1) : '';
+        if (!b64) return null;
+        const bytes = android.util.Base64.decode(b64, android.util.Base64.DEFAULT);
+        return android.graphics.BitmapFactory.decodeByteArray(bytes, 0, bytes.length);
+      }
+      const conn = new java.net.URL(icon).openConnection();
+      conn.setConnectTimeout(5000);
+      conn.setReadTimeout(5000);
+      const stream = conn.getInputStream();
+      const bmp = android.graphics.BitmapFactory.decodeStream(stream);
+      stream.close();
+      return bmp;
+    } catch (e) {
+      console.warn('AppWrap: notification largeIcon load failed', e);
+      return null;
+    }
   };
 
   bridge.register('notifications.requestPermission', async () => {
@@ -37,20 +66,24 @@ export function registerAndroidHandlers(): void {
     return ok ? 'granted' : 'denied';
   });
 
-  bridge.register('notifications.schedule', ({ id, title, body, delaySec, deepLink }: any) => {
-    ensureChannel();
+  bridge.register('notifications.schedule', ({ id, title, body, delaySec, deepLink, sender, icon }: any) => {
+    const ident = notifIdentity({ title, body, sender, icon });
+    // Per-sender channel gives the mini-app its own identity + settings row; else the shared one.
+    const channelId = ident.useIdentity && ident.senderName ? senderChannelId(ident.senderName) : CHANNEL_ID;
+    ensureChannel(channelId, ident.useIdentity && ident.senderName ? ident.senderName : 'Notifications');
     const nid = id ?? Math.floor(Math.random() * 100000);
     const timer = setTimeout(() => {
       pendingTimers.delete(nid);
       const ctx = context();
       const builder = android.os.Build.VERSION.SDK_INT >= 26
-        ? new android.app.Notification.Builder(ctx, CHANNEL_ID)
+        ? new android.app.Notification.Builder(ctx, channelId)
         : new android.app.Notification.Builder(ctx);
       builder
         .setSmallIcon(ctx.getApplicationInfo().icon)
-        .setContentTitle(String(title ?? ''))
+        .setContentTitle(ident.title)
         .setAutoCancel(true);
-      if (body) builder.setContentText(String(body));
+      if (ident.subtitle) builder.setSubText(ident.subtitle);
+      if (ident.body) builder.setContentText(ident.body);
       // Tap → re-open the (singleTask) activity with a VIEW intent; onNewIntent
       // routes it through the same deep-link path as an external open.
       if (deepLink) {
@@ -66,7 +99,19 @@ export function registerAndroidHandlers(): void {
           : android.app.PendingIntent.FLAG_UPDATE_CURRENT;
         builder.setContentIntent(android.app.PendingIntent.getActivity(ctx, nid, viewIntent, piFlags));
       }
-      notificationManager().notify(nid, builder.build());
+      // With an icon: fetch the bitmap off the main thread (URL fetch would crash on it),
+      // set it as the large icon, then post. Without: post inline.
+      if (ident.iconUrl) {
+        new java.lang.Thread(new java.lang.Runnable({
+          run: () => {
+            const bmp = loadBitmap(ident.iconUrl);
+            if (bmp) builder.setLargeIcon(bmp);
+            notificationManager().notify(nid, builder.build());
+          },
+        })).start();
+      } else {
+        notificationManager().notify(nid, builder.build());
+      }
     }, Math.max(1, delaySec ?? 1) * 1000);
     pendingTimers.set(nid, timer);
     return { id: nid };

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

@@ -3,6 +3,7 @@ import { bridge } from './bridge';
 import { onDeepLink } from './events';
 import { onRemoteMessage } from './handlers-push';
 import { uiImageToDataUrl } from './ios-image';
+import { notifIdentity, type NotifIdentity } from './notif-identity';
 import { maskForLock, setIosOrientationMask } from './orientation';
 
 interface GeoResult { lat: number; lng: number; accuracy: number; }
@@ -212,25 +213,39 @@ export function registerExtendedHandlers(): void {
     });
   });
 
-  bridge.register('notifications.schedule', ({ id, title, body, delaySec, deepLink }: { id?: number; title?: string; body?: string; delaySec?: number; deepLink?: string }) => {
+  bridge.register('notifications.schedule', ({ id, title, body, delaySec, deepLink, sender, icon, badge }: { id?: number; title?: string; body?: string; delaySec?: number; deepLink?: string; sender?: string; icon?: string; badge?: number }) => {
     if (!isIOS) throw Object.assign(new Error('iOS only for now'), { code: 'UNSUPPORTED' });
     const nid = id ?? Math.floor(Math.random() * 100000);
+    const ident = notifIdentity({ title, body, sender, icon });
     return new Promise((resolve, reject) => {
       const content = UNMutableNotificationContent.new();
-      content.title = String(title ?? '');
-      if (body) content.body = String(body);
+      content.title = ident.title;
+      if (ident.subtitle) content.subtitle = ident.subtitle;
+      if (ident.body) content.body = ident.body;
+      // App-icon badge on delivery (set before the communication-style wrap so it's carried through).
+      if (typeof badge === 'number') content.badge = badge;
+      // Group per-sender so the mini-app's notifications thread together (iOS 15+ also
+      // uses this alongside the communication-style avatar below).
+      if (ident.useIdentity && ident.senderName) content.threadIdentifier = ident.senderName;
       // Carry the deep-link on the notification; the tap delegate re-emits it.
       // Plain JS object → NativeScript marshals it to NSDictionary (more reliable
       // than dictionaryWithObjectForKey across NS versions).
       // cast: NS marshals a plain JS object → NSDictionary at the interop boundary (typed NSDictionary).
       if (deepLink) content.userInfo = { url: String(deepLink) } as any;
+
+      // iOS 15+ COMMUNICATION notification: present the mini-app as the sender (name +
+      // circular avatar) via an INSendMessageIntent. Degrades to the plain `content`
+      // above pre-iOS-15 or when styling declines (e.g. missing communication entitlement).
+      const finalContent: UNNotificationContent =
+        (ident.useIdentity && communicationContent(content, String(nid), ident)) || content;
+
       const trigger = UNTimeIntervalNotificationTrigger.triggerWithTimeIntervalRepeats(
         Math.max(1, delaySec ?? 1),
         false
       );
       const request = UNNotificationRequest.requestWithIdentifierContentTrigger(
         String(nid),
-        content,
+        finalContent,
         trigger
       );
       UNUserNotificationCenter.currentNotificationCenter().addNotificationRequestWithCompletionHandler(
@@ -434,6 +449,69 @@ export function installForegroundNotificationDelegate(): void {
   UNUserNotificationCenter.currentNotificationCenter().delegate = notifDelegate;
 }
 
+/** Load an icon (http(s) URL or data-URI) into NSData for an INImage avatar. Sync
+ * fetch — acceptable for a small local-notification icon; returns null on failure. */
+function iconNSData(icon: string): NSData | null {
+  try {
+    if (icon.startsWith('data:')) {
+      const comma = icon.indexOf(',');
+      const b64 = comma >= 0 ? icon.slice(comma + 1) : '';
+      if (!b64) return null;
+      return NSData.alloc().initWithBase64EncodedStringOptions(b64, NSDataBase64DecodingOptions.IgnoreUnknownCharacters);
+    }
+    const url = NSURL.URLWithString(icon);
+    return url ? NSData.dataWithContentsOfURL(url) : null;
+  } catch (e) {
+    console.warn('[appwrap] notification icon load failed', String(e));
+    return null;
+  }
+}
+
+/**
+ * Build an iOS-15+ communication notification: an INSendMessageIntent whose sender IS
+ * the mini-app (name + INImage avatar), donated, then `content.updating(from:)` so the
+ * banner renders with the sender's identity. Mirrors feedox's NotificationService.swift.
+ * Returns null pre-iOS-15 or if any step declines (caller falls back to plain content).
+ */
+function communicationContent(content: UNMutableNotificationContent, id: string, ident: NotifIdentity): UNNotificationContent | null {
+  // iOS 15.0+ only — INSendMessageIntent conforms to UNNotificationContentProviding there.
+  if (!NSProcessInfo.processInfo.isOperatingSystemAtLeastVersion({ majorVersion: 15, minorVersion: 0, patchVersion: 0 })) {
+    return null;
+  }
+  try {
+    const displayName = ident.senderName || ident.title;
+    const handleValue = ident.senderName || id;
+    let image: INImage | null = null;
+    if (ident.iconUrl) {
+      const data = iconNSData(ident.iconUrl);
+      if (data) image = INImage.imageWithImageData(data);
+    }
+    const handle = INPersonHandle.alloc().initWithValueType(handleValue, INPersonHandleType.Unknown);
+    // null for optional ObjC object params (nameComponents/contactIdentifier); interop marshals it to nil.
+    const sender = INPerson.alloc().initWithPersonHandleNameComponentsDisplayNameImageContactIdentifierCustomIdentifier(
+      handle, null as any, displayName, image as any, null as any, handleValue
+    );
+    const intent = INSendMessageIntent.alloc().initWithRecipientsOutgoingMessageTypeContentSpeakableGroupNameConversationIdentifierServiceNameSenderAttachments(
+      null as any,
+      INOutgoingMessageType.OutgoingMessageText,
+      content.body,
+      INSpeakableString.alloc().initWithSpokenPhrase(displayName),
+      handleValue,
+      null as any,
+      sender,
+      null as any
+    );
+    const interaction = INInteraction.alloc().initWithIntentResponse(intent, null as any);
+    interaction.direction = INInteractionDirection.Incoming;
+    interaction.donateInteractionWithCompletion(null as any);
+    // INSendMessageIntent conforms to UNNotificationContentProviding (iOS 15+).
+    return content.contentByUpdatingWithProviderError(intent as unknown as UNNotificationContentProviding, null);
+  } catch (e) {
+    console.warn('[appwrap] communication notification styling declined', String(e));
+    return null;
+  }
+}
+
 /** A remote (APNs) notification has a UNPushNotificationTrigger; local ones have a time/calendar trigger. */
 function isRemotePush(notification: UNNotification): boolean {
   const trigger = notification?.request?.trigger;

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

@@ -1,4 +1,4 @@
-import { Application, ApplicationSettings, Color, Utils, isAndroid, isIOS } from '@nativescript/core';
+import { Application, ApplicationSettings, Color, ImageSource, Utils, isAndroid, isIOS } from '@nativescript/core';
 import { bridge } from './bridge';
 
 declare const androidx: any; // no NS types: androidx
@@ -201,6 +201,53 @@ export function registerSystemHandlers(): void {
     }
   });
 
+  // Pin a STANDALONE launcher icon to the home screen (distinct from setShortcuts' long-press menu).
+  // Android 8+ (API 26) ShortcutManager.requestPinShortcut — the system shows the add-to-home-screen
+  // prompt. iOS has NO equivalent API (a pinned mini-app icon there is served by the widget instead),
+  // so the capability map gates this to android-only and we return {pinned:false} defensively.
+  // `url` is the full deep link (e.g. blank://a/<id>) supplied by the caller — keeps this app-agnostic;
+  // the tap flows through the app's existing deep-link routing. `iconUrl` is fetched to a bitmap tile.
+  bridge.register('app.pinShortcut', async ({ id, title, url, iconUrl, subtitle }: { id: string; title: string; url: string; iconUrl?: string; subtitle?: string }) => {
+    if (!id || !title || !url) throw err('NATIVE_ERROR', 'app.pinShortcut: id, title, url required');
+    if (!isAndroid) return { pinned: false, reason: 'unsupported' as const };
+    if (android.os.Build.VERSION.SDK_INT < 26) return { pinned: false, reason: 'unsupported' as const };
+    const ctx = Utils.android.getApplicationContext();
+    const sm = ctx.getSystemService(android.content.Context.SHORTCUT_SERVICE);
+    if (!sm || !sm.isRequestPinShortcutSupported()) return { pinned: false, reason: 'unsupported' as const };
+
+    const intent = new android.content.Intent(android.content.Intent.ACTION_VIEW, android.net.Uri.parse(String(url)));
+    const launchClass = (Application.android.foregroundActivity ?? Application.android.startActivity)?.getClass();
+    if (launchClass) intent.setClassName(ctx, launchClass.getName());
+    intent.addFlags(android.content.Intent.FLAG_ACTIVITY_NEW_TASK | android.content.Intent.FLAG_ACTIVITY_CLEAR_TOP);
+
+    const b = new android.content.pm.ShortcutInfo.Builder(ctx, 'pin_' + String(id))
+      .setShortLabel(String(title))
+      .setLongLabel(String(subtitle ?? title))
+      .setIntent(intent);
+
+    // Tile icon: fetch iconUrl → bitmap. On any failure fall back to the app launcher icon (never
+    // block the pin on a network hiccup). ImageSource.fromUrl resolves off the main thread.
+    let iconSet = false;
+    if (iconUrl) {
+      try {
+        const img = await ImageSource.fromUrl(String(iconUrl));
+        if (img?.android) {
+          b.setIcon(android.graphics.drawable.Icon.createWithBitmap(img.android));
+          iconSet = true;
+        }
+      } catch (e) {
+        console.log('app.pinShortcut: icon fetch failed, using launcher icon: ' + e);
+      }
+    }
+    if (!iconSet) {
+      const resId = ctx.getApplicationInfo().icon;
+      if (resId) b.setIcon(android.graphics.drawable.Icon.createWithResource(ctx, resId));
+    }
+
+    sm.requestPinShortcut(b.build(), null);
+    return { pinned: true };
+  });
+
   // Privacy screen — hide content in the app-switcher / block screenshots. iOS: cover the key window
   // with a blur while inactive/backgrounded (wired via the app lifecycle below). Android: FLAG_SECURE.
   bridge.register('screen.setPrivacy', ({ enabled }: { enabled: boolean }) => {

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

@@ -0,0 +1,97 @@
+import { Application, ImageSource, Utils, isAndroid, isIOS } from '@nativescript/core';
+import { bridge } from './bridge';
+
+// WidgetKit's WidgetCenter is Swift-only (no ObjC API) → unreachable from NS directly. The widget
+// module ships an @objc shim (AppwrapWidgetReload) in the app to bridge reloadAllTimelines():
+declare const AppwrapWidgetReload: any;
+
+const err = (code: string, message: string) => Object.assign(new Error(message), { code });
+
+// Shared-store key per widget kind, so a `data` publish never clobbers the `launcher` grid.
+const payloadKeyFor = (slot?: string) => (slot === 'data' ? 'appwrap.widget.data' : 'appwrap.widget');
+const PREFS_NAME = 'appwrap.widget';         // Android SharedPreferences file (keyed per slot inside)
+
+/** iOS App Group id — `group.<bundleId>`, matching what the CLI stamps onto both targets. */
+function iosAppGroup(): string {
+  return 'group.' + NSBundle.mainBundle.bundleIdentifier;
+}
+
+/** Download an image to a PNG file, returning the saved filename (or null on failure). Reused for
+ *  iOS (App Group container) and Android (files dir). */
+async function saveIcon(url: string, dir: string, filename: string): Promise<string | null> {
+  try {
+    const img = await ImageSource.fromUrl(url);
+    const dest = dir.replace(/\/$/, '') + '/' + filename;
+    if (img?.saveToFile(dest, 'png')) return filename;
+  } catch (e) {
+    console.log('widget: icon fetch failed (' + url + '): ' + e);
+  }
+  return null;
+}
+
+type PublishEntry = { label: string; sublabel?: string; deepLink?: string; iconUrl?: string; icon?: string; badge?: number };
+type PublishPayload = {
+  template?: 'icon-grid' | 'stat' | 'list';
+  title?: string;
+  entries?: PublishEntry[];
+  stat?: { value: string; label?: string; sublabel?: string };
+  deepLink?: string;
+  slot?: 'launcher' | 'data';
+};
+
+export function registerWidgetHandlers(): void {
+  // Publish a payload the home-screen widget renders. Downloads any entry.iconUrl into the shared
+  // container (→ entry.icon filename) and writes the JSON to the App Group (iOS) / SharedPreferences
+  // (Android), then asks the OS to reload the widget. Pass `{}`/no entries to clear.
+  bridge.register('widget.publish', async (payload: PublishPayload) => {
+    const template = payload?.template ?? 'icon-grid';
+    const entries = (payload?.entries ?? []).filter((e) => e && e.label);
+    const key = payloadKeyFor(payload?.slot);
+
+    if (isIOS) {
+      const group = iosAppGroup();
+      const containerDir = NSFileManager.defaultManager
+        .containerURLForSecurityApplicationGroupIdentifier(group)?.path;
+      // fetch icons into the container (in parallel), rewriting iconUrl → icon filename (slot-scoped
+      // so a launcher/data publish never overwrites the other's tiles)
+      const prefix = payload?.slot === 'data' ? 'd' : 'l';
+      if (containerDir) {
+        await Promise.all(entries.map(async (e, i) => {
+          if (e.iconUrl) e.icon = (await saveIcon(e.iconUrl, containerDir, `${prefix}_${i}.png`)) ?? undefined;
+          delete e.iconUrl;
+        }));
+      }
+      const json = JSON.stringify({ template, title: payload.title, entries, stat: payload.stat, deepLink: payload.deepLink });
+      const defaults = NSUserDefaults.alloc().initWithSuiteName(group);
+      defaults?.setObjectForKey(json, key);
+      if (typeof AppwrapWidgetReload !== 'undefined') AppwrapWidgetReload.reloadAll();
+      return { published: true };
+    }
+
+    if (isAndroid) {
+      // Android ships the launcher widget only; a `data`-slot publish still persists (for a future
+      // data provider) but there's no receiver to refresh, so it's a no-op render-wise today.
+      const ctx = Utils.android.getApplicationContext();
+      const filesDir = ctx.getFilesDir().getAbsolutePath();
+      const prefix = payload?.slot === 'data' ? 'd' : 'l';
+      await Promise.all(entries.map(async (e, i) => {
+        if (e.iconUrl) e.icon = (await saveIcon(e.iconUrl, filesDir, `${prefix}_${i}.png`)) ?? undefined;
+        delete e.iconUrl;
+      }));
+      const json = JSON.stringify({ template, title: payload.title, entries, stat: payload.stat, deepLink: payload.deepLink });
+      ctx.getSharedPreferences(PREFS_NAME, 0).edit().putString(key, json).apply();
+      if (payload?.slot === 'data') return { published: true };
+      // Kick the provider to re-render: broadcast an APPWIDGET_UPDATE to our widget ids.
+      const mgr = android.appwidget.AppWidgetManager.getInstance(ctx);
+      const cn = new android.content.ComponentName(ctx, 'cc.livx.appwrap.AppwrapWidgetProvider');
+      const ids = mgr.getAppWidgetIds(cn);
+      const intent = new android.content.Intent(android.appwidget.AppWidgetManager.ACTION_APPWIDGET_UPDATE);
+      intent.setComponent(cn);
+      intent.putExtra(android.appwidget.AppWidgetManager.EXTRA_APPWIDGET_IDS, ids);
+      ctx.sendBroadcast(intent);
+      return { published: true };
+    }
+
+    return { published: false, reason: 'unsupported' as const };
+  });
+}

package/runtime/app/shell/notif-identity.ts

@@ -0,0 +1,45 @@
+/**
+ * PURE payload → "who is this from" mapping for LOCAL notifications (no NativeScript
+ * imports; bun-tested). Shared by the iOS communication-notification path and the
+ * Android per-sender-channel path so both derive the same identity from the same rules.
+ *
+ * When a `sender` name is given it becomes the notification's "from" title and the
+ * original `title` is demoted to the subtitle (dropped when it would just duplicate
+ * the sender). `icon` (URL or data-URI) is the avatar / large icon. `useIdentity` is
+ * true when either a sender or an icon is present — i.e. when the platform should
+ * present a custom-sender notification instead of the plain host-app one.
+ */
+
+export interface NotifIdentityInput {
+  title?: string;
+  body?: string;
+  sender?: string;
+  icon?: string;
+}
+
+export interface NotifIdentity {
+  /** Main display title — the sender name when provided, else the original title. */
+  title: string;
+  /** Original title demoted to subtitle ('' = omit). */
+  subtitle: string;
+  body: string;
+  /** Display name for the communication sender / channel ('' = none). */
+  senderName: string;
+  /** Icon URL or data-URI for the avatar / large icon ('' = none). */
+  iconUrl: string;
+  /** True when a custom identity (sender and/or icon) should be applied. */
+  useIdentity: boolean;
+}
+
+export function notifIdentity(o: NotifIdentityInput): NotifIdentity {
+  const title = String(o.title ?? '');
+  const body = String(o.body ?? '');
+  const senderName = o.sender ? String(o.sender) : '';
+  const iconUrl = o.icon ? String(o.icon) : '';
+  const useIdentity = !!(senderName || iconUrl);
+  // A named sender becomes the "from" title; the original title is demoted to the
+  // subtitle (dropped when it would merely repeat the sender name).
+  const displayTitle = senderName || title;
+  const subtitle = senderName && title && title !== senderName ? title : '';
+  return { title: displayTitle, subtitle, body, senderName, iconUrl, useIdentity };
+}

package/runtime/modules-native/widget/App_Resources/Android/src/main/java/cc/livx/appwrap/AppwrapWidgetProvider.kt

@@ -0,0 +1,79 @@
+package cc.livx.appwrap
+
+import android.app.PendingIntent
+import android.appwidget.AppWidgetManager
+import android.appwidget.AppWidgetProvider
+import android.content.Context
+import android.content.Intent
+import android.graphics.BitmapFactory
+import android.net.Uri
+import android.view.View
+import android.widget.RemoteViews
+import org.json.JSONObject
+import java.io.File
+
+/**
+ * Home-screen launcher widget (Android parity of the iOS WidgetKit launcher). Reads the payload the
+ * `widget.publish` handler wrote into SharedPreferences ("appwrap.widget" / key "appwrap.widget") and
+ * renders up to 4 icon-grid tiles; each tile deep-links back into the app via its entry's URL. Icons
+ * are PNGs the handler saved into the app files dir. Resource ids are looked up by name so the module
+ * needs no compile-time reference to the host app's R class.
+ */
+class AppwrapWidgetProvider : AppWidgetProvider() {
+    private val tiles = listOf("tile0", "tile1", "tile2", "tile3")
+
+    override fun onUpdate(ctx: Context, mgr: AppWidgetManager, ids: IntArray) {
+        for (id in ids) render(ctx, mgr, id)
+    }
+
+    private fun res(ctx: Context, type: String, name: String) =
+        ctx.resources.getIdentifier(name, type, ctx.packageName)
+
+    private fun render(ctx: Context, mgr: AppWidgetManager, id: Int) {
+        val rv = RemoteViews(ctx.packageName, res(ctx, "layout", "appwrap_widget"))
+        val raw = ctx.getSharedPreferences("appwrap.widget", Context.MODE_PRIVATE)
+            .getString("appwrap.widget", null)
+        val payload = raw?.let { runCatching { JSONObject(it) }.getOrNull() }
+        val title = payload?.optString("title") ?: ""
+        rv.setTextViewText(res(ctx, "id", "appwrap_widget_title"), title)
+        rv.setViewVisibility(res(ctx, "id", "appwrap_widget_title"),
+            if (title.isEmpty()) View.GONE else View.VISIBLE)
+        val entries = payload?.optJSONArray("entries")
+
+        for (i in tiles.indices) {
+            val tileId = res(ctx, "id", tiles[i])
+            val e = if (entries != null && i < entries.length()) entries.optJSONObject(i) else null
+            if (e == null) { rv.setViewVisibility(tileId, View.INVISIBLE); continue }
+            rv.setViewVisibility(tileId, View.VISIBLE)
+            rv.setTextViewText(res(ctx, "id", "${tiles[i]}_label"), e.optString("label"))
+            // unread-count badge on the icon's top-right corner (absent/0 → hidden)
+            val badgeId = res(ctx, "id", "${tiles[i]}_badge")
+            val badge = e.optInt("badge", 0)
+            if (badge > 0) {
+                rv.setTextViewText(badgeId, if (badge > 99) "99+" else badge.toString())
+                rv.setViewVisibility(badgeId, View.VISIBLE)
+            } else rv.setViewVisibility(badgeId, View.GONE)
+            val icon = e.optString("icon", "")
+            if (icon.isNotEmpty()) {
+                val f = File(ctx.filesDir, icon)
+                if (f.exists()) BitmapFactory.decodeFile(f.absolutePath)
+                    ?.let { rv.setImageViewBitmap(res(ctx, "id", "${tiles[i]}_icon"), it) }
+            }
+            val link = e.optString("deepLink", "")
+            if (link.isNotEmpty()) {
+                // Target the app's OWN launch activity explicitly + carry the deep link as data — the
+                // shell reads intent.getData() (like a pinned shortcut). Relying on an ACTION_VIEW
+                // intent-filter match would need an App Links autoVerify filter for https hosts, which
+                // the shell doesn't declare; an explicit component always opens the app.
+                val intent = (ctx.packageManager.getLaunchIntentForPackage(ctx.packageName)
+                    ?: Intent(Intent.ACTION_VIEW).setPackage(ctx.packageName))
+                    .setAction(Intent.ACTION_VIEW)
+                    .setData(Uri.parse(link))
+                    .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP)
+                val flags = PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+                rv.setOnClickPendingIntent(tileId, PendingIntent.getActivity(ctx, i, intent, flags))
+            }
+        }
+        mgr.updateAppWidget(id, rv)
+    }
+}

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

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Red pill background for the widget tile's unread-count badge. -->
+<shape xmlns:android="http://schemas.android.com/apk/res/android" android:shape="rectangle">
+    <solid android:color="#FF3B30" />
+    <stroke android:width="1.5dp" android:color="#FFFFFF" />
+    <corners android:radius="9dp" />
+</shape>