@livx.cc/appwrap 0.61.15 → 0.61.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.61.15",
+  "version": "0.61.17",
   "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_Resources/iOS/src/AppwrapKeyboardAccessory.m

@@ -0,0 +1,25 @@
+// appwrap: config `iosHideKeyboardAccessory: true` stamps Info.plist `AppwrapHideKeyboardAccessory` → this
+// drops WKWebView's ▲▼✓ keyboard input-accessory bar. The bar is the `inputAccessoryView` of the private
+// WKContentView (the first responder while a web field is focused); we give THAT class a nil-returning
+// override. Native on purpose: doing it from JS (NativeScript extend / objc runtime interop on a
+// metadata-less private class) SIGABRTs on device. Absent/false key → no-op.
+#import <UIKit/UIKit.h>
+#import <objc/runtime.h>
+#import <dlfcn.h>
+
+@interface AppwrapKeyboardAccessory : NSObject
+@end
+
+@implementation AppwrapKeyboardAccessory
++ (void)load {
+  if (![[[NSBundle mainBundle] objectForInfoDictionaryKey:@"AppwrapHideKeyboardAccessory"] boolValue]) return;
+  // WebKit may not be loaded yet at +load (the shell reaches it via NativeScript metadata, not a link) — load it.
+  dlopen("/System/Library/Frameworks/WebKit.framework/WebKit", RTLD_LAZY);
+  Class cls = NSClassFromString(@"WKContentView");
+  Method m = cls ? class_getInstanceMethod(cls, @selector(inputAccessoryView)) : NULL;
+  if (!m) { NSLog(@"[appwrap] keyboard accessory: WKContentView not found — bar kept"); return; }
+  IMP nilImp = imp_implementationWithBlock(^id(id _self) { return nil; });
+  // Add on WKContentView itself (not the inherited UIResponder method) so other responders are untouched.
+  if (!class_addMethod(cls, @selector(inputAccessoryView), nilImp, method_getTypeEncoding(m))) method_setImplementation(m, nilImp);
+}
+@end

package/runtime/App_Resources/iOS/src/AppwrapKeyboardFocus.m

@@ -0,0 +1,30 @@
+// appwrap: config `iosKeyboardWithoutUserAction: true` stamps Info.plist `AppwrapKeyboardWithoutUserAction` →
+// programmatic `el.focus()` raises the keyboard (WKWebView's missing `keyboardDisplayRequiresUserAction = NO`).
+// WebKit only shows the keyboard when the private WKContentView focus hook sees `userIsInteracting`; we wrap
+// that hook and force it YES (the approach Cordova/Capacitor ship). Native for the same reason as
+// AppwrapKeyboardAccessory.m (JS swizzles of private WebKit classes SIGABRT on device). Absent key → no-op;
+// selector not found (future iOS renames it) → logged no-op, never a crash.
+#import <UIKit/UIKit.h>
+#import <objc/runtime.h>
+#import <dlfcn.h>
+
+@interface AppwrapKeyboardFocus : NSObject
+@end
+
+@implementation AppwrapKeyboardFocus
++ (void)load {
+  if (![[[NSBundle mainBundle] objectForInfoDictionaryKey:@"AppwrapKeyboardWithoutUserAction"] boolValue]) return;
+  dlopen("/System/Library/Frameworks/WebKit.framework/WebKit", RTLD_LAZY);
+  Class cls = NSClassFromString(@"WKContentView");
+  // iOS 13+ signature; args after userIsInteracting are passed through untouched. Scalars are taken as
+  // 64-bit words (arm64/x86_64 pass each in its own register) so no bits of `activityStateChanges` are lost.
+  SEL sel = sel_getUid("_elementDidFocus:userIsInteracting:blurPreviousNode:activityStateChanges:userObject:");
+  Method m = cls ? class_getInstanceMethod(cls, sel) : NULL;
+  if (!m) { NSLog(@"[appwrap] keyboard focus: WKContentView focus hook not found — focus() needs a tap"); return; }
+  typedef void (*Orig)(id, SEL, void *, BOOL, uintptr_t, uintptr_t, id);
+  Orig orig = (Orig)method_getImplementation(m);
+  method_setImplementation(m, imp_implementationWithBlock(^void(id me, void *info, BOOL interacting, uintptr_t blur, uintptr_t changes, id userObject) {
+    orig(me, sel, info, YES, blur, changes, userObject);
+  }));
+}
+@end

package/runtime/app/shell/android-helpers.ts

@@ -30,6 +30,26 @@ export function requestPermissions(permissions: string[]): Promise<boolean> {
   });
 }
 
