@livx.cc/appwrap 0.19.0

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

@@ -0,0 +1,258 @@
+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 } from './web-quirks';
+import { envGlobalsJs } from './env';
+import { createUiDelegate } from './ios-ui-delegate';
+import { appwrapNativeLog } from './native-log';
+
+/**
+ * iOS CustomWebView — configures WKWebView before creation (inline media,
+ * persistent data store), registers a real WKScriptMessageHandler named
+ * `appwrap` (page → `webkit.messageHandlers.appwrap.postMessage(json)`), and
+ * serves the bundled PWA via a custom `app://` WKURLSchemeHandler so
+ * unmodified ES-module PWAs load with a stable origin (file:// blocks module
+ * scripts — origin "null" CORS).
+ */
+// Forwarded WebView console/errors → the shared native-log sink (Documents/appwrap-web.log).
+const appendWebLog = appwrapNativeLog;
+
+export class CustomWebView extends WebView {
+  /** Set by the bridge before load; receives raw envelope JSON. */
+  onAppwrapMessage: ((json: string) => void) | null = null;
+  private _scriptHandler: any; // retained — WKUserContentController holds it weakly
+  private _logHandler: any; // retained — debug console-forwarding handler
+  private _schemeHandler: any;
+  // NOT `_uiDelegate`: the base NativeScript WebView uses that exact field name, and
+  // TS `private` is compile-time only — sharing it let super.initNativeView() overwrite
+  // our media-capture delegate with NS's, so getUserMedia re-prompted every call.
+  private _appwrapUiDelegate: any; // retained — WKWebView holds uiDelegate weakly
+
+  /** No-op on iOS: WKWebView suspends rAF/timers itself when the app leaves the foreground.
+   * Kept for parity with the Android impl (wired to suspend/resume in main-page). */
+  setRenderingActive(_active: boolean): void {
+    /* OS-managed on iOS */
+  }
+
+  createNativeView(): WKWebView {
+    const config = WKWebViewConfiguration.new();
+    config.allowsInlineMediaPlayback = true;
+    config.allowsPictureInPictureMediaPlayback = true;
+    config.mediaTypesRequiringUserActionForPlayback = 0; // WKAudiovisualMediaTypeNone
+    config.websiteDataStore = WKWebsiteDataStore.defaultDataStore();
+
+    // Env hints + framework globals (backend origin) + a getUserMedia guard for UNDECLARED capabilities
+    // (must reject in JS before WebKit's native capture path — see mediaCaptureGuardJs) + native-feel
+    // suppression, all injected before the page's own scripts run. Globals first so the page can read
+    // __APPWRAP__ / __APPWRAP_BACKEND_ORIGIN__.
+    const hasPlistKey = (k: string) => !!NSBundle.mainBundle.objectForInfoDictionaryKey(k);
+    const mediaGuard = mediaCaptureGuardJs(hasPlistKey('NSCameraUsageDescription'), hasPlistKey('NSMicrophoneUsageDescription'));
+    for (const src of [envGlobalsJs(), APPWRAP_GLOBALS_JS, mediaGuard, NATIVE_FEEL_JS]) {
+      const script = WKUserScript.alloc().initWithSourceInjectionTimeForMainFrameOnly(
+        src,
+        WKUserScriptInjectionTime.AtDocumentStart,
+        true
+      );
+      config.userContentController.addUserScript(script);
+    }
+
+    const owner = new WeakRef<CustomWebView>(this);
+    const HandlerClass = (NSObject as any).extend(
+      {
+        userContentControllerDidReceiveScriptMessage(
+          _controller: WKUserContentController,
+          message: WKScriptMessage
+        ): void {
+          const view = owner.get ? owner.get() : (owner as any).deref();
+          const body = message.body;
+          // Envelopes always travel as JSON strings (protocol v1)
+          if (view?.onAppwrapMessage && typeof body === 'string') {
+            view.onAppwrapMessage(body);
+          }
+        },
+      },
+      { protocols: [WKScriptMessageHandler] }
+    );
+    this._scriptHandler = HandlerClass.new();
+    config.userContentController.addScriptMessageHandlerName(this._scriptHandler, 'appwrap');
+
+    // Debug console-forwarding: web console/errors → NSLog (via NS console.log) → device console,
+    // so `appwrap logs ios` can stream them headlessly. Only wired in debug mode.
+    if (SHELL_CONFIG.debug) {
+      const LogClass = (NSObject as any).extend(
+        {
+          userContentControllerDidReceiveScriptMessage(_c: WKUserContentController, message: WKScriptMessage): void {
+            // Write to the file sink — NS console.log / NSLog don't surface to devicectl/idevicesyslog
+            // on a device build, but a file in the app container is reliably pullable.
+            if (typeof message.body === 'string') appendWebLog(message.body);
+          },
+        },
+        { protocols: [WKScriptMessageHandler] }
+      );
+      this._logHandler = LogClass.new();
+      config.userContentController.addScriptMessageHandlerName(this._logHandler, 'appwrapLog');
+      appendWebLog('[native] log handler registered'); // boot marker: proves the file sink works
+    }
+
+    this._schemeHandler = createAppSchemeHandler();
+    config.setURLSchemeHandlerForURLScheme(this._schemeHandler, 'app');
+
+    const webView = WKWebView.alloc().initWithFrameConfiguration(CGRectZero, config);
+
+    // Kill the remaining "web page" tells the viewport/CSS can't reach:
+    // rubber-band overscroll, long-press link preview, data-detector menus,
+    // and the auto content-inset (the page owns safe areas via env()).
+    webView.scrollView.bounces = false;
+    webView.scrollView.contentInsetAdjustmentBehavior = 2; // .never
+    webView.allowsLinkPreview = false;
+    // Edge-swipe to go back/forward in WebView history — the iOS native gesture
+    // users expect. SPAs that own their own history still get it for free.
+    webView.allowsBackForwardNavigationGestures = true;
+    if ((webView.configuration as any).dataDetectorTypes !== undefined) {
+      (webView.configuration as any).dataDetectorTypes = 0; // WKDataDetectorTypeNone
+    }
+
+    // Observability (debug mode only): make the WebView debuggable via Safari Web Inspector
+    // (Develop → <device> → Para) — full console + network. iOS 16.4+ (guarded). Off in store builds.
+    if (SHELL_CONFIG.debug && webView.respondsToSelector('setInspectable:')) (webView as any).inspectable = true;
+
+    this._appwrapUiDelegate = createUiDelegate();
+    webView.UIDelegate = this._appwrapUiDelegate;
+
+    return webView;
+  }
+
+  initNativeView(): void {
+    super.initNativeView();
+    // NativeScript's WebView assigns its own wkWebView.UIDelegate during init,
+    // which clobbers the media-capture grant set in createNativeView — so WebKit
+    // falls back to prompting on every getUserMedia call. Reassert ours last so
+    // the `.grant` sticks: iOS then prompts once (TCC), like a native app.
+    const wk = this.nativeViewProtected as WKWebView;
+    if (wk && this._appwrapUiDelegate) wk.UIDelegate = this._appwrapUiDelegate;
+    // Lightweight self-check surfaced via debug.webviewInfo (support diagnostics).
+    (global as any).__appwrapWebviewDiag =
+      `delegateIsMine=${!!wk && wk.UIDelegate === this._appwrapUiDelegate} ` +
+      `respondsToMedia=${!!wk && !!wk.UIDelegate && !!(wk.UIDelegate as any).respondsToSelector?.('webView:requestMediaCapturePermissionForOrigin:initiatedByFrame:type:decisionHandler:')}`;
+  }
+}
+
+/**
+ * app://local/<path> handler:
+ *  - bundled file exists       → serve it (the offline www).
+ *  - GET navigation, no ext    → SPA fallback to the app shell (client-side routes).
+ *  - else + backendOrigin set  → PROXY to the backend via a native URLSession request, returned
+ *      under the app:// URL so the WebView sees it as SAME-ORIGIN (no CORS needed — this is what
+ *      makes a same-origin PWA's relative /api & /functions calls work offline). iOS gives us the
+ *      request body, so POSTs proxy fine.
+ *  - else                      → 404 (or SPA fallback when there's no backend).
+ */
+function createAppSchemeHandler(): any {
+  const wwwPath = nsPath.join(knownFolders.currentApp().path, 'www');
+
+  const serveFile = (task: any, url: any, filePath: string, ext: string): void => {
+    const data = NSData.dataWithContentsOfFile(filePath);
+    const mime = mimeFor(ext, filePath);
+    const response = NSHTTPURLResponse.alloc().initWithURLStatusCodeHTTPVersionHeaderFields(
+      url, 200, 'HTTP/1.1',
+      {
+        'Content-Type': `${mime}; charset=utf-8`,
+        'Content-Length': String(data?.length ?? 0),
+        'Access-Control-Allow-Origin': '*',
+        'Cache-Control': 'no-cache',
+      } as any
+    );
+    task.didReceiveResponse(response);
+    if (data) task.didReceiveData(data);
+    task.didFinish();
+  };
+
+  const proxyToBackend = (task: any, url: any, rel: string): void => {
+    const backend = SHELL_CONFIG.backendOrigin.replace(/\/+$/, '');
+    const query = url.query ? `?${url.query}` : '';
+    const req = NSMutableURLRequest.requestWithURL(NSURL.URLWithString(`${backend}/${rel}${query}`));
+    req.HTTPMethod = String(task.request.HTTPMethod ?? 'GET');
+    const hdrs = task.request.allHTTPHeaderFields;
+    if (hdrs) req.allHTTPHeaderFields = hdrs;
+    req.setValueForHTTPHeaderField(null as any, 'Host'); // let URLSession set Host from the target URL
+    // WKURLSchemeHandler delivers a POST/PUT body via HTTPBodyStream (not HTTPBody) — read it.
+    let body = task.request.HTTPBody;
+    if (!body && task.request.HTTPBodyStream) {
+      const stream = task.request.HTTPBodyStream;
+      const acc = NSMutableData.alloc().init();
+      const cap = 16384;
+      const buf = (global as any).interop.alloc(cap);
+      stream.open();
+      while (stream.hasBytesAvailable) {
+        const n = stream.readMaxLength(buf, cap);
+        if (n <= 0) break;
+        acc.appendBytesLength(buf, n);
+      }
+      stream.close();
+      if (acc.length) body = acc;
+    }
+    if (body) req.HTTPBody = body;
+
+    const dataTask = NSURLSession.sharedSession.dataTaskWithRequestCompletionHandler(
+      req,
+      (data: any, resp: any, error: any) => {
+        try {
+          if (error || !resp) {
+            const r = NSHTTPURLResponse.alloc().initWithURLStatusCodeHTTPVersionHeaderFields(
+              url, 502, 'HTTP/1.1', { 'Content-Length': '0' } as any
+            );
+            task.didReceiveResponse(r);
+            task.didFinish();
+            return;
+          }
+          // Re-emit under the app:// URL (same-origin). Strip Content-Encoding (URLSession already
+          // decoded the body) and recompute length; keep the upstream Content-Type + status.
+          const ct = resp.valueForHTTPHeaderField?.('Content-Type') ?? 'application/octet-stream';
+          const out = NSHTTPURLResponse.alloc().initWithURLStatusCodeHTTPVersionHeaderFields(
+            url, resp.statusCode ?? 200, 'HTTP/1.1',
+            { 'Content-Type': ct, 'Content-Length': String(data?.length ?? 0), 'Cache-Control': 'no-cache' } as any
+          );
+          task.didReceiveResponse(out);
+          if (data) task.didReceiveData(data);
+          task.didFinish();
+        } catch (e) {
+          // task was stopped/cancelled mid-flight — messaging it throws; ignore.
+        }
+      }
+    );
+    dataTask.resume();
+  };
+
+  const HandlerClass = (NSObject as any).extend(
+    {
+      webViewStartURLSchemeTask(_webView: WKWebView, task: any): void {
+        const url = task.request.URL;
+        let rel = decodeURIComponent(String(url.path ?? '/')).replace(/^\/+/, '');
+        if (!rel) rel = SHELL_CONFIG.entry;
+        const filePath = nsPath.join(wwwPath, rel);
+        const ext = rel.includes('.') ? rel.split('.').pop()!.toLowerCase() : '';
+
+        if (File.exists(filePath)) { serveFile(task, url, filePath, ext); return; }
+
+        const method = String(task.request.HTTPMethod ?? 'GET').toUpperCase();
+        const accept = task.request.valueForHTTPHeaderField?.('Accept') ?? '';
+        const isNavigation = method === 'GET' && accept.indexOf('text/html') >= 0;
+
+        if (isNavigation && !ext) { serveFile(task, url, nsPath.join(wwwPath, SHELL_CONFIG.entry), 'html'); return; }
+        if (SHELL_CONFIG.backendOrigin) { proxyToBackend(task, url, rel); return; }
+        if (!ext) { serveFile(task, url, nsPath.join(wwwPath, SHELL_CONFIG.entry), 'html'); return; }
+
+        const resp = NSHTTPURLResponse.alloc().initWithURLStatusCodeHTTPVersionHeaderFields(
+          url, 404, 'HTTP/1.1', { 'Content-Length': '0' } as any
+        );
+        task.didReceiveResponse(resp);
+        task.didFinish();
+      },
+      webViewStopURLSchemeTask(_webView: WKWebView, _task: any): void {
+        // single-shot responses; in-flight proxy completions are guarded by try/catch.
+      },
+    },
+    { protocols: [WKURLSchemeHandler] }
+  );
+  return HandlerClass.new();
+}

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

