@livx.cc/appwrap 0.61.4 → 0.61.5

package/package.json

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

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

@@ -1,7 +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';
+import { notifIdentity, notifActions } 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;
@@ -66,8 +66,9 @@ export function registerAndroidHandlers(): void {
     return ok ? 'granted' : 'denied';
   });
 
-  bridge.register('notifications.schedule', ({ id, title, body, delaySec, deepLink, sender, icon, silent }: any) => {
+  bridge.register('notifications.schedule', ({ id, title, body, delaySec, deepLink, sender, icon, silent, image, actions }: any) => {
     const ident = notifIdentity({ title, body, sender, icon });
+    const buttons = notifActions(actions);
     // 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');
@@ -89,10 +90,13 @@ export function registerAndroidHandlers(): void {
       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) {
+      // routes it through the same deep-link path as an external open. Each action button gets its
+      // OWN PendingIntent — same shape, different target, and a distinct request code (a shared one
+      // would make FLAG_UPDATE_CURRENT overwrite every earlier button's target with the last).
+      let reqCode = nid * 8;
+      const openIntent = (link: string) => {
         const viewIntent = new android.content.Intent(
-          android.content.Intent.ACTION_VIEW, android.net.Uri.parse(String(deepLink))
+          android.content.Intent.ACTION_VIEW, android.net.Uri.parse(String(link))
         );
         viewIntent.setPackage(ctx.getPackageName());
         viewIntent.addFlags(
@@ -101,15 +105,35 @@ export function registerAndroidHandlers(): void {
         const piFlags = android.os.Build.VERSION.SDK_INT >= 23
           ? android.app.PendingIntent.FLAG_IMMUTABLE | android.app.PendingIntent.FLAG_UPDATE_CURRENT
           : android.app.PendingIntent.FLAG_UPDATE_CURRENT;
-        builder.setContentIntent(android.app.PendingIntent.getActivity(ctx, nid, viewIntent, piFlags));
+        return android.app.PendingIntent.getActivity(ctx, reqCode++, viewIntent, piFlags);
+      };
+      if (deepLink) builder.setContentIntent(openIntent(String(deepLink)));
+      for (const b of buttons) {
+        if (!b.deepLink) continue;
+        // Icon 0 — modern Android draws action buttons as text only, and a bogus resource id crashes
+        // the builder. `Notification.Action.Builder` needs an Icon object on API 23+; the deprecated
+        // three-arg overload is the one that accepts 0 and is still honoured.
+        builder.addAction(0, b.title, openIntent(b.deepLink));
       }
-      // 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) {
+      // Artwork and the sender icon are both network reads — do them on a background thread (a URL
+      // fetch on the main thread throws NetworkOnMainThread) and post once both have resolved.
+      if (ident.iconUrl || image) {
         new java.lang.Thread(new java.lang.Runnable({
           run: () => {
-            const bmp = loadBitmap(ident.iconUrl);
-            if (bmp) builder.setLargeIcon(bmp);
+            if (ident.iconUrl) {
+              const bmp = loadBitmap(ident.iconUrl);
+              if (bmp) builder.setLargeIcon(bmp);
+            }
+            if (image) {
+              const hero = loadBitmap(String(image));
+              // BigPictureStyle IS the rich card: collapsed it shows the large icon, expanded the
+              // hero. Keep the large icon on expand so the mini-app's identity survives the expand.
+              if (hero) {
+                const style = new android.app.Notification.BigPictureStyle().bigPicture(hero);
+                if (ident.body) style.setSummaryText(ident.body);
+                builder.setStyle(style);
+              }
+            }
             notificationManager().notify(nid, builder.build());
           },
         })).start();

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

@@ -4,8 +4,10 @@ import { onDeepLink } from './events';
 import { geoAuthAction } from './geo-auth';
 import { onRemoteMessage } from './handlers-push';
 import { uiImageToDataUrl } from './ios-image';
-import { notifIdentity, type NotifIdentity } from './notif-identity';
+import { notifIdentity, notifActions, bestEffort, bestEffortAsync, type NotifIdentity, type NotifAction } from './notif-identity';
 import { resolveSoundName } from './notif-sound';
+import { resolveAttachment } from './notif-attachment';
+import { sha256Hex } from './sha256';
 import { maskForLock, setIosOrientationMask } from './orientation';
 
 interface GeoResult { lat: number; lng: number; accuracy: number; }
@@ -130,12 +132,21 @@ function ensureIosDelegates(): void {
       // userInfo may come back as an NSDictionary or an auto-marshalled JS object.
       // any: dual-path payload (NSDictionary vs marshalled JS object) probed dynamically.
       const info: any = response.notification.request.content.userInfo;
-      const url = info ? (typeof info.objectForKey === 'function' ? info.objectForKey('url') : info.url) : null;
+      const at = (k: string) => (info ? (typeof info.objectForKey === 'function' ? info.objectForKey(k) : info[k]) : null);
+      // A BUTTON tap carries the action's own identifier; the banner body carries the default one.
+      // Each button's target was stamped as `a:<id>` at schedule time — fall back to the body's
+      // `url` so a button with no target of its own still opens the app rather than doing nothing.
+      const action = String(response.actionIdentifier ?? '');
+      const isButton = !!action && action !== UNNotificationDefaultActionIdentifier;
+      // A swipe-away cannot reach here at all: the categories we register pass no
+      // `.customDismissAction`, so iOS never wakes the delegate for a dismissal — which is
+      // exactly the wanted behaviour (a dismiss must not fall through to `url` and launch).
+      const url = (isButton && at(`a:${action}`)) || at('url');
       // Diagnostic breadcrumb (persists across the cold relaunch) — surfaced in the handshake's debug field.
       try {
         ApplicationSettings.setString(
           'kit:__notifTap',
-          JSON.stringify({ at: Date.now(), url: url ? String(url) : null, hadInfo: !!info })
+          JSON.stringify({ at: Date.now(), url: url ? String(url) : null, action: action || null, hadInfo: !!info })
         );
       } catch {
         /* diagnostic only */
@@ -228,14 +239,33 @@ export function registerExtendedHandlers(): void {
     });
   });
 
-  bridge.register('notifications.schedule', async ({ id, title, body, delaySec, deepLink, sender, icon, badge, silent, sound }: { id?: number; title?: string; body?: string; delaySec?: number; deepLink?: string; sender?: string; icon?: string; badge?: number; silent?: boolean; sound?: string }) => {
+  bridge.register('notifications.schedule', async ({ id, title, body, delaySec, deepLink, sender, icon, badge, silent, sound, image, actions }: { id?: number; title?: string; body?: string; delaySec?: number; deepLink?: string; sender?: string; icon?: string; badge?: number; silent?: boolean; sound?: string; image?: string; actions?: NotifAction[] }) => {
     if (!isIOS) throw Object.assign(new Error('iOS only for now'), { code: 'UNSUPPORTED' });
     const nid = id ?? Math.floor(Math.random() * 100000);
+    // The OS accepts a request it will never present when authorization is missing (a reinstall
+    // resets it). Say so instead of resolving a success the user will never see.
+    if (!(await notificationsAuthorized())) {
+      throw Object.assign(
+        new Error('Notifications are not authorized for this app'),
+        { code: 'NOT_AUTHORIZED' }
+      );
+    }
     const ident = notifIdentity({ title, body, sender, icon });
+    const buttons = notifActions(actions);
     // A custom sound is a FILE the OS reads, never a URL it fetches — resolve (download + transcode +
     // cache) before building the content. Null means "unusable", and the default alert takes over
     // below: the app rings with the wrong sound rather than not at all.
-    const soundName = !silent && sound ? await resolveSoundName(String(sound)) : null;
+    const soundName = !silent && sound
+      ? await bestEffortAsync('sound', () => resolveSoundName(String(sound)), null)
+      : null;
+    // Same rule as the sound: artwork is a FILE the OS reads, never a URL it fetches. Resolve it up
+    // front so the content is built once. `image` wins; otherwise the sender icon rides along as the
+    // banner thumbnail when communication styling is unavailable (no entitlement / pre-iOS-15) —
+    // without it, a mini-app notification would carry NO app artwork at all on those builds.
+    const artwork = image ? String(image) : (ident.iconUrl && !communicationStylingAvailable() ? ident.iconUrl : '');
+    const attachment = artwork
+      ? await bestEffortAsync('artwork', () => resolveAttachment(artwork, `art-${nid}`), null)
+      : null;
     return new Promise((resolve, reject) => {
       const content = UNMutableNotificationContent.new();
       content.title = ident.title;
@@ -261,13 +291,32 @@ export function registerExtendedHandlers(): void {
       // 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;
+      // Carry the tap target AND each button's target: the delegate reads `actionIdentifier` and
+      // picks `a:<id>`, falling back to `url` for a tap on the banner body itself.
+      const info: Record<string, string> = {};
+      if (deepLink) info.url = String(deepLink);
+      for (const b of buttons) if (b.deepLink) info[`a:${b.id}`] = b.deepLink;
+      if (Object.keys(info).length) content.userInfo = info as any;
+
+      // Buttons live on a CATEGORY, not on the content — iOS looks the category up by id at
+      // delivery time, so it must be registered before the request is added.
+      if (buttons.length) {
+        const category = bestEffort('buttons', () => registerActionCategory(buttons), '');
+        if (category) content.categoryIdentifier = category;
+      }
+
+      // ARTWORK. A caller-supplied `image` is the hero. With no image, the sender's ICON becomes
+      // the attachment whenever the communication path declined — that thumbnail is then the only
+      // place the mini-app's own artwork appears, so it is what "identity" degrades to.
+      if (attachment) content.attachments = [attachment] 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;
+        (ident.useIdentity &&
+          bestEffort('sender identity', () => communicationContent(content, String(nid), ident), null)) ||
+        content;
 
       const trigger = UNTimeIntervalNotificationTrigger.triggerWithTimeIntervalRepeats(
         Math.max(1, delaySec ?? 1),
@@ -509,6 +558,86 @@ function iconNSData(icon: string): NSData | null {
   }
 }
 
+/**
+ * Has the user actually granted notifications to THIS install?
+ *
+ * `addNotificationRequest` succeeds with no error when authorization is missing — the request is
+ * accepted and then never presented. A reinstall (or a capability change that forces one) resets
+ * authorization, so a schedule call reporting `{id}` is not evidence anything will arrive. Read the
+ * center's own answer and fail loudly instead of lying to the caller.
+ */
+function notificationsAuthorized(): Promise<boolean> {
+  return new Promise((resolve) => {
+    UNUserNotificationCenter.currentNotificationCenter().getNotificationSettingsWithCompletionHandler(
+      (settings) => {
+        const s = settings?.authorizationStatus;
+        resolve(
+          s === UNAuthorizationStatus.Authorized ||
+          s === UNAuthorizationStatus.Provisional ||
+          s === UNAuthorizationStatus.Ephemeral
+        );
+      }
+    );
+  });
+}
+
+/**
+ * Can this build present a COMMUNICATION notification (mini-app name + circular avatar)?
+ *
+ * Two independent things must be true, and BOTH are build-time facts, so this is cheap and exact:
+ *  1. iOS 15+ — where INSendMessageIntent conforms to UNNotificationContentProviding.
+ *  2. The app declares `NSUserActivityTypes` containing `INSendMessageIntent`. The appwrap CLI
+ *     stamps that key ONLY when `com.apple.developer.usernotifications.communication` is configured,
+ *     and SpringBoard denies the API without the pair — so its absence means the styling WILL
+ *     decline at runtime, which is exactly when the icon has to reach the banner some other way.
+ */
+function communicationStylingAvailable(): boolean {
+  if (!isIOS) return false;
+  if (!NSProcessInfo.processInfo.isOperatingSystemAtLeastVersion({ majorVersion: 15, minorVersion: 0, patchVersion: 0 })) {
+    return false;
+  }
+  try {
+    const types = NSBundle.mainBundle.objectForInfoDictionaryKey('NSUserActivityTypes') as NSArray<string> | null;
+    return !!types && types.containsObject('INSendMessageIntent');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Register (idempotently) a UNNotificationCategory carrying `buttons`, and return its identifier.
+ *
+ * iOS resolves a notification's buttons by looking its `categoryIdentifier` up in the center's
+ * category SET at delivery time, and `setNotificationCategories` REPLACES that set — so categories
+ * are accumulated here and re-set as a union. The identifier is a hash of the buttons, so the same
+ * button set reuses one category instead of growing the set on every schedule call.
+ */
+const notifCategories = new Map<string, UNNotificationCategory>();
+function registerActionCategory(buttons: NotifAction[]): string {
+  const key = 'awcat-' + sha256Hex(buttons.map((b) => `${b.id}\u0000${b.title}`).join('\u0001')).slice(0, 24);
+  if (!notifCategories.has(key)) {
+    const actions = NSMutableArray.alloc().init() as NSMutableArray<UNNotificationAction>;
+    for (const b of buttons) {
+      // .Foreground: every button here deep-links back into the app, so the tap must bring it up.
+      actions.addObject(
+        UNNotificationAction.actionWithIdentifierTitleOptions(b.id, b.title, UNNotificationActionOptions.Foreground)
+      );
+    }
+    notifCategories.set(
+      key,
+      UNNotificationCategory.categoryWithIdentifierActionsIntentIdentifiersOptions(
+        // 0 = no category options: the buttons are the whole point, and CustomDismissAction would
+        // wake the delegate on a swipe-away for nothing.
+        key, actions as never, NSArray.array() as never, 0 as UNNotificationCategoryOptions
+      )
+    );
+  }
+  const set = NSMutableSet.alloc().init() as NSMutableSet<UNNotificationCategory>;
+  for (const c of notifCategories.values()) set.addObject(c);
+  UNUserNotificationCenter.currentNotificationCenter().setNotificationCategories(set as never);
+  return key;
+}
+
 /**
  * Build an iOS-15+ communication notification: an INSendMessageIntent whose sender IS
  * the mini-app (name + INImage avatar), donated, then `content.updating(from:)` so the
@@ -516,10 +645,9 @@ function iconNSData(icon: string): NSData | null {
  * 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;
-  }
+  // iOS 15+ AND the NSUserActivityTypes/entitlement pair — without both, SpringBoard denies the
+  // API and this would burn an INInteraction donation to learn what the bundle already states.
+  if (!communicationStylingAvailable()) return null;
   try {
     const displayName = ident.senderName || ident.title;
     const handleValue = ident.senderName || id;

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

@@ -0,0 +1,138 @@
+/**
+ * Rich-notification ARTWORK on iOS — turn an image URL (or data-URI) into a
+ * `UNNotificationAttachment`.
+ *
+ * WHY THIS IS NOT JUST "pass the url": like sounds, iOS never fetches a notification attachment.
+ * `UNNotificationAttachment` takes a *file URL* the app owns, validates it by extension/UTI, and
+ * then MOVES it into its own store — so a `image: <url>` option that forwards the string renders
+ * nothing at all, silently. Download once, cache under a hash of the URL, and hand the OS a path.
+ *
+ * The attachment is what makes a banner a card: iOS shows it as the thumbnail on a collapsed
+ * banner and as the hero image when the banner is expanded. It is ALSO the only way a mini-app's
+ * own artwork reaches the banner when the communication-notification path is unavailable (no
+ * `com.apple.developer.usernotifications.communication` entitlement), which is why the
+ * notification handler falls back to attaching the sender's icon.
+ *
+ * Every failure path returns null and the caller posts a plain banner — a card without its picture
+ * is a cosmetic miss; a dropped notification is not.
+ */
+import { sha256Hex } from './sha256';
+
+/** Artwork is decoration on a one-shot alert, not a download: never hold the schedule call open. */
+const FETCH_TIMEOUT_MS = 10_000;
+
+/** Extensions UNNotificationAttachment accepts for an image. Anything else is coerced to .png. */
+const IMAGE_EXTS = ['png', 'jpg', 'jpeg', 'gif', 'heic', 'heif', 'webp'];
+
+/** `<app container>/Library/Caches/appwrap-notif`, created on demand. */
+function mediaDir(): string | null {
+  const caches = NSSearchPathForDirectoriesInDomains(
+    NSSearchPathDirectory.CachesDirectory, NSSearchPathDomainMask.UserDomainMask, true
+  );
+  if (!caches || caches.count === 0) return null;
+  const dir = `${caches.objectAtIndex(0)}/appwrap-notif`;
+  const fm = NSFileManager.defaultManager;
+  if (!fm.fileExistsAtPath(dir)) {
+    fm.createDirectoryAtPathWithIntermediateDirectoriesAttributesError(dir, true, null);
+  }
+  return fm.fileExistsAtPath(dir) ? dir : null;
+}
+
+/** Best-effort extension from a URL path; falls back to png (which iOS sniffs happily). */
+function extOf(url: string): string {
+  const path = url.split('?')[0].split('#')[0];
+  const ext = (path.split('.').pop() ?? '').toLowerCase();
+  return IMAGE_EXTS.includes(ext) ? ext : 'png';
+}
+
+/** Write bytes to `dest`; true when the file lands. */
+function writeData(data: NSData | null, dest: string): boolean {
+  if (!data || data.length === 0) return false;
+  return data.writeToFileAtomically(dest, true);
+}
+
+/**
+ * ONE session for the process, not one per call. A session created as a local was free to be
+ * collected while its task was still in flight, which lands as an intermittent, SILENT "download
+ * failed" — the notification then posts with no artwork and nothing says why. Held at module scope
+ * it stays alive for the task's lifetime.
+ */
+let sharedSession: NSURLSession | null = null;
+function session(): NSURLSession {
+  if (!sharedSession) {
+    const cfg = NSURLSessionConfiguration.defaultSessionConfiguration;
+    cfg.timeoutIntervalForRequest = FETCH_TIMEOUT_MS / 1000;
+    sharedSession = NSURLSession.sessionWithConfiguration(cfg);
+  }
+  return sharedSession;
+}
+
+/** Download to `dest`. Resolves false on any transport failure (offline, 404, timeout). */
+function downloadTo(url: string, dest: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const nsUrl = NSURL.URLWithString(url);
+    if (!nsUrl) return resolve(false);
+    const task = session().dataTaskWithURLCompletionHandler(nsUrl, (data, response, error) => {
+      const status = (response as NSHTTPURLResponse)?.statusCode ?? 0;
+      if (error || !data || (status && (status < 200 || status >= 300))) {
+        console.warn(`[appwrap] notification image download failed (${status || error?.localizedDescription})`);
+        return resolve(false);
+      }
+      resolve(writeData(data, dest));
+    });
+    task.resume();
+  });
+}
+
+/**
+ * Resolve an image URL / data-URI to a `UNNotificationAttachment`, or null to post without artwork.
+ * `id` is the attachment identifier (unique per notification content).
+ */
+export async function resolveAttachment(image: string, id: string): Promise<UNNotificationAttachment | null> {
+  const value = String(image ?? '').trim();
+  if (!value) return null;
+  const dir = mediaDir();
+  if (!dir) return null;
+
+  const isData = value.startsWith('data:');
+  const ext = isData ? (/^data:image\/(\w+)/.exec(value)?.[1] ?? 'png').toLowerCase() : extOf(value);
+  const dest = `${dir}/${sha256Hex(value).slice(0, 32)}.${IMAGE_EXTS.includes(ext) ? ext : 'png'}`;
+
+  const fm = NSFileManager.defaultManager;
+  if (!fm.fileExistsAtPath(dest)) {
+    let ok = false;
+    if (isData) {
+      const comma = value.indexOf(',');
+      const b64 = comma >= 0 ? value.slice(comma + 1) : '';
+      ok = !!b64 && writeData(
+        NSData.alloc().initWithBase64EncodedStringOptions(b64, NSDataBase64DecodingOptions.IgnoreUnknownCharacters),
+        dest
+      );
+    } else if (/^https?:\/\//i.test(value)) {
+      ok = await downloadTo(value, dest);
+    }
+    if (!ok) return null;
+  }
+
+  try {
+    // iOS MOVES the file into its own attachment store, so hand it a COPY — otherwise the cache
+    // entry vanishes and every later notification re-downloads (or, worse, finds a half-moved file).
+    const copy = `${dir}/use-${id}-${Date.now()}.${dest.split('.').pop()}`;
+    if (!fm.copyItemAtPathToPathError(dest, copy, null)) return null;
+    try {
+      // iOS moves the file ONLY on success; a rejected/throwing attachment leaves the copy
+      // behind, so every failed schedule would grow the cache. Reclaim it here.
+      const att = UNNotificationAttachment.attachmentWithIdentifierURLOptionsError(
+        id, NSURL.fileURLWithPath(copy), null, null
+      );
+      if (!att) fm.removeItemAtPathError(copy, null);
+      return att;
+    } catch (e) {
+      fm.removeItemAtPathError(copy, null);
+      throw e;
+    }
+  } catch (e) {
+    console.warn('[appwrap] notification attachment rejected', String(e));
+    return null;
+  }
+}

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

@@ -10,6 +10,13 @@
  * present a custom-sender notification instead of the plain host-app one.
  */
 
+/** One tappable button on a rich notification. `deepLink` is where the tap lands. */
+export interface NotifAction {
+  id: string;
+  title: string;
+  deepLink?: string;
+}
+
 export interface NotifIdentityInput {
   title?: string;
   body?: string;
@@ -31,6 +38,34 @@ export interface NotifIdentity {
   useIdentity: boolean;
 }
 
+/**
+ * The OS ceiling that actually renders: iOS shows 2 buttons on a collapsed banner (4 expanded),
+ * Android 3. Three is the widest set every platform draws without silently dropping one.
+ */
+export const MAX_NOTIF_ACTIONS = 3;
+
+/**
+ * Normalize a caller's `actions` into at most {@link MAX_NOTIF_ACTIONS} well-formed buttons.
+ * Entries with no id or no title are DROPPED rather than rendered as a blank button, and ids are
+ * deduped — a repeated id would make two buttons indistinguishable to the tap router.
+ */
+export function notifActions(actions: unknown): NotifAction[] {
+  if (!Array.isArray(actions)) return [];
+  const seen = new Set<string>();
+  const out: NotifAction[] = [];
+  for (const raw of actions) {
+    const a = raw as Partial<NotifAction> | null;
+    const id = String(a?.id ?? '').trim();
+    const title = String(a?.title ?? '').trim();
+    if (!id || !title || seen.has(id)) continue;
+    seen.add(id);
+    const deepLink = a?.deepLink ? String(a.deepLink) : undefined;
+    out.push(deepLink ? { id, title, deepLink } : { id, title });
+    if (out.length >= MAX_NOTIF_ACTIONS) break;
+  }
+  return out;
+}
+
 export function notifIdentity(o: NotifIdentityInput): NotifIdentity {
   const title = String(o.title ?? '');
   const body = String(o.body ?? '');
@@ -43,3 +78,32 @@ export function notifIdentity(o: NotifIdentityInput): NotifIdentity {
   const subtitle = senderName && title && title !== senderName ? title : '';
   return { title: displayTitle, subtitle, body, senderName, iconUrl, useIdentity };
 }
+
+/**
+ * DECORATION MUST NEVER COST THE NOTIFICATION.
+ *
+ * Everything a rich banner adds — a custom sound, hero artwork, the button CATEGORY, the
+ * communication-style sender identity — is a nicety layered onto one alert. Each of those steps
+ * calls into ObjC and each can throw (a rejected attachment, a category the center refuses, an
+ * intent SpringBoard denies). Left unguarded, any one of those throws escapes `notifications.schedule`
+ * and the user gets NOTHING — a cosmetic failure silently promoted to a dropped notification.
+ * Run every decorative step through here: it degrades to `fallback` and says why.
+ */
+export function bestEffort<T>(what: string, fn: () => T, fallback: T): T {
+  try {
+    return fn();
+  } catch (e) {
+    console.warn(`[appwrap] notification ${what} skipped — posting without it: ${String(e)}`);
+    return fallback;
+  }
+}
+
+/** Async twin of `bestEffort` for the steps that download (sound, artwork). */
+export async function bestEffortAsync<T>(what: string, fn: () => Promise<T>, fallback: T): Promise<T> {
+  try {
+    return await fn();
+  } catch (e) {
+    console.warn(`[appwrap] notification ${what} skipped — posting without it: ${String(e)}`);
+    return fallback;
+  }
+}

package/runtime/tests/notif-identity.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import { notifIdentity } from '../app/shell/notif-identity';
+import { notifIdentity, notifActions, bestEffort, bestEffortAsync, MAX_NOTIF_ACTIONS } from '../app/shell/notif-identity';
 
 describe('notifIdentity', () => {
   test('no sender/icon → plain, identity not used', () => {
@@ -41,3 +41,46 @@ describe('notifIdentity', () => {
     expect(r.useIdentity).toBe(false);
   });
 });
+
+describe('notifActions', () => {
+  test('drops entries with no id or title, and dedupes ids', () => {
+    const r = notifActions([
+      { id: 'later', title: 'Maybe later' },
+      { id: '', title: 'nameless' },
+      { id: 'chat', title: '' },
+      { id: 'later', title: 'duplicate' },
+      { id: 'chat', title: "Let's chat!", deepLink: 'blank://a/x?screen=chat' },
+    ]);
+    expect(r.map((a) => a.id)).toEqual(['later', 'chat']);
+    expect(r[1].deepLink).toBe('blank://a/x?screen=chat');
+    expect(r[0].deepLink).toBeUndefined();
+  });
+
+  test('caps at 3 — the widest set every platform actually draws', () => {
+    const many = [1, 2, 3, 4, 5].map((n) => ({ id: `a${n}`, title: `A${n}` }));
+    expect(notifActions(many)).toHaveLength(MAX_NOTIF_ACTIONS);
+    expect(MAX_NOTIF_ACTIONS).toBe(3);
+  });
+
+  test('a missing / non-array actions option is simply no buttons', () => {
+    expect(notifActions(undefined)).toEqual([]);
+    expect(notifActions('nope' as unknown)).toEqual([]);
+  });
+});
+
+describe('bestEffort — decoration never costs the notification', () => {
+  test('a throwing decorative step degrades to the fallback instead of propagating', () => {
+    expect(bestEffort('buttons', () => { throw new Error('category refused'); }, '')).toBe('');
+    expect(bestEffort('sender identity', () => { throw new Error('SpringBoard denied'); }, null)).toBeNull();
+  });
+
+  test('the value passes through untouched when the step succeeds', () => {
+    expect(bestEffort('buttons', () => 'awcat-abc', '')).toBe('awcat-abc');
+  });
+
+  test('async: a rejected artwork/sound resolve degrades to null, it does not reject', async () => {
+    await expect(bestEffortAsync('artwork', async () => { throw new Error('download blew up'); }, null))
+      .resolves.toBeNull();
+    await expect(bestEffortAsync('sound', async () => 'ding.caf', null)).resolves.toBe('ding.caf');
+  });
+});

package/src/cli.ts

@@ -107,8 +107,16 @@ const ANDROID_PERMISSION_KEYS: Record<string, string[]> = {
  * REAL path — a dev checkout may stage the package-root dir as a symlink to the repo-root source (what
  * prepack does with a copy), and Bun's cpSync refuses a symlink as a copy-source root. */
 function resolveAssetRoot(rel: string): string {
+  // In a MONOREPO checkout the repo-root source wins, always. `prepack` stages a COPY of runtime/
+  // and templates/ at the package root and `postpack` deletes it — but a postpack that never ran
+  // (an interrupted publish) leaves that copy behind, and every later local build silently compiled
+  // the STALE snapshot instead of the source, with no warning and a perfectly successful build. The
+  // monorepo is identified structurally (this file lives at <root>/packages/appwrap-cli/src), never
+  // by "is there a runtime/ dir three levels up" — a consumer project may well have one of its own.
+  const inMonorepo = basename(resolve(import.meta.dir, '../..')) === 'packages';
   const local = resolve(import.meta.dir, '..', rel);
-  const dir = existsSync(local) ? local : resolve(import.meta.dir, '../../..', rel);
+  const root = resolve(import.meta.dir, '../../..', rel);
+  const dir = inMonorepo && existsSync(root) ? root : existsSync(local) ? local : root;
   try { return realpathSync(dir); } catch { return dir; }
 }
 const TEMPLATE_DIR = resolveAssetRoot('runtime');
@@ -904,13 +912,20 @@ export async function loadConfig(cwd: string, flags: Record<string, string>): Pr
   }
   const cfg = await readConfigFile(configPath);
 
-  // Warn (never fail) on keys this appwrap doesn't recognize. A config authored for a NEWER appwrap
-  // silently no-ops its unknown keys on an older install (e.g. `targetedDevices` before 0.39 → wrong
-  // device family, no error). Turn that silent no-op into a signal.
+  // FAIL on keys this appwrap doesn't recognize. A config authored for a NEWER appwrap silently
+  // no-ops its unknown keys on an older install, and a WARNING is not enough: it scrolls past in a
+  // CI log and the lane goes green. That shipped a real dead capability — Blank declared
+  // `iosInfoPlist: { NSSupportsLiveActivities: true }` against a CLI that predated the key, so the
+  // plist key was absent, the build/signing/upload all succeeded, and every Live Activity call was
+  // refused on the phone with nothing anywhere saying why. A config key that does nothing is a lie
+  // about what the binary contains, so it stops the build.
   const stray = unknownConfigKeys(cfg as unknown as Record<string, unknown>);
   if (stray.length) {
     const ver = pkgVersion(resolve(import.meta.dir, '../package.json'));
-    for (const k of stray) console.warn(`⚠ appwrap: unrecognized config key '${k}' — ignored. If you expect it to apply, your installed @livx.cc/appwrap (${ver}) may predate it — upgrade.`);
+    console.error(`✖ appwrap: unrecognized config key(s): ${stray.map((k) => `'${k}'`).join(', ')}\n`
+      + `  Installed @livx.cc/appwrap is ${ver}. Either it predates these keys (upgrade), or they are typos (remove them).\n`
+      + `  Refusing to build: an ignored key means the shell does NOT carry what the config claims.`);
+    process.exit(1);
   }
 
   // Manifest as source: the appwrap config wins, the PWA manifest fills the gaps, template default last.
@@ -1076,6 +1091,21 @@ function stampIOSDisplayName(outDir: string, cfg: AppwrapConfig, req: NativeReqs
     // styling). Declaring INStartCallIntent in an app with no calling feature is an App Review flag.
     extras.push(`  <key>NSUserActivityTypes</key>\n  <array>\n    <string>INSendMessageIntent</string>\n  </array>`);
   }
+  // Config-declared plist keys (`iosInfoPlist`). Inside the idempotent block, so removing the config
+  // key removes the plist key — the same both-ways contract as every other stamp here. A key the
+  // TEMPLATE already declares outside the block would produce a duplicate <key> in one dict, which is
+  // an invalid plist that Xcode accepts and the App Store rejects, so that case throws instead.
+  for (const [key, value] of Object.entries(cfg.iosInfoPlist ?? {})) {
+    if (new RegExp(`<key>${key}</key>`).test(src)) {
+      throw new Error(`iosInfoPlist: "${key}" is already declared in the app's Info.plist — remove it from the config (a duplicate <key> is an invalid plist).`);
+    }
+    const body = typeof value === 'boolean' ? `  <${value}/>`
+      : typeof value === 'number' ? `  <integer>${value}</integer>`
+      : Array.isArray(value) ? `  <array>\n${value.map((v) => `    <string>${v}</string>`).join('\n')}\n  </array>`
+      : `  <string>${value}</string>`;
+    extras.push(`  <key>${key}</key>\n${body}`);
+  }
+
   if (extras.length) {
     src = src.replace(
       /<\/dict>\s*<\/plist>\s*$/,

package/src/config.ts

@@ -286,6 +286,14 @@ export interface AppwrapConfig {
    * string / string[]. NOTE: the entitlement must also be enabled on the App ID / provisioning profile
    * (some need Apple approval) or a distribution build won't sign. Absent → no change. */
   iosEntitlements?: Record<string, boolean | string | string[]>;
+  /** Extra keys merged into the app's generated `Info.plist`, for plist facts the module system
+   * doesn't model — e.g. `{ NSSupportsLiveActivities: true }`, which is what ActivityKit requires and
+   * which carries NO entitlement and NO portal step. Stamped inside the idempotent
+   * `<!-- appwrap:begin -->` block, so it is added and removed with the config rather than accumulating.
+   * Value shapes: boolean → `<true/>`/`<false/>`, number → `<integer>`, string → `<string>`,
+   * string[] → `<array>` of strings. A key the template already declares OUTSIDE the block (e.g.
+   * `CFBundleName`) is refused loudly — two `<key>`s in one dict is an invalid plist. */
+  iosInfoPlist?: Record<string, boolean | number | string | string[]>;
   /** iOS code-signing style for device / `deploy` builds. Default `'auto'` (Xcode automatic signing —
    * requires the team's Apple ID signed into Xcode's GUI to mint profiles). Set `'manual'` to sign
    * device builds with provisioning profiles ALREADY installed on this machine (matched by
@@ -380,15 +388,18 @@ export function defineConfig(config: AppwrapConfig): AppwrapConfig {
 
 /**
  * Top-level keys appwrap recognizes — KEEP IN SYNC with `AppwrapConfig` above (top-level only; nested
- * keys like `push.ios` are not listed). Drives `unknownConfigKeys`, which warns (never fails) on stray
+ * keys like `push.ios` are not listed). Drives `unknownConfigKeys`, which FAILS the build on stray
  * keys at load time. The motivating bug: a config written for a NEWER appwrap silently no-ops its
  * unknown keys on an OLDER installed version (e.g. `targetedDevices` before 0.39 → a universal build
- * with no error, then an App Store rejection). A loud warning turns that silent no-op into a signal.
+ * with no error, then an App Store rejection; `iosInfoPlist` before 0.61.5 → a Live Activity refused
+ * on the device while every gate stayed green). This was a warning until 0.61.5 and a warning is not
+ * a gate — it scrolls past in CI. Adding a key here is therefore MANDATORY when adding it to
+ * `AppwrapConfig`, or every config that uses it stops building.
  */
 export const KNOWN_CONFIG_KEYS: ReadonlySet<string> = new Set([
   'androidAppLinks', 'appBoundDomains', 'backendOrigin', 'backgroundAudio', 'backgroundColor', 'backgroundTasks', 'buildNumber', 'ci', 'debug',
   'debugLog', 'desktop', 'devMenu', 'edgeToEdge', 'entry', 'icon', 'id', 'iosKeyboardExtraLift', 'loader', 'modules', 'modulePacks', 'name',
-  'androidLockTextZoom', 'envSwitcher', 'iosEntitlements', 'neutralizeServiceWorker', 'oauthRedirectSchemes', 'openNewWindowsInBrowser', 'orientation', 'overrides', 'permissions',
+  'androidLockTextZoom', 'envSwitcher', 'iosEntitlements', 'iosInfoPlist', 'neutralizeServiceWorker', 'oauthRedirectSchemes', 'openNewWindowsInBrowser', 'orientation', 'overrides', 'permissions',
   'plugins', 'push', 'pwaDist', 'queryPackages', 'queryUrlSchemes', 'serverUrl', 'shareTarget', 'signing', 'signingProfiles', 'statusBarStyle', 'store',
   'splashIcon', 'storekitConfig', 'targetedDevices', 'teamId', 'themeColor', 'trackingDomains', 'urlScheme',
   'usesNonExemptEncryption', 'vendorPaths', 'version',