+/** WebChromeClient.onPermissionRequest (getUserMedia): grant the WebView's per-origin capture after
+ * ensuring the app holds the matching OS runtime permission (CAMERA / RECORD_AUDIO). Stateless —
+ * shared by the app WebView and the `webview` overlay. */
+export function handleWebPermissionRequest(request: android.webkit.PermissionRequest): void {
+  const PR = android.webkit.PermissionRequest;
+  const resources: string[] = Array.from(request.getResources());
+  const perms = new Set<string>();
+  for (const r of resources) {
+    if (r === PR.RESOURCE_VIDEO_CAPTURE) perms.add('android.permission.CAMERA');
+    if (r === PR.RESOURCE_AUDIO_CAPTURE) perms.add('android.permission.RECORD_AUDIO');
+  }
+  if (!perms.size) {
+    Utils.dispatchToMainThread(() => request.grant(request.getResources()));
+    return;
+  }
+  requestPermissions(Array.from(perms)).then((ok) =>
+    Utils.dispatchToMainThread(() => (ok ? request.grant(request.getResources()) : request.deny()))
+  );
+}
+
 /** Decode a content Uri (downscaled to `maxSize` longest edge) into a JPEG data URL. */
 export function uriToDataUrl(uri: android.net.Uri, maxSize: number): string | null {
   const cr = Utils.android.getApplicationContext().getContentResolver();

package/runtime/app/shell/capabilities.manifest.ts

@@ -212,6 +212,15 @@ export const MODULES: ModuleManifest[] = [
     },
   },
 
+  // ── webview — in-app WebView OVERLAY (a second chrome-less WKWebView over the app, page-driven) ──
+  // vs browser.open (SFSafariViewController: modal, own chrome, separate cookie jar): this one shares the
+  // persistent default data store and is steered by the page (open/nav/hide/show/close + webview.state
+  // events). iOS: WKWebView; Android: android.webkit.WebView in the content frame. No permission, no native dep. Strippable.
+  {
+    name: 'webview', group: 'webview',
+    capabilities: { webview: { ios: true, android: true } },
+  },
+
   // ── speech (TTS + STT) — opt-in module; ONE coherent kit.speech, TWO honest capabilities ──
   // ONE module (not split TTS-core / STT-opt-in): TTS-only apps are rare and a split fractures
   // `kit.speech` across tiers. The module declares the STT perms (mic + speech-recognition); the