@@ -0,0 +1,17 @@
+import { WebView } from '@nativescript/core';
+
+/**
+ * Android/common CustomWebView. Web→native transport on Android v0 is the
+ * polled queue installed by the bootstrap user script (see bridge.ts);
+ * a real addJavascriptInterface upgrade comes later.
+ */
+export class CustomWebView extends WebView {
+  /** Set by the bridge before load; receives raw envelope JSON. */
+  onAppwrapMessage: ((json: string) => void) | null = null;
+
+  /** Pause/resume the render + JS-timer pipeline on app background/foreground. Platform-specific
+   * (see custom-webview.android.ts); no-op on iOS, which suspends rAF on its own. */
+  setRenderingActive(_active: boolean): void {
+    /* overridden per-platform */
+  }
+}

package/runtime/app/shell/env.ts

@@ -0,0 +1,81 @@
+import { Application, isAndroid } from '@nativescript/core';
+
+declare const android: any, NSProcessInfo: any, UIAccessibilityIsReduceMotionEnabled: any;
+
+/**
+ * Runtime environment hints the page can't reliably detect itself, surfaced natively so a PWA can
+ * scale its rendering down inside the shell. Injected at document-start as `window.__APPWRAP__` (see
+ * envGlobalsJs) so it's readable BEFORE the page's own scripts decide what to draw.
+ *
+ *  • isEmulator  — running on an emulator/simulator. Its GPU is software-rasterized, so a full-screen
+ *                  CSS/canvas animation that's free on real hardware pegs the host CPU. Apps should
+ *                  cap DPR / disable heavy backgrounds when set.
+ *  • reduceMotion— the OS "reduce motion" accessibility setting is on. Apps should disable non-essential
+ *                  animation (mirrors the `prefers-reduced-motion` media query, but works pre-paint).
+ */
+export interface AppwrapEnv {
+  native: boolean;
+  platform: 'android' | 'ios';
+  isEmulator: boolean;
+  reduceMotion: boolean;
+}
+
+export function detectEnv(): AppwrapEnv {
+  return isAndroid
+    ? { native: true, platform: 'android', isEmulator: androidIsEmulator(), reduceMotion: androidReduceMotion() }
+    : { native: true, platform: 'ios', isEmulator: iosIsSimulator(), reduceMotion: iosReduceMotion() };
+}
+
+/** Document-start snippet: merge the detected hints onto `window.__APPWRAP__` (idempotent). */
+export function envGlobalsJs(): string {
+  const env = detectEnv();
+  return `;(function(){try{window.__APPWRAP__=Object.assign({},window.__APPWRAP__,${JSON.stringify(env)});}catch(e){}})();`;
+}
+
+// ── Android ──────────────────────────────────────────────────────────
+function androidIsEmulator(): boolean {
+  try {
+    const B = android.os.Build;
+    const has = (v: any, s: string) => String(v || '').toLowerCase().includes(s);
+    return (
+      has(B.FINGERPRINT, 'generic') || has(B.FINGERPRINT, 'emulator') || has(B.FINGERPRINT, 'unknown') ||
+      has(B.MODEL, 'google_sdk') || has(B.MODEL, 'emulator') || has(B.MODEL, 'android sdk built for') ||
+      has(B.MANUFACTURER, 'genymotion') || has(B.BRAND, 'generic') ||
+      has(B.HARDWARE, 'goldfish') || has(B.HARDWARE, 'ranchu') || String(B.PRODUCT || '') === 'google_sdk'
+    );
+  } catch (e) {
+    console.warn('AppWrap: emulator detect failed', e);
+    return false;
+  }
+}
+
+function androidReduceMotion(): boolean {
+  try {
+    const ctx = Application.android.context || Application.android.foregroundActivity;
+    // ANIMATOR_DURATION_SCALE == 0 ⇒ user disabled animations (Settings → Accessibility / Developer).
+    const scale = android.provider.Settings.Global.getFloat(
+      ctx.getContentResolver(), android.provider.Settings.Global.ANIMATOR_DURATION_SCALE, 1.0
+    );
+    return scale === 0;
+  } catch (e) {
+    console.warn('AppWrap: reduce-motion detect failed', e);
+    return false;
+  }
+}
+
+// ── iOS ──────────────────────────────────────────────────────────────
+function iosIsSimulator(): boolean {
+  try {
+    return NSProcessInfo.processInfo.environment.objectForKey('SIMULATOR_DEVICE_NAME') != null;
+  } catch (e) {
+    return false;
+  }
+}
+
+function iosReduceMotion(): boolean {
+  try {
+    return !!UIAccessibilityIsReduceMotionEnabled();
+  } catch (e) {
+    return false;
+  }
+}

