@livx.cc/appwrap 0.40.1 → 0.42.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.40.1",
+  "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/runtime/package.json

@@ -12,6 +12,7 @@
     "@nativescript/secure-storage": "^4.0.1"
   },
   "devDependencies": {
+    "@nativescript/android": "9.0.4",
     "@nativescript/ios": "9.0.2",
     "@nativescript/types": "~9.0.0",
     "@nativescript/webpack": "~5.0.25",

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.');
 }
@@ -1268,23 +1566,26 @@ function openInspector(cfg: AppwrapConfig, flags: Record<string, string>, platfo
 /** `appwrap dev <ios|android> [--sim] [--detached] [--debug] [--url <devserver>|--port <p>]` — the
  * live-dev loop. Subsumes the old `run`/`debug` verbs AND the old `dev` (loader:server stamp).
  *
- *  Default target = the physical DEVICE: clean deploy (== `deploy`, the shared path — NOT reimplemented)
- *  → stay ATTACHED streaming the WebView console + watch project sources → rebuild+reinstall on save.
- *  We MUST NOT use `ns run` livesync on a device — it throws `Invalid version … Got type "object"`, an
- *  ns-internal semver bug we can't fix; so device-dev is deploy + logs + a plain rebuild watch loop.
+ *  Default target = the physical DEVICE.
+ *   • ANDROID: `ns run` livesync for true on-device HMR (incremental, no full reinstall) + a source
+ *     watcher that rebuilds the web & re-stages www on save so PWA edits flow into the livesync. The old
+ *     "Invalid version … Got type object" crash that made this look unfixable was just the shell
+ *     package.json failing to declare @nativescript/android → ns read the runtime version as null.
+ *   • iOS: the proven deploy + redeploy-on-save loop (NOT ns run — `ns run ios --device` hits the
+ *     personal-team signing/registration path `deploy ios` handles bespokely; pending device-verify).
  *
  *  Flags:
  *   --sim       → emulator/simulator via `ns run` (HMR is reliable there); `--debug` → `ns debug`.
  *   --url/--port→ stamp loader:'server' at that dev-server URL (web hot-reloads inside the WebView), deploy + attach.
- *   --detached  → deploy + exit (install & launch only; don't attach/watch).
- *   --debug     → also open the WebView inspector (chrome://inspect / Safari), then attach.
+ *   --detached  → deploy + exit (install & launch only; don't attach/watch — the MIUI-safe `--user 0` install).
+ *   --debug     → android: `ns debug` (inspector); iOS/url: open the WebView inspector then attach.
  */
 async function dev(cwd: string, flags: Record<string, string>, positionals: string[]): Promise<void> {
   const platform = positionals[0];
   const sim = 'sim' in flags || positionals[1] === 'sim';
   const wantDebug = 'debug' in flags;
   if (platform !== 'ios' && platform !== 'android') {
-    console.error('Usage: appwrap dev <ios|android> [--sim] [--detached] [--debug] [--url <devserver>|--port <p>]');
+    console.error('Usage: appwrap dev <ios|android> [--sim] [--detached] [--debug] [--wifi] [--device <id|ip[:port]>] [--url <devserver>|--port <p>]');
     process.exit(1);
   }
   const cfg = await loadConfig(cwd, flags);
@@ -1320,45 +1621,69 @@ 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] : [])]);
     return;
   }
 