@@ -341,7 +350,7 @@ export const MODULES: ModuleManifest[] = [
 
 /** Opt-in registration groups that own their own NS handler file (strippable when inactive). Core
  * groups (core/extended/parity/system/media) are always bundled; only these are CLI-gated. */
-export const OPTIONAL_GROUPS = ['oauth', 'reviews', 'scanner', 'speech', 'tracking', 'appleSignIn', 'backgroundTask', 'shareTarget'] as const;
+export const OPTIONAL_GROUPS = ['oauth', 'reviews', 'scanner', 'speech', 'tracking', 'appleSignIn', 'backgroundTask', 'shareTarget', 'webview'] as const;
 
 /** CLI-gated groups (strippable in explicit mode) that legacy mode (no `modules` key) STILL auto-bundles
  * for back-compat. Empty now that billing (its only member) moved to a host-provided pack — kept as the

package/runtime/app/shell/config.ts

@@ -73,6 +73,9 @@ export const SHELL_CONFIG = {
    * 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,
+  /** iOS only. Remove WKWebView's ▲▼✓ keyboard accessory bar (native: App_Resources/iOS/src/AppwrapKeyboardAccessory.m, gated on Info.plist AppwrapHideKeyboardAccessory). With the bar
+   * gone the extra lift above is not applied — it only compensates the bar's phantom reservation. */
+  iosHideKeyboardAccessory: false,
   /** `splashHold` config: hold the launch splash over the WebView until the page calls
    * `ui.splash.hide` (or `timeoutMs` passes / the load fails). `logo` = a `splashIcon` was stamped
    * (iOS `LaunchScreen.Center` imageset, Android `splash_logo` drawable). See wireSplashHold. */

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

@@ -3,7 +3,7 @@ import { SHELL_CONFIG } from './config';
 import { mimeFor } from './mime';
 import { APPWRAP_GLOBALS_JS, NATIVE_FEEL_JS, serviceWorkerGuardJs, externalNavGuardJs } from './web-quirks';
 import { envGlobalsJs } from './env';
-import { requestPermissions } from './android-helpers';
+import { handleWebPermissionRequest } from './android-helpers';
 import { showFileChooser } from './file-chooser.android';
 import { hostOf } from './env-switcher';
 
@@ -66,20 +66,7 @@ function getChromeClientClass(): any {
     // app holds the matching OS runtime permission (CAMERA / RECORD_AUDIO).
     // No instance state — safe on the shared class.
     onPermissionRequest(request: android.webkit.PermissionRequest): void {
-      const PR = android.webkit.PermissionRequest;
-      const resources: string[] = Array.from(request.getResources());
-      const perms = new Set<string>();
-      for (const r of resources) {
-        if (r === PR.RESOURCE_VIDEO_CAPTURE) perms.add('android.permission.CAMERA');
-        if (r === PR.RESOURCE_AUDIO_CAPTURE) perms.add('android.permission.RECORD_AUDIO');
-      }
-      if (!perms.size) {
-        Utils.dispatchToMainThread(() => request.grant(request.getResources()));
-        return;
-      }
-      requestPermissions(Array.from(perms)).then((ok) =>
-        Utils.dispatchToMainThread(() => (ok ? request.grant(request.getResources()) : request.deny()))
-      );
+      handleWebPermissionRequest(request);
     },
 
     // <input type="file"> — NOT optional here: replacing NS's WebChromeClient removed the

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

@@ -0,0 +1,305 @@
+import { Utils, isIOS, isAndroid, Application } from '@nativescript/core';
+import { bridge } from './bridge';
+import { createUiDelegate } from './ios-ui-delegate';
+import { handleWebPermissionRequest } from './android-helpers';
+
+const err = (code: string, message: string) => Object.assign(new Error(message), { code });
+
+/** WKWebView properties whose change is a navigation-state change (KVO-observable). */
+const KVO_KEYS = ['URL', 'title', 'canGoBack', 'canGoForward', 'loading'];
+
+/**
+ * In-app WebView OVERLAY (iOS) — a second, full WKWebView layered over the app's own WebView, below
+ * `top` CSS px and above `bottom` CSS px (so the page keeps its own top bar / bottom dock visible). Unlike `browser.open`
+ * (SFSafariViewController: modal, its own chrome, isolated cookies), this is chrome-less, page-driven
+ * and shares the PERSISTENT default data store (cookies/logins survive relaunch).
+ *
+ *   webview.open  {url, top?, bottom?}          — show (or, if open, navigate + show / re-inset)
+ *   webview.nav   {op:'back'|'forward'|'reload'|'go', url?}
+ *   webview.hide / webview.show {top?,bottom?}  — keep state, reveal/cover the page beneath (show re-insets)
+ *   webview.close                               — tear down; emits `webview.closed`
+ * Events: `webview.state` {url,title,canGoBack,canGoForward,loading} on every navigation change.
+ *
+ * Swipe back/forward on, target=_blank/window.open loads in place (shared ios-ui-delegate), keyboard +
+ * safe areas handled by WKWebView's own scroll-view insets (contentInsetAdjustment automatic).
+ * Android: an android.webkit.WebView added to the activity's content frame, margins derived from the app
+ * WebView's box (re-applied when it re-lays out), cookies via the process-wide CookieManager (persistent),
+ * getUserMedia via the shared permission handler, _blank in place (no multiple-window support).
+ */
+export function registerWebViewHandlers(): void {
+  if (isIOS) registerIos();
+  else if (isAndroid) registerAndroid();
+}
+
+
+
+function registerIos(): void {
+  // Strong refs — WKWebView holds its delegates weakly and KVO observers aren't retained.
+  let wv: WKWebView | null = null;
+  let observer: NSObject | null = null;
+  let uiDelegate: WKUIDelegate | null = null;
+  let topConstraint: NSLayoutConstraint | null = null;
+  let bottomConstraint: NSLayoutConstraint | null = null;
+  let emitQueued = false;
+  let ObserverClass: any; // KVO sink, built once (ObjC class names are global)
+
+  const state = () => ({
+    url: wv?.URL?.absoluteString ?? '',
+    title: wv?.title ?? '',
+    canGoBack: !!wv?.canGoBack,
+    canGoForward: !!wv?.canGoForward,
+    loading: !!wv?.loading,
+  });
+
+  // Several KVO keys flip together on one navigation — coalesce into one event per runloop turn.
+  const emitState = () => {
+    if (emitQueued) return;
+    emitQueued = true;
+    setTimeout(() => { emitQueued = false; if (wv) bridge.emit('webview.state', state()); }, 0);
+  };
+
+  const load = (url: string) => {
+    const nsUrl = NSURL.URLWithString(url);
+    if (!nsUrl) throw err('NATIVE_ERROR', `webview: invalid url ${url}`);
+    wv!.loadRequest(NSURLRequest.requestWithURL(nsUrl));
+  };
+
+  const create = (top: number, bottom: number) => {
+    const host = bridge.getWebView()?.ios as WKWebView | undefined;
+    const container = host?.superview ?? Utils.ios.getRootViewController()?.view;
+    if (!container) throw err('NATIVE_ERROR', 'webview.open: no host view');
+
+    const config = WKWebViewConfiguration.new();
+    config.websiteDataStore = WKWebsiteDataStore.defaultDataStore();
+    config.allowsInlineMediaPlayback = true;
+    const view = WKWebView.alloc().initWithFrameConfiguration(CGRectZero, config);
+    view.allowsBackForwardNavigationGestures = true;
+    uiDelegate = createUiDelegate();
+    view.UIDelegate = uiDelegate;
+    if (host?.backgroundColor) { view.backgroundColor = host.backgroundColor; view.opaque = false; }
+    if ((view as any).inspectable !== undefined) (view as any).inspectable = true; // iOS 16.4+ Safari inspector
+
+    view.translatesAutoresizingMaskIntoConstraints = false;
+    container.addSubview(view);
+    // Anchor to the app WebView's box so `top`/`bottom` are in the page's own CSS px (== points).
+    const ref: any = host ?? container;
+    topConstraint = view.topAnchor.constraintEqualToAnchorConstant(ref.topAnchor, top);
+    bottomConstraint = view.bottomAnchor.constraintEqualToAnchorConstant(ref.bottomAnchor, -bottom);
+    NSLayoutConstraint.activateConstraints([
+      topConstraint,
+      bottomConstraint,
+      view.leadingAnchor.constraintEqualToAnchor(ref.leadingAnchor),
+      view.trailingAnchor.constraintEqualToAnchor(ref.trailingAnchor),
+    ] as any);
+
+    ObserverClass ??= (NSObject as any).extend(
+      {
+        observeValueForKeyPathOfObjectChangeContext() {
+          // Shell-coloured + non-opaque only to avoid a white flash before the first load; after it, WebKit
+          // must paint the page's own canvas, or a page with no background shows the (dark) shell through.
+          if (wv && !wv.opaque && !wv.loading && wv.URL) wv.opaque = true;
+          emitState();
+        },
+      },
+      { name: 'AppwrapWebViewOverlayObserver' }
+    );
+    observer = ObserverClass.new();
+    for (const k of KVO_KEYS) view.addObserverForKeyPathOptionsContext(observer!, k, NSKeyValueObservingOptions.New, null);
+    wv = view;
+  };
+
+  const destroy = () => {
+    if (!wv) return;
+    for (const k of KVO_KEYS) { try { wv.removeObserverForKeyPath(observer!, k); } catch { /* not observed */ } }
+    wv.stopLoading();
+    wv.removeFromSuperview();
+    wv = null; observer = null; uiDelegate = null; topConstraint = null; bottomConstraint = null;
+    bridge.emit('webview.closed', {});
+  };
+
+  const onMain = <T>(fn: () => T): Promise<T> =>
+    new Promise((resolve, reject) => Utils.dispatchToMainThread(() => {
+      try { resolve(fn()); } catch (e) { reject(e); }
+    }));
+
+  const inset = (v?: number) => Math.max(0, Number(v) || 0);
+  /** Re-apply insets on a live overlay; an omitted side keeps its current value. */
+  const setInsets = (top?: number, bottom?: number) => {
+    if (top !== undefined && topConstraint) topConstraint.constant = inset(top);
+    if (bottom !== undefined && bottomConstraint) bottomConstraint.constant = -inset(bottom);
+  };
+
+  bridge.register('webview.open', ({ url, top, bottom }: { url: string; top?: number; bottom?: number }) => {
+    const target = String(url ?? '');
+    if (!target) throw err('NATIVE_ERROR', 'webview.open: empty url');
+    return onMain(() => {
+      if (!wv) create(inset(top), inset(bottom));
+      else setInsets(top, bottom);
+      wv!.hidden = false;
+      wv!.superview?.bringSubviewToFront(wv!);
+      load(target);
+      return state();
+    });
+  });
+
+  bridge.register('webview.nav', ({ op, url }: { op: string; url?: string }) =>
+    onMain(() => {
+      if (!wv) throw err('NATIVE_ERROR', 'webview.nav: not open');
+      if (op === 'back') { if (wv.canGoBack) wv.goBack(); }
+      else if (op === 'forward') { if (wv.canGoForward) wv.goForward(); }
+      else if (op === 'reload') wv.reload();
+      else if (op === 'go') load(String(url ?? ''));
+      else throw err('NATIVE_ERROR', `webview.nav: unknown op ${op}`);
+      return state();
+    })
+  );
+
+  bridge.register('webview.hide', () => onMain(() => { if (wv) wv.hidden = true; return { open: !!wv }; }));
+  bridge.register('webview.show', (p?: { top?: number; bottom?: number } | null) => onMain(() => {
+    if (wv) { setInsets(p?.top, p?.bottom); wv.hidden = false; wv.superview?.bringSubviewToFront(wv); }
+    return { open: !!wv };
+  }));
+  bridge.register('webview.close', () => onMain(() => { destroy(); }));
+}
+
+function registerAndroid(): void {
+  let wv: any = null; // android.webkit.WebView
+  let insets = { top: 0, bottom: 0 };
+  let layoutListener: any = null;
+  let host: any = null;
+  let emitQueued = false;
+  // NS caches extend() proxies by shape — build each client class ONCE; route to the single live overlay.
+  let ViewClient: any, ChromeClient: any;
+
+  const state = () => ({
+    url: wv?.getUrl() ?? '',
+    title: wv?.getTitle() ?? '',
+    canGoBack: !!wv?.canGoBack(),
+    canGoForward: !!wv?.canGoForward(),
+    loading: !!wv && wv.getProgress() < 100,
+  });
+  const emitState = () => {
+    if (emitQueued) return;
+    emitQueued = true;
+    setTimeout(() => { emitQueued = false; if (wv) bridge.emit('webview.state', state()); }, 0);
+  };
+
+  const activity = () => Application.android.foregroundActivity ?? Application.android.startActivity;
+  const density = () => Utils.android.getApplicationContext().getResources().getDisplayMetrics().density || 1;
+  const content = (): any => activity()?.findViewById(android.R.id.content); // FrameLayout
+
+  /** Place the overlay over the app WebView's box, `top`/`bottom` CSS px inside it. */
+  const layout = () => {
+    const frame = content();
+    if (!wv || !frame) return;
+    const d = density();
+    const fl = [0, 0], hl = [0, 0];
+    frame.getLocationInWindow(fl);
+    let boxTop = 0, boxBottom = 0;
+    if (host) {
+      host.getLocationInWindow(hl);
+      boxTop = hl[1] - fl[1];
+      boxBottom = frame.getHeight() - (boxTop + host.getHeight());
+    }
+    const lp = new android.widget.FrameLayout.LayoutParams(-1, -1);
+    lp.topMargin = Math.max(0, Math.round(boxTop + insets.top * d));
+    lp.bottomMargin = Math.max(0, Math.round(boxBottom + insets.bottom * d));
+    wv.setLayoutParams(lp);
+  };
+
+  const load = (url: string) => {
+    if (!/^[a-z][a-z0-9+.-]*:/i.test(url)) throw err('NATIVE_ERROR', `webview: invalid url ${url}`);
+    wv.loadUrl(url);
+  };
+
+  const create = () => {
+    const frame = content();
+    if (!frame) throw err('NATIVE_ERROR', 'webview.open: no host view');
+    host = bridge.getWebView()?.android ?? null;
+    ViewClient ??= (android.webkit.WebViewClient as any).extend({
+      onPageStarted() { emitState(); },
+      onPageFinished() { emitState(); },
+      doUpdateVisitedHistory() { emitState(); },
+    });
+    ChromeClient ??= (android.webkit.WebChromeClient as any).extend({
+      onReceivedTitle() { emitState(); },
+      onProgressChanged() { emitState(); },
+      onPermissionRequest(request: any) { handleWebPermissionRequest(request); },
+    });
+    const view = new android.webkit.WebView(activity());
+    const st = view.getSettings();
+    st.setJavaScriptEnabled(true);
+    st.setDomStorageEnabled(true);
+    st.setMediaPlaybackRequiresUserGesture(false);
+    st.setSupportMultipleWindows(false); // target=_blank / window.open load in place
+    android.webkit.CookieManager.getInstance().setAcceptThirdPartyCookies(view, true);
+    const client = new ViewClient(), chrome = new ChromeClient();
+    view.setWebViewClient(client);
+    view.setWebChromeClient(chrome);
+    (view as any)._appwrapClients = [client, chrome]; // keep JS peers alive (NS GC doesn't see the native hold)
+    const bg = host?.getBackground?.();
+    if (bg instanceof android.graphics.drawable.ColorDrawable) view.setBackgroundColor(bg.getColor());
+    android.webkit.WebView.setWebContentsDebuggingEnabled(true);
+    wv = view;
+    frame.addView(view);
+    layout();
+    if (host) {
+      layoutListener = new android.view.View.OnLayoutChangeListener({ onLayoutChange() { layout(); } });
+      host.addOnLayoutChangeListener(layoutListener);
+    }
+  };
+
+  const destroy = () => {
+    if (!wv) return;
+    if (host && layoutListener) host.removeOnLayoutChangeListener(layoutListener);
+    wv.stopLoading();
+    wv.getParent()?.removeView(wv);
+    wv.destroy();
+    wv = null; host = null; layoutListener = null;
+    android.webkit.CookieManager.getInstance().flush();
+    bridge.emit('webview.closed', {});
+  };
+
+  const onMain = <T>(fn: () => T): Promise<T> =>
+    new Promise((resolve, reject) => Utils.dispatchToMainThread(() => {
+      try { resolve(fn()); } catch (e) { reject(e); }
+    }));
+  const inset = (v?: number) => Math.max(0, Number(v) || 0);
+  const setInsets = (top?: number, bottom?: number) => {
+    if (top !== undefined) insets.top = inset(top);
+    if (bottom !== undefined) insets.bottom = inset(bottom);
+    layout();
+  };
+  const reveal = () => { wv.setVisibility(android.view.View.VISIBLE); wv.bringToFront(); };
+
+  bridge.register('webview.open', ({ url, top, bottom }: { url: string; top?: number; bottom?: number }) => {
+    const target = String(url ?? '');
+    if (!target) throw err('NATIVE_ERROR', 'webview.open: empty url');
+    return onMain(() => {
+      if (!wv) { insets = { top: inset(top), bottom: inset(bottom) }; create(); }
+      else setInsets(top, bottom);
+      reveal();
+      load(target);
+      return state();
+    });
+  });
+
+  bridge.register('webview.nav', ({ op, url }: { op: string; url?: string }) =>
+    onMain(() => {
+      if (!wv) throw err('NATIVE_ERROR', 'webview.nav: not open');
+      if (op === 'back') { if (wv.canGoBack()) wv.goBack(); }
+      else if (op === 'forward') { if (wv.canGoForward()) wv.goForward(); }
+      else if (op === 'reload') wv.reload();
+      else if (op === 'go') load(String(url ?? ''));
+      else throw err('NATIVE_ERROR', `webview.nav: unknown op ${op}`);
+      return state();
+    })
+  );
+
+  bridge.register('webview.hide', () => onMain(() => { wv?.setVisibility(android.view.View.GONE); return { open: !!wv }; }));
+  bridge.register('webview.show', (p?: { top?: number; bottom?: number } | null) => onMain(() => {
+    if (wv) { setInsets(p?.top, p?.bottom); reveal(); }
+    return { open: !!wv };
+  }));
+  bridge.register('webview.close', () => onMain(() => { destroy(); }));
+}

package/runtime/app/shell/handlers.ts

@@ -15,7 +15,7 @@ import { appwrapNativeLog } from './native-log';
 const dlog = (line: string) => { if (SHELL_CONFIG.debug) appwrapNativeLog(line); };
 
 /** Build identifier for the native shell bundle — bump per deploy to spot stale bundles. */
-export const SHELL_BUILD = 'save-to-photos-1';
+export const SHELL_BUILD = 'webview-overlay-1';
 
 /** Version status the web side (native-kit `kit.updates`) reports via `app.reportWebVersion`. */
 export interface WebVersionInfo { current?: string; latest?: string; build?: string | number; updateAvailable?: boolean; }

package/runtime/app/shell/keyboard.ts

@@ -36,8 +36,10 @@ export function registerKeyboardHandlers(): void {
   bridge.register('keyboard.hide', () => {
     Utils.dispatchToMainThread(() => {
       if (isIOS) {
-        // WKWebView is a UIView → endEditing resigns the active field's first responder.
-        (bridge.getWebView()?.ios as any)?.endEditing?.(true);
+        // endEditing on the WINDOW resigns whichever field is first responder — incl. one inside a
+        // sibling view (the `webview` overlay), which the app WebView's own endEditing can't reach.
+        const wv = bridge.getWebView()?.ios as any;
+        (wv?.window ?? UIApplication.sharedApplication.keyWindow ?? wv)?.endEditing?.(true);
       } else if (isAndroid) {
         hideAndroidKeyboard();
       }
@@ -159,7 +161,7 @@ function armIosKeyboardObservers(): 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);
+    activeExtraLift = sawWillShow || SHELL_CONFIG.iosHideKeyboardAccessory ? 0 : (SHELL_CONFIG.iosKeyboardExtraLift ?? 82);
     const value = note?.userInfo?.objectForKey?.(UIKeyboardFrameEndUserInfoKey);
     const rect = value?.CGRectValue;
     // Keyboard frames are in screen coordinates: a webview momentarily out of its window (screen

package/src/cli.ts

@@ -36,6 +36,7 @@ import {
   stampAndroidOrientation,
   stampAndroidQueries,
   stampAppBoundDomains,
+  stampInsecureHosts,
   stampPlistBackgroundTasks,
   stampPlistOrientations,
   stampPrivacyTracking,
@@ -401,6 +402,7 @@ const OPTIONAL_GROUP_HANDLERS: Record<string, { file: string; fn: string }> = {
   appleSignIn: { file: './handlers-apple-signin', fn: 'registerAppleSignInHandlers' },
   backgroundTask: { file: './handlers-background', fn: 'registerBackgroundTaskHandlers' },
   shareTarget: { file: './handlers-share-target', fn: 'registerShareTargetHandlers' },
+  webview: { file: './handlers-webview', fn: 'registerWebViewHandlers' },
   // billing/health/widget live in host-provided module packs — a consumer opts in via modulePacks.
 };
 
@@ -1008,6 +1010,7 @@ export const SHELL_CONFIG = {
   pushAndroid: ${JSON.stringify(!!cfg.push?.enabled && cfg.push?.android !== false)},
   pushRegistrationUrl: ${JSON.stringify(cfg.push?.registrationUrl ?? '')},
   iosKeyboardExtraLift: ${JSON.stringify(cfg.iosKeyboardExtraLift ?? 82)},
+  iosHideKeyboardAccessory: ${JSON.stringify(cfg.iosHideKeyboardAccessory ?? false)},
   splash: ${JSON.stringify(splash)} as { hold: boolean; timeoutMs: number; logo: boolean },
   envSwitcher: ${JSON.stringify(envSwitcher)} as { enabled: boolean; envs: { label: string; url: string }[]; allowPattern: string },
   webCaps: ${JSON.stringify(webCaps)} as { camera: boolean; microphone: boolean; geolocation: boolean },
@@ -1068,6 +1071,10 @@ function stampIOSDisplayName(outDir: string, cfg: AppwrapConfig, req: NativeReqs
   // strips the WKAppBoundDomains key, so it no-ops when the field is absent.
   src = stampAppBoundDomains(src, cfg.appBoundDomains);
 
+  // ATS per-domain exceptions for plain-http hosts (e.g. a Tailscale `ts.net` box). Merged into the
+  // template's NSAppTransportSecurity dict; idempotent both ways.
+  src = stampInsecureHosts(src, cfg.insecureHosts);
+
   // Permission usage strings + URL scheme + export-compliance — idempotent: strip stamped block, re-add
   src = src.replace(/\s*<!-- appwrap:begin -->[\s\S]*?<!-- appwrap:end -->/g, '');
   const extras: string[] = [];
@@ -1077,6 +1084,9 @@ function stampIOSDisplayName(outDir: string, cfg: AppwrapConfig, req: NativeReqs
   for (const { key, usage } of req.iosPlist) {
     extras.push(`  <key>${key}</key>\n  <string>${usage}</string>`);
   }
+  // Read by the native AppwrapKeyboardAccessory +load (runtime App_Resources/iOS/src) — no JS involved.
+  if (cfg.iosHideKeyboardAccessory) extras.push(`  <key>AppwrapHideKeyboardAccessory</key>\n  <true/>`);
+  if (cfg.iosKeyboardWithoutUserAction) extras.push(`  <key>AppwrapKeyboardWithoutUserAction</key>\n  <true/>`);
   if (cfg.urlScheme) {
     extras.push(
       `  <key>CFBundleURLTypes</key>\n  <array>\n    <dict>\n      <key>CFBundleTypeRole</key>\n      <string>Editor</string>\n      <key>CFBundleURLName</key>\n      <string>${cfg.id}</string>\n      <key>CFBundleURLSchemes</key>\n      <array>\n        <string>${cfg.urlScheme}</string>\n      </array>\n    </dict>\n  </array>`

package/src/config.ts

@@ -131,6 +131,17 @@ export interface AppwrapConfig {
    * 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;
+  /** iOS only. Remove WKWebView's ▲▼✓ keyboard input-accessory bar (terminal/chat UIs that own their
+   * own input chrome). Also drops the extra keyboard lift, which only compensates that bar. Default false. */
+  iosHideKeyboardAccessory?: boolean;
+  /** iOS only. Let programmatic `el.focus()` raise the keyboard without a user tap (the UIWebView-era
+   * `keyboardDisplayRequiresUserAction = false`; WKWebView has no public switch, so a native +load
+   * forces WebKit's focus path to `userIsInteracting`). Applies to every WKWebView in the app. Default false. */
+  iosKeyboardWithoutUserAction?: boolean;
+  /** iOS only. Hosts allowed over plain http (ATS `NSExceptionDomains`, subdomains included) — e.g.
+   * `['ts.net']` for a Tailscale box. Per-domain, never NSAllowsArbitraryLoads. Local-network/IP
+   * hosts are already allowed (`NSAllowsLocalNetworking`). */
+  insecureHosts?: string[];
   pwaDist: string;
   /** Desktop-shell block, consumed by an external desktop host (a module pack) that registers a
    * `'desktop'` platform handler via `runCli({ platforms })`. Carried OPAQUE — nothing here reads
@@ -406,7 +417,7 @@ export function defineConfig(config: AppwrapConfig): AppwrapConfig {
  */
 export const KNOWN_CONFIG_KEYS: ReadonlySet<string> = new Set([
   'androidAppLinks', 'appBoundDomains', 'backendOrigin', 'backgroundAudio', 'backgroundColor', 'backgroundTasks', 'buildNumber', 'ci', 'debug',
-  'debugLog', 'desktop', 'devMenu', 'edgeToEdge', 'entry', 'icon', 'id', 'iosKeyboardExtraLift', 'loader', 'modules', 'modulePacks', 'name',
+  'debugLog', 'desktop', 'devMenu', 'edgeToEdge', 'entry', 'icon', 'id', 'iosHideKeyboardAccessory', 'iosKeyboardExtraLift', 'iosKeyboardWithoutUserAction', 'insecureHosts', 'loader', 'modules', 'modulePacks', 'name',
   'androidLockTextZoom', 'envSwitcher', 'iosEntitlements', 'iosInfoPlist', 'neutralizeServiceWorker', 'oauthRedirectSchemes', 'openNewWindowsInBrowser', 'orientation', 'overrides', 'permissions',
   'plugins', 'push', 'pwaDist', 'queryPackages', 'queryUrlSchemes', 'serverUrl', 'shareTarget', 'signing', 'signingProfiles', 'statusBarStyle', 'store',
   'splashHold', 'splashIcon', 'storekitConfig', 'targetedDevices', 'teamId', 'themeColor', 'trackingDomains', 'urlScheme',

package/src/derive.ts

@@ -261,6 +261,26 @@ export function stampAppBoundDomains(src: string, domains: string[] | undefined)
   return src;
 }
 
+/**
+ * Stamp ATS exceptions for plain-http hosts (config `insecureHosts`) into the template's EXISTING
+ * `NSAppTransportSecurity` dict as `NSExceptionDomains` — each host with IncludesSubdomains +
+ * InsecureHTTPLoads. Scoped per domain on purpose (never NSAllowsArbitraryLoads, an App Review flag).
+ * e.g. `['ts.net']` lets the WebView load `http://box.tailnet.ts.net:7707`. Idempotent both ways:
+ * the marked block is stripped first, so an empty/absent list removes it.
+ */
+export function stampInsecureHosts(src: string, hosts: string[] | undefined): string {
+  src = src.replace(/\s*<!-- appwrap:insecure -->[\s\S]*?<!-- \/appwrap:insecure -->/g, '');
+  const list = (hosts ?? []).map((h) => h.trim().replace(/^\*?\./, '')).filter(Boolean);
+  if (!list.length) return src;
+  const ats = /(<key>NSAppTransportSecurity<\/key>\s*<dict>)/;
+  const entries = list.map((h) =>
+    `\t\t\t<key>${h}</key>\n\t\t\t<dict>\n\t\t\t\t<key>NSIncludesSubdomains</key>\n\t\t\t\t<true/>\n` +
+    `\t\t\t\t<key>NSExceptionAllowsInsecureHTTPLoads</key>\n\t\t\t\t<true/>\n\t\t\t</dict>`).join('\n');
+  const block = `\n\t\t<!-- appwrap:insecure -->\n\t\t<key>NSExceptionDomains</key>\n\t\t<dict>\n${entries}\n\t\t</dict>\n\t\t<!-- /appwrap:insecure -->`;
+  if (ats.test(src)) return src.replace(ats, `$1${block}`);
+  return src.replace(/<\/dict>\s*<\/plist>\s*$/, `\t<key>NSAppTransportSecurity</key>\n\t<dict>${block}\n\t</dict>\n</dict>\n</plist>\n`);
+}
+
 /**
  * Stamp the App Tracking Transparency declarations into PrivacyInfo.xcprivacy. Rewrites the two
  * tracking keys IN PLACE (the template ships them, so we never restructure the doc — we only flip