@livx.cc/appwrap 0.30.0 → 0.30.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.30.0",
+  "version": "0.30.2",
   "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/main-page.ts

@@ -17,9 +17,44 @@ import { startDevMenu } from './shell/devmenu';
 import { SHELL_CONFIG } from './shell/config';
 import { bindStatusBarPage, setStatusBarStyle, applyThemeColor, enableAndroidEdgeToEdge, wireAndroidSafeArea } from './shell/status-bar';
 import { CustomWebView } from './shell/custom-webview';
+import { appwrapNativeLog } from './shell/native-log';
 
 let initialized = false;
 
+/** DEBUG iOS lifecycle tracer — logs NS suspend/resume/displayed AND the raw UIApplication
+ * activation notifications (willResignActive/didBecomeActive/didEnterBackground/willEnterForeground)
+ * with each connected scene's activationState, to Documents/appwrap-web.log. Diagnostic for the
+ * StoreKit-sheet freeze: a system sheet that only resigns-active (never backgrounds) produces a
+ * different event sequence than a real background, so the resume/wake path may not fire on dismiss. */
+let _lifecycleTraced = false;
+function traceIosLifecycle(): void {
+  if (_lifecycleTraced) return;
+  _lifecycleTraced = true;
+  const log = (e: string): void => {
+    let states = '';
+    try {
+      const scenes = UIApplication.sharedApplication.connectedScenes.allObjects;
+      for (let i = 0; i < scenes.count; i++) {
+        const s = scenes.objectAtIndex(i) as UIScene;
+        states += ` [${(s as any).session?.role ?? '?'}:act=${s.activationState}]`;
+      }
+    } catch { states = ' (scene-read-err)'; }
+    appwrapNativeLog(`[native:lifecycle] ${e}${states}`);
+  };
+  Application.on(Application.suspendEvent, () => log('NS.suspend'));
+  Application.on(Application.resumeEvent, () => log('NS.resume'));
+  Application.on(Application.displayedEvent, () => log('NS.displayed'));
+  const nc = NSNotificationCenter.defaultCenter;
+  const obs = (name: string, tag: string): void => {
+    nc.addObserverForNameObjectQueueUsingBlock(name, null, null, () => log(tag));
+  };
+  obs(UIApplicationWillResignActiveNotification, 'UIApp.willResignActive');
+  obs(UIApplicationDidBecomeActiveNotification, 'UIApp.didBecomeActive');
+  obs(UIApplicationDidEnterBackgroundNotification, 'UIApp.didEnterBackground');
+  obs(UIApplicationWillEnterForegroundNotification, 'UIApp.willEnterForeground');
+  appwrapNativeLog('[native:lifecycle] tracer armed');
+}
+
 export function onPageLoaded(args: EventData): void {
   const page = args.object as Page;
   page.bindingContext = { backgroundColor: SHELL_CONFIG.backgroundColor };
@@ -62,7 +97,16 @@ export function onPageLoaded(args: EventData): void {
   // Halt the WebView render + JS-timer pipeline while backgrounded so a page running a continuous
   // animation (Android doesn't auto-pause rAF off-screen) stops burning CPU/battery. No-op on iOS.
   Application.on(Application.suspendEvent, () => webView.setRenderingActive(false));
-  Application.on(Application.resumeEvent, () => webView.setRenderingActive(true));
+  Application.on(Application.resumeEvent, () => {
+    webView.setRenderingActive(true);
+    // iOS: wake the WebContent renderer NOW (it stays THROTTLED for ~30-45s after a full-window system
+    // surface — StoreKit manage-subscriptions sheet, itms-apps deep link, backgrounding — froze it).
+    webView.wakeWebContent();
+  });
+
+  // DEBUG: trace the iOS app-lifecycle event sequence to the pullable log sink so we can see WHICH
+  // resume signal does (or doesn't) fire when returning from the StoreKit sheet vs a normal background.
+  if (isIOS && SHELL_CONFIG.debug) traceIosLifecycle();
 
   // Android system back → WebView history (iOS gets this via the edge-swipe
   // gesture). Only swallow the press when there's history to pop; otherwise let

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

@@ -89,6 +89,18 @@ export class CustomWebView extends WebView {
     }
   }
 
+  /** iOS-only renderer-wake (see custom-webview.ios.ts). No-op on Android: onResume()/resumeTimers()
+   * in setRenderingActive already restart the WebView pipeline on foreground. */
+  wakeWebContent(): void {
+    /* iOS-only */
+  }
+
+  /** iOS-only post-native-surface recovery (see custom-webview.ios.ts). No-op on Android: dismissing a
+   * native screen returns through the normal activity resume, which already restores the WebView. */
+  recoverAfterNativeSurface(): void {
+    /* iOS-only */
+  }
+
   private installDocumentStartShim(wv: android.webkit.WebView): void {
     try {
       const wkt = androidx.webkit;

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

@@ -74,6 +74,95 @@ export class CustomWebView extends WebView {
     /* OS-managed on iOS */
   }
 
+  /**
+   * Proactively WAKE the WebContent renderer process on foreground (wired to Application.resumeEvent
+   * for iOS in main-page). WHY: when a full-window system surface covers the app — StoreKit's
+   * showManageSubscriptions(in:) (hosted out-of-process by com.apple.ios.StoreKitUIService), the
+   * itms-apps subscriptions deep link, or any backgrounding — the UIScene goes non-foreground and
+   * WebKit THROTTLES/SUSPENDS the WKWebView's WebContent process; its JS stops and the app UI (which
+   * IS the WebView) freezes. On return, WebKit re-acquires the scene assertion lazily (~30-45s),
+   * leaving the page frozen until then. An inbound `evaluateJavaScript` is a foreground WebContent
+   * activity (WebPageProxy::runJavaScriptInFrameInScriptWorld) — it forces WebKit to restore the
+   * process NOW instead of waiting out the throttle. The injected JS also re-fires a synthetic
+   * `visibilitychange`/`pageshow` so a loader:'server' web app reconnects its sockets immediately
+   * (it would otherwise wait for WebKit to deliver the native visibility event late). No-op on Android. */
+  wakeWebContent(): void {
+    const wk = this.nativeViewProtected as WKWebView;
+    if (!wk) return;
+    if (SHELL_CONFIG.debug) appendWebLog(`[native:lifecycle] wakeWebContent run (frame ${wk.frame.size.width}x${wk.frame.size.height})`);
+    // (1) COMPOSITOR NUDGE — force a layout + compositing pass so a WebView that returned from an
+    // occluding system surface (StoreKit sheet, deep link, backgrounding) repaints + re-hit-tests NOW
+    // rather than waiting out WebKit's lazy restore. A 1px frame perturbation, restored in the same
+    // runloop. (For the StoreKit-sheet freeze the primary fix is neutralising the orphaned tracking
+    // window in handlers-billing/the Swift shim; this nudge + the JS wake below complete the resume the
+    // OS never fires for that sheet — see handlers-billing.manageSubscriptionsSheet.)
+    const f = wk.frame;
+    if (f.size.width > 0 && f.size.height > 1) {
+      wk.frame = CGRectMake(f.origin.x, f.origin.y, f.size.width, f.size.height - 1);
+      wk.frame = f;
+      wk.setNeedsLayout();
+      wk.layoutIfNeeded();
+    }
+    // (2) Re-emit visibility so the page's own visibilitychange/pageshow listeners (socket reconnect,
+    // session refresh) run right away. document.hidden is already false on foreground — this just
+    // un-blocks resume handlers that gate on the event rather than polling.
+    wk.evaluateJavaScriptCompletionHandler(
+      `try{document.dispatchEvent(new Event('visibilitychange'));` +
+      `window.dispatchEvent(new PageTransitionEvent('pageshow',{persisted:true}));}catch(e){}`,
+      () => { /* fire-and-forget; the eval itself is the wake */ }
+    );
+  }
+
+  /** Call after dismissing ANY native surface presented over the WebView (StoreKit sheet, OAuth
+   * ASWebAuthenticationSession, SFSafariViewController, pickers, share, alerts). Such surfaces can
+   * leave the WebView frozen: a same-scene system sheet doesn't fire resumeEvent AND can orphan an
+   * interactive window above ours that swallows touches. We neutralise any stray window FIRST (so the
+   * wake re-attaches over a clean stack), then wake. Deferred so the dismissal animation finalizes the
+   * orphan window first. Idempotent + safe (no stray ⇒ no-op). No-op on Android. */
+  recoverAfterNativeSurface(): void {
+    setTimeout(() => {
+      try { this.neutralizeStrayWindows(); } catch (e) { /* best-effort */ }
+      this.wakeWebContent();
+    }, 350);
+  }
+
+  /** Remove any window sitting ABOVE our main app window (a leftover system-surface window that can
+   * intercept touches): disable interaction, hide, and detach from the scene. Re-key our main window.
+   * Main = lowest-level non-hidden window with a rootViewController. Logs before/after (debug). */
+  private neutralizeStrayWindows(): void {
+    const dbg = SHELL_CONFIG.debug;
+    const scenes = UIApplication.sharedApplication.connectedScenes.allObjects;
+    for (let i = 0; i < scenes.count; i++) {
+      const scene = scenes.objectAtIndex(i);
+      if (!scene.isKindOfClass(UIWindowScene.class())) continue;
+      const ws = scene as UIWindowScene;
+      const windows = ws.windows;
+      let main: UIWindow | null = null;
+      for (let j = 0; j < windows.count; j++) {
+        const w = windows.objectAtIndex(j);
+        if (w.hidden || !w.rootViewController) continue;
+        if (!main || w.windowLevel < main.windowLevel) main = w;
+      }
+      for (let j = 0; j < windows.count; j++) {
+        const w = windows.objectAtIndex(j);
+        if (main && w !== main && w.windowLevel > 0 && !w.hidden) {
+          if (dbg) appendWebLog(`[native:recover] stray win[${j}] lvl=${w.windowLevel} uie=${w.userInteractionEnabled} key=${w.keyWindow}`);
+          w.userInteractionEnabled = false;
+          w.hidden = true;
+          w.windowScene = null; // detach from the scene — strongest removal
+          if (dbg) appendWebLog(`[native:recover]  after set: hidden=${w.hidden} uie=${w.userInteractionEnabled} scene=${w.windowScene ? 'set' : 'nil'}`);
+        }
+      }
+      if (main) main.makeKeyAndVisible();
+      if (dbg) {
+        let s = '';
+        const after = ws.windows;
+        for (let k = 0; k < after.count; k++) { const w = after.objectAtIndex(k); s += ` [${k}]lvl${w.windowLevel}h${w.hidden}k${w.keyWindow}`; }
+        appendWebLog(`[native:recover] post mainKey=${main ? main.keyWindow : '?'} windows:${s}`);
+      }
+    }
+  }
+
   createNativeView(): WKWebView {
     const config = WKWebViewConfiguration.new();
     config.allowsInlineMediaPlayback = true;

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

@@ -14,4 +14,17 @@ export class CustomWebView extends WebView {
   setRenderingActive(_active: boolean): void {
     /* overridden per-platform */
   }
+
+  /** iOS: wake the WebContent renderer on foreground so a system-sheet/background throttle doesn't
+   * leave the WebView frozen for ~30-45s (see custom-webview.ios.ts). No-op on Android. */
+  wakeWebContent(): void {
+    /* overridden per-platform */
+  }
+
+  /** Call after dismissing ANY native surface presented over the WebView (StoreKit sheet, OAuth,
+   * SFSafariViewController, pickers, share, alerts). iOS: neutralises an orphaned touch-stealing
+   * window the surface may leave + wakes the renderer (see custom-webview.ios.ts). No-op on Android. */
+  recoverAfterNativeSurface(): void {
+    /* overridden per-platform */
+  }
 }

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

@@ -1,5 +1,7 @@
 import { Utils, isIOS } from '@nativescript/core';
 import { bridge } from './bridge';
+import { appwrapNativeLog } from './native-log';
+import { SHELL_CONFIG } from './config';
 
 // @objc Swift shim (AppwrapManageSubscriptions.swift, billing nativeSrc) — no NS types; bridges
 // StoreKit 2's Swift-async showManageSubscriptions(in:) to a completion the ObjC bridge can call.
@@ -215,6 +217,11 @@ export function registerBillingHandlers(): void {
   bridge.register('billing.manageSubscriptionsSheet', () => {
     return new Promise<void>((resolve, reject) => {
       AppwrapManageSubscriptions.present((message: string | null) => {
+        if (SHELL_CONFIG.debug) appwrapNativeLog(`[native:lifecycle] manageSubscriptionsSheet done err=${message ?? 'none'}`);
+        // The sheet dismisses WITHOUT the app scene leaving foregroundActive → no resumeEvent, and it
+        // orphans a touch-stealing window above ours. Recover from this completion (the only callback
+        // that fires). Shared across all native surfaces; see CustomWebView.recoverAfterNativeSurface.
+        bridge.getWebView()?.recoverAfterNativeSurface();
         if (message) reject(err('NATIVE_ERROR', message));
         else resolve();
       });

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

@@ -57,6 +57,8 @@ class PhotoPickerDelegate extends NSObject implements PHPickerViewControllerDele
   }
   pickerDidFinishPicking(picker: PHPickerViewController, results: NSArray<PHPickerResult>): void {
     picker.dismissViewControllerAnimatedCompletion(true, null);
+    // Recover the WebView after the picker dismisses (orphaned-window / renderer-throttle guard).
+    bridge.getWebView()?.recoverAfterNativeSurface();
     const result = results.count > 0 ? results.objectAtIndex(0) : null;
     if (!result) return this.onResult?.({ picked: false });
     result.itemProvider.loadObjectOfClassCompletionHandler(UIImage.class(), (img: UIImage) => {

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

@@ -51,6 +51,9 @@ export function registerOAuthHandlers(): void {
             (callbackURL: NSURL, error: NSError) => {
               activeSession = null;
               activeProvider = null;
+              // ASWebAuthenticationSession can leave the WebView frozen on dismiss the same way the
+              // StoreKit sheet does (orphaned tracking window / no resume) — recover from its completion.
+              bridge.getWebView()?.recoverAfterNativeSurface();
               if (error) {
                 // ASWebAuthenticationSessionErrorCodeCanceledLogin === 1 (user dismissed the sheet).
                 const code = error.code === 1 ? 'CANCELLED' : 'NATIVE_ERROR';

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

@@ -5,6 +5,20 @@ declare const androidx: any; // no NS types: androidx
 
 const err = (code: string, message: string) => Object.assign(new Error(message), { code });
 
+// SFSafariViewController is a same-app presented surface — on "Done" it can leave the WebView frozen
+// (orphaned tracking window / throttled renderer), so recover from its didFinish. Strong-ref the
+// delegate while the browser is up (ARC would otherwise free it). Mirrors the OAuth delegate pattern.
+let activeSafariDelegate: NSObject | null = null;
+@NativeClass()
+class SafariDelegate extends NSObject implements SFSafariViewControllerDelegate {
+  static ObjCProtocols = [SFSafariViewControllerDelegate];
+  static new(): SafariDelegate { return <SafariDelegate>super.new(); }
+  safariViewControllerDidFinish(_controller: SFSafariViewController): void {
+    activeSafariDelegate = null;
+    bridge.getWebView()?.recoverAfterNativeSurface();
+  }
+}
+
 /** Running on a simulator/emulator? (mirrors env.ts detection; kept local to avoid a cross-import). */
 function detectEmulator(): boolean {
   if (isIOS) {
@@ -190,6 +204,8 @@ export function registerSystemHandlers(): void {
       Utils.dispatchToMainThread(() => {
         const vc = SFSafariViewController.alloc().initWithURL(NSURL.URLWithString(target));
         if (toolbarColor) vc.preferredControlTintColor = new Color(String(toolbarColor)).ios;
+        activeSafariDelegate = SafariDelegate.new();
+        vc.delegate = activeSafariDelegate as SFSafariViewControllerDelegate;
         Utils.ios.getRootViewController().presentViewControllerAnimatedCompletion(vc, true, null);
       });
     } else if (isAndroid) {

package/runtime/app/shell/handlers.ts

@@ -88,6 +88,9 @@ export function registerHandlers(): void {
       if (controller.popoverPresentationController) {
         controller.popoverPresentationController.sourceView = rootVC.view;
       }
+      // Recover the WebView on dismiss — a presented sheet can orphan a touch-stealing window / leave
+      // the renderer throttled (see CustomWebView.recoverAfterNativeSurface).
+      controller.completionWithItemsHandler = () => { bridge.getWebView()?.recoverAfterNativeSurface(); };
       rootVC.presentViewControllerAnimatedCompletion(controller, true, null);
     } else if (isAndroid) {
       const intent = new android.content.Intent(android.content.Intent.ACTION_SEND);

package/runtime/modules-native/billing/App_Resources/iOS/src/AppwrapManageSubscriptions.swift

@@ -5,12 +5,17 @@ import UIKit
 // StoreKit 2's `AppStore.showManageSubscriptions(in:)` is Swift-only + async, so it can't be reached
 // from the ObjC bridge NativeScript uses. This @objc wrapper bridges the async call to a completion
 // callback (NativeScript can't await Swift async) and runs it on the main actor against the active
-// foreground UIWindowScene. Shipped via the billing module's nativeSrc → compiled into the app target
-// only when `billing` is active. iOS 15+ (StoreKit 2); the JS layer guards the deep-link fallback.
+// foreground UIWindowScene. Shipped via the billing module's nativeSrc → compiled only when `billing`
+// is active. iOS 15+ (StoreKit 2); the JS layer guards the deep-link fallback.
+//
+// NOTE: this sheet presents/dismisses WITHOUT the app scene leaving foregroundActive, so iOS fires no
+// resumeEvent and leaves an orphaned interactive tracking-window above ours that swallows touches. The
+// JS handler recovers from THIS completion via `CustomWebView.recoverAfterNativeSurface()` (shared with
+// every other native surface) — so this shim only needs to present + report success/failure.
 @objc(AppwrapManageSubscriptions)
 public final class AppwrapManageSubscriptions: NSObject {
-  // completion(nil) on success; completion(message) on failure. Always invoked on the main thread
-  // so the NativeScript JS continuation (and WebView response delivery) resumes on the UI thread.
+  // completion(nil) on success; completion(message) on failure. Always invoked on the main thread so
+  // the NS JS continuation (which then drives the WebView recovery) resumes on the UI thread.
   @objc public static func present(_ completion: @escaping (String?) -> Void) {
     guard #available(iOS 15.0, *) else {
       completion("StoreKit 2 manage-subscriptions sheet requires iOS 15+")
@@ -31,7 +36,7 @@ public final class AppwrapManageSubscriptions: NSObject {
   }
 
   // The foreground-active window scene (the one allowed to present UI). Falls back to any connected
-  // window scene so a not-yet-foregroundActive launch still finds a presenter.
+  // window scene so a not-yet-foreground launch still finds a presenter.
   @MainActor private static func activeWindowScene() -> UIWindowScene? {
     let scenes = UIApplication.shared.connectedScenes.compactMap { $0 as? UIWindowScene }
     return scenes.first { $0.activationState == .foregroundActive } ?? scenes.first