package/runtime/app/shell/events.ts

@@ -0,0 +1,100 @@
+import { Application, Connectivity, isAndroid } from '@nativescript/core';
+import { bridge } from './bridge';
+import { connectivityStatus } from './handlers-extended';
+
+let pendingDeepLink: string | null = null;
+let pendingPushTap: { data: Record<string, string> } | null = null;
+// True only once the PWA's JS has handshaked — i.e. the WebView is actually
+// running our bundle and about to subscribe. Native page-load is too early:
+// a deeplink.open emitted then lands in a WebView with no listener and is lost
+// (the cold-start-from-notification bug). So we gate delivery on the handshake.
+let pwaReady = false;
+
+/** Called by the iOS delegate (cold start or while running) and Android intents. */
+export function onDeepLink(url: string): void {
+  if (pwaReady) bridge.emit('deeplink.open', { url });
+  else pendingDeepLink = url; // buffer until the PWA handshakes
+}
+
+/** Android: a tray notification (FCM) was tapped → re-launched the activity with the data payload as
+ * intent extras. Buffered until handshake like deep links (cold-start-from-notification). iOS routes
+ * taps via the AppDelegate (handlers-push onRemoteMessage). */
+export function onPushTap(payload: { data: Record<string, string> }): void {
+  if (pwaReady) bridge.emit('push.tap', payload);
+  else pendingPushTap = payload;
+}
+
+/**
+ * The PWA completed app.handshake → its JS is live and registers its
+ * lifecycle listeners right after kit.ready() resolves. Flush any deep link
+ * that arrived during launch (cold start), after a beat for listener install.
+ */
+export function onPwaHandshake(): void {
+  if (pwaReady) return;
+  pwaReady = true;
+  if (pendingDeepLink) {
+    const url = pendingDeepLink;
+    pendingDeepLink = null;
+    setTimeout(() => bridge.emit('deeplink.open', { url }), 500);
+  }
+  if (pendingPushTap) {
+    const payload = pendingPushTap;
+    pendingPushTap = null;
+    setTimeout(() => bridge.emit('push.tap', payload), 500);
+  }
+}
+
+/** Wire lifecycle + connectivity event forwarding (the PWA subscribes to these). */
+export function startEventForwarding(): void {
+  Application.on(Application.suspendEvent, () => bridge.emit('app.pause'));
+  Application.on(Application.resumeEvent, () => bridge.emit('app.resume'));
+  Application.on(Application.orientationChangedEvent, (args: any) =>
+    bridge.emit('screen.orientation.change', args?.newValue === 'landscape' ? 'landscape' : 'portrait')
+  );
+
+  Connectivity.startMonitoring(() => bridge.emit('network.change', connectivityStatus()));
+
+  if (isAndroid) wireAndroidDeepLinks();
+}
+
+/** Intents: launch intent (cold start) + onNewIntent (warm, singleTask). Carries both VIEW deep links
+ * and FCM notification-tap extras. */
+function wireAndroidDeepLinks(): void {
+  const emitFromIntent = (intent: any) => {
+    try {
+      const data = intent?.getData?.();
+      if (data) onDeepLink(String(data.toString()));
+      const tap = readFcmTapExtras(intent);
+      if (tap) onPushTap(tap);
+    } catch (e) {
+      console.warn('AppWrap: intent read failed', e);
+    }
+  };
+
+  Application.android.on(Application.android.activityNewIntentEvent as any, (args: any) =>
+    emitFromIntent(args.intent)
+  );
+  emitFromIntent(Application.android.startActivity?.getIntent?.());
+}
+
+/** A tapped FCM notification re-launches the activity with the message's data payload as string
+ * extras, alongside FCM's own `google.*`/`gcm.*`/`from`/`collapse_key` bookkeeping keys. Detect via
+ * those markers; return the app's data keys only. Null when this isn't an FCM-originated intent. */
+function readFcmTapExtras(intent: any): { data: Record<string, string> } | null {
+  try {
+    const extras = intent?.getExtras?.();
+    if (!extras || (!extras.containsKey('google.message_id') && !extras.containsKey('from'))) return null;
+    const data: Record<string, string> = {};
+    const it = extras.keySet().iterator();
+    while (it.hasNext()) {
+      const k = String(it.next());
+      if (k.startsWith('google.') || k.startsWith('gcm.') || k === 'from' || k === 'collapse_key') continue;
+      const v = extras.get(k);
+      if (v != null) data[k] = String(v);
+    }
+    return { data };
+  } catch (e) {
+    console.warn('AppWrap: FCM extras read failed', e);
+    return null;
+  }
+}

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

