@livx.cc/appwrap 0.58.0 → 0.58.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.58.0",
+  "version": "0.58.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/capabilities.manifest.ts

@@ -282,10 +282,16 @@ export const MODULES: ModuleManifest[] = [
   // proven cold-start buffering (handshake `deepLink`) + warm `deeplink.open` event with zero new
   // bridge surface. iOS: a generated share-extension TARGET (`AppwrapShare`, from this module's
   // nativeSrc via NS's App_Resources/iOS/extensions seam — same machinery as the widget pack) that
-  // forwards to the host app over `urlScheme` (REQUIRED in config); images cross via the App Group
-  // container (entitlement below, stamped on both targets) and the host shell relocates them into the
-  // app cache so the JS contract is platform-identical. Consume via `kit.shareTarget.onReceive` (or
-  // raw `kit.lifecycle.onDeepLink`).
+  // PERSISTS the payload as the same `<urlScheme>://share?…` URL into an App-Group UserDefaults
+  // MAILBOX (modern iOS blocks share extensions from launching their host via openURL:, so there is
+  // no live hand-off — the extension shows a brief "Added to <App>" confirmation instead); the host
+  // drains the mailbox on cold launch + every resume (read-once) into the same deep-link path. Images
+  // cross via the App Group container (entitlement below, stamped on both targets) and the host shell
+  // relocates them into the app cache so the JS contract is platform-identical. `urlScheme` REQUIRED. Consume via `kit.shareTarget.onReceive` (or
+  // raw `kit.lifecycle.onDeepLink`). OPTIONAL direct sync: config `shareTarget.directSync` lets the
+  // iOS extension complete the share ITSELF (one templated HTTP call, "Syncing… → Synced" drawer
+  // status) using the app-published context KV (`kit.shareTarget.setContext`) — mailbox stays the
+  // fallback on any failure. See ShareDirectSyncConfig in appwrap-cli config.ts.
   {
     name: 'shareTarget', group: 'shareTarget', nativeSrc: 'shareTarget',
     capabilities: { shareTarget: 'native' },

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

@@ -161,6 +161,23 @@ class DevCertNavDelegate extends NSObject implements WKNavigationDelegate {
 }
 
 export class CustomWebView extends WebView {
+  constructor() {
+    super();
+    // The WKWebView must OWN the safe areas for CSS env(safe-area-inset-*) to be non-zero: WebKit
+    // (WKWebViewIOS.mm _computedUnobscuredSafeAreaInset) feeds env() from the WKWebView's OWN UIKit
+    // safeAreaInsets when contentInsetAdjustmentBehavior is .never — which requires the view's frame
+    // to genuinely extend under the status bar / home indicator. NS core's WebView defaults
+    // `iosOverflowSafeArea` to FALSE (only layout containers default true), which routes every layout
+    // pass through IOSHelper.shrinkToSafeArea: whenever the pass runs with the view attached to a
+    // window, the frame is boxed inside the safe area → safeAreaInsets become 0 → env() = 0, and the
+    // wrapped page's own safe-area padding collapses (content behind the notch). Whether the shrink
+    // actually lands is TIMING-dependent (NS's _cachedFrame skips re-adjustment when the frame value
+    // is unchanged), so devices differ. `true` flips NS to its expandBeyondSafeArea path —
+    // deterministic full-bleed frame, real safeAreaInsets, env() populated. Page-level padding then
+    // works with zero per-app configuration. (iOS-only NS property; inert on Android.)
+    this.iosOverflowSafeArea = true;
+  }
+
   /** Set by the bridge before load; receives raw envelope JSON. */
   onAppwrapMessage: ((json: string) => void) | null = null;
   private _scriptHandler!: AppwrapScriptHandler; // retained — WKUserContentController holds it weakly
@@ -363,8 +380,44 @@ export class CustomWebView extends WebView {
     return webView;
   }
 
+  /** Debug diagnostic: snapshot the native safe-area geometry (frame, safeAreaInsets, scroll-view
+   * inset behavior, superview chain) into the page as `window.__appwrapSafeAreaDiag` + the file log.
+   * Support surface for "env(safe-area-inset-*) is 0" reports — separates the UIKit side (view
+   * geometry, this snapshot) from the WebKit side (viewport-fit meta, see NATIVE_FEEL_JS): the field
+   * bug this was built for showed PERFECT native insets while a late page viewport meta without
+   * viewport-fit reverted cover and zeroed env(). Debug builds only. */
+  private snapshotSafeAreaDiag(tag: string): void {
+    const wk = this.nativeViewProtected as WKWebView;
+    if (!wk) return;
+    const r = (x: CGRect) => `${Math.round(x.origin.x)},${Math.round(x.origin.y)},${Math.round(x.size.width)}x${Math.round(x.size.height)}`;
+    const ins = (i: UIEdgeInsets) => `t${i.top} l${i.left} b${i.bottom} r${i.right}`;
+    const chain: string[] = [];
+    let v: UIView | null = wk;
+    while (v) { chain.push(`${NSStringFromClass(v.class())}[${r(v.frame)}]sa(${ins(v.safeAreaInsets)})`); v = v.superview; }
+    const win = wk.window;
+    const diag = {
+      tag,
+      frame: r(wk.frame), bounds: r(wk.bounds),
+      safeAreaInsets: ins(wk.safeAreaInsets),
+      behavior: wk.scrollView.contentInsetAdjustmentBehavior,
+      adjusted: ins(wk.scrollView.adjustedContentInset),
+      contentInset: ins(wk.scrollView.contentInset),
+      inWindow: !!win,
+      windowSA: win ? ins(win.safeAreaInsets) : 'nil',
+      windowFrame: win ? r(win.frame) : 'nil',
+      chain: chain.join(' < '),
+    };
+    const js = `window.__appwrapSafeAreaDiag=${JSON.stringify(JSON.stringify(diag))};`;
+    wk.evaluateJavaScriptCompletionHandler(js, () => { /* fire-and-forget */ });
+    appendWebLog(`[native:sa-diag] ${JSON.stringify(diag)}`);
+  }
+
   initNativeView(): void {
     super.initNativeView();
+    // Debug builds: delayed safe-area snapshots after the view settles in-window (see method doc).
+    if (SHELL_CONFIG.debug) {
+      for (const ms of [1500, 4000, 8000]) setTimeout(() => this.snapshotSafeAreaDiag(`t+${ms}`), ms);
+    }
     // NativeScript's WebView assigns its own wkWebView.UIDelegate during init,
     // which clobbers the media-capture grant set in createNativeView — so WebKit
     // falls back to prompting on every getUserMedia call. Reassert ours last so

package/runtime/app/shell/handlers-share-target.ts

@@ -1,7 +1,14 @@
 import { Application, Utils, isAndroid, isIOS } from '@nativescript/core';
 import type { AndroidActivityNewIntentEventData } from '@nativescript/core';
 import { SHELL_CONFIG } from './config';
+import { bridge } from './bridge';
 import { onDeepLink, setDeepLinkTransformer } from './events';
+import { MAILBOX_KEY, drainShareMailbox, type ShareMailboxStore } from './share-mailbox';
+
+/** App Group UserDefaults key holding the app-published SHARE CONTEXT (JSON string KV). Written by
+ * `shareTarget.setContext`, read by the AppwrapShare extension to resolve direct-sync `{key}`
+ * template placeholders. Must match ShareViewController.swift. */
+const CONTEXT_KEY = 'appwrap-share-context';
 
 /**
  * shareTarget (INBOUND share sheet) — Android. The manifest's ACTION_SEND(_MULTIPLE) intent-filter
@@ -17,17 +24,37 @@ import { onDeepLink, setDeepLinkTransformer } from './events';
  *  - `file`  — repeated; each is a path RELATIVE TO THE APP CACHE DIR (`appwrap-share/…`) where the
  *    shared stream (image) was copied — read it via `kit.fs.read(p, { dir: 'cache', encoding: 'base64' })`.
  *
- * iOS: the generated `AppwrapShare` extension (this module's nativeSrc) forwards the payload as the
- * SAME URL over the app's urlScheme — that link enters through the normal openURL delegate path. Text
- * rides in the URL directly; images land in the App Group container as `gfile=<name>` params, which
- * the transformer below relocates into the app cache and rewrites to `file=` (cache-relative) so the
- * contract the web app sees is platform-identical.
+ * iOS: the generated `AppwrapShare` extension (this module's nativeSrc) PERSISTS the payload as the
+ * SAME URL into an App-Group "mailbox" (UserDefaults key `appwrap-share-mailbox`, a string array) —
+ * modern iOS silently blocks a share extension from launching its host via `openURL:`, so there is
+ * no live hand-off; the host drains the mailbox on cold launch and on every foreground/resume
+ * (read-once) and feeds each URL through the normal deep-link path (cold: buffered into the
+ * handshake `deepLink`; warm: `deeplink.open` event). Text rides in the URL directly; images land in
+ * the App Group container as `gfile=<name>` params, which the transformer below relocates into the
+ * app cache and rewrites to `file=` (cache-relative) so the contract the web app sees is
+ * platform-identical.
  */
 export function registerShareTargetHandlers(): void {
+  // Share-context KV (kit.shareTarget.setContext) — generic, app-opaque. Only iOS persists it (the
+  // AppwrapShare extension is the sole consumer); Android accepts + ignores so a cross-platform web
+  // app can call it unconditionally without an UNSUPPORTED rejection.
+  bridge.register('shareTarget.setContext', ({ context }: { context?: Record<string, string | number> | null }) => {
+    if (!isIOS) return;
+    const d = NSUserDefaults.alloc().initWithSuiteName(`group.${SHELL_CONFIG.appId}`);
+    if (!d) return;
+    if (context && typeof context === 'object') d.setObjectForKey(JSON.stringify(context), CONTEXT_KEY);
+    else d.removeObjectForKey(CONTEXT_KEY);
+  });
   if (isIOS) {
     // Rewrite share links carrying App-Group files (gfile=) → cache files (file=). Text-only share
     // links (no gfile) pass through untouched.
     setDeepLinkTransformer((url) => (url.includes('://share?') && url.includes('gfile=') ? iosRelocateGroupFiles(url) : url));
+    const drain = () => {
+      try { drainShareMailbox(iosMailboxStore(), onDeepLink); }
+      catch (e) { console.warn('AppWrap: share mailbox drain failed', e); }
+    };
+    drain(); // cold launch — a share made while the app was killed is waiting in the mailbox
+    Application.on(Application.resumeEvent, drain); // warm — user shared, then switched back to the app
     return;
   }
   if (!isAndroid) return;
@@ -38,6 +65,23 @@ export function registerShareTargetHandlers(): void {
   deliverShareIntent(Application.android.startActivity?.getIntent?.());
 }
 
+// ── iOS App-Group mailbox (written by the AppwrapShare extension, drained by the host) ──
+// Drain semantics (read-once, crash-safe) are PURE and live in share-mailbox.ts (bun-tested).
+
+/** The real iOS store: `group.<appId>` suite UserDefaults, string-array under MAILBOX_KEY. */
+function iosMailboxStore(): ShareMailboxStore {
+  const defaults = NSUserDefaults.alloc().initWithSuiteName(`group.${SHELL_CONFIG.appId}`);
+  return {
+    read: () => {
+      const arr = defaults?.arrayForKey(MAILBOX_KEY);
+      const out: string[] = [];
+      for (let i = 0; arr && i < arr.count; i++) out.push(String(arr.objectAtIndex(i)));
+      return out;
+    },
+    clear: () => { defaults?.removeObjectForKey(MAILBOX_KEY); },
+  };
+}
+
 /** iOS: move each `gfile=<name>` from `<AppGroup>/appwrap-share/` into `<Caches>/appwrap-share/` and
  * rewrite the param to `file=appwrap-share/<name>` (the fs `cache` root), matching Android's shape.
  * Any file that can't be moved (missing group container, purged file) is dropped from the link;

package/runtime/app/shell/share-mailbox.ts

@@ -0,0 +1,40 @@
+/**
+ * PURE iOS shareTarget mailbox-drain logic (no NativeScript imports; bun-tested — mirrors
+ * geo-auth.ts/notif-identity.ts: the semantics live here, handlers-share-target.ts only does the
+ * NSUserDefaults plumbing).
+ *
+ * WHY a mailbox: modern iOS silently blocks a share extension's responder-chain `openURL:` — a share
+ * extension may NOT launch its host app. So the generated `AppwrapShare` extension durably appends
+ * the share URL (`<scheme>://share?…`) to an App-Group UserDefaults string array under MAILBOX_KEY,
+ * and the HOST drains it on cold launch and on every foreground/resume. Read-once: the drain clears
+ * the mailbox BEFORE delivering, so overlapping drains can never double-deliver; crash-safety: the
+ * extension's write persists until a drain actually runs, and one runs on every foreground.
+ */
+
+/** App-Group UserDefaults key the extension appends to (see ShareViewController.swift). */
+export const MAILBOX_KEY = 'appwrap-share-mailbox';
+
+/** Minimal seam over the App-Group UserDefaults mailbox — injectable for tests. */
+export interface ShareMailboxStore {
+  read(): string[];
+  clear(): void;
+}
+
+/**
+ * Drain the share mailbox: read all pending share URLs, CLEAR first (exactly-once), then deliver
+ * each through `deliver` (the normal deep-link ingress: cold launches buffer into the handshake
+ * `deepLink`, warm apps get `deeplink.open`). Non-share/garbage entries are dropped. Returns the
+ * number of URLs delivered.
+ */
+export function drainShareMailbox(store: ShareMailboxStore, deliver: (url: string) => void): number {
+  const urls = store.read();
+  if (!urls.length) return 0;
+  store.clear(); // read-once: clear BEFORE delivering so re-entry during delivery can't duplicate
+  let delivered = 0;
+  for (const u of urls) {
+    if (typeof u !== 'string' || !u.includes('://share?')) continue;
+    delivered++;
+    deliver(u);
+  }
+  return delivered;
+}

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

@@ -296,14 +296,21 @@ export const NATIVE_FEEL_JS = `(function(){
   window.__appwrapNativeFeel = true;
   function apply(){
     var head = document.head || document.documentElement;
-    var vp = document.querySelector('meta[name=viewport]');
+    // Normalize the LAST viewport meta — WebKit honors the last one parsed, so patching the first
+    // (or an injected one) is silently overridden when the page's own meta appears later in <head>.
+    // Device-verified failure: injected meta had viewport-fit=cover, the site's own plain
+    // "width=device-width, initial-scale=1.0" meta parsed after it → viewport-fit reverted to auto
+    // → env(safe-area-inset-*) = 0 despite correct native safeAreaInsets (t47/b34).
+    var metas = document.querySelectorAll('meta[name=viewport]');
+    var vp = metas.length ? metas[metas.length - 1] : null;
     if (!vp){ vp = document.createElement('meta'); vp.setAttribute('name','viewport'); head.appendChild(vp); }
     var c = vp.getAttribute('content') || 'width=device-width, initial-scale=1';
     if (!/user-scalable\\s*=\\s*no/.test(c)) c += ', maximum-scale=1, user-scalable=no';
     // viewport-fit=cover makes env(safe-area-inset-*) resolve to real notch /
     // home-indicator insets — the WebView owns the safe areas (contentInset .never).
+    // A page's own explicit viewport-fit is respected (only appended when absent).
     if (!/viewport-fit/.test(c)) c += ', viewport-fit=cover';
-    vp.setAttribute('content', c);
+    if (vp.getAttribute('content') !== c) vp.setAttribute('content', c);
     if (!document.getElementById('__appwrap_feel')){
       var s = document.createElement('style'); s.id = '__appwrap_feel';
       s.textContent = ${JSON.stringify(NATIVE_FEEL_CSS)};
@@ -322,6 +329,22 @@ export const NATIVE_FEEL_JS = `(function(){
   }
   apply();
   if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', apply);
+  // SPA head managers (React Helmet, Next, vue-meta) add/rewrite the viewport meta AFTER load —
+  // re-normalize whenever one changes. apply() is idempotent (only writes on an actual content
+  // change), so the observer can't loop on its own writes.
+  try {
+    new MutationObserver(function(muts){
+      for (var i = 0; i < muts.length; i++){
+        var m = muts[i];
+        var t = m.target;
+        if (t && t.nodeName === 'META' && t.getAttribute('name') === 'viewport') return apply();
+        for (var j = 0; j < (m.addedNodes ? m.addedNodes.length : 0); j++){
+          var n = m.addedNodes[j];
+          if (n.nodeName === 'META' && n.getAttribute && n.getAttribute('name') === 'viewport') return apply();
+        }
+      }
+    }).observe(document.documentElement, { childList: true, subtree: true, attributes: true, attributeFilter: ['content', 'name'] });
+  } catch(e) { /* observer is a hardening layer; core apply() already ran */ }
   // Pinch-zoom on iOS fires gesture* even with user-scalable=no in some builds.
   document.addEventListener('gesturestart', function(e){ e.preventDefault(); }, { passive: false });
 })();`;

package/runtime/modules-native/shareTarget/App_Resources/iOS/extensions/AppwrapShare/ShareViewController.swift

@@ -3,45 +3,67 @@ import MobileCoreServices
 
 /// appwrap shareTarget — iOS share extension (`AppwrapShare` target, generated per-app by the CLI).
 ///
-/// Collects the shared attachments (text / web URL / images), then forwards them to the HOST app as
-/// the SAME deep-link contract Android uses:
-///   __URL_SCHEME__://share?text=<enc>&title=<enc>&gfile=<enc>&gfile=<enc>…
-///  - text / web URLs ride entirely in the URL (no files involved).
-///  - images are written into the shared App Group container under `appwrap-share/`; each `gfile`
-///    param is the file NAME there. The host shell relocates them into the app cache and rewrites
-///    `gfile=` → `file=` (cache-relative) before the link reaches the web app — so the JS contract
-///    is identical on both platforms (see runtime/app/shell/handlers-share-target.ts).
+/// Collects the shared attachments (text / web URL / images), then delivers them one of two ways:
+///
+/// 1. DIRECT SYNC (opt-in via config `shareTarget.directSync`, stamped as `__SHARE_SYNC_B64__` —
+///    base64 JSON, empty = off): the extension completes the share ITSELF with one HTTP call to the
+///    app's backend, showing an honest "Syncing… → Synced" status in the drawer. `{key}` placeholders
+///    in the URL / success-message templates resolve from the SHARE CONTEXT — a small JSON KV the
+///    web app published via `kit.shareTarget.setContext(...)` (App Group UserDefaults key
+///    `appwrap-share-context`). `merge:"append"` GETs the resource first, appends the shared text to
+///    the existing text field (newline-joined) and preserves the existing image unless a new one is
+///    shared. Any failure — offline, non-2xx, missing/unresolvable context, >1 image, oversized
+///    image — falls back to (2). Apple forbids a share extension launching its host app; direct sync
+///    makes launching unnecessary.
+///
+/// 2. MAILBOX (always available, the pre-direct-sync behavior): PERSIST the payload as a mailbox
+///    entry in the shared App Group UserDefaults — the SAME deep-link contract Android uses:
+///      __URL_SCHEME__://share?text=<enc>&title=<enc>&gfile=<enc>&gfile=<enc>…
+///    - text / web URLs ride entirely in the URL (no files involved).
+///    - images are written into the shared App Group container under `appwrap-share/`; each `gfile`
+///      param is the file NAME there. The host shell relocates them into the app cache and rewrites
+///      `gfile=` → `file=` (cache-relative) before the link reaches the web app — so the JS contract
+///      is identical on both platforms (see runtime/app/shell/handlers-share-target.ts).
+///    The host drains the mailbox (App Group key `appwrap-share-mailbox`, an appended string array)
+///    on cold launch AND on every foreground/resume (read-once).
 ///
 /// Build-time tokens (stamped by `appwrap init`/`sync`): __URL_SCHEME__ (config `urlScheme`),
-/// __APP_GROUP__ (`group.<appId>`), __APP_NAME__ (Info.plist display name).
+/// __APP_GROUP__ (`group.<appId>`), __APP_NAME__ (Info.plist display name), __SHARE_SYNC_B64__
+/// (config `shareTarget.directSync`, defaults applied — see appwrap-cli config.ts).
 class ShareViewController: UIViewController {
     private var processed = false
+    private var statusPill: UILabel?
 
     override func viewDidAppear(_ animated: Bool) {
         super.viewDidAppear(animated)
         guard !processed else { return }
         processed = true
-        collectPayload { [weak self] params in
+        collectPayload { [weak self] texts, files in
             guard let self = self else { return }
-            if params.isEmpty {
+            if texts.isEmpty && files.isEmpty {
                 self.extensionContext?.completeRequest(returningItems: nil, completionHandler: nil)
                 return
             }
-            let url = URL(string: "__URL_SCHEME__://share?" + params.joined(separator: "&"))
-            if let url = url { self.openHostApp(url) }
-            // Give the openURL hand-off a beat before the extension process is torn down.
-            DispatchQueue.main.asyncAfter(deadline: .now() + 0.4) {
-                self.extensionContext?.completeRequest(returningItems: nil, completionHandler: nil)
+            if let sync = self.directSyncPlan(texts: texts, files: files) {
+                self.showStatus("Syncing…")
+                self.runDirectSync(sync, texts: texts, files: files)
+            } else {
+                self.finishViaMailbox(texts: texts, files: files)
             }
         }
     }
 
     // MARK: payload collection
 
-    private func collectPayload(_ done: @escaping ([String]) -> Void) {
+    /// Collect shared text/URLs (`texts`) and image file NAMES (`files`, already stashed into the
+    /// App Group `appwrap-share/` dir — both delivery paths read them from there).
+    private func collectPayload(_ done: @escaping ([String], [String]) -> Void) {
         var texts: [String] = []
         var files: [String] = []
         let group = DispatchGroup()
+        // loadItem completions fire on provider-internal queues — serialize array mutation
+        // (concurrent appends on a Swift Array are UB with multi-attachment shares).
+        let collectQ = DispatchQueue(label: "appwrap.share.collect")
 
         let items = (extensionContext?.inputItems as? [NSExtensionItem]) ?? []
         for item in items {
@@ -49,33 +71,34 @@ class ShareViewController: UIViewController {
                 if provider.hasItemConformingToTypeIdentifier("public.url") && !provider.hasItemConformingToTypeIdentifier("public.file-url") {
                     group.enter()
                     provider.loadItem(forTypeIdentifier: "public.url", options: nil) { data, _ in
-                        if let u = data as? URL { texts.append(u.absoluteString) }
-                        group.leave()
+                        collectQ.async {
+                            if let u = data as? URL { texts.append(u.absoluteString) }
+                            group.leave()
+                        }
                     }
                 } else if provider.hasItemConformingToTypeIdentifier("public.plain-text") {
                     group.enter()
                     provider.loadItem(forTypeIdentifier: "public.plain-text", options: nil) { data, _ in
-                        if let s = data as? String, !s.isEmpty { texts.append(s) }
-                        else if let d = data as? Data, let s = String(data: d, encoding: .utf8), !s.isEmpty { texts.append(s) }
-                        group.leave()
+                        collectQ.async {
+                            if let s = data as? String, !s.isEmpty { texts.append(s) }
+                            else if let d = data as? Data, let s = String(data: d, encoding: .utf8), !s.isEmpty { texts.append(s) }
+                            group.leave()
+                        }
                     }
                 } else if provider.hasItemConformingToTypeIdentifier("public.image") {
                     group.enter()
                     provider.loadItem(forTypeIdentifier: "public.image", options: nil) { data, _ in
-                        if let name = self.stashImage(data) { files.append(name) }
-                        group.leave()
+                        let name = self.stashImage(data) // heavy I/O stays off the serial queue
+                        collectQ.async {
+                            if let name { files.append(name) }
+                            group.leave()
+                        }
                     }
                 }
             }
         }
 
-        group.notify(queue: .main) {
-            var params: [String] = []
-            let enc = { (s: String) in s.addingPercentEncoding(withAllowedCharacters: .alphanumerics) ?? "" }
-            if !texts.isEmpty { params.append("text=" + enc(texts.joined(separator: "\n"))) }
-            for f in files { params.append("gfile=" + enc(f)) }
-            done(params)
-        }
+        group.notify(queue: .main) { done(texts, files) }
     }
 
     /// Write a shared image (URL / Data / UIImage, whatever the provider hands over) into the App
@@ -106,19 +129,210 @@ class ShareViewController: UIViewController {
         return nil
     }
 
-    // MARK: host-app hand-off
+    private func groupFileURL(_ name: String) -> URL? {
+        FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: "__APP_GROUP__")?
+            .appendingPathComponent("appwrap-share", isDirectory: true).appendingPathComponent(name)
+    }
+
+    // MARK: direct sync (config `shareTarget.directSync` — stamped, empty token = off)
 
-    /// An app extension has no UIApplication.shared — the established path is walking the responder
-    /// chain to the hosting app's UIApplication and performing `openURL:` on it.
-    private func openHostApp(_ url: URL) {
-        var responder: UIResponder? = self as UIResponder
-        let selector = NSSelectorFromString("openURL:")
-        while let r = responder {
-            if r.responds(to: selector) && !(r is UIViewController) {
-                r.perform(selector, with: url)
-                return
+    private struct SyncPlan {
+        let url: URL
+        let method: String
+        let textField: String
+        let imageField: String
+        let append: Bool
+        let imageDataURL: String?  // nil = no image shared
+        let imageFile: String?     // stashed name, deleted after a successful sync
+        let successText: String
+    }
+
+    /// Decide whether THIS share can direct-sync: config stamped, context published, url template
+    /// fully resolved, ≤1 image, image under the size cap. nil → mailbox path.
+    private func directSyncPlan(texts: [String], files: [String]) -> SyncPlan? {
+        let b64 = "__SHARE_SYNC_B64__"
+        guard !b64.isEmpty,
+              let cfgData = Data(base64Encoded: b64),
+              let cfg = (try? JSONSerialization.jsonObject(with: cfgData)) as? [String: Any],
+              let urlTemplate = cfg["urlTemplate"] as? String,
+              let ctx = shareContext(),
+              let urlStr = resolveTemplate(urlTemplate, ctx), let url = URL(string: urlStr)
+        else { return nil }
+        guard files.count <= 1 else { return nil } // multi-image shares keep full fidelity via the mailbox
+
+        let fields = cfg["fields"] as? [String: Any]
+        let maxImageBytes = (cfg["maxImageBytes"] as? Int) ?? 4_000_000
+        var imageDataURL: String? = nil
+        if let name = files.first {
+            guard let fileURL = groupFileURL(name), let data = try? Data(contentsOf: fileURL) else { return nil }
+            var encoded = "data:\(sniffMime(data));base64,\(data.base64EncodedString())"
+            if encoded.utf8.count > maxImageBytes {
+                // Typical camera photos exceed the cap — mirror the web app's pipeline: downscale
+                // (longest edge → maxImageEdge, JPEG jpegQuality) before giving up. Only a still-over
+                // (or undecodable) image sends the share down the mailbox, which keeps the ORIGINAL
+                // bytes (the app downscales on drain, unchanged).
+                let edge = CGFloat((cfg["maxImageEdge"] as? Double) ?? 2000)
+                let quality = CGFloat((cfg["jpegQuality"] as? Double) ?? 0.85)
+                guard let small = downscaled(data, maxEdge: edge, quality: quality) else { return nil }
+                encoded = "data:image/jpeg;base64,\(small.base64EncodedString())"
+                guard encoded.utf8.count <= maxImageBytes else { return nil } // still oversized → mailbox
             }
-            responder = r.next
+            imageDataURL = encoded
         }
+        let successTemplate = (cfg["successMessage"] as? String) ?? "Synced"
+        return SyncPlan(
+            url: url,
+            method: (cfg["method"] as? String) ?? "PUT",
+            textField: (fields?["text"] as? String) ?? "content",
+            imageField: (fields?["image"] as? String) ?? "image",
+            append: (cfg["merge"] as? String) == "append",
+            imageDataURL: imageDataURL,
+            imageFile: files.first,
+            successText: resolveTemplate(successTemplate, ctx) ?? "Synced"
+        )
+    }
+
+    /// The app-published share context (App Group key `appwrap-share-context`, JSON KV). Numbers are
+    /// stringified so templates can interpolate them.
+    private func shareContext() -> [String: String]? {
+        guard let d = UserDefaults(suiteName: "__APP_GROUP__"),
+              let raw = d.string(forKey: "appwrap-share-context"),
+              let obj = (try? JSONSerialization.jsonObject(with: Data(raw.utf8))) as? [String: Any]
+        else { return nil }
+        var out: [String: String] = [:]
+        for (k, v) in obj { out[k] = "\(v)" }
+        return out
+    }
+
+    /// Replace `{key}` placeholders from the context. nil when any placeholder stays unresolved —
+    /// a partially-resolved URL must never be called.
+    private func resolveTemplate(_ template: String, _ ctx: [String: String]) -> String? {
+        var s = template
+        for (k, v) in ctx { s = s.replacingOccurrences(of: "{\(k)}", with: v) }
+        return s.range(of: #"\{[^}]+\}"#, options: .regularExpression) == nil ? s : nil
+    }
+
+    /// Re-render an oversized image to `maxEdge` px longest edge, JPEG at `quality`. nil on decode
+    /// failure (e.g. non-image bytes) — the caller falls back to the mailbox.
+    private func downscaled(_ data: Data, maxEdge: CGFloat, quality: CGFloat) -> Data? {
+        guard let img = UIImage(data: data), img.size.width > 0, img.size.height > 0 else { return nil }
+        let w = img.size.width * img.scale, h = img.size.height * img.scale
+        let scale = min(1, maxEdge / max(w, h))
+        let size = CGSize(width: max(1, floor(w * scale)), height: max(1, floor(h * scale)))
+        let fmt = UIGraphicsImageRendererFormat.default()
+        fmt.scale = 1
+        let out = UIGraphicsImageRenderer(size: size, format: fmt).image { _ in
+            img.draw(in: CGRect(origin: .zero, size: size))
+        }
+        return out.jpegData(compressionQuality: quality)
+    }
+
+    private func sniffMime(_ d: Data) -> String {
+        if d.starts(with: [0x89, 0x50, 0x4E, 0x47]) { return "image/png" }
+        if d.starts(with: [0xFF, 0xD8]) { return "image/jpeg" }
+        if d.starts(with: [0x47, 0x49, 0x46]) { return "image/gif" }
+        if d.count > 11, d[8...11].elementsEqual([0x57, 0x45, 0x42, 0x50]) { return "image/webp" }
+        return "image/jpeg" // best-effort default (e.g. HEIC handed over re-encoded)
+    }
+
+    /// Execute the sync: (append mode) GET current → merge → write; else write as-is. Any failure
+    /// falls back to the mailbox — the share is never lost.
+    private func runDirectSync(_ plan: SyncPlan, texts: [String], files: [String]) {
+        let fallback: () -> Void = { [weak self] in self?.finishViaMailbox(texts: texts, files: files) }
+        let newText = texts.joined(separator: "\n")
+
+        let write: ([String: Any]) -> Void = { [weak self] existing in
+            guard let self = self else { return }
+            let oldText = (existing[plan.textField] as? String) ?? ""
+            let merged = plan.append && !oldText.isEmpty && !newText.isEmpty ? "\(oldText)\n\(newText)"
+                : (newText.isEmpty ? oldText : newText)
+            var body: [String: Any] = [plan.textField: merged]
+            // New image replaces; append mode preserves the existing one (the endpoint is a full PUT).
+            if let img = plan.imageDataURL { body[plan.imageField] = img }
+            else if plan.append, let old = existing[plan.imageField] { body[plan.imageField] = old }
+            else { body[plan.imageField] = NSNull() }
+            var req = URLRequest(url: plan.url, timeoutInterval: 15)
+            req.httpMethod = plan.method
+            req.setValue("application/json", forHTTPHeaderField: "Content-Type")
+            req.httpBody = try? JSONSerialization.data(withJSONObject: body)
+            URLSession.shared.dataTask(with: req) { _, resp, _ in
+                DispatchQueue.main.async {
+                    guard let code = (resp as? HTTPURLResponse)?.statusCode, (200..<300).contains(code) else { fallback(); return }
+                    if let name = plan.imageFile, let u = self.groupFileURL(name) { try? FileManager.default.removeItem(at: u) }
+                    self.finish(status: "✓ \(plan.successText)")
+                }
+            }.resume()
+        }
+
+        if plan.append {
+            var req = URLRequest(url: plan.url, timeoutInterval: 15)
+            req.httpMethod = "GET"
+            URLSession.shared.dataTask(with: req) { data, resp, _ in
+                DispatchQueue.main.async {
+                    guard let code = (resp as? HTTPURLResponse)?.statusCode else { fallback(); return } // offline
+                    if code == 404 { write([:]); return } // nothing there yet — first write
+                    guard (200..<300).contains(code) else { fallback(); return }
+                    let existing = data.flatMap { (try? JSONSerialization.jsonObject(with: $0)) as? [String: Any] } ?? [:]
+                    write(existing)
+                }
+            }.resume()
+        } else {
+            write([:])
+        }
+    }
+
+    // MARK: host-app hand-off (App-Group mailbox)
+
+    private func finishViaMailbox(texts: [String], files: [String]) {
+        var params: [String] = []
+        let enc = { (s: String) in s.addingPercentEncoding(withAllowedCharacters: .alphanumerics) ?? "" }
+        if !texts.isEmpty { params.append("text=" + enc(texts.joined(separator: "\n"))) }
+        for f in files { params.append("gfile=" + enc(f)) }
+        enqueueMailbox("__URL_SCHEME__://share?" + params.joined(separator: "&"))
+        finish(status: "Added to __APP_NAME__")
+    }
+
+    /// Durably append the share URL to the App Group mailbox. The host app drains this key
+    /// (read-once) on cold launch and on every foreground — see handlers-share-target.ts.
+    private func enqueueMailbox(_ url: String) {
+        guard let d = UserDefaults(suiteName: "__APP_GROUP__") else { return }
+        var box = d.stringArray(forKey: "appwrap-share-mailbox") ?? []
+        box.append(url)
+        d.set(box, forKey: "appwrap-share-mailbox")
+        d.synchronize() // the extension process dies moments later — force the write to disk
+    }
+
+    /// Show the final status, let it register visually, then complete the request.
+    private func finish(status: String) {
+        showStatus(status)
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.9) {
+            self.extensionContext?.completeRequest(returningItems: nil, completionHandler: nil)
+        }
+    }
+
+    // MARK: drawer status pill
+
+    /// Centered status pill ("Syncing…" / "✓ Synced…" / "Added to <AppName>") so the share never
+    /// feels like a silent dismiss — the host app is NOT launched (iOS forbids that from a share
+    /// extension). Reused across status changes.
+    private func showStatus(_ text: String) {
+        if let pill = statusPill { pill.text = "  \(text)  "; return }
+        let pill = UILabel()
+        pill.text = "  \(text)  "
+        pill.font = UIFont.preferredFont(forTextStyle: .subheadline)
+        pill.textColor = .white
+        pill.backgroundColor = UIColor.black.withAlphaComponent(0.8)
+        pill.layer.cornerRadius = 18
+        pill.clipsToBounds = true
+        pill.translatesAutoresizingMaskIntoConstraints = false
+        view.addSubview(pill)
+        NSLayoutConstraint.activate([
+            pill.centerXAnchor.constraint(equalTo: view.centerXAnchor),
+            pill.centerYAnchor.constraint(equalTo: view.centerYAnchor),
+            pill.heightAnchor.constraint(equalToConstant: 36),
+        ])
+        pill.alpha = 0
+        UIView.animate(withDuration: 0.15) { pill.alpha = 1 }
+        statusPill = pill
     }
 }

package/runtime/tests/ios-safe-area.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Static invariants for iOS safe-area / env(safe-area-inset-*) support.
+ *
+ * The iOS shell source can't be imported here (it references WKWebView/UIKit globals at module
+ * scope), so these are SOURCE-LEVEL assertions of the three conditions WebKit requires for a
+ * wrapped page's `env(safe-area-inset-*)` to be non-zero:
+ *   1. the WKWebView frame extends under the bars (NS `iosOverflowSafeArea = true` — default is
+ *      false, which routes layout through shrinkToSafeArea and zeroes the view's safeAreaInsets),
+ *   2. `scrollView.contentInsetAdjustmentBehavior = .never` (2) — otherwise WebKit consumes the
+ *      insets as contentInset instead of exposing them to CSS,
+ *   3. the injected viewport meta keeps/adds `viewport-fit=cover` (never strips the page's own).
+ * Field bug this pins: loader:'server' app on a notch device rendered under the status bar with
+ * env() = 0, so the site's own (correct) safe-area padding collapsed.
+ */
+const shellDir = join(import.meta.dir, '..', 'app', 'shell');
+const iosSrc = readFileSync(join(shellDir, 'custom-webview.ios.ts'), 'utf8');
+
+describe('iOS WKWebView exposes real safe-area insets to page CSS', () => {
+  test('CustomWebView opts into NS full-bleed layout (iosOverflowSafeArea)', () => {
+    expect(iosSrc).toMatch(/this\.iosOverflowSafeArea\s*=\s*true/);
+  });
+
+  test('scrollView contentInsetAdjustmentBehavior is .never', () => {
+    expect(iosSrc).toMatch(/scrollView\.contentInsetAdjustmentBehavior\s*=\s*2/);
+  });
+
+  test('injected viewport meta preserves/adds viewport-fit=cover', async () => {
+    const { NATIVE_FEEL_JS } = await import('../app/shell/web-quirks');
+    // Adds cover only when the page's meta doesn't already declare a viewport-fit (never overrides).
+    expect(NATIVE_FEEL_JS).toContain("if (!/viewport-fit/.test(c)) c += ', viewport-fit=cover'");
+    // WebKit honors the LAST viewport meta — normalizing the first (or an injected one) is silently
+    // reverted by a page's own later meta (device-verified: env() stayed 0 with perfect native insets).
+    expect(NATIVE_FEEL_JS).toContain('metas[metas.length - 1]');
+    // SPA head managers rewrite the meta after load — the observer re-normalizes.
+    expect(NATIVE_FEEL_JS).toContain('MutationObserver');
+  });
+});

package/runtime/tests/share-mailbox.test.ts

@@ -0,0 +1,78 @@
+/**
+ * iOS shareTarget App-Group mailbox — the durable extension→host hand-off (modern iOS blocks a share
+ * extension from launching its host via `openURL:`, so payloads are persisted and DRAINED by the host
+ * on cold launch + every resume). Contract under test: exactly-once delivery (clear-before-deliver),
+ * crash-safety (nothing lost while no drain ran), cold→resume sequencing, and garbage filtering.
+ */
+import { describe, expect, test } from 'bun:test';
+import { drainShareMailbox } from '../app/shell/share-mailbox';
+
+/** In-memory stand-in for the App-Group UserDefaults mailbox the extension appends to. */
+function fakeStore(initial: string[] = []) {
+  let box = [...initial];
+  return {
+    box: () => box,
+    push: (u: string) => box.push(u), // what ShareViewController.enqueueMailbox does
+    store: {
+      read: () => [...box],
+      clear: () => { box = []; },
+    },
+  };
+}
+
+describe('drainShareMailbox — exactly-once, crash-safe delivery', () => {
+  test('cold launch: delivers every pending share URL in order, then the mailbox is empty (read-once)', () => {
+    const { store, box } = fakeStore(['app://share?text=a', 'app://share?text=b']);
+    const got: string[] = [];
+    expect(drainShareMailbox(store, (u) => got.push(u))).toBe(2);
+    expect(got).toEqual(['app://share?text=a', 'app://share?text=b']);
+    expect(box()).toEqual([]);
+    // A second drain right after (e.g. resumeEvent firing just after the cold-launch drain) delivers NOTHING.
+    expect(drainShareMailbox(store, (u) => got.push(u))).toBe(0);
+    expect(got).toHaveLength(2);
+  });
+
+  test('resume: a share enqueued while backgrounded is picked up by the next foreground drain, once', () => {
+    const { store, push } = fakeStore();
+    const got: string[] = [];
+    expect(drainShareMailbox(store, (u) => got.push(u))).toBe(0); // cold launch, nothing shared yet
+    push('app://share?text=warm&gfile=pic.png'); // extension writes while app is backgrounded
+    expect(drainShareMailbox(store, (u) => got.push(u))).toBe(1); // foreground → resume drain
+    expect(drainShareMailbox(store, (u) => got.push(u))).toBe(0); // next resume: already consumed
+    expect(got).toEqual(['app://share?text=warm&gfile=pic.png']);
+  });
+
+  test('clears BEFORE delivering — a re-entrant drain during delivery cannot double-deliver', () => {
+    const { store } = fakeStore(['app://share?text=x']);
+    const got: string[] = [];
+    drainShareMailbox(store, (u) => {
+      got.push(u);
+      drainShareMailbox(store, (u2) => got.push(u2)); // overlapping drain mid-delivery
+    });
+    expect(got).toEqual(['app://share?text=x']);
+  });
+
+  test('crash-safety: an entry written by the extension persists until a drain actually runs', () => {
+    const { store, box } = fakeStore(['app://share?text=kept']);
+    // Host crashed (or was never opened) after the extension wrote — nothing consumed the store.
+    expect(box()).toEqual(['app://share?text=kept']); // still there on the next launch/foreground
+    const got: string[] = [];
+    drainShareMailbox(store, (u) => got.push(u));
+    expect(got).toEqual(['app://share?text=kept']);
+  });
+
+  test('non-share / garbage entries are dropped but still cleared', () => {
+    const { store, box } = fakeStore(['not a url', 'app://other?x=1', 'app://share?text=ok']);
+    const got: string[] = [];
+    expect(drainShareMailbox(store, (u) => got.push(u))).toBe(1);
+    expect(got).toEqual(['app://share?text=ok']);
+    expect(box()).toEqual([]);
+  });
+
+  test('empty mailbox: no clear, no delivery', () => {
+    let cleared = false;
+    const n = drainShareMailbox({ read: () => [], clear: () => { cleared = true; } }, () => { throw new Error('must not deliver'); });
+    expect(n).toBe(0);
+    expect(cleared).toBe(false);
+  });
+});

package/src/cli.ts

@@ -22,7 +22,7 @@ import type * as CapManifest from '../../../runtime/app/shell/capabilities.manif
 // Config shape lives in its own import-safe module so a `appwrap.config.ts` file can import the
 // type + `defineConfig` helper without pulling in (and running) the CLI dispatch.
 import type { AppwrapConfig } from './config';
-import { unknownConfigKeys } from './config';
+import { encodeShareDirectSync, unknownConfigKeys } from './config';
 import { resolveModulePacks, type ResolvedModule, type SyncContext } from './packs';
 import { createHash } from 'crypto';
 // Icon helpers re-exported so the EE desktop lane (which owns the Tauri chassis) can reuse them via
@@ -671,9 +671,16 @@ function copyModuleNativeSrc(outDir: string, req: NativeReqs): Set<string> {
  * config so a module ships app-agnostic and the CLI stamps the app-specific value in. Not module-
  * specific: any module (built-in or pack) can use these tokens. `__APP_GROUP__` → the App Group id
  * shared by the app + an extension (e.g. widget, shareTarget); `__URL_SCHEME__` → config `urlScheme`
- * (the shareTarget extension forwards to the host app through it); `__APP_NAME__` → display name. */
+ * (the shareTarget extension forwards to the host app through it); `__APP_NAME__` → display name;
+ * `__SHARE_SYNC_B64__` → base64(JSON) of `shareTarget.directSync` with defaults applied (empty =
+ * direct sync off — base64 so arbitrary config JSON is safe inside a Swift string literal). */
 function buildTokens(cfg: AppwrapConfig): Record<string, string> {
-  return { __APP_GROUP__: `group.${cfg.id}`, __URL_SCHEME__: cfg.urlScheme ?? '', __APP_NAME__: cfg.name };
+  return {
+    __APP_GROUP__: `group.${cfg.id}`,
+    __URL_SCHEME__: cfg.urlScheme ?? '',
+    __APP_NAME__: cfg.name,
+    __SHARE_SYNC_B64__: encodeShareDirectSync(cfg.shareTarget?.directSync),
+  };
 }
 
 /** Substitute any {@link buildTokens} in a stamped string (entitlement value or native-source file). */

package/src/config.ts

@@ -40,6 +40,64 @@ export interface EnvSwitcherConfig {
   deeplink?: boolean;
 }
 
+/** iOS share-extension direct sync (`shareTarget.directSync`). When configured, the generated
+ * `AppwrapShare` extension tries to complete the share ITSELF — one HTTP call to the app's backend,
+ * with an honest "Syncing… → Synced" drawer status — instead of only parking the payload in the
+ * App-Group mailbox for the next app open (Apple forbids a share extension launching its host, so
+ * this makes launching unnecessary). Any failure (offline, non-2xx, missing/incomplete context,
+ * oversized image) falls back to the unchanged mailbox behavior.
+ *
+ * `{key}` placeholders in the templates resolve from the SHARE CONTEXT — a small KV the web app
+ * publishes via `kit.shareTarget.setContext({...})` (persisted as JSON in the App Group under
+ * `appwrap-share-context`). The framework treats both the context and the templates as opaque —
+ * nothing app-specific is baked in. */
+export interface ShareDirectSyncConfig {
+  /** Endpoint template, e.g. `https://api.example.com/bin/{binId}`. Every `{key}` must resolve from
+   * the published context or the sync is skipped (mailbox fallback). */
+  urlTemplate: string;
+  /** HTTP method for the write (default `PUT`). Body is JSON. */
+  method?: 'PUT' | 'POST';
+  /** JSON body field names: shared text goes under `text` (default `content`), the shared image —
+   * as a base64 data URL — under `image` (default `image`). */
+  fields?: { text?: string; image?: string };
+  /** `append` (default `replace`): GET the same URL first, append the shared text to the existing
+   * `fields.text` value (newline-joined) and PRESERVE the existing image unless a new one is shared.
+   * `replace` writes the payload as-is (no GET). */
+  merge?: 'append' | 'replace';
+  /** Max encoded image size (bytes, default 4_000_000). A larger shared image is first DOWNSCALED
+   * (longest edge → `maxImageEdge`, JPEG `jpegQuality`) — mirroring the typical web-side pipeline;
+   * only if it still exceeds the cap (or fails to decode) does the whole share fall back to the
+   * mailbox (which keeps the ORIGINAL bytes for the app to ingest). */
+  maxImageBytes?: number;
+  /** Downscale target when over `maxImageBytes`: longest edge in px (default 2000). */
+  maxImageEdge?: number;
+  /** JPEG re-encode quality for the downscale (0–1, default 0.85). */
+  jpegQuality?: number;
+  /** Drawer success text template (default `Synced`), `{key}` from context — e.g. `Synced to {binId}`. */
+  successMessage?: string;
+}
+
+/** {@link ShareDirectSyncConfig} with defaults applied — the exact shape stamped into the extension. */
+export function resolveShareDirectSync(ds: ShareDirectSyncConfig): Required<Omit<ShareDirectSyncConfig, 'fields'>> & { fields: { text: string; image: string } } {
+  return {
+    urlTemplate: ds.urlTemplate,
+    method: ds.method ?? 'PUT',
+    fields: { text: ds.fields?.text ?? 'content', image: ds.fields?.image ?? 'image' },
+    merge: ds.merge ?? 'replace',
+    maxImageBytes: ds.maxImageBytes ?? 4_000_000,
+    maxImageEdge: ds.maxImageEdge ?? 2000,
+    jpegQuality: ds.jpegQuality ?? 0.85,
+    successMessage: ds.successMessage ?? 'Synced',
+  };
+}
+
+/** Base64(JSON) encoding of the resolved direct-sync config — safe to stamp inside a Swift string
+ * literal (base64 needs no escaping). Empty string when absent/invalid → the feature is inert. */
+export function encodeShareDirectSync(ds: ShareDirectSyncConfig | undefined): string {
+  if (!ds?.urlTemplate) return '';
+  return Buffer.from(JSON.stringify(resolveShareDirectSync(ds)), 'utf8').toString('base64');
+}
+
 export interface AppwrapConfig {
   id: string;
   name: string;
@@ -308,6 +366,10 @@ export interface AppwrapConfig {
    * (the per-app `permissions{}` map only OVERRIDES the default usage copy). When ABSENT, every
    * capability is active and permissions come solely from `permissions{}` (pre-modules behavior). */
   modules?: string[];
+  /** `shareTarget` module options (module must be listed in `modules`). Currently just the iOS
+   * share-extension direct-sync lane — see {@link ShareDirectSyncConfig}. Absent → mailbox-only
+   * behavior, unchanged. */
+  shareTarget?: { directSync?: ShareDirectSyncConfig };
   /** Extra module packs layered on top of the built-in capabilities (see packs.ts). Each entry is a
    * local directory OR an npm package name; a pack contributes `ModuleManifest[]` (+ handler files,
    * native source, an optional kit client). Packs apply in order, LAST-WINS by module name, so a pack
@@ -375,7 +437,7 @@ export const KNOWN_CONFIG_KEYS: ReadonlySet<string> = new Set([
   'androidAppLinks', 'appBoundDomains', 'backendOrigin', 'backgroundAudio', 'backgroundColor', 'backgroundTasks', 'buildNumber', 'debug',
   'debugLog', 'desktop', 'devMenu', 'edgeToEdge', 'entry', 'icon', 'id', 'iosKeyboardExtraLift', 'loader', 'modules', 'modulePacks', 'name',
   'envSwitcher', 'iosEntitlements', 'neutralizeServiceWorker', 'oauthRedirectSchemes', 'openNewWindowsInBrowser', 'orientation', 'overrides', 'permissions',
-  'plugins', 'push', 'pwaDist', 'queryPackages', 'queryUrlSchemes', 'serverUrl', 'signing', 'signingProfiles', 'statusBarStyle',
+  'plugins', 'push', 'pwaDist', 'queryPackages', 'queryUrlSchemes', 'serverUrl', 'shareTarget', 'signing', 'signingProfiles', 'statusBarStyle',
   'splashIcon', 'storekitConfig', 'targetedDevices', 'teamId', 'themeColor', 'trackingDomains', 'urlScheme',
   'usesNonExemptEncryption', 'vendorPaths', 'version',
 ]);