-  // ── device: clean deploy (the shared `deploy` path — NO ns livesync) ──
+  // ── ANDROID device + bundled loader: ns run livesync = true on-device HMR (incremental, no reinstall) ──
+  // Unblocked by declaring @nativescript/android in the shell package.json: ns reads the android runtime
+  // version on the livesync path; when it's undeclared that lookup returns null → `semver.gt(null, …)` →
+  // the "Invalid version … Got type object" crash that long made on-device livesync look unfixable.
+  // ns watches native/app + native/www-src; since the PWA SOURCE lives OUTSIDE native/, we run a source
+  // watcher alongside that rebuilds the web + re-stages www on save — ns's livesync then pushes it.
+  // (Must spawn ns async, not execFileSync: a sync exec freezes the fs.watch loop.)
+  // iOS is intentionally NOT on ns run here: `ns run ios --device` hits the personal-team device
+  // registration/signing path that `deploy ios` handles bespokely — unverified, so iOS keeps the proven
+  // deploy + redeploy-on-save loop below until it's device-verified.
+  if (platform === 'android' && !devUrl && !('detached' in flags)) {
+    const device = resolveDevice(outDir, 'android', flags);
+    // MIUI/Xiaomi auto-denies a bare `adb install`; only `--user 0` works (deploy uses it). Pre-installing
+    // via deploy establishes the package so `ns run`'s subsequent install lands as an allowed UPDATE
+    // rather than a blocked fresh bare-install — the device-verified path. (~one extra fast install.)
+    await deploy(cwd, { ...flags, 'no-launch': '' }, ['android'], cfg);
+    const nsArgs = [wantDebug ? 'debug' : 'run', 'android', '--device', device.id];
+    const env = prepareNsEnv(outDir, nsArgs);
+    console.log(`\n▶ dev: ns ${nsArgs.join(' ')} (on-device HMR) + watching sources → re-stage on save. Ctrl-C to stop.`);
+    // Own process group so Ctrl-C / kill reaps ns AND its grandchildren (gradle, adb logcat, webpack).
+    const nsChild = spawn('ns', nsArgs, { cwd: outDir, stdio: 'inherit', detached: true, env });
+    const stop = () => { try { if (nsChild.pid) process.kill(-nsChild.pid); } catch { /* already gone */ } };
+    process.on('exit', stop);
+    process.on('SIGINT', () => { stop(); process.exit(0); });
+    nsChild.on('exit', (code) => process.exit(code ?? 0));
+    await watchAndSync(cwd, flags, outDir, cfg); // rebuild + re-stage on save; ns livesync pushes it
+    return;
+  }
+
+  // ── iOS device (bundled), --url, or --detached: the proven one-shot deploy path ──
   await deploy(cwd, flags, [platform], devUrl ? effectiveCfg : undefined);
   // Follow-ups reuse the just-deployed device from last-device memory — drop an interactive `-d`.
   const followFlags = { ...flags }; delete followFlags.d;
-
   if (wantDebug) openInspector(effectiveCfg, followFlags, platform, outDir);
-
   if ('detached' in flags) {
     console.log('\n✓ --detached — installed & launched; not attaching/watching.');
     return;
   }
-
-  // Attach: stream the WebView console. With a bundled loader we ALSO watch sources → rebuild+reinstall
-  // on save. With a dev-server loader (--url) the web hot-reloads from the server INSIDE the WebView, so
-  // a native rebuild is pointless (and would re-stamp the bundled loader) — just stream the console.
   if (devUrl) {
+    // --url: the web hot-reloads from the dev server INSIDE the WebView; just stream the console.
     console.log('\n▶ dev: web hot-reloads from the dev server inside the WebView; streaming the console. Ctrl-C to stop.');
     await logs(cwd, followFlags, [platform]);
     return;
   }
-  console.log(`\n▶ dev: streaming WebView console + watching sources (edit a file → rebuild+reinstall). Ctrl-C to stop.`);
+  // iOS bundled device: stream the WebView console + redeploy (rebuild+reinstall) on save. No ns livesync
+  // on an iOS device yet (see above), so a full redeploy is the device-safe refresh path.
+  console.log('\n▶ dev: streaming WebView console + watching sources (edit a file → rebuild+reinstall). Ctrl-C to stop.');
   const logArgs = [import.meta.path, 'logs', platform];
   if (followFlags.device) logArgs.push('--device', followFlags.device);
   if (followFlags.out) logArgs.push('--out', followFlags.out);
   if (followFlags.config) logArgs.push('--config', followFlags.config);
-  // `detached: true` puts the log child in its OWN process group so we can kill the WHOLE group —
-  // the child is `bun … logs`, which itself spawns `adb logcat`; `logChild.kill()` would only reap the
-  // `bun` and orphan the `adb logcat` grandchild when the signal hits the leader pid (e.g. `kill <pid>`
-  // / a supervisor, not interactive Ctrl-C which signals the group). `process.kill(-pid)` reaps both.
+  // `detached: true` → own process group so we reap the whole tree (bun → adb/idevicesyslog) on Ctrl-C.
   const logChild = spawn('bun', logArgs, { stdio: 'inherit', detached: true });
-  const stop = () => { try { if (logChild.pid) process.kill(-logChild.pid); } catch { /* already gone */ } };
-  process.on('exit', stop);
-  process.on('SIGINT', () => { stop(); process.exit(0); });
+  const stopLog = () => { try { if (logChild.pid) process.kill(-logChild.pid); } catch { /* already gone */ } };
+  process.on('exit', stopLog);
+  process.on('SIGINT', () => { stopLog(); process.exit(0); });
   await watchAndRedeploy(cwd, followFlags, platform);
 }
 