@@ -0,0 +1 @@
+/** Generated by `appwrap` — imports the FCM messaging service only when push is wired. Do not edit. */

package/runtime/app/shell/fcm-firebase.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Minimal ambient declarations for the Firebase Messaging Android classes the FCM service extends.
+ * The full classes are provided at runtime by the `firebase-messaging` AAR (added by the CLI only
+ * when push is wired) — the NativeScript Android runtime marshals them. Declare-merges into the
+ * `com` namespace from @nativescript/types-android. Mirrors ios-frameworks.d.ts.
+ */
+declare namespace com.google.firebase.messaging {
+  class RemoteMessage {
+    getData(): any /* java.util.Map<string,string> */;
+    getNotification(): { getTitle(): string; getBody(): string } | null;
+  }
+  class FirebaseMessagingService extends android.app.Service {
+    onMessageReceived(message: RemoteMessage): void;
+    onNewToken(token: string): void;
+  }
+}

package/runtime/app/shell/fcm-service.android.ts

@@ -0,0 +1,40 @@
+import { Utils } from '@nativescript/core';
+import { onFcmMessage } from './handlers-push';
+
+/**
+ * Hand-rolled FirebaseMessagingService (plugin-free) — receives FCM messages while the app process
+ * is alive and forwards them to the JS bridge as `push.message`. Covers DATA payloads + foreground
+ * delivery of notification payloads (which FCM withholds from the tray while the app is foreground).
+ *
+ * GATING is load-bearing: this class extends a Firebase base that only exists on the classpath when
+ * push is wired. It's bundled solely via `fcm-bootstrap.generated.ts` (the CLI imports it only when
+ * google-services.json is present) and the `<service>` is stamped into AndroidManifest only then —
+ * so a non-push Android build never compiles a class extending an absent base.
+ *
+ * Tray-notification taps are routed separately (events.ts reads the launch Intent's FCM extras →
+ * `push.tap`); this service is the foreground/data path.
+ */
+@NativeClass()
+@JavaProxy('cc.livx.appwrap.AppwrapMessagingService')
+export class AppwrapMessagingService extends com.google.firebase.messaging.FirebaseMessagingService {
+  onMessageReceived(message: com.google.firebase.messaging.RemoteMessage): void {
+    super.onMessageReceived(message);
+    try {
+      const data: Record<string, string> = {};
+      const map = message.getData();
+      const keys = map.keySet().toArray();
+      for (let i = 0; i < keys.length; i++) {
+        const k = String(keys[i]);
+        data[k] = String(map.get(k));
+      }
+      const notif = message.getNotification();
+      const title = notif ? notif.getTitle() : undefined;
+      const body = notif ? notif.getBody() : undefined;
+      // bridge.emit evaluates JS on the live WebView (main-thread only); the service runs on a binder
+      // thread. No-ops gracefully if the WebView isn't up (process booted headlessly for a data msg).
+      Utils.dispatchToMainThread(() => onFcmMessage(data, title || undefined, body || undefined));
+    } catch (e) {
+      console.log('[push] onMessageReceived error: ' + e);
+    }
+  }
+}

package/runtime/app/shell/fcm-service.ios.ts

@@ -0,0 +1,3 @@
+// iOS has no FirebaseMessagingService — inbound APNs is handled by the AppDelegate (handlers-push.ts).
+// This stub lets `import './fcm-service'` resolve on both platforms (NS platform-suffix resolution).
+export {};