@livx.cc/appwrap 0.41.0 → 0.42.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.41.0",
+  "version": "0.42.1",
   "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/config.ts

@@ -59,4 +59,10 @@ export const SHELL_CONFIG = {
    * `{ token, platform: 'ios'|'android' }`. Native HTTP avoids the WKWebView `app://` cross-origin/CORS
    * wall, so a token reaches your server without any WebView fetch. Empty = the app handles sending. */
   pushRegistrationUrl: '',
+  /** iOS only. Extra points to lift the WebView ABOVE the reported keyboard height on focus. iOS 26
+   * reports a keyboard ~this-many points TALLER than it draws on warm re-focus (a phantom accessory
+   * reservation), which would leave a black strip between the resized WebView and the real keys.
+   * Lifting extra makes the page cover that strip (the keyboard hides the thin bottom row of content).
+   * Default 82. Set 0 for NO extra lift (input sits flush at the reported height; the strip may show). */
+  iosKeyboardExtraLift: 82,
 };

package/runtime/app/shell/keyboard.ts

@@ -1,12 +1,24 @@
 import { Application, Utils, isAndroid, isIOS } from '@nativescript/core';
 import { bridge } from './bridge';
+import { SHELL_CONFIG } from './config';
+import { appwrapNativeLog } from './native-log';
 
 declare const android: any;
 // iOS keyboard-notification globals (marshalled from UIKit at runtime).
 declare const NSNotificationCenter: any;
 declare const UIKeyboardWillShowNotification: string;
+declare const UIKeyboardDidShowNotification: string;
 declare const UIKeyboardWillHideNotification: string;
+declare const UIKeyboardDidHideNotification: string;
+declare const UIKeyboardWillChangeFrameNotification: string;
+declare const UIKeyboardDidChangeFrameNotification: string;
 declare const UIKeyboardFrameEndUserInfoKey: string;
+declare const UIKeyboardAnimationDurationUserInfoKey: string;
+declare const UIEdgeInsetsZero: any;
+declare const NSObject: any;
+declare const UIScrollViewDelegate: any;
+declare function CGPointMake(x: number, y: number): any;
+declare const UIColor: any;
 
 let observersArmed = false;
 
@@ -36,17 +48,217 @@ export function registerKeyboardHandlers(): void {
   else if (isAndroid) armAndroidKeyboardObserver();
 }
 