@@ -1386,7 +1711,9 @@ function resolveAndroidSdk(): string | undefined {
   return candidates.find((d) => existsSync(join(d, 'platform-tools')) || existsSync(join(d, 'platforms')));
 }
 
-function runNs(outDir: string, args: string[]): void {
+/** Build the env for an `ns` invocation in `outDir` (auto-detect Android SDK, ensure bun-installed deps).
+ * Shared by the blocking `runNs` (sim) and the non-blocking spawn in `dev` (device livesync). */
+function prepareNsEnv(outDir: string, args: string[]): NodeJS.ProcessEnv {
   const env: NodeJS.ProcessEnv = { ...process.env };
   // Android: inject a discovered SDK so `ns` finds it even when the user's shell never exported
   // ANDROID_HOME (new terminal not sourced, conda base shell, etc.) — the common deploy blocker.
@@ -1405,10 +1732,34 @@ function runNs(outDir: string, args: string[]): void {
     console.log(`▶ bun install  (cwd: ${outDir})`);
     execFileSync('bun', ['install'], { cwd: outDir, stdio: 'inherit', env });
   }
+  return env;
+}
+
+function runNs(outDir: string, args: string[]): void {
+  const env = prepareNsEnv(outDir, args);
   console.log(`▶ ns ${args.join(' ')}  (cwd: ${outDir})`);
   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. */
@@ -1427,22 +1778,58 @@ function readStampedLoader(outDir: string): { loader: string; serverUrl: string;
   }
 }
 
-/** Lean watch loop for `dev <platform>`: re-run the clean deploy path whenever a project
- * source file changes (debounced). Skips generated/output dirs. NOT ns livesync — a full rebuild+
- * reinstall, which is the only device-safe path (see `run`'s note). macOS recursive fs.watch. */
+/** Watch loop for iOS `dev` (no on-device ns livesync yet): re-run the clean deploy path on a project
+ * source change (debounced) — a full rebuild+reinstall, the device-safe refresh for iOS. Skips
+ * generated/output dirs. macOS recursive fs.watch. (Android uses watchAndSync + ns livesync instead.) */
 async function watchAndRedeploy(cwd: string, flags: Record<string, string>, platform: 'ios' | 'android'): Promise<void> {
   const { watch } = await import('fs');
-  const ignore = /(^|\/)(native|node_modules|dist|\.git|\.appwrap)(\/|$)/;
+  const ignore = /(^|\/)(native|node_modules|dist|public|\.git|\.appwrap)(\/|$)/;
   console.log(`\n👀 watching ${cwd} for changes → rebuild+reinstall on save (Ctrl-C to stop).`);
   let timer: ReturnType<typeof setTimeout> | undefined;
   let busy = false;
+  let quietUntil = 0;
   watch(cwd, { recursive: true }, (_evt, file) => {
-    if (!file || ignore.test(String(file)) || busy) return;
+    if (!file || ignore.test(String(file)) || busy || Date.now() < quietUntil) return;
     clearTimeout(timer);
     timer = setTimeout(async () => {
       busy = true;
       console.log(`\n🔁 change: ${file} → redeploying…`);
       try { await deploy(cwd, flags, [platform]); } catch (e) { console.error(`⚠ redeploy failed: ${(e as Error).message}`); }
+      quietUntil = Date.now() + 1500;
+      busy = false;
+    }, 600);
+  });
+  await new Promise<void>(() => { /* run until Ctrl-C */ });
+}
+
+/** Lean watch loop for Android `dev`: on a project source change, rebuild the web + RE-STAGE only
+ * the web bundle (dist → native/www-src) — debounced. Deliberately NOT a full `regenerateCore`: that
+ * re-copies App_Resources/package.json and makes ns do a full native rebuild+reinstall (defeating HMR
+ * and tripping MIUI). Staging www-src only keeps the `ns run` livesync on the JS hot-push path. The
+ * watcher sees the PROJECT dir, so it only catches PWA source edits (the shell template lives elsewhere).
+ * Skips generated/output dirs. macOS recursive fs.watch. */
+async function watchAndSync(cwd: string, flags: Record<string, string>, outDir: string, cfg: AppwrapConfig): Promise<void> {
+  const { watch } = await import('fs');
+  // Skip generated/output trees. `dist` is the web build output; `public` is where many build steps
+  // ALSO emit (e.g. a copied bundle / stamped index) — both must be ignored or the rebuild's own writes
+  // re-trigger the watch in a loop. A post-rebuild cooldown is the generic backstop for any other
+  // output dir we don't know about (the project's build target is project-specific).
+  const ignore = /(^|\/)(native|node_modules|dist|public|\.git|\.appwrap)(\/|$)/;
+  console.log(`👀 watching ${cwd} → rebuild + re-stage on save (ns livesync pushes it).`);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let busy = false;
+  let quietUntil = 0; // ignore events for a beat after a rebuild — its own file writes aren't user edits
+  watch(cwd, { recursive: true }, (_evt, file) => {
+    if (!file || ignore.test(String(file)) || busy || Date.now() < quietUntil) return;
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      busy = true;
+      console.log(`\n🔁 change: ${file} → rebuild web + re-stage www…`);
+      try {
+        buildWebIfBundled(cwd, cfg, flags);
+        copyPwa(cwd, outDir, cfg); // stage dist → www-src only; ns livesync hot-pushes it (no reinstall)
+      } catch (e) { console.error(`⚠ re-stage failed: ${(e as Error).message}`); }
+      quietUntil = Date.now() + 1500;
       busy = false;
     }, 600);
   });
