@livx.cc/appwrap 0.30.1 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.30.1",
+  "version": "0.32.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/shell/custom-webview.android.ts

@@ -95,6 +95,12 @@ export class CustomWebView extends WebView {
     /* 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

@@ -113,6 +113,56 @@ export class CustomWebView extends WebView {
     );
   }
 
+  /** 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

@@ -20,4 +20,11 @@ export class CustomWebView extends WebView {
   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

@@ -5,8 +5,7 @@ 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.
-// completion(errorMessage, diagnostic): diagnostic is a post-dismiss window-hierarchy dump (DEBUG).
-declare const AppwrapManageSubscriptions: { present(completion: (message: string | null, diagnostic: string | null) => void): void };
+declare const AppwrapManageSubscriptions: { present(completion: (message: string | null) => void): void };
 
 /**
  * In-app purchases — iOS StoreKit 1 (SKPaymentQueue). StoreKit 2 (Product/Transaction)
@@ -217,14 +216,12 @@ export function registerBillingHandlers(): void {
   // deep-link path above is untouched. Rejects on iOS <15, no scene, or a StoreKit error.
   bridge.register('billing.manageSubscriptionsSheet', () => {
     return new Promise<void>((resolve, reject) => {
-      AppwrapManageSubscriptions.present((message: string | null, diagnostic: string | null) => {
-        if (SHELL_CONFIG.debug) appwrapNativeLog(`[native:lifecycle] manageSubscriptionsSheet done err=${message ?? 'none'}\n${diagnostic ?? '(no diag)'}`);
-        // The StoreKit sheet presents/dismisses WITHOUT the app scene leaving foregroundActive, so iOS
-        // never fires resumeEvent → the WebView's normal foreground wake (wakeWebContent) doesn't run.
-        // Drive it explicitly here (the only callback that fires) to un-throttle/repaint the WebView.
-        // (The native shim separately neutralises the orphaned StoreKit tracking-window that otherwise
-        // floats above our window and swallows touches — together they clear the post-sheet freeze.)
-        bridge.getWebView()?.wakeWebContent();
+      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-push.ts

@@ -19,10 +19,24 @@ import { SHELL_CONFIG } from './config';
 let pendingRegister: { resolve: (t: PushToken) => void; reject: (e: Error) => void } | null = null;
 let cachedToken: string | null = null;
 
-interface PushToken { platform: 'apns' | 'fcm'; token: string; }
+interface PushToken { platform: 'apns' | 'fcm'; token: string; topic?: string; }
+
+/** The app's bundle/package id — the APNs `apns-topic` MUST equal it or APNs rejects with
+ * `DeviceTokenNotForTopic`. iOS: NSBundle bundle id; Android: the application package id (FCM
+ * ignores apns-topic, so it's informational there). Resolved natively so consumers never hardcode it. */
+function appTopic(): string | undefined {
+  try {
+    if (isIOS) return NSBundle.mainBundle.bundleIdentifier;
+    if (isAndroid) return Utils.android.getApplicationContext().getPackageName();
+  } catch (e: any) {
+    console.log('[push] bundle-id resolve failed: ' + (e?.message ?? e));
+  }
+  return undefined;
+}
 
 /** POST the device token to the app's configured backend NATIVELY (no WKWebView fetch → no app://
- * cross-origin/CORS wall). The backend stores it + sends pushes. No-op when no URL is configured. */
+ * cross-origin/CORS wall). The backend stores it + sends pushes. No-op when no URL is configured.
+ * Includes `topic` (the bundle/package id) so the backend can set the correct apns-topic header. */
 function registerTokenWithBackend(platform: 'ios' | 'android', token: string): void {
   const url = SHELL_CONFIG.pushRegistrationUrl;
   if (!url) return;
@@ -31,7 +45,7 @@ function registerTokenWithBackend(platform: 'ios' | 'android', token: string): v
   try {
     Http.request({
       url, method: 'POST', headers: { 'Content-Type': 'application/json' },
-      content: JSON.stringify({ token, platform }),
+      content: JSON.stringify({ token, platform, topic: appTopic() }),
     })
       .then((res) => console.log('[push] token registered with backend → ' + res.statusCode))
       .catch((e: any) => console.log('[push] backend register failed: ' + (e?.message ?? e)));
@@ -48,7 +62,7 @@ export function onApnsToken(hexToken: string): void {
   console.log('[push] APNs token: ' + hexToken);
   registerTokenWithBackend('ios', hexToken);
   if (pendingRegister) {
-    pendingRegister.resolve({ platform: 'apns', token: hexToken });
+    pendingRegister.resolve({ platform: 'apns', token: hexToken, topic: appTopic() });
     pendingRegister = null;
   }
 }
@@ -143,7 +157,7 @@ export function registerPushHandlers(): void {
   bridge.register('push.register', () => {
     if (isIOS) {
       return new Promise<PushToken>((resolve, reject) => {
-        if (cachedToken) return resolve({ platform: 'apns', token: cachedToken });
+        if (cachedToken) return resolve({ platform: 'apns', token: cachedToken, topic: appTopic() });
         pendingRegister = { resolve, reject };
         Utils.dispatchToMainThread(() => UIApplication.sharedApplication.registerForRemoteNotifications());
         setTimeout(() => {
@@ -235,7 +249,7 @@ function androidGetToken(): Promise<PushToken> {
           if (t.isSuccessful()) {
             const tok = String(t.getResult());
             registerTokenWithBackend('android', tok); // parity with iOS onApnsToken
-            resolve({ platform: 'fcm', token: tok });
+            resolve({ platform: 'fcm', token: tok, topic: appTopic() });
           } else reject(Object.assign(new Error('FCM token fetch failed'), { code: '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,87 +5,36 @@ 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.
 //
-// THE FREEZE IT FIXES: showManageSubscriptions(in:) presents/dismisses WITHOUT the app scene ever
-// leaving foregroundActive (verified: zero app-lifecycle events fire across present→dismiss), so (a)
-// the OS never fires a resume the WebView could wake on, and (b) the dismissal leaves an orphaned
-// interactive UITrackingElementWindow at windowLevel 1 ABOVE our app window that swallows every touch —
-// the app underneath stays alive but unresponsive ("frozen for minutes" until iOS reaps the window).
-// We recover explicitly from THIS completion (the only thing that fires): after letting the dismissal
-// settle, neutralise any stray above-our-main window (uie=false + hide) and re-key our window. The JS
-// layer additionally drives the WebView's own resume (wakeWebContent) since no native resume arrives.
+// 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(error, diagnostic): error nil on success / message on failure; diagnostic is a
-  // before/after window-hierarchy dump (DEBUG aid) the JS layer logs to the file sink. Always on main.
-  @objc public static func present(_ completion: @escaping (String?, String?) -> Void) {
+  // 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+", nil)
+      completion("StoreKit 2 manage-subscriptions sheet requires iOS 15+")
       return
     }
     Task { @MainActor in
       guard let scene = AppwrapManageSubscriptions.activeWindowScene() else {
-        completion("No active UIWindowScene to present the subscriptions sheet", nil)
+        completion("No active UIWindowScene to present the subscriptions sheet")
         return
       }
-      var err: String? = nil
       do {
         try await AppStore.showManageSubscriptions(in: scene)
+        completion(nil)
       } catch {
-        err = error.localizedDescription
+        completion(error.localizedDescription)
       }
-      let before = AppwrapManageSubscriptions.dump(scene, tag: "BEFORE")
-      // The await can return before the dismissal animation finishes finalizing the orphan tracking
-      // window — settle first, then neutralise it (hiding at completion-time was too early to stick).
-      try? await Task.sleep(nanoseconds: 350_000_000)
-      let after = AppwrapManageSubscriptions.recover(scene)
-      completion(err, before + "\n" + after)
     }
   }
 
-  // Read-only dump of the scene's windows (+ presented-VC chain, key/interaction flags) for diagnosis.
-  @available(iOS 15.0, *)
-  @MainActor private static func dump(_ scene: UIWindowScene, tag: String) -> String {
-    var lines: [String] = ["\(tag): windows=\(scene.windows.count) keyWin=\(scene.keyWindow.map { ptr($0) } ?? "nil")"]
-    for (i, w) in scene.windows.enumerated() {
-      var presented: [String] = []
-      var vc = w.rootViewController
-      while let p = vc?.presentedViewController { presented.append(String(describing: type(of: p))); vc = p }
-      lines.append("  [\(i)] \(ptr(w)) level=\(w.windowLevel.rawValue) key=\(w.isKeyWindow) hidden=\(w.isHidden) uie=\(w.isUserInteractionEnabled) root=\(w.rootViewController.map { String(describing: type(of: $0)) } ?? "nil") presented=\(presented.isEmpty ? "none" : presented.joined(separator: ">"))")
-    }
-    return lines.joined(separator: "\n")
-  }
-
-  // Neutralise any window sitting ABOVE our main app window (touch-stealer), dismiss a lingering
-  // presented controller, and re-assert our main window as key. Returns the post-recovery dump.
-  @available(iOS 15.0, *)
-  @MainActor private static func recover(_ scene: UIWindowScene) -> String {
-    var lines: [String] = []
-    let main = scene.windows
-      .filter { !$0.isHidden && $0.rootViewController != nil }
-      .min { $0.windowLevel.rawValue < $1.windowLevel.rawValue }
-    for (i, w) in scene.windows.enumerated() {
-      if let presented = w.rootViewController?.presentedViewController {
-        presented.dismiss(animated: false)
-        lines.append("  recover: dismissed \(String(describing: type(of: presented))) on win[\(i)]")
-      }
-      if let m = main, w !== m, w.windowLevel.rawValue >= m.windowLevel.rawValue, w.windowLevel.rawValue > 0 {
-        // Pass touches THROUGH to our app window below, and take it out of the hierarchy.
-        w.isUserInteractionEnabled = false
-        w.isHidden = true
-        lines.append("  recover: neutralised win[\(i)] level=\(w.windowLevel.rawValue) root=\(w.rootViewController.map { String(describing: type(of: $0)) } ?? "nil")")
-      }
-    }
-    if let m = main { m.makeKeyAndVisible(); lines.append("  recover: re-keyed main") }
-    return AppwrapManageSubscriptions.dump(scene, tag: "AFTER-RECOVER") + "\n" + lines.joined(separator: "\n")
-  }
-
-  @MainActor private static func ptr(_ w: UIWindow) -> String {
-    return "UIWindow<\(UInt(bitPattern: ObjectIdentifier(w).hashValue) & 0xffffff)>"
-  }
-
   // The foreground-active window scene (the one allowed to present UI). Falls back to any connected
   // window scene so a not-yet-foreground launch still finds a presenter.
   @MainActor private static func activeWindowScene() -> UIWindowScene? {

package/runtime/package.json

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

package/src/cli.ts

@@ -9,7 +9,7 @@
  * Shape: { id, name, version, entry?, backgroundColor?, statusBarStyle?, pwaDist }. See config.ts.
  */
 import { execFileSync } from 'child_process';
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { cpSync, existsSync, mkdirSync, openSync, closeSync, readdirSync, readFileSync, readSync, rmSync, statSync, writeFileSync, writeSync } from 'fs';
 import { networkInterfaces, tmpdir } from 'os';
 import { dirname, join, resolve } from 'path';
 import { pathToFileURL } from 'url';
@@ -336,11 +336,17 @@ async function readConfigFile(configPath: string): Promise<AppwrapConfig> {
   return cfg as AppwrapConfig;
 }
 
-async function loadConfig(cwd: string, flags: Record<string, string>): Promise<AppwrapConfig> {
-  // Explicit --config wins; otherwise probe ts → js → json (TS preferred).
-  const configPath = flags.config
+/** Resolve the user's appwrap config file path the CLI loads from: explicit --config wins;
+ * otherwise probe ts → js → json (TS preferred). Single source of discovery (reused by the
+ * team-id pin-to-config writer so it never re-invents the probe). */
+function resolveConfigPath(cwd: string, flags: Record<string, string>): string {
+  return flags.config
     ? resolve(cwd, flags.config)
     : (CONFIG_CANDIDATES.map((f) => resolve(cwd, f)).find(existsSync) ?? resolve(cwd, CONFIG_CANDIDATES[0]));
+}
+
+async function loadConfig(cwd: string, flags: Record<string, string>): Promise<AppwrapConfig> {
+  const configPath = resolveConfigPath(cwd, flags);
   if (!existsSync(configPath)) {
     console.error(`✖ Config not found — looked for ${CONFIG_CANDIDATES.join(' / ')} in ${cwd}`);
     process.exit(1);
@@ -463,15 +469,31 @@ function stampIOSDisplayName(outDir: string, cfg: AppwrapConfig, req: NativeReqs
   writeFileSync(plist, src);
 }
 
-function stampTeamId(outDir: string, cfg: AppwrapConfig): void {
+function stampTeamId(outDir: string, cfg: AppwrapConfig, ctx?: { cwd: string; configPath: string }): void {
   const xcconfig = join(outDir, 'App_Resources/iOS/build.xcconfig');
-  // A placeholder/empty teamId silently produces an unsignable build (DEVELOPMENT_TEAM = YOUR_APPLE_TEAM_ID
-  // → xcodebuild "No Account for Team"). Warn loudly rather than let a long build fail cryptically.
-  if (!cfg.teamId || /YOUR_APPLE_TEAM_ID|^$/.test(cfg.teamId)) {
-    console.warn(`⚠ teamId is unset/placeholder ("${cfg.teamId ?? ''}") — device builds won't sign.\n` +
-      '  Set it to your Apple Team ID in appwrap.config (Xcode → Settings → Accounts shows it; ' +
-      'Individual = paid, Personal Team = free).');
-    return;
+  // Resolution order: a real (non-placeholder) cfg.teamId wins; else $APPWRAP_TEAM_ID (headless/CI);
+  // else the enriched interactive picker (which then offers to pin its choice to the config). This
+  // intercepts BEFORE `ns build` runs so NS never shows its plain, unenriched prompt.
+  const isPlaceholder = !cfg.teamId || /YOUR_APPLE_TEAM_ID|^$/.test(cfg.teamId);
+  if (isPlaceholder) {
+    const envTeam = process.env.APPWRAP_TEAM_ID?.trim();
+    if (envTeam) {
+      cfg.teamId = envTeam;
+      console.log(`  team ← ${envTeam} (from $APPWRAP_TEAM_ID)`);
+    } else if (!process.stdout.isTTY) {
+      console.warn(`⚠ teamId is unset — set it in appwrap.config, set $APPWRAP_TEAM_ID, or run interactively to pick from your teams.`);
+      return;
+    } else {
+      const picked = pickTeamIdInteractively();
+      cfg.teamId = picked.teamId;
+      // Offer to persist the choice so the user isn't re-prompted on every deploy. No-TTY/headless is
+      // already handled above; promptYesNo additionally guards against a non-interactive stdin.
+      if (ctx && promptYesNo(`  Pin "${picked.name} (${picked.teamId})" to appwrap.config so you're not asked again?`, true)) {
+        pinTeamIdToConfig(ctx.configPath, picked.teamId);
+      } else {
+        console.log(`  ⓘ  To skip this prompt: set teamId: "${picked.teamId}" in appwrap.config (or set $APPWRAP_TEAM_ID).`);
+      }
+    }
   }
   if (!existsSync(xcconfig)) return;
   let src = readFileSync(xcconfig, 'utf8');
@@ -948,7 +970,7 @@ function copyCiTemplates(cwd: string, outDir: string, cfg: AppwrapConfig): void
  * Excludes the first-time scaffold (managed-guard, CI, .gitignore) + overrides/version-manifest, which the
  * callers sequence around this so overrides win LAST and the marker writes after.
  */
-function regenerateCore(cwd: string, outDir: string, cfg: AppwrapConfig, opts: { firstRun?: boolean } = {}): void {
+function regenerateCore(cwd: string, outDir: string, cfg: AppwrapConfig, opts: { firstRun?: boolean; flags?: Record<string, string> } = {}): void {
   const req = nativeReqs(cfg);
   if (opts.firstRun && !req.explicit) {
     console.log('  ℹ no `modules` in the appwrap config → all capabilities active. Declare `modules` to shrink the store build (strip unused handlers/perms).');
@@ -964,7 +986,7 @@ function regenerateCore(cwd: string, outDir: string, cfg: AppwrapConfig, opts: {
   stampShellConfig(outDir, cfg);
   stampNativeScriptConfig(outDir, cfg);
   stampIOSDisplayName(outDir, cfg, req);
-  stampTeamId(outDir, cfg);
+  stampTeamId(outDir, cfg, { cwd, configPath: resolveConfigPath(cwd, opts.flags ?? {}) });
   stampAndroidAppName(outDir, cfg, req);
   stampAndroidVersion(outDir, cfg);
   stampAndroidGradleDeps(outDir, req.androidGradleDeps);
@@ -1004,7 +1026,7 @@ async function init(cwd: string, flags: Record<string, string>): Promise<void> {
 
   console.log(`🎁 appwrap init → ${outDir}`);
   mkdirSync(outDir, { recursive: true });
-  regenerateCore(cwd, outDir, cfg, { firstRun: true });
+  regenerateCore(cwd, outDir, cfg, { firstRun: true, flags });
   copyCiTemplates(cwd, outDir, cfg); // first-time scaffold (never overwrites)
   writeFileSync(join(outDir, '.gitignore'), 'node_modules/\nplatforms/\nhooks/\n');
   applyOverrides(cwd, outDir, cfg); // escape hatch — last, so custom native code wins
@@ -1022,7 +1044,7 @@ async function sync(cwd: string, flags: Record<string, string>): Promise<void> {
     console.error(`✖ Wrapper not found at ${outDir} — run \`appwrap init\` first`);
     process.exit(1);
   }
-  regenerateCore(cwd, outDir, cfg);
+  regenerateCore(cwd, outDir, cfg, { flags });
   applyOverrides(cwd, outDir, cfg); // overrides win last
   stampVersionManifest(outDir, cfg); // keep the managed-marker / provenance current
   console.log('✓ Synced.');
@@ -1121,6 +1143,7 @@ async function build(cwd: string, flags: Record<string, string>, positionals: st
   }
 }
 
+interface AppleTeam { teamId: string; name: string; email?: string; paid: boolean }
 interface DeviceInfo { id: string; name: string; model: string; transport: string }
 
 /** The subset of a `xcrun devicectl list devices --json-output` device entry appwrap reads. */
@@ -1131,6 +1154,217 @@ interface DevicectlDevice {
   connectionProperties?: { tunnelState?: string; transportType?: string };
 }
 
+/** Read Apple team metadata from provisioning profiles + distribution certs in the keychain.
+ * Provisioning profiles give us the reliable teamId↔teamName mapping; distribution certs
+ * often embed the account email in the display name. */
+function detectAppleTeams(): AppleTeam[] {
+  const teams = new Map<string, AppleTeam>();
+
+  // 1. Provisioning profiles → teamId + teamName (most reliable)
+  const profilesDir = join(process.env.HOME ?? '', 'Library/MobileDevice/Provisioning Profiles');
+  if (existsSync(profilesDir)) {
+    try {
+      const files = readdirSync(profilesDir).filter((f) => f.endsWith('.mobileprovision'));
+      for (const f of files) {
+        try {
+          const raw = execFileSync('security', ['cms', '-D', '-i', join(profilesDir, f)],
+            { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+          const idMatch = raw.match(/<key>TeamIdentifier<\/key>\s*<array>\s*<string>([^<]+)<\/string>/);
+          const nameMatch = raw.match(/<key>TeamName<\/key>\s*<string>([^<]+)<\/string>/);
+          if (idMatch && nameMatch) {
+            const teamId = idMatch[1];
+            const name = nameMatch[1];
+            const free = /personal team/i.test(name);
+            if (!teams.has(teamId)) teams.set(teamId, { teamId, name, paid: !free });
+          }
+        } catch { /* skip unreadable profile */ }
+      }
+    } catch { /* skip if dir unreadable */ }
+  }
+
+  // 2. Keychain distribution/Developer-ID certs → teamId + possible email in name
+  try {
+    const out = execFileSync('security', ['find-identity', '-v', '-p', 'codesigning'],
+      { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+    for (const line of out.split('\n')) {
+      const m = line.match(/"(?:Apple Distribution|Developer ID Application): (.+?) \(([A-Z0-9]{10})\)"/);
+      if (!m) continue;
+      const [, label, teamId] = m;
+      const email = label.includes('@') ? label.trim() : undefined;
+      const existing = teams.get(teamId);
+      if (existing) {
+        if (email && !existing.email) existing.email = email;
+      } else {
+        teams.set(teamId, { teamId, name: label.trim(), email, paid: !/personal team/i.test(label) });
+      }
+    }
+  } catch { /* keychain unavailable */ }
+
+  return [...teams.values()];
+}
+
+/** Arrow-key interactive selector. Returns the index of the chosen item. */
+function arrowSelect(prompt: string, items: string[]): number {
+  const tty = openSync('/dev/tty', 'r+');
+  const write = (s: string) => writeSync(tty, s);
+  const ESC = '\x1b';
+
+  write(`${prompt}\n`);
+  let idx = 0;
+  const HINT = '\x1b[2m  ↑↓ / j k to move · Enter to confirm\x1b[0m';
+  const render = (clear: boolean) => {
+    if (clear) write(`\x1b[${items.length + 1}A`); // +1 for the hint line
+    for (let i = 0; i < items.length; i++)
+      write(`\r\x1b[K${i === idx ? '❯ ' : '  '}${items[i]}\n`);
+    write(`\r\x1b[K${HINT}\n`);
+  };
+  render(false);
+
+  // raw mode via stty
+  execFileSync('stty', ['-icanon', '-echo'], { stdio: ['inherit', 'inherit', 'inherit'] });
+  const buf = Buffer.alloc(6);
+  try {
+    for (;;) {
+      const n = readSync(tty, buf, 0, 6, null);
+      const key = buf.slice(0, n).toString();
+      if (key === `${ESC}[A` || key === 'k') { idx = (idx - 1 + items.length) % items.length; render(true); }
+      else if (key === `${ESC}[B` || key === 'j') { idx = (idx + 1) % items.length; render(true); }
+      else if (key === '\r' || key === '\n') break;
+      else if (key === '\x03') { write('\n'); process.exit(1); } // Ctrl-C
+    }
+  } finally {
+    execFileSync('stty', ['icanon', 'echo'], { stdio: ['inherit', 'inherit', 'inherit'] });
+    // Erase the hint line so the selected value prints cleanly after
+    write(`\x1b[1A\r\x1b[K`);
+    write('\n');
+    closeSync(tty);
+  }
+  return idx;
+}
+
+/** Interactively prompt for an Apple team when teamId is unset. Shows enriched metadata
+ * (email, paid/free) sourced from local keychain + provisioning profiles. */
+function pickTeamIdInteractively(): { teamId: string; name: string } {
+  const teams = detectAppleTeams();
+  if (teams.length === 0) {
+    console.error('✖ No Apple signing teams found in keychain/provisioning profiles.\n' +
+      '  Sign into Xcode → Settings → Accounts, then re-run.');
+    process.exit(1);
+  }
+  if (teams.length === 1) {
+    const t = teams[0];
+    console.log(`  team ← ${t.name} (${t.teamId})${t.email ? ` <${t.email}>` : ''} [${t.paid ? 'paid' : 'free'}] (only option)`);
+    return { teamId: t.teamId, name: t.name };
+  }
+  const items = teams.map((t) => {
+    const badge = t.paid ? '✓ paid' : '○ free';
+    const email = t.email ? ` <${t.email}>` : '';
+    return `${t.name} (${t.teamId})${email}  [${badge}]`;
+  });
+  const idx = arrowSelect('Found multiple Apple teams — pick one to use for signing:', items);
+  return { teamId: teams[idx].teamId, name: teams[idx].name };
+}
+
+/** Y/n confirmation on the TTY (default-yes here). Reuses the global `prompt` primitive. A
+ * non-interactive / piped stdin returns null → falls back to `def` ONLY when there's a real TTY;
+ * a fully headless run never reaches here (callers gate on `process.stdout.isTTY` first), but be
+ * defensive: if stdin can't be read, do NOT pin (safer to re-ask than to silently mutate config). */
+function promptYesNo(message: string, def: boolean): boolean {
+  if (!process.stdin.isTTY) return false;
+  const suffix = def ? ' [Y/n] ' : ' [y/N] ';
+  const ans = (globalThis as { prompt(msg?: string): string | null }).prompt(message + suffix);
+  if (ans == null) return false;
+  const a = ans.trim().toLowerCase();
+  if (a === '') return def;
+  return a === 'y' || a === 'yes';
+}
+
+/** Persist `teamId` into the user's appwrap config so the interactive picker isn't re-run every
+ * deploy. Pure string surgery (returns the new file content) so it's unit-testable across both
+ * supported formats:
+ *  - `.json` — set/replace the top-level `"teamId"` property (preserves 2-space indent).
+ *  - `.ts`/`.js` — replace an existing `teamId:` field value (incl. the `YOUR_APPLE_TEAM_ID`
+ *    placeholder), else insert a new `teamId: '<id>',` line near the other top-level fields
+ *    (after `id:`, matching its indentation/quote style). If the shape is unexpected, returns
+ *    `null` so the caller skips the write rather than corrupting the file. */
+export function pinTeamIdInConfigSource(src: string, teamId: string, isJson: boolean): string | null {
+  if (isJson) {
+    let obj: Record<string, unknown>;
+    try { obj = JSON.parse(src) as Record<string, unknown>; } catch { return null; }
+    if (typeof obj !== 'object' || obj == null) return null;
+    obj.teamId = teamId;
+    return JSON.stringify(obj, null, 2) + (src.endsWith('\n') ? '\n' : '');
+  }
+  // TS/JS: replace an existing teamId field value, preserving its quote style.
+  const existing = /(\bteamId\s*:\s*)(['"`])[^'"`]*\2/;
+  if (existing.test(src)) {
+    return src.replace(existing, (_m, lead: string, q: string) => `${lead}${q}${teamId}${q}`);
+  }
+  // No teamId field — insert after the `id:` field (mirroring its indentation + quote style).
+  const idLine = /^([ \t]*)id\s*:\s*(['"`])[^'"`]*\2\s*,?[ \t]*$/m;
+  const m = idLine.exec(src);
+  if (!m) return null; // unfamiliar shape — don't risk corrupting it
+  const indent = m[1];
+  const quote = m[2];
+  return src.slice(0, m.index + m[0].length)
+    + `\n${indent}teamId: ${quote}${teamId}${quote},`
+    + src.slice(m.index + m[0].length);
+}
+
+/** Write the pinned teamId to the resolved config file (thin IO wrapper over the pure helper). */
+function pinTeamIdToConfig(configPath: string, teamId: string): void {
+  if (!existsSync(configPath)) {
+    console.warn(`  ⚠ could not pin teamId — config not found at ${configPath}`);
+    return;
+  }
+  const src = readFileSync(configPath, 'utf8');
+  const next = pinTeamIdInConfigSource(src, teamId, configPath.endsWith('.json'));
+  if (next == null) {
+    console.warn(`  ⚠ couldn't safely edit ${configPath} (unexpected shape) — leaving it untouched. Set teamId: '${teamId}' manually.`);
+    return;
+  }
+  writeFileSync(configPath, next);
+  console.log(`  ✓ pinned teamId: '${teamId}' to ${configPath}`);
+}
+
+// ── Build fingerprint for smart resume ───────────────────────────────────────────────────────────
+
+/** Cheap fingerprint of SOURCE build inputs: mtime sum of the PWA dist/ + appwrap config.
+ * App_Resources/ is intentionally excluded — sync() rewrites it every run, so its mtime always
+ * changes and would make the fingerprint permanently stale.
+ * Collision risk is acceptable — a false "match" just skips a redundant build, not a correctness bug. */
+function buildFingerprint(cwd: string, cfg: { pwaDist?: string }, _outDir: string): string {
+  const mtime = (p: string): number => {
+    if (!existsSync(p)) return 0;
+    try {
+      const s = statSync(p);
+      if (s.isDirectory()) {
+        let sum = 0;
+        for (const e of readdirSync(p, { withFileTypes: true }))
+          sum += mtime(join(p, e.name));
+        return sum;
+      }
+      return s.mtimeMs;
+    } catch { return 0; }
+  };
+  const distDir = cfg.pwaDist ? resolve(cwd, cfg.pwaDist) : join(cwd, 'dist');
+  const parts = [mtime(distDir), mtime(join(cwd, 'appwrap.config.ts'))];
+  // Simple djb2-style hash — good enough for a build-skip check (not cryptographic).
+  let h = 5381;
+  for (const n of parts) h = (((h << 5) + h) ^ (n | 0)) >>> 0;
+  return h.toString(36);
+}
+
+const BUILD_CACHE_FILE = '.appwrap-build-cache.json';
+interface BuildCache { fingerprint: string; ipaPath: string; builtAt: string }
+
+function readBuildCache(outDir: string): BuildCache | null {
+  try { return JSON.parse(readFileSync(join(outDir, BUILD_CACHE_FILE), 'utf8')); } catch { return null; }
+}
+function writeBuildCache(outDir: string, cache: BuildCache): void {
+  try { writeFileSync(join(outDir, BUILD_CACHE_FILE), JSON.stringify(cache, null, 2)); } catch { /* non-fatal */ }
+}
+
 /** Discover usable physical iOS devices via devicectl (USB + network). Excludes 'unavailable'
  * tunnels and non-iOS (watch). Returns [] if none. */
 function listIosDevices(): DeviceInfo[] {
@@ -1199,27 +1433,53 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
   await sync(cwd, flags); // re-stamp config + copy latest PWA dist (+ vendor backend assets)
   // Dev deploy → debug mode: keep-awake + WebView inspector for continuous troubleshooting.
   stampShellConfig(outDir, { ...cfg, debug: true });
-  console.log('▶ ns build ios --for-device  (debug: keep-awake + inspector on)');
-  try {
-    execFileSync('ns', ['build', 'ios', '--for-device'], { cwd: outDir, stdio: 'inherit' });
-  } catch (e) {
-    // The xcodebuild dump above is cryptic; surface the two signing failures we actually hit most.
-    console.error(
-      '\n✖ Device build failed — if the errors above mention signing:\n' +
-        `  • "Failed Registering Bundle Identifier … not available" → the App ID "${cfg.id}" is already\n` +
-        '    registered to another team (e.g. a prior free-team build). Change `id` in appwrap.config to a\n' +
-        '    unique string and re-deploy.\n' +
-        '  • "profile doesn\'t include the … entitlement" (e.g. HealthKit) → that capability needs a PAID\n' +
-        '    team (Individual). A free Personal Team can\'t hold it — switch teamId or drop the module.\n' +
-        '  • "No Account for Team" → sign that Apple ID into Xcode → Settings → Accounts first.'
-    );
-    process.exit(1);
-  }
 
   const ipaDir = join(outDir, 'platforms/ios/build/Debug-iphoneos');
-  const ipa = existsSync(ipaDir) ? readdirSync(ipaDir).find((f) => f.endsWith('.ipa')) : undefined;
+
+  // Smart resume: skip ns build (pod install + xcodebuild) when inputs haven't changed.
+  // --resume (-r): opt in to fingerprint-based skip (same logic as auto, but explicit — useful when
+  //   the auto check has no prior cache yet and you want to force a skip on first run after a manual build).
+  // Auto: always checks fingerprint; never skips if sources/deps changed.
+  const resume = 'resume' in flags || 'r' in flags;
+  const force = 'force' in flags || 'f' in flags;
+  const fp = buildFingerprint(cwd, cfg, outDir);
+  const cache = readBuildCache(outDir);
+  const existingIpa = existsSync(ipaDir)
+    ? readdirSync(ipaDir).find((f) => f.endsWith('.ipa'))
+    : undefined;
+  const fingerprintMatch = !force && existingIpa && cache?.fingerprint === fp && cache?.ipaPath === join(ipaDir, existingIpa);
+  // --resume also accepts a missing cache file (e.g. after a manual Xcode build or first run),
+  // but ONLY when the fingerprint matches what's currently on disk — never skips a needed build.
+  const noCache = existingIpa && !cache;
+  const canSkipBuild = !force && (fingerprintMatch || (resume && noCache));
+
+  if (canSkipBuild) {
+    const reason = fingerprintMatch ? 'inputs unchanged since last build' : '--resume (first run, .ipa present)';
+    console.log(`⚡ Skipping build — ${reason} (${existingIpa})`);
+  } else {
+    console.log(`▶ ns build ios --for-device  (debug: keep-awake + inspector on)${force ? '  [--force: skipping cache]' : ''}`);
+    try {
+      execFileSync('ns', ['build', 'ios', '--for-device'], { cwd: outDir, stdio: 'inherit' });
+    } catch (e) {
+      // The xcodebuild dump above is cryptic; surface the two signing failures we actually hit most.
+      console.error(
+        '\n✖ Device build failed — if the errors above mention signing:\n' +
+          `  • "Failed Registering Bundle Identifier … not available" → the App ID "${cfg.id}" is already\n` +
+          '    registered to another team (e.g. a prior free-team build). Change `id` in appwrap.config to a\n' +
+          '    unique string and re-deploy.\n' +
+          '  • "profile doesn\'t include the … entitlement" (e.g. HealthKit) → that capability needs a PAID\n' +
+          '    team (Individual). A free Personal Team can\'t hold it — switch teamId or drop the module.\n' +
+          '  • "No Account for Team" → sign that Apple ID into Xcode → Settings → Accounts first.'
+      );
+      process.exit(1);
+    }
+  }
+
+  const builtIpa = existsSync(ipaDir) ? readdirSync(ipaDir).find((f) => f.endsWith('.ipa')) : undefined;
+  const ipa = builtIpa;
   if (!ipa) { console.error(`✖ No .ipa produced in ${ipaDir}`); process.exit(1); }
   const ipaPath = join(ipaDir, ipa);
+  if (!canSkipBuild) writeBuildCache(outDir, { fingerprint: fp, ipaPath, builtAt: new Date().toISOString() });
 
   console.log(`▶ installing ${ipa} → ${device.name} [${device.transport}]`);
   let installedViaUsbmux = false;