-/** iOS: NSNotificationCenter observers → emit keyboard.show {height} / keyboard.hide. */
+/**
+ * iOS: native keyboard avoidance — a faithful port of Capacitor's `resize: native` mode
+ * (capacitor-keyboard Keyboard.m), which is the battle-tested way to do this in a WKWebView shell:
+ *
+ *  1. DETACH the WKWebView from UIKit keyboard notifications. WKWebView internally observes them
+ *     and applies its own scrollView insets/auto-scroll; with two keyboard-handling authorities the
+ *     layouts stack and fling content. Capacitor removes the webview as an observer so the shell is
+ *     the ONLY authority.
+ *  2. RESIZE the webview frame to (window height − keyboard height) AFTER the keyboard animation
+ *     finishes (animationDuration + 0.2s, debounced) — never mid-animation. Restore on hide with a
+ *     near-zero delay. `marginBottom` is kept in sync so NativeScript layout passes agree with the
+ *     frame instead of clobbering it.
+ *  3. ZERO the scrollView contentInset on every keyboard event — WebKit's leftover keyboard inset
+ *     is what double-compensates and leaves black bands.
+ *
+ * Also emits keyboard.show {height} / keyboard.hide to the page (heights in points ≈ CSS px).
+ */
 function armIosKeyboardObservers(): void {
   const center = NSNotificationCenter.defaultCenter;
-  center.addObserverForNameObjectQueueUsingBlock(UIKeyboardWillShowNotification, null, null, (note: any) => {
+  let paddingBottom = 0;
+  let pendingUpdate: any = null;
+  let webkitDetached = false;
+  // Extra lift applied by the CURRENT show, decided by whether the ▲▼✓ accessory bar is drawn:
+  // a COLD focus (fires UIKeyboardWillShow) draws the bar → reported height is accurate → 0 extra;
+  // a WARM re-focus (arrives as didShow-only, no willShow) drops the bar but still reports the taller
+  // height → apply the configured extra lift to close the gap. Reset when the keyboard fully hides.
+  let sawWillShow = false;
+  let activeExtraLift = 0;
+
+  const getWk = (): WKWebView | undefined => bridge.getWebView()?.ios as WKWebView | undefined;
+
+  // (1) Make the shell the only keyboard-handling authority (Capacitor does exactly this in load()).
+  const detachWebKitKeyboardHandling = (): void => {
+    if (webkitDetached) return;
+    const wk = getWk();
+    if (!wk) return;
+    for (const name of [
+      UIKeyboardWillShowNotification,
+      UIKeyboardWillHideNotification,
+      UIKeyboardWillChangeFrameNotification,
+      UIKeyboardDidChangeFrameNotification,
+    ]) {
+      center.removeObserverNameObject(wk, name, null);
+    }
+    webkitDetached = true;
+    if (SHELL_CONFIG.debug) appwrapNativeLog('[native:keyboard] detached WKWebView keyboard observers');
+  };
+
+  // (3) Kill WebKit's keyboard contentInset so it can't double-compensate our resize.
+  const resetScrollView = (): void => {
+    const wk = getWk();
+    if (wk) wk.scrollView.contentInset = UIEdgeInsetsZero;
+  };
+
+  // (2) The Capacitor _updateFrame: webview frame = window bounds minus the keyboard band.
+  // Never skippable: if the webview is momentarily detached from the window (page navigation,
+  // instance switch — which is also when the keyboard dismisses), RETRY until it reattaches.
+  // A bailed restore that's assumed applied leaves the frame shrunk forever (black band).
+  const updateFrame = (attempt = 0): void => {
+    const wv = bridge.getWebView();
+    const wk = getWk();
+    const win = wk?.window;
+    if (!wv || !wk || !win) {
+      if (attempt < 20) pendingUpdate = setTimeout(() => Utils.dispatchToMainThread(() => updateFrame(attempt + 1)), 100);
+      else if (SHELL_CONFIG.debug) appwrapNativeLog(`[native:keyboard] frame update gave up (webview detached), pad=${paddingBottom}`);
+      return;
+    }
+    // SINGLE layout authority: NativeScript. Only the margin changes — never wk.frame directly.
+    // A manual frame write disagrees with NS layout (safe-area math) and the two ping-pong,
+    // which is what produced gaps, content under the status bar, and residual scroll state.
+    // Subtract the bottom safe-area inset: NS layout already excludes it, and the keyboard COVERS
+    // it — margining the full keyboard height double-counts those 34pt as a gap above the keyboard.
+    const safeBottom = win.safeAreaInsets?.bottom ?? 0;
+    // On a WARM re-focus iOS 26 reports a keyboard TALLER than it draws (it reserves the ▲▼✓ accessory
+    // row but doesn't draw it), leaving bare black native space between the shrunk webview and the
+    // real keys. `activeExtraLift` (see onShow) is the configured extra lift on those warm shows and 0
+    // on cold shows where the bar IS drawn — so the webview covers the strip only when it's needed.
+    wv.marginBottom = paddingBottom > 0 ? Math.max(0, paddingBottom - safeBottom - activeExtraLift) : 0;
+    // Property change alone doesn't reliably trigger a layout pass outside NS's own flow
+    // (restore path: margin=0 was set but the view stayed shrunk until the next layout).
+    wv.requestLayout();
+    resetScrollView();
+    // The page scrolls in inner containers; the outer scrollView must stay at origin. Clears
+    // WebKit's focus auto-scroll leftovers and the "whole app scrollable" residue after hide.
+    wk.scrollView.setContentOffsetAnimated(CGPointMake(0, 0), false);
+    if (SHELL_CONFIG.debug) appwrapNativeLog(`[native:keyboard] marginBottom=${wv.marginBottom} (kb=${paddingBottom}, extraLift=${activeExtraLift}, ${sawWillShow ? 'cold' : 'warm'})`);
+  };
+
+  // No same-value skip: re-applying an identical frame is free, and unconditional application
+  // makes every keyboard event self-healing after a missed/bailed update.
+  const setKeyboardHeight = (height: number, delayMs: number): void => {
+    paddingBottom = height;
+    if (pendingUpdate) clearTimeout(pendingUpdate); // debounce like cancelPreviousPerformRequests
+    pendingUpdate = setTimeout(() => Utils.dispatchToMainThread(() => updateFrame()), delayMs);
+  };
+
+  // Re-focus does NOT re-fire willShow — capture-verified: a second tap arrives ONLY as
+  // didShow/willChangeFrame. All three feed the same idempotent handler; whichever iOS sends, the
+  // shrink lands. Height-0 frame events do nothing (hide is owned by the willHide/didHide pair).
+  const onShow = (tag: string, settleMs: number | null) => (note: any): void => {
+    detachWebKitKeyboardHandling();
+    if (tag === 'willShow') sawWillShow = true; // cold acquire → the accessory bar will be drawn
+    // Warm re-focus (didShow/willChangeFrame with no willShow this cycle) → bar dropped → lift extra.
+    activeExtraLift = sawWillShow ? 0 : (SHELL_CONFIG.iosKeyboardExtraLift ?? 82);
     const value = note?.userInfo?.objectForKey?.(UIKeyboardFrameEndUserInfoKey);
-    const height = value ? value.CGRectValue.size.height : 0; // points ≈ CSS px in WKWebView
-    bridge.emit('keyboard.show', { height: Math.round(height) });
-  });
+    // Overlap with the window, NOT frame.size.height: iOS delivers keyboard-sized but off-screen
+    // end-frames during dismissal — size.height would shrink a keyboard-less screen.
+    let height = 0;
+    let winH = 0;
+    if (value) {
+      const end = value.CGRectValue;
+      const win = getWk()?.window;
+      winH = win ? win.bounds.size.height : 0;
+      height = winH ? Math.max(0, Math.round(winH - end.origin.y)) : Math.round(end.size.height);
+    }
+    if (SHELL_CONFIG.debug) appwrapNativeLog(`[native:keyboard] ${tag} height=${height}`);
+    resetScrollView();
+    if (height <= 0) return;
+    // Guard against bogus full-screen keyboard frames. iOS occasionally delivers a transitional frame
+    // with origin.y≈0 (seen during SMS-OTP autofill) → height ≈ the whole window → the resize would
+    // shrink the webview to a sliver (huge black gap). A real software keyboard is never >85% of the
+    // screen; ignore the event and wait for the real frame (which follows and self-heals).
+    if (winH && height > winH * 0.85) {
+      if (SHELL_CONFIG.debug) appwrapNativeLog(`[native:keyboard] ignore bogus height=${height} (win=${Math.round(winH)})`);
+      return;
+    }
+    // Paint the webview/window backdrop the page color so the resize shows no white flash. (The
+    // iOS-26 phantom keyboard-height gap is closed geometrically by the extra lift in updateFrame.)
+    syncBackdropColor();
+    const duration = note?.userInfo?.objectForKey?.(UIKeyboardAnimationDurationUserInfoKey)?.doubleValue ?? 0.25;
+    // willShow/willChangeFrame: resize after the animation settles. didShow: already settled.
+    setKeyboardHeight(height, settleMs ?? (duration + 0.2) * 1000);
+    bridge.emit('keyboard.show', { height });
+  };
+  center.addObserverForNameObjectQueueUsingBlock(UIKeyboardWillShowNotification, null, null, onShow('willShow', null));
+  center.addObserverForNameObjectQueueUsingBlock(UIKeyboardWillChangeFrameNotification, null, null, onShow('willChangeFrame', null));
+  center.addObserverForNameObjectQueueUsingBlock(UIKeyboardDidShowNotification, null, null, onShow('didShow', 50));
   center.addObserverForNameObjectQueueUsingBlock(UIKeyboardWillHideNotification, null, null, () => {
+    if (SHELL_CONFIG.debug) appwrapNativeLog('[native:keyboard] willHide → restore');
+    setKeyboardHeight(0, 10);
+    resetScrollView();
     bridge.emit('keyboard.hide');
   });
+  center.addObserverForNameObjectQueueUsingBlock(UIKeyboardDidHideNotification, null, null, () => {
+    setKeyboardHeight(0, 10); // enforcement pass — a hidden keyboard must always end at full height
+    resetScrollView();
+    sawWillShow = false; // keyboard fully gone → next show re-decides cold (bar) vs warm (no bar)
+  });
+
+  armScrollClamp();
+}
+
+/**
+ * Sample the page's background color once per keyboard-show and paint the webview + its window with
+ * it (Capacitor's autoBackdropColor) so there are no white flashes during the resize.
+ */
+function syncBackdropColor(): void {
+  try {
+    const wk = bridge.getWebView()?.ios as WKWebView | undefined;
+    if (!wk) return;
+    wk.evaluateJavaScriptCompletionHandler('window.getComputedStyle(document.body).backgroundColor', (result: any) => {
+      const m = /rgba?\(\s*(\d+)[,\s]+(\d+)[,\s]+(\d+)/.exec(String(result ?? ''));
+      if (!m) return;
+      Utils.dispatchToMainThread(() => {
+        const w = bridge.getWebView()?.ios as WKWebView | undefined;
+        if (!w) return;
+        const color = UIColor.colorWithRedGreenBlueAlpha(+m[1] / 255, +m[2] / 255, +m[3] / 255, 1);
+        w.backgroundColor = color;
+        if (w.window) w.window.backgroundColor = color;
+        if (SHELL_CONFIG.debug) appwrapNativeLog(`[native:keyboard] backdrop ← rgb(${m[1]},${m[2]},${m[3]})`);
+      });
+    });
+  } catch (e) {
+    if (SHELL_CONFIG.debug) appwrapNativeLog(`[native:keyboard] backdrop sync failed: ${e}`);
+  }
+}
+
+let clampDelegate: any; // retained — a bare local would be GC'd and the native delegate dies with it
+
+/**
+ * Continuous outer-scroll clamp. WebKit's keyboard machinery scrolls the WKWebView's outer
+ * scrollView at arbitrary times (focus auto-scroll while the keyboard is up, late "restore scroll"
+ * compensation ~1s after hide — probe-verified offset=386 with content == bounds). Timed pins lose
+ * that race by definition; a scrollViewDidScroll delegate wins every time: on EVERY scroll event
+ * clamp the offset to the legitimate range. Pages that fit the viewport (app shells — inner divs
+ * scroll, not the page) have exactly one legal offset: 0. Genuinely scrollable pages keep normal
+ * in-range scrolling untouched.
+ */
+function armScrollClamp(): void {
+  const attach = (attempt = 0): void => {
+    const wk = bridge.getWebView()?.ios as WKWebView | undefined;
+    if (!wk) {
+      if (attempt < 50) setTimeout(() => attach(attempt + 1), 200);
+      return;
+    }
+    const Delegate = (NSObject as any).extend(
+      {
+        scrollViewDidScroll(sv: any): void {
+          const maxY = Math.max(0, sv.contentSize.height - sv.bounds.size.height + sv.contentInset.bottom);
+          const y = sv.contentOffset.y;
+          const clamped = Math.min(Math.max(y, 0), maxY);
+          if (Math.abs(clamped - y) > 0.5) sv.setContentOffsetAnimated(CGPointMake(sv.contentOffset.x, clamped), false);
+        },
+      },
+      { protocols: [UIScrollViewDelegate] },
+    );
+    clampDelegate = Delegate.new();
+    wk.scrollView.delegate = clampDelegate;
+    if (SHELL_CONFIG.debug) appwrapNativeLog('[native:keyboard] scroll clamp armed');
+  };
+  attach();
 }
 
 /** Android: a global-layout listener compares the decor view's visible frame to its full height. */

package/runtime/app/shell/web-quirks.ts

@@ -191,8 +191,10 @@ export function externalNavGuardJs(enabled: boolean): string {
 const NATIVE_FEEL_CSS = [
   'html{-webkit-text-size-adjust:100%;text-size-adjust:100%}',
   'html,body{overscroll-behavior:none;touch-action:manipulation}',
-  '*{-webkit-touch-callout:none;-webkit-tap-highlight-color:transparent}',
-  ':where(:not(input,textarea,[contenteditable],[contenteditable] *)){-webkit-user-select:none;user-select:none}',
+  '*{-webkit-tap-highlight-color:transparent}',
+  // touch-callout:none suppresses long-press menus, but on inputs/textareas/contenteditable that also
+  // kills the iOS Copy/Paste callout — so exclude editable fields (same set as the user-select rule).
+  ':where(:not(input,textarea,[contenteditable],[contenteditable] *)){-webkit-touch-callout:none;-webkit-user-select:none;user-select:none}',
 ].join('');
 
 /** Accessibility-standard reduced-motion reset — collapse animation/transition durations to ~0 and

package/src/cli.ts

@@ -248,7 +248,7 @@ function stampEntitlements(outDir: string, cfg: AppwrapConfig, req: NativeReqs):
   const iosDir = join(outDir, 'App_Resources/iOS');
   if (!existsSync(iosDir)) return;
   const file = join(iosDir, 'app.entitlements');
-  const ent: Record<string, boolean | string | string[]> = { ...req.iosEntitlements };
+  const ent: Record<string, boolean | string | string[]> = { ...req.iosEntitlements, ...cfg.iosEntitlements };
   if (!!cfg.push?.enabled && cfg.push?.ios !== false) ent['aps-environment'] = cfg.push.apsEnvironment ?? 'development';
   const keys = Object.keys(ent);
   if (keys.length === 0) { rmSync(file, { force: true }); return; }
@@ -445,6 +445,7 @@ export const SHELL_CONFIG = {
   pushIos: ${JSON.stringify(!!cfg.push?.enabled && cfg.push?.ios !== false)},
   pushAndroid: ${JSON.stringify(!!cfg.push?.enabled && cfg.push?.android !== false)},
   pushRegistrationUrl: ${JSON.stringify(cfg.push?.registrationUrl ?? '')},
+  iosKeyboardExtraLift: ${JSON.stringify(cfg.iosKeyboardExtraLift ?? 82)},
 };
 `;
   writeFileSync(join(outDir, 'app/shell/config.ts'), content);
@@ -534,6 +535,29 @@ function stampIOSDisplayName(outDir: string, cfg: AppwrapConfig, req: NativeReqs
   writeFileSync(plist, src);
 }
 
+/** Stamp each app extension's Info.plist CFBundleShortVersionString + CFBundleVersion to match the
+ * main app (marketing version + monotonic build). App Store validation HARD-FAILS on a mismatch.
+ * Extension Info.plists ship verbatim from overrides (NS never stamps them), so this MUST run AFTER
+ * applyOverrides — same seam as stampManualSigning (an override would otherwise clobber the stamp). */
+function stampIOSExtensionVersions(outDir: string, cfg: AppwrapConfig): void {
+  const extRoot = join(outDir, 'App_Resources/iOS/extensions');
+  if (!existsSync(extRoot)) return;
+  const build = String(buildNumberOf(cfg));
+  for (const ext of readdirSync(extRoot, { withFileTypes: true })) {
+    if (!ext.isDirectory()) continue;
+    const plist = join(extRoot, ext.name, 'Info.plist');
+    if (!existsSync(plist)) continue;
+    let src = readFileSync(plist, 'utf8');
+    const stamp = (key: string, value: string) => {
+      const re = new RegExp(`(<key>${key}</key>\\s*<string>)[^<]*(</string>)`);
+      src = re.test(src) ? src.replace(re, `$1${value}$2`) : src;
+    };
+    stamp('CFBundleShortVersionString', cfg.version);
+    stamp('CFBundleVersion', build);
+    writeFileSync(plist, src);
+  }
+}
+
 function stampTeamId(outDir: string, cfg: AppwrapConfig, ctx?: { cwd: string; configPath: string }): void {
   const xcconfig = join(outDir, 'App_Resources/iOS/build.xcconfig');
   // Resolution order: a real (non-placeholder) cfg.teamId wins; else $APPWRAP_TEAM_ID (headless/CI);
@@ -568,6 +592,237 @@ function stampTeamId(outDir: string, cfg: AppwrapConfig, ctx?: { cwd: string; co
   writeFileSync(xcconfig, src);
 }
 
+interface ProvProfile { name: string; uuid: string; teamId: string; bundleId: string; exp: number }
+
+/** Discover provisioning profiles installed on this machine (both the legacy MobileDevice dir and
+ * the modern Xcode UserData dir). Each is decoded with `security cms` and reduced to the fields we
+ * match on: profile Name, its TeamIdentifier, the bundle id (application-identifier minus the team
+ * prefix), and expiration (ms epoch). Unreadable/legacy profiles are skipped. */
+function findProvisioningProfiles(): ProvProfile[] {
+  const dirs = [
+    join(process.env.HOME ?? '', 'Library/MobileDevice/Provisioning Profiles'),
+    join(process.env.HOME ?? '', 'Library/Developer/Xcode/UserData/Provisioning Profiles'),
+  ];
+  // Dedup by UUID: the SAME profile commonly lives in BOTH dirs (Xcode copies from MobileDevice into
+  // its UserData store) — without this, selectSigningProfile would see one profile as two and
+  // spuriously prompt / warn of "ambiguity".
+  const byUuid = new Map<string, ProvProfile>();
+  for (const dir of dirs) {
+    if (!existsSync(dir)) continue;
+    let files: string[] = [];
+    try { files = readdirSync(dir).filter((f) => f.endsWith('.mobileprovision')); } catch { continue; }
+    for (const f of files) {
+      try {
+        const raw = execFileSync('security', ['cms', '-D', '-i', join(dir, f)],
+          { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+        const name = raw.match(/<key>Name<\/key>\s*<string>([^<]+)<\/string>/)?.[1];
+        const uuid = raw.match(/<key>UUID<\/key>\s*<string>([^<]+)<\/string>/)?.[1];
+        const team = raw.match(/<key>TeamIdentifier<\/key>\s*<array>\s*<string>([^<]+)<\/string>/)?.[1];
+        const appId = raw.match(/<key>application-identifier<\/key>\s*<string>([^<]+)<\/string>/)?.[1];
+        const expStr = raw.match(/<key>ExpirationDate<\/key>\s*<date>([^<]+)<\/date>/)?.[1];
+        if (!name || !uuid || !team || !appId || byUuid.has(uuid)) continue;
+        // application-identifier is `<TEAM>.<bundle.id>`; strip the team prefix to get the bundle id.
+        const bundleId = appId.startsWith(team + '.') ? appId.slice(team.length + 1) : appId;
+        byUuid.set(uuid, { name, uuid, teamId: team, bundleId, exp: expStr ? Date.parse(expStr) : 0 });
+      } catch { /* skip unreadable profile */ }
+    }
+  }
+  return [...byUuid.values()];
+}
+
+/** Pick the provisioning-profile NAME to sign `bundleId` with, from the installed profiles for `teamId`.
+ * Order: a valid pinned choice (cfg.signingProfiles) → the sole match → interactive pick (TTY, then
+ * pinned) → newest-expiry (headless). Returns null when nothing matches (caller warns + skips). */
+function selectSigningProfile(
+  profiles: ProvProfile[], teamId: string, bundleId: string, cfg: AppwrapConfig,
+  ctx?: { configPath: string },
+): string | null {
+  const now = Date.now();
+  const matches = profiles.filter((p) => p.teamId === teamId && p.bundleId === bundleId && p.exp > now);
+  if (matches.length === 0) return null;
+  const pinned = cfg.signingProfiles?.[bundleId];
+  if (pinned && matches.some((p) => p.name === pinned)) return pinned;
+  if (matches.length === 1) return matches[0].name;
+  // Ambiguous: prompt on a real TTY (and pin the choice), else deterministically take newest expiry.
+  if (process.stdout.isTTY) {
+    const sorted = [...matches].sort((a, b) => b.exp - a.exp);
+    const idx = arrowSelect(`Multiple profiles for ${bundleId} — pick one to sign with:`,
+      sorted.map((p) => `${p.name}  (expires ${new Date(p.exp).toISOString().slice(0, 10)})`));
+    const chosen = sorted[idx].name;
+    if (ctx) pinSigningProfileToConfig(ctx.configPath, bundleId, chosen);
+    return chosen;
+  }
+  const newest = [...matches].sort((a, b) => b.exp - a.exp)[0];
+  console.warn(`  ⚠ ${matches.length} profiles match ${bundleId}; using newest "${newest.name}" (pin one via signingProfiles to silence).`);
+  return newest.name;
+}
+
+/** Manual code-signing for device builds (`signing: 'manual'`). Resolves the app + each extension
+ * target to an installed provisioning profile (by `<teamId>.<bundleId>`) and stamps Manual signing
+ * into build.xcconfig (main app) + each extension's extension.json targetBuildConfigurationProperties.
+ * This is what makes `appwrap deploy ios` provision extensions + special entitlements without an Xcode
+ * GUI login. No-op unless signing==='manual'. iOS-only files; harmless on other platforms. */
+function stampManualSigning(outDir: string, cfg: AppwrapConfig, ctx?: { configPath: string }): void {
+  const mode = process.env.APPWRAP_SIGNING?.trim() || cfg.signing;
+  if (mode !== 'manual') {
+    // Not manual → tear down any artifacts a PREVIOUS manual run left in native/ (it isn't fully
+    // wiped on sync), so `deploy` doesn't keep passing a now-stale --provision / export map.
+    for (const p of ['.appwrap-signing.json', 'hooks/after-prepare/appwrap-signing.js', 'App_Resources/iOS/extensions/provisioning.json']) {
+      const f = join(outDir, p);
+      if (existsSync(f)) rmSync(f, { force: true });
+    }
+    return;
+  }
+  const teamId = cfg.teamId;
+  if (!teamId || /YOUR_APPLE_TEAM_ID|^$/.test(teamId)) {
+    console.warn('  ⚠ signing: manual but teamId is unset — skipping manual signing.');
+    return;
+  }
+  const profiles = findProvisioningProfiles();
+  let mainProvision: string | null = null;
+
+  // Main app target → build.xcconfig.
+  const xcconfig = join(outDir, 'App_Resources/iOS/build.xcconfig');
+  if (existsSync(xcconfig)) {
+    const name = selectSigningProfile(profiles, teamId, cfg.id, cfg, ctx);
+    if (!name) {
+      console.warn(`  ⚠ no valid profile for ${cfg.id} (team ${teamId}) — automatic signing will run. Install one or seed via Xcode.`);
+    } else {
+      mainProvision = name;
+      let src = readFileSync(xcconfig, 'utf8');
+      const setKey = (s: string, key: string, val: string): string =>
+        // Anchored + multiline so we never rewrite the commented `// CODE_SIGN_IDENTITY = …` template line.
+        new RegExp(`^\\s*${key}\\s*=`, 'm').test(s)
+          ? s.replace(new RegExp(`^\\s*${key}\\s*=\\s*[^;\\n]*;?`, 'm'), `${key} = ${val};`)
+          : s + `\n${key} = ${val};`;
+      src = setKey(src, 'CODE_SIGN_STYLE', 'Manual');
+      src = setKey(src, 'CODE_SIGN_IDENTITY', 'Apple Development');
+      src = setKey(src, 'PROVISIONING_PROFILE_SPECIFIER', name);
+      writeFileSync(xcconfig, src.endsWith('\n') ? src : src + '\n');
+      console.log(`  sign ← ${cfg.id} → "${name}" (manual)`);
+    }
+  }
+
+  // Extension targets (bundle id = <appId>.<Name>). extension.json CAN'T carry the signing: NS's
+  // prepareSigning runs AFTER it and force-propagates the MAIN app's signing onto every extension
+  // (clobbering the team/profile — and an extension needs a DIFFERENT profile than the app). So we
+  // install an after-prepare hook that stamps each extension target's signing into project.pbxproj
+  // LAST, after NS is done. Same seam StoreKit wiring uses.
+  const extRoot = join(outDir, 'App_Resources/iOS/extensions');
+  const extEntries: Array<{ bundleId: string; profile: string }> = [];
+  if (existsSync(extRoot)) {
+    for (const ext of readdirSync(extRoot, { withFileTypes: true })) {
+      if (!ext.isDirectory()) continue;
+      if (!existsSync(join(extRoot, ext.name, 'extension.json'))) continue;
+      const extBundle = `${cfg.id}.${ext.name}`;
+      const name = selectSigningProfile(profiles, teamId, extBundle, cfg, ctx);
+      if (!name) { console.warn(`  ⚠ no valid profile for extension ${extBundle} — it may fail to sign.`); continue; }
+      extEntries.push({ bundleId: extBundle, profile: name });
+      console.log(`  sign ← ${extBundle} → "${name}" (manual, via hook)`);
+    }
+  }
+  const hookDir = join(outDir, 'hooks/after-prepare');
+  const hookFile = join(hookDir, 'appwrap-signing.js');
+  if (extEntries.length) {
+    mkdirSync(hookDir, { recursive: true });
+    writeFileSync(hookFile, SIGNING_HOOK(teamId, extEntries));
+    // NS's exportOptions reads extension profiles from this file (extensions/provisioning.json) —
+    // it maps each extension bundle id → profile name so `xcodebuild -exportArchive` can build the .ipa.
+    writeFileSync(join(extRoot, 'provisioning.json'),
+      JSON.stringify(Object.fromEntries(extEntries.map((e) => [e.bundleId, e.profile])), null, 2) + '\n');
+  } else {
+    // No extensions to sign → clear any hook / provisioning map a prior run left behind.
+    if (existsSync(hookFile)) rmSync(hookFile, { force: true });
+    const provJson = join(extRoot, 'provisioning.json');
+    if (existsSync(provJson)) rmSync(provJson, { force: true });
+  }
+
+  // Sidecar the resolved main-app profile so the device-build step can pass `ns build … --provision
+  // <name>` — that's the switch that makes NS emit a manual-signing exportOptions.plist (with the app
+  // AND each extension's provisioningProfiles) for `xcodebuild -exportArchive`. Without it the export
+  // has no profile map and fails even though the archive signed fine.
+  const sidecar = join(outDir, '.appwrap-signing.json');
+  if (mainProvision) writeFileSync(sidecar, JSON.stringify({ provision: mainProvision }) + '\n');
+  else if (existsSync(sidecar)) rmSync(sidecar, { force: true });
+}
+
+/** After-prepare hook source: stamps manual signing into each extension target's build settings in
+ * project.pbxproj — run AFTER `ns prepare` (hence after NS's prepareSigning), so it's the final word.
+ * Self-contained (no deps), zero-arg (NS DI won't choke). Per extension it upserts DEVELOPMENT_TEAM,
+ * PROVISIONING_PROFILE_SPECIFIER, CODE_SIGN_STYLE=Manual, CODE_SIGN_IDENTITY in every buildSettings
+ * block whose PRODUCT_BUNDLE_IDENTIFIER matches the extension's bundle id. */
+const SIGNING_HOOK = (team: string, entries: Array<{ bundleId: string; profile: string }>) => `// Generated by \`appwrap\` — stamps manual signing onto extension targets in project.pbxproj.
+const fs = require('fs');
+const path = require('path');
+const TEAM = ${JSON.stringify(team)};
+const ENTRIES = ${JSON.stringify(entries)};
+module.exports = function () {
+  const iosDir = path.join(__dirname, '..', '..', 'platforms', 'ios');
+  if (!fs.existsSync(iosDir)) return;
+  const projDir = fs.readdirSync(iosDir).find((d) => d.endsWith('.xcodeproj') && d !== 'Pods.xcodeproj');
+  if (!projDir) return;
+  const pbx = path.join(iosDir, projDir, 'project.pbxproj');
+  if (!fs.existsSync(pbx)) return;
+  let src = fs.readFileSync(pbx, 'utf8');
+  const q = (v) => (/\\s/.test(v) ? '"' + v + '"' : v);
+  // Upsert a key inside one buildSettings block: replace its line if present, else insert after
+  // PRODUCT_BUNDLE_IDENTIFIER. Also strips PROVISIONING_PROFILE (UUID form) to avoid a stale mismatch.
+  const upsert = (block, key, val) => {
+    const re = new RegExp('(^\\\\s*)' + key + '\\\\s*=\\\\s*[^;\\\\n]*;', 'm');
+    if (re.test(block)) return block.replace(re, (_m, indent) => indent + key + ' = ' + val + ';');
+    return block.replace(/(^(\\s*)PRODUCT_BUNDLE_IDENTIFIER\\s*=\\s*[^;\\n]*;)/m,
+      (m, _l, indent) => m + '\\n' + indent + key + ' = ' + val + ';');
+  };
+  for (const { bundleId, profile } of ENTRIES) {
+    // Each XCBuildConfiguration's buildSettings block (Debug + Release) for this extension target.
+    src = src.replace(/buildSettings = \\{[\\s\\S]*?\\n(\\t*)\\};/g, (block) => {
+      const bidRe = new RegExp('PRODUCT_BUNDLE_IDENTIFIER\\\\s*=\\\\s*"?' + bundleId.replace(/[.]/g, '\\\\.') + '"?;');
+      if (!bidRe.test(block)) return block;
+      block = block.replace(/^\\s*PROVISIONING_PROFILE\\s*=\\s*[^;\\n]*;\\n?/m, '');
+      block = upsert(block, 'CODE_SIGN_STYLE', 'Manual');
+      block = upsert(block, 'DEVELOPMENT_TEAM', TEAM);
+      block = upsert(block, 'CODE_SIGN_IDENTITY', q('Apple Development'));
+      block = upsert(block, 'PROVISIONING_PROFILE_SPECIFIER', q(profile));
+      return block;
+    });
+  }
+  fs.writeFileSync(pbx, src);
+  console.log('  appwrap: manual signing stamped for ' + ENTRIES.map((e) => e.bundleId).join(', '));
+};
+`;
+
+/** Persist a manual-signing profile choice (bundle id → profile name) so an ambiguous match isn't
+ * re-prompted. JSON configs are updated structurally; TS/JS get a best-effort inserted line (a hint
+ * is printed if the shape is unfamiliar — the deterministic newest-expiry pick still works meanwhile). */
+function pinSigningProfileToConfig(configPath: string, bundleId: string, profileName: string): void {
+  if (!existsSync(configPath)) return;
+  const src = readFileSync(configPath, 'utf8');
+  if (configPath.endsWith('.json')) {
+    try {
+      const obj = JSON.parse(src) as Record<string, unknown>;
+      const map = (obj.signingProfiles as Record<string, string>) ?? {};
+      map[bundleId] = profileName;
+      obj.signingProfiles = map;
+      writeFileSync(configPath, JSON.stringify(obj, null, 2) + (src.endsWith('\n') ? '\n' : ''));
+      console.log(`  ✓ pinned signingProfiles['${bundleId}'] = '${profileName}'`);
+    } catch { /* leave untouched */ }
+    return;
+  }
+  if (/\bsigningProfiles\s*:/.test(src)) {
+    console.log(`  ⓘ add '${bundleId}': '${profileName}' to signingProfiles in ${configPath} to silence this prompt.`);
+    return;
+  }
+  const anchor = /^([ \t]*)(signing|id)\s*:\s*(['"`])[^'"`]*\3\s*,?[ \t]*$/m;
+  const m = anchor.exec(src);
+  if (!m) { console.log(`  ⓘ set signingProfiles: { '${bundleId}': '${profileName}' } in ${configPath} to silence this prompt.`); return; }
+  const indent = m[1];
+  const next = src.slice(0, m.index + m[0].length)
+    + `\n${indent}signingProfiles: { '${bundleId}': '${profileName}' },`
+    + src.slice(m.index + m[0].length);
+  writeFileSync(configPath, next);
+  console.log(`  ✓ pinned signingProfiles['${bundleId}'] = '${profileName}' in ${configPath}`);
+}
+
 /** Stamp TARGETED_DEVICE_FAMILY into build.xcconfig from cfg.targetedDevices. `'iphone'` → `1`
  * (iPhone-only → UIDeviceFamily=[1], so the App Store doesn't require iPad screenshots);
  * `'universal'`/unset → `1,2` (NativeScript's default). Idempotent: replaces any prior value. */
@@ -891,6 +1146,23 @@ function generateIcons(cwd: string, outDir: string, cfg: AppwrapConfig): void {
     }
   }
 
+  // iOS launch screen: stamp the centered splash logo — ONLY from an explicit `splashIcon`
+  // (a transparent-bg wordmark/glyph). NOT the app icon: an icon carries its own opaque background,
+  // which would render as an ugly box floating on the solid splash. Without `splashIcon` the Center
+  // layer is blanked in stampLaunchScreen → clean solid-backgroundColor splash, no logo. Square, ~220pt.
+  if (cfg.splashIcon) {
+    const splashSrc = resolve(cwd, cfg.splashIcon);
+    const centerSet = join(outDir, 'App_Resources/iOS/Assets.xcassets/LaunchScreen.Center.imageset');
+    if (!existsSync(splashSrc)) {
+      console.warn(`⚠ config \`splashIcon\` not found: ${splashSrc} — splash will be a plain background`);
+    } else if (existsSync(join(centerSet, 'Contents.json'))) {
+      const c = JSON.parse(readFileSync(join(centerSet, 'Contents.json'), 'utf8'));
+      for (const img of c.images as Array<{ scale: string; filename: string }>) {
+        ras.resize(splashSrc, Math.round(220 * parseFloat(img.scale)), join(centerSet, img.filename));
+      }
+    }
+  }
+
   const ANDROID_DENSITIES: Record<string, number> = { mdpi: 48, hdpi: 72, xhdpi: 96, xxhdpi: 144, xxxhdpi: 192 };
   const res = join(outDir, 'App_Resources/Android/src/main/res');
   for (const [density, px] of Object.entries(ANDROID_DENSITIES)) {
@@ -920,8 +1192,30 @@ function generateIcons(cwd: string, outDir: string, cfg: AppwrapConfig): void {
   console.log(`  icon ← ${source} (${w}px)`);
 }
 
-/** Tint the iOS launch screen to the configured background color. */
+/** De-NativeScript the launch screen: blank the iOS NS-blue AspectFill layer (UNCONDITIONAL — the
+ * default must never ship), then tint the iOS storyboard + Android splash to the app's backgroundColor. */
 function stampLaunchScreen(outDir: string, cfg: AppwrapConfig): void {
+  // iOS: blank the full-screen AspectFill layer FIRST, regardless of backgroundColor. The template
+  // ships the default NativeScript-blue background bitmap there, which paints OVER the storyboard
+  // background → the tint (and any brand color) is invisible and every app shows the NS splash.
+  // Overwrite those rasters with a 1×1 transparent pixel so the storyboard's solid background shows
+  // through; the centered app-icon logo (branded in generateIcons) sits on top. Tool-free (no
+  // sips/magick → works on any CI).
+  const TRANSPARENT_PNG = Buffer.from(
+    'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==',
+    'base64'
+  );
+  const blankImageset = (name: string): void => {
+    const set = join(outDir, `App_Resources/iOS/Assets.xcassets/${name}.imageset`);
+    if (!existsSync(join(set, 'Contents.json'))) return;
+    const c = JSON.parse(readFileSync(join(set, 'Contents.json'), 'utf8'));
+    for (const img of c.images as Array<{ filename: string }>) writeFileSync(join(set, img.filename), TRANSPARENT_PNG);
+  };
+  blankImageset('LaunchScreen.AspectFill');
+  // Blank the centered NS wordmark too → clean solid-color splash. generateIcons repaints Center from
+  // `splashIcon` AFTER this (it runs later in regenerateCore), so an opted-in logo survives.
+  blankImageset('LaunchScreen.Center');
+
   if (!cfg.backgroundColor) return;
   const hex = cfg.backgroundColor.replace('#', '');
   if (!/^[0-9a-fA-F]{6}$/.test(hex)) return;
@@ -1198,6 +1492,8 @@ async function init(cwd: string, flags: Record<string, string>): Promise<void> {
   copyCiTemplates(cwd, outDir, cfg, 'force' in flags); // GH workflows: first-time only; fastlane lane: re-emit on --force
   writeFileSync(join(outDir, '.gitignore'), 'node_modules/\nplatforms/\nhooks/\n');
   applyOverrides(cwd, outDir, cfg); // escape hatch — last, so custom native code wins
+  stampManualSigning(outDir, cfg, { configPath: resolveConfigPath(cwd, flags) }); // AFTER overrides: a consumer's extension.json / build.xcconfig would otherwise clobber the signing stamp
+  stampIOSExtensionVersions(outDir, cfg); // AFTER overrides: extension Info.plist ships from overrides; version must match the app's or App Store validation fails
   stampVersionManifest(outDir, cfg); // provenance — also marks the dir appwrap-managed
   console.log(`✓ Wrapper ready (generated — gitignore \`${flags.out ?? 'native'}/\`, regenerate with \`appwrap init\`).\n  Run it: appwrap dev ios   (or: appwrap dev android)`);
 }
@@ -1214,6 +1510,8 @@ async function sync(cwd: string, flags: Record<string, string>, cfgOverride?: Ap
   }
   regenerateCore(cwd, outDir, cfg, { flags });
   applyOverrides(cwd, outDir, cfg); // overrides win last
+  stampManualSigning(outDir, cfg, { configPath: resolveConfigPath(cwd, flags) }); // AFTER overrides: a consumer's extension.json / build.xcconfig would otherwise clobber the signing stamp
+  stampIOSExtensionVersions(outDir, cfg); // AFTER overrides: extension Info.plist ships from overrides; version must match the app's or App Store validation fails
   stampVersionManifest(outDir, cfg); // keep the managed-marker / provenance current
   console.log('✓ Synced.');
 }
@@ -1323,6 +1621,7 @@ async function dev(cwd: string, flags: Record<string, string>, positionals: stri
         : cfg;
     regenerateCore(cwd, outDir, simCfg, { flags });
     applyOverrides(cwd, outDir, simCfg); // overrides win last — same order as sync
+    stampIOSExtensionVersions(outDir, simCfg); // AFTER overrides: keep extension version matching the app's (Xcode warns on mismatch)
     stampVersionManifest(outDir, simCfg);
     console.log(simCfg.loader === 'server' ? `✓ Refreshed wrapper (dev loader → ${simCfg.serverUrl})` : '✓ Refreshed wrapper from template + PWA');
     runNs(outDir, [wantDebug ? 'debug' : 'run', platform, ...(flags.device ? ['--device', flags.device] : [])]);
@@ -1442,6 +1741,25 @@ function runNs(outDir: string, args: string[]): void {
   execFileSync('ns', args, { cwd: outDir, stdio: 'inherit', env });
 }
 
+/** Wipe the generated NativeScript state (`ns clean`: platforms/, hooks/, node_modules/) then restore
+ * deps. The escape hatch when the generated tree drifts from the current project — e.g. a moved/renamed
+ * repo leaves a STALE platforms/ios/Podfile that ns keeps appending to (corrupt merge, orphaned
+ * post_install, mixed old/new paths) → CocoaPods "unexpected end" and the build never recovers on its own. */
+async function clean(cwd: string, flags: Record<string, string>): Promise<void> {
+  const outDir = resolve(cwd, flags.out ?? 'native');
+  if (!existsSync(outDir)) {
+    console.error(`✖ Wrapper not found at ${outDir} — nothing to clean (run \`appwrap init\` first)`);
+    process.exit(1);
+  }
+  console.log(`▶ ns clean  (cwd: ${outDir})  — wiping platforms/, hooks/, node_modules/`);
+  execFileSync('ns', ['clean'], { cwd: outDir, stdio: 'inherit', env: { ...process.env } });
+  // ns clean also removes node_modules; restore it so the tree is usable and the next deploy doesn't
+  // pay the reinstall inline (prepareNsEnv would otherwise lazily bun-install on the following build).
+  console.log(`▶ bun install  (cwd: ${outDir})  — restoring deps`);
+  execFileSync('bun', ['install'], { cwd: outDir, stdio: 'inherit', env: { ...process.env } });
+  console.log('✓ Cleaned. Next `appwrap deploy` regenerates platforms/ from App_Resources.');
+}
+
 /** Read the loader currently stamped into the generated shell (app/shell/config.ts). Used to
  * preserve an ACTIVE dev loader across a `dev --sim` refresh. Returns null if the
  * generated config is absent/unreadable — the caller then falls back to the appwrap config. */
@@ -2274,9 +2592,16 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
     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]' : ''}`);
+    // Manual signing (signing:'manual') → pass the main-app profile as --provision so NS emits a
+    // manual exportOptions.plist covering the app + its extensions (see stampManualSigning sidecar).
+    const nsArgs = ['build', 'ios', '--for-device'];
+    try {
+      const sc = JSON.parse(readFileSync(join(outDir, '.appwrap-signing.json'), 'utf8')) as { provision?: string };
+      if (sc.provision) nsArgs.push('--provision', sc.provision);
+    } catch { /* no sidecar → automatic signing */ }
+    console.log(`▶ ns ${nsArgs.join(' ')}  (debug: keep-awake + inspector on)${force ? '  [--force: skipping cache]' : ''}`);
     try {
-      execFileSync('ns', ['build', 'ios', '--for-device'], { cwd: outDir, stdio: 'inherit' });
+      execFileSync('ns', nsArgs, { cwd: outDir, stdio: 'inherit' });
     } catch (e) {
       // The xcodebuild dump above is cryptic; surface the two signing failures we actually hit most.
       console.error(
@@ -2300,16 +2625,19 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
 
   console.log(`▶ installing ${ipa} → ${device.name} [${device.transport}]`);
   let installedViaUsbmux = false;
+  let installed = false;
+  // A wireless (localNetwork) install of a multi-MB .ipa legitimately takes longer than a wired one —
+  // 25s is a wired number; too tight for Wi-Fi, tripping the fallback on a healthy-but-slow install.
+  const wireless = /localNetwork|wifi/i.test(device.transport);
+  const installTimeout = wireless ? '120' : '25';
+  // Capture (not inherit) so we can recognize specific failures; echo it for visibility. Wrapped so a
+  // LOCKED device waits-and-retries. --timeout lets one attempt tolerate a brief locked/unavailable window.
+  const runDevicectlInstall = (): string => withUnlockRetry('Install', () =>
+    execFileSync('xcrun', ['devicectl', 'device', 'install', 'app', '--timeout', installTimeout, '--device', device.id, ipaPath], { encoding: 'utf8', stdio: ['inherit', 'pipe', 'pipe'] })
+  );
   try {
-    // Capture (not inherit) so we can recognize specific failures; echo it for visibility.
-    // Wrapped so a LOCKED device waits-and-retries instead of hard-failing (the common annoyance).
-    // --timeout: devicectl has no first-class "wait for unlock", but its overall-timeout lets a single
-    // attempt tolerate a brief locked/unavailable window before erroring; the outer retry covers the
-    // fail-fast case + the unlock prompt. (Verified against `devicectl --help`; community wraps it too.)
-    const out = withUnlockRetry('Install', () =>
-      execFileSync('xcrun', ['devicectl', 'device', 'install', 'app', '--timeout', '25', '--device', device.id, ipaPath], { encoding: 'utf8', stdio: ['inherit', 'pipe', 'pipe'] })
-    );
-    process.stdout.write(out);
+    process.stdout.write(runDevicectlInstall());
+    installed = true;
   } catch (e: unknown) {
     const log = execErrText(e);
     process.stderr.write(log);
@@ -2325,19 +2653,33 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
       );
       process.exit(1);
     } else if (/Command timeout|got stuck|could not be reached|Unable to connect to device/.test(log)) {
-      // devicectl/CoreDevice is stuck (a connection hang, NOT a lock). usbmux (ideviceinstaller) is a
-      // separate stack that usually still works — auto-fall-back instead of chasing a phantom "unlock".
-      console.error('\n⚠ devicectl/CoreDevice is stuck (connection hang, not a lock) — falling back to ideviceinstaller (usbmux)…');
-      if (usbmuxInstall(ipaPath)) {
-        installedViaUsbmux = true;
-      } else {
-        console.error(
-          '✖ usbmux fallback unavailable.\n' +
-            '  → Re-plug the USB cable (re-establishes the CoreDevice tunnel) and re-run, OR\n' +
-            '    `brew install ideviceinstaller` for a usbmux install path.\n' +
-            `  The built .ipa is ready: ${ipaPath}`
-        );
-        process.exit(1);
+      // devicectl/CoreDevice is stuck (connection hang, NOT a lock). Usual cause: a pegged
+      // CoreDeviceService daemon. SELF-HEAL: kill it (auto-respawns clean) and retry devicectl once —
+      // this is the fix a human otherwise applies by hand, and it's the ONLY path that works for a
+      // wireless-only device (usbmux is USB-only).
+      if (killStuckCoreDeviceService()) {
+        console.error('\n↻ CoreDevice tunnel was stuck (likely a pegged CoreDeviceService) — restarted it, retrying install…');
+        try { process.stdout.write(runDevicectlInstall()); installed = true; }
+        catch (e2) { process.stderr.write(execErrText(e2)); }
+      }
+      // Still stuck → usbmux (ideviceinstaller), which only helps a USB-reachable device.
+      if (!installed) {
+        console.error('\n⚠ devicectl still stuck — trying ideviceinstaller (usbmux, USB only)…');
+        if (usbmuxInstall(ipaPath)) {
+          installedViaUsbmux = true; installed = true;
+        } else {
+          console.error(
+            '✖ Install failed: the CoreDevice tunnel stayed stuck and there is no usbmux (USB) path.\n' +
+              (wireless
+                ? '  This device is on Wi-Fi only — CoreDeviceService was just restarted, so simply RE-RUN\n' +
+                  '    `appwrap deploy ios` (the .ipa is cached; it will only re-install). For the most reliable\n' +
+                  '    path, plug in the USB cable.\n'
+                : '  → Re-plug the USB cable (re-establishes the CoreDevice tunnel) and re-run, OR\n' +
+                  '    `brew install ideviceinstaller` for a usbmux install path.\n') +
+              `  The built .ipa is ready: ${ipaPath}`
+          );
+          process.exit(1);
+        }
       }
     } else {
       console.error(
@@ -2358,7 +2700,7 @@ async function deploy(cwd: string, flags: Record<string, string>, positionals: s
       // old serverUrl) despite a correct new build — masquerading as a build/cache bug. (A reinstall
       // over the top does NOT replace a running process; this avoids the manual uninstall dance.)
       withUnlockRetry('Launch', () =>
-        execFileSync('xcrun', ['devicectl', 'device', 'process', 'launch', '--terminate-existing', '--timeout', '25', '--device', device.id, cfg.id], { encoding: 'utf8', stdio: ['inherit', 'pipe', 'pipe'] })
+        execFileSync('xcrun', ['devicectl', 'device', 'process', 'launch', '--terminate-existing', '--timeout', installTimeout, '--device', device.id, cfg.id], { encoding: 'utf8', stdio: ['inherit', 'pipe', 'pipe'] })
       );
     } catch {
       console.error('⚠ Launch failed (still locked after waiting). The app is installed — unlock and tap it, or re-run.');
@@ -2383,6 +2725,20 @@ function usbmuxInstall(ipaPath: string): boolean {
   }
 }
 
+/** Apple's `CoreDeviceService` daemon intermittently pegs a CPU core at 100% and wedges the device
+ * tunnel — `devicectl` then hangs until its timeout (worse on a wireless/localNetwork target). Killing
+ * it is the documented remedy: launchd auto-respawns it clean. Best-effort; returns true if we
+ * signalled a matching process (pkill exits non-zero → throws → false when nothing matched). */
+function killStuckCoreDeviceService(): boolean {
+  try {
+    execFileSync('pkill', ['-9', '-f', 'CoreDeviceService.xpc'], { stdio: 'ignore' });
+    sleepSync(4000); // let launchd respawn it + re-establish the tunnel before we retry
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /** Run a devicectl op; if it fails because the device is LOCKED (or transiently unavailable), prompt
  * once and poll-retry until it succeeds or the budget runs out — instead of hard-failing. A free-team
  * 3-app-limit error is NOT a lock, so it's re-thrown immediately for the caller's specific handling.
@@ -2555,6 +2911,9 @@ async function main(): Promise<void> {
     case 'sync':
       await sync(cwd, flags);
       break;
+    case 'clean':
+      await clean(cwd, flags);
+      break;
     case 'dev':
       await dev(cwd, flags, positionals);
       break;
@@ -2597,6 +2956,7 @@ async function main(): Promise<void> {
         '  publish <ios|android> [prod]              (beta: TestFlight / Play internal. prod: App Store / Play production)\n' +
         '  build <ios|android> [--release] [--aab]   (store artifact only — no install/upload)\n' +
         '  logs <ios|android> [--once] [--native]    (stream WebView console; --native = full OS log)\n' +
+        '  clean                                     (ns clean: wipe generated platforms/hooks/node_modules, restore deps — fixes stale/corrupt Podfile after a repo move)\n' +
         '  aliases: `release ios` = `publish ios`; `submit ios` = `publish ios prod`.');
       process.exit(command ? 1 : 0);
   }

package/src/config.ts

@@ -45,6 +45,11 @@ export interface AppwrapConfig {
    * paints the bar regions itself. Default false = bars show the page `backgroundColor` (works, but
    * can't match a multi-theme app). iOS is always genuinely edge-to-edge. */
   edgeToEdge?: boolean;
+  /** iOS only. Extra points to lift the WebView above the reported keyboard height on focus, to hide
+   * the iOS-26 phantom keyboard-height gap (the reported keyboard is taller than it draws on warm
+   * re-focus, leaving a black strip). Default 82; the keyboard covers the thin bottom content row.
+   * Set 0 for no extra lift (input flush at the reported height; the strip may show). */
+  iosKeyboardExtraLift?: number;
   pwaDist: string;
   /** Custom URL scheme for deep links (e.g. "hellowrap" → hellowrap://...). */
   urlScheme?: string;
@@ -63,6 +68,10 @@ export interface AppwrapConfig {
   queryPackages?: string[];
   /** App icon source (≥512px square png). Defaults to the largest icon in the PWA manifest. */
   icon?: string;
+  /** Optional centered logo for the iOS launch splash — a TRANSPARENT-background png (a wordmark or
+   * glyph, NOT the app icon, whose opaque background would show as a box on the splash). When absent
+   * the splash is a clean solid `backgroundColor` fill with no logo. */
+  splashIcon?: string;
   /** Loader: 'app' (default — app:// scheme, ES modules OK), 'file' (debug fallback), or 'server'
    * (load `serverUrl` live — dev HMR over LAN or a deployed URL). `appwrap dev` sets this. */
   loader?: 'app' | 'file' | 'server';
@@ -143,6 +152,23 @@ export interface AppwrapConfig {
   /** iOS export-compliance. `ITSAppUsesNonExemptEncryption` — stamped `false` by default (skips the
    * per-upload prompt). Set `true` only if the app uses non-exempt encryption. */
   usesNonExemptEncryption?: boolean;
+  /** Extra iOS entitlements merged into the generated `app.entitlements` (on top of the ones active
+   * modules + push contribute). For capabilities the module system doesn't (yet) model — e.g.
+   * `{ 'com.apple.developer.declared-age-range': true }`. Key = entitlement string, value = boolean /
+   * 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[]>;
+  /** 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
+   * `<teamId>.<bundleId>`, incl. app-extension targets). This is what lets `appwrap deploy ios`
+   * provision app extensions + special-access entitlements (e.g. declared-age-range) headlessly,
+   * without an Xcode GUI login. Store/TestFlight builds still go through `appwrap release` (fastlane+match). */
+  signing?: 'auto' | 'manual';
+  /** Manual-signing profile pins (bundle id → provisioning-profile NAME). Auto-filled when a `'manual'`
+   * build finds MULTIPLE candidate profiles for an id and you pick one interactively — so you're not
+   * re-prompted. Usually unset: a single matching profile is selected automatically. */
+  signingProfiles?: Record<string, string>;
   /** Pure-native escape hatch: a directory (relative to the PWA project) whose contents are copied
    * OVER the generated wrapper after stamping — for legacy/custom native code the declarative config
    * can't express. Default `'appwrap.overrides'`; applied only if it exists. */
@@ -214,11 +240,11 @@ export function defineConfig(config: AppwrapConfig): AppwrapConfig {
  * with no error, then an App Store rejection). A loud warning turns that silent no-op into a signal.
  */
 export const KNOWN_CONFIG_KEYS: ReadonlySet<string> = new Set([
-  'appBoundDomains', 'backendOrigin', 'backgroundColor', 'backgroundTasks', 'buildNumber', 'debug',
-  'debugLog', 'devMenu', 'edgeToEdge', 'entry', 'icon', 'id', 'loader', 'modules', 'name',
-  'neutralizeServiceWorker', 'openNewWindowsInBrowser', 'orientation', 'overrides', 'permissions',
-  'plugins', 'push', 'pwaDist', 'queryPackages', 'queryUrlSchemes', 'serverUrl', 'statusBarStyle',
-  'storekitConfig', 'targetedDevices', 'teamId', 'themeColor', 'trackingDomains', 'urlScheme',
+  'appBoundDomains', 'backendOrigin', 'backgroundAudio', 'backgroundColor', 'backgroundTasks', 'buildNumber', 'debug',
+  'debugLog', 'devMenu', 'edgeToEdge', 'entry', 'icon', 'id', 'iosKeyboardExtraLift', 'loader', 'modules', 'name',
+  'iosEntitlements', 'neutralizeServiceWorker', 'openNewWindowsInBrowser', 'orientation', 'overrides', 'permissions',
+  'plugins', 'push', 'pwaDist', 'queryPackages', 'queryUrlSchemes', 'serverUrl', 'signing', 'signingProfiles', 'statusBarStyle',
+  'splashIcon', 'storekitConfig', 'targetedDevices', 'teamId', 'themeColor', 'trackingDomains', 'urlScheme',
   'usesNonExemptEncryption', 'vendorPaths', 'version',
 ]);