@@ -1871,7 +2258,8 @@ function listDevices(platform: 'ios' | 'android'): DeviceInfo[] {
   return listAndroidDevices(adb).map((serial) => {
     let model = '';
     try { model = execFileSync(adb, ['-s', serial, 'shell', 'getprop', 'ro.product.model'], { encoding: 'utf8' }).trim(); } catch { /* offline */ }
-    return { id: serial, name: model || serial, model, transport: 'usb' };
+    // A network adb serial is `host:port` (USB serials never contain ':') → label it wifi.
+    return { id: serial, name: model || serial, model, transport: serial.includes(':') ? 'wifi' : 'usb' };
   });
 }
 
@@ -1893,10 +2281,21 @@ function pickInteractively(devices: DeviceInfo[]): DeviceInfo {
 /** Resolve the target device for a platform command (the reusable core). Persists the choice under
  * `outDir` so the next command (e.g. `run`→`logs`) reuses it. */
 function resolveDevice(outDir: string, platform: 'ios' | 'android', flags: Record<string, string>): DeviceInfo {
-  const devices = listDevices(platform);
+  const adb = platform === 'android' ? androidAdb() : '';
+
+  // --wifi (android): flip a USB device to wireless adb (or reconnect a remembered one), then target it.
+  if (platform === 'android' && 'wifi' in flags) enableWifiAdb(adb, outDir, flags);
+
+  // --device <ip[:port]> (android): if it's a network target that isn't attached yet, `adb connect` it.
+  if (platform === 'android' && flags.device && looksLikeAdbHost(flags.device)) {
+    const target = withAdbPort(flags.device);
+    if (!listAndroidDevices(adb).includes(target)) { adbConnect(adb, target); flags.device = target; }
+  }
+
+  let devices = listDevices(platform);
   const noneMsg = platform === 'ios'
     ? '✖ No connected iOS device found. Plug in via USB (unlocked, "Trust") or pair over Wi-Fi.'
-    : '✖ No authorized Android device. Connect via USB + accept the "Allow USB debugging" prompt (check with `adb devices`).';
+    : '✖ No authorized Android device.\n  USB: plug in + accept "Allow USB debugging".\n  Wireless: `appwrap dev android --wifi` (flip a USB device to wireless), enable the phone\'s "Wireless debugging" (auto-discovered via mDNS), or `--device <ip[:port]>` (an already-paired device).\n  (check with `adb devices`)';
 
   // --device <id|name> — exact (or unambiguous prefix) match against connected devices.
   if (flags.device) {
@@ -1905,6 +2304,22 @@ function resolveDevice(outDir: string, platform: 'ios' | 'android', flags: Recor
     writeLastDevice(outDir, platform, m.id);
     return m;
   }
+
+  // Android: nothing attached but a wireless device was remembered → auto-reconnect it (survives sleep /
+  // USB-unplug, so plain `appwrap dev android` keeps working cordless after the first `--wifi`).
+  if (platform === 'android' && !('d' in flags)) {
+    const last = readLastDevice(outDir, 'android');
+    if (last && last.includes(':') && !devices.find((d) => d.id === last) && adbConnect(adb, last)) devices = listDevices(platform);
+  }
+
+  // Android passive discovery (iOS parity): still nothing → pick up any mDNS-advertised wireless device
+  // (tcpip / "Wireless debugging" on) and adb-connect it, so plain `dev android` finds it with no flag —
+  // the same zero-config a network-paired iPhone gets from devicectl.
+  if (platform === 'android' && devices.length === 0 && !flags.device) {
+    const found = androidMdnsTargets(adb).filter((t) => !listAndroidDevices(adb).includes(t) && adbConnect(adb, t));
+    if (found.length) devices = listDevices(platform);
+  }
+
   if (devices.length === 0) { console.error(noneMsg); process.exit(1); }
 
   // -d → always prompt. Otherwise prefer the remembered device, then the sole device.
@@ -1968,6 +2383,86 @@ function androidAdb(): string {
   return 'adb';
 }
 
+/** Synchronous sleep — the device-resolution path is all sync execFileSync, so we can't await. */
+function sleepSync(ms: number): void { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+
+/** A `--device` value that looks like a network target (ip / hostname[:port]) vs a USB serial — USB
+ * adb serials are bare alphanumerics, never containing a '.' (ip/host) or ':' (host:port). */
+function looksLikeAdbHost(s: string): boolean { return s.includes('.') || s.includes(':'); }
+/** Normalize a wireless target to host:port (adb's default tcpip port is 5555). */
+function withAdbPort(host: string): string { return /:\d+$/.test(host) ? host : `${host}:5555`; }
+
+/** `adb connect <target>` — true if connected (or already was). Prints the outcome. */
+function adbConnect(adb: string, target: string): boolean {
+  try {
+    const out = execFileSync(adb, ['connect', target], { encoding: 'utf8' }).trim();
+    const ok = /connected to|already connected/i.test(out);
+    console.log(ok ? `🔗 ${out}` : `⚠ adb connect ${target}: ${out}`);
+    return ok;
+  } catch (e) {
+    console.error(`⚠ adb connect ${target} failed: ${execErrText(e).trim()}`);
+    return false;
+  }
+}
+
+/** mDNS-discovered wireless adb targets (`ip:port`) — the passive path that matches iOS devicectl's
+ * network listing. The device advertises once tcpip is on (`--wifi`) or Android-11+ "Wireless debugging"
+ * is enabled, so `appwrap dev android` finds it with NO flag (parity with `dev ios` over the network). */
+function androidMdnsTargets(adb: string): string[] {
+  try {
+    return execFileSync(adb, ['mdns', 'services'], { encoding: 'utf8', timeout: 8000 })
+      .split('\n')
+      .map((l) => l.match(/(\d+\.\d+\.\d+\.\d+:\d+)\s*$/)?.[1])
+      .filter((x): x is string => !!x);
+  } catch { return []; }
+}
+
+/** Read a USB-connected device's Wi-Fi (wlan0) IPv4, or null if it isn't on Wi-Fi. */
+function androidWifiIp(adb: string, serial: string): string | null {
+  for (const args of [
+    ['-s', serial, 'shell', 'ip', '-o', 'route', 'get', '1.1.1.1'],   // "... src 192.168.1.50"
+    ['-s', serial, 'shell', 'ip', '-o', '-f', 'inet', 'addr', 'show', 'wlan0'], // "inet 192.168.1.50/24"
+  ]) {
+    try {
+      const m = execFileSync(adb, args, { encoding: 'utf8' }).match(/(?:src|inet)\s+(\d+\.\d+\.\d+\.\d+)/);
+      if (m && !m[1].startsWith('127.')) return m[1];
+    } catch { /* try next */ }
+  }
+  return null;
+}
+
+/** `--wifi`: flip a USB-connected device into TCP/IP mode and `adb connect` it over the LAN, so the user
+ * can unplug and keep iterating cordless. If nothing's on USB but a wireless device was remembered, just
+ * reconnect that. Sets `flags.device` to the wireless target (and clears `wifi`) so the rest of the
+ * resolve/deploy path — and any later resolveDevice call — targets it without re-flipping. */
+function enableWifiAdb(adb: string, outDir: string, flags: Record<string, string>): void {
+  const usb = listAndroidDevices(adb).filter((s) => !s.includes(':')); // USB-attached serials only
+  if (usb.length === 0) {
+    const last = readLastDevice(outDir, 'android');
+    if (last && last.includes(':') && adbConnect(adb, last)) { flags.device = last; delete flags.wifi; return; }
+    console.error('✖ --wifi needs a USB-connected device to flip to wireless (none found). Plug in once + accept "Allow USB debugging", or pass --device <ip[:port]> for an already-paired device.');
+    process.exit(1);
+  }
+  const serial = flags.device && usb.includes(flags.device) ? flags.device : usb[0];
+  if (usb.length > 1 && serial === usb[0] && !(flags.device && usb.includes(flags.device))) {
+    console.log(`  (multiple USB devices; flipping ${serial} — pass --device <serial> to choose another)`);
+  }
+  const ip = androidWifiIp(adb, serial);
+  if (!ip) { console.error(`✖ Couldn't read ${serial}'s Wi-Fi IP — is it on Wi-Fi? (try: adb -s ${serial} shell ip route)`); process.exit(1); }
+  console.log(`📶 ${serial}: enabling wireless adb on :5555…`);
+  try { execFileSync(adb, ['-s', serial, 'tcpip', '5555'], { stdio: 'pipe' }); }
+  catch (e) { console.error(`✖ adb tcpip failed: ${execErrText(e).trim()}`); process.exit(1); }
+  const target = `${ip}:5555`;
+  // tcpip restarts adbd on the device — connect with a few retries while it comes back up.
+  let connected = false;
+  for (let i = 0; i < 6 && !connected; i++) { sleepSync(700); connected = adbConnect(adb, target); }
+  if (!connected) { console.error(`✖ Couldn't connect to ${target} after tcpip — same Wi-Fi network? firewall blocking :5555?`); process.exit(1); }
+  writeLastDevice(outDir, 'android', target);
+  console.log(`✓ Wireless adb ready → ${target}. You can unplug USB now.`);
+  flags.device = target;
+  delete flags.wifi;
+}
+
 /** Authorized (`device` state) adb serials. Skips `unauthorized`/`offline`. */
 function listAndroidDevices(adb: string): string[] {
   try {
@@ -2097,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 {
-      execFileSync('ns', ['build', 'ios', '--for-device'], { cwd: outDir, stdio: 'inherit' });
+      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', nsArgs, { cwd: outDir, stdio: 'inherit' });
     } catch (e) {
       // The xcodebuild dump above is cryptic; surface the two signing failures we actually hit most.
       console.error(
@@ -2123,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);
@@ -2148,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(
@@ -2181,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.');
@@ -2206,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.
@@ -2378,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;
@@ -2408,15 +2944,19 @@ async function main(): Promise<void> {
     default:
       console.log('Usage: appwrap <init|sync|dev|build|deploy|publish|logs> [--config <path>] [--out native]\n' +
         '  config: appwrap.config.ts (preferred) → .js → appwrap.json\n' +
-        '  Device selection (dev/deploy/logs/publish): --device <id|name> | -d (pick from a list) | else last-used / sole device.\n\n' +
-        '  dev <ios|android> [--sim] [--detached] [--debug] [--url <devserver>|--port <p>]\n' +
-        '       live-dev: DEVICE → clean deploy + stream console + watch sources (rebuild on save).\n' +
-        '       --sim = ns run/HMR on emulator; --url/--port = web HMR from a dev server inside the WebView;\n' +
-        '       --detached = install & launch then exit; --debug = also open the WebView inspector.\n' +
+        '  Device selection (dev/deploy/logs/publish): --device <id|name|ip[:port]> | -d (pick from a list) | else last-used / sole device.\n' +
+        '  Android wireless: --wifi flips a USB device to wireless adb (unplug + keep going); thereafter the\n' +
+        '       device is auto-discovered via mDNS — plain `dev android` finds it with NO flag (iOS parity).\n' +
+        '       --device <ip[:port]> `adb connect`s an already-paired one.\n\n' +
+        '  dev <ios|android> [--sim] [--detached] [--debug] [--wifi] [--url <devserver>|--port <p>]\n' +
+        '       live-dev: ANDROID device → ns run livesync (true on-device HMR) + re-stage on save;\n' +
+        '       iOS device → deploy + rebuild/reinstall on save. --sim = ns run/HMR on emulator;\n' +
+        '       --url/--port = web HMR from a dev server inside the WebView; --detached = install & exit.\n' +
         '  deploy <ios|android> [--no-launch] [--no-web-build] [-f]   (clean ship-once: build → install → launch → exit)\n' +
         '  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',
 ]);