@livx.cc/appwrap 0.57.0 → 0.58.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.57.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_Resources/Android/src/main/AndroidManifest.xml

@@ -58,6 +58,8 @@
 		<!-- App Links (https) — autoVerify intent-filters stamped per host from config.androidAppLinks
 		     (or derived from iOS associated-domains applinks:). Needs assetlinks.json on the host. -->
 		<!-- appwrap:app-links --><!-- /appwrap:app-links -->
+		<!-- Main-activity XML from active modules (e.g. shareTarget's ACTION_SEND filter) -->
+		<!-- appwrap:activity --><!-- /appwrap:activity -->
 	</activity>
 		<activity android:name="com.tns.ErrorReportActivity"/>
 

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

@@ -56,6 +56,9 @@ export interface ModuleManifest {
     /** Raw XML injected inside the AndroidManifest `<application>` (activities, providers,
      * intent-filters a capability needs — e.g. Health Connect's permission-rationale activity). */
     manifestApplication?: string;
+    /** Raw XML injected inside the MAIN `<activity>` (intent-filters a capability needs on the
+     * launcher activity — e.g. shareTarget's ACTION_SEND filter). */
+    manifestActivity?: string;
   };
   /** Module-owned native source: a dir under `runtime/modules-native/<nativeSrc>/` mirroring the
    * App_Resources layout, copied into `native/` ONLY when the module is active (stays strippable).
@@ -272,13 +275,50 @@ export const MODULES: ModuleManifest[] = [
     android: { gradleDeps: ['androidx.work:work-runtime:2.9.1', 'com.google.guava:guava:33.3.1-android'] },
   },
 
+  // ── shareTarget — INBOUND OS share sheet (receive shared text/images) — opt-in, STRIPPABLE ──
+  // Android: an ACTION_SEND(_MULTIPLE) intent-filter on the main activity puts the app in the share
+  // sheet; the strippable handler reads the SEND intent (cold launch + warm onNewIntent) and
+  // re-delivers it through the EXISTING deep-link path as `<urlScheme>://share?text=…` — riding the
+  // 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
+  // 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' },
+    ios: { entitlements: { 'com.apple.security.application-groups': ['__APP_GROUP__'] } },
+    android: {
+      manifestActivity:
+        `<intent-filter>\n` +
+        `\t\t\t<action android:name="android.intent.action.SEND" />\n` +
+        `\t\t\t<category android:name="android.intent.category.DEFAULT" />\n` +
+        `\t\t\t<data android:mimeType="text/plain" />\n` +
+        `\t\t\t<data android:mimeType="image/*" />\n` +
+        `\t\t</intent-filter>\n` +
+        `\t\t<intent-filter>\n` +
+        `\t\t\t<action android:name="android.intent.action.SEND_MULTIPLE" />\n` +
+        `\t\t\t<category android:name="android.intent.category.DEFAULT" />\n` +
+        `\t\t\t<data android:mimeType="image/*" />\n` +
+        `\t\t</intent-filter>`,
+    },
+  },
+
   // NOTE: billing, health, and widget are NOT part of CE — they live in host-provided module packs
   // (a consumer opts in via `modulePacks`).
 ];
 
 /** 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'] as const;
+export const OPTIONAL_GROUPS = ['oauth', 'reviews', 'scanner', 'speech', 'tracking', 'appleSignIn', 'backgroundTask', 'shareTarget'] 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/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/events.ts

@@ -25,8 +25,20 @@ export function setDeepLinkInterceptor(fn: ((url: string) => boolean) | null): v
   deepLinkInterceptor = fn;
 }
 
+/** A pending native-side REWRITER of an inbound deep link (e.g. shareTarget on iOS relocating shared
+ * files from the App Group container into the app cache and rewriting the link to point at them).
+ * Runs before the interceptor; returns the URL to deliver (usually unchanged). Set by
+ * handlers-share-target. Distinct from the interceptor: a transform forwards, an interceptor consumes. */
+let deepLinkTransformer: ((url: string) => string) | null = null;
+export function setDeepLinkTransformer(fn: ((url: string) => string) | null): void {
+  deepLinkTransformer = fn;
+}
+
 /** Called by the iOS delegate (cold start or while running) and Android intents. */
 export function onDeepLink(url: string): void {
+  if (deepLinkTransformer) {
+    try { url = deepLinkTransformer(url); } catch (e) { console.warn('AppWrap: deep-link transform failed', e); }
+  }
   // Give a native consumer (OAuth callback) first refusal — a matched OAuth redirect is internal
   // plumbing, not an app deep link, so it's swallowed here and never forwarded to the PWA.
   if (deepLinkInterceptor?.(url)) return;
@@ -48,8 +60,15 @@ export function onDeepLink(url: string): void {
  * Returns null when the launch wasn't from a link (or it was already consumed / delivered warm).
  */
 export function consumePendingDeepLink(): string | null {
-  const url = pendingDeepLink;
+  let url = pendingDeepLink;
   pendingDeepLink = null;
+  // Re-apply the transformer: an iOS cold-launch link is ingested in didFinishLaunching, BEFORE
+  // main-page init registers transformers (e.g. shareTarget's gfile=→file= relocation) — so the
+  // buffered URL may still be raw. Transformers are idempotent (guard on their own markers), so a
+  // link already transformed at ingress passes through unchanged.
+  if (url && deepLinkTransformer) {
+    try { url = deepLinkTransformer(url); } catch (e) { console.warn('AppWrap: deep-link transform failed', e); }
+  }
   return url;
 }
 

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

@@ -0,0 +1,199 @@
+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
+ * (stamped by the CLI when the module is active) lands the shared payload on the main activity as a
+ * SEND intent; this handler reads it (cold launch + warm onNewIntent) and re-delivers through the
+ * EXISTING deep-link path as a synthetic URL — so it inherits the proven cold-start buffering
+ * (delivered in the handshake `deepLink`) and warm `deeplink.open` event with no new bridge surface.
+ *
+ * URL contract (parsed by kit.shareTarget, also directly consumable via kit.lifecycle.onDeepLink):
+ *   <urlScheme>://share?text=<enc>&title=<enc>&file=<enc>&file=<enc>…
+ *  - `text`  — EXTRA_TEXT (shared text / URL), when present.
+ *  - `title` — EXTRA_SUBJECT, when present.
+ *  - `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) 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;
+  Application.android.on(Application.android.activityNewIntentEvent, (args: AndroidActivityNewIntentEventData) =>
+    deliverShareIntent(args.intent)
+  );
+  // Cold start: the SEND intent IS the launch intent (events.ts only reads getData(), null for SEND).
+  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;
+ * text/title params always survive. */
+function iosRelocateGroupFiles(url: string): string {
+  try {
+    const [head, query = ''] = url.split('?');
+    const fm = NSFileManager.defaultManager;
+    const groupRoot = fm.containerURLForSecurityApplicationGroupIdentifier(`group.${SHELL_CONFIG.appId}`);
+    const cacheBase = NSSearchPathForDirectoriesInDomains(13 /* Caches */, 1, true).objectAtIndex(0) as string;
+    const destDir = `${cacheBase}/appwrap-share`;
+    fm.createDirectoryAtPathWithIntermediateDirectoriesAttributesError(destDir, true, null, null);
+    const params: string[] = [];
+    for (const pair of query.split('&')) {
+      if (!pair.startsWith('gfile=')) { if (pair) params.push(pair); continue; }
+      if (!groupRoot) continue; // no group entitlement in this build — drop the file, keep the text
+      const name = decodeURIComponent(pair.slice('gfile='.length));
+      if (!name || name.includes('/') || name.includes('..')) continue; // extension controls names — don't let one escape the dir
+      const src = `${String(groupRoot.path)}/appwrap-share/${name}`;
+      const dest = `${destDir}/${name}`;
+      fm.removeItemAtPathError(dest, null); // overwrite-safe (moveItem fails on an existing dest)
+      if (fm.moveItemAtPathToPathError(src, dest, null)) params.push(`file=${encodeURIComponent(`appwrap-share/${name}`)}`);
+    }
+    return `${head}?${params.join('&')}`;
+  } catch (e) {
+    console.warn('AppWrap: share group-file relocation failed', e);
+    return url;
+  }
+}
+
+const CONSUMED = 'appwrap_share_consumed';
+
+function deliverShareIntent(intent: android.content.Intent | null | undefined): void {
+  try {
+    const action = intent?.getAction?.();
+    if (action !== 'android.intent.action.SEND' && action !== 'android.intent.action.SEND_MULTIPLE') return;
+    if (intent!.getBooleanExtra?.(CONSUMED, false)) return; // relayout re-read of the same launch intent
+    intent!.putExtra?.(CONSUMED, true);
+
+    const params: string[] = [];
+    const text = intent!.getStringExtra?.(android.content.Intent.EXTRA_TEXT);
+    if (text) params.push(`text=${encodeURIComponent(String(text))}`);
+    const subject = intent!.getStringExtra?.(android.content.Intent.EXTRA_SUBJECT);
+    if (subject) params.push(`title=${encodeURIComponent(String(subject))}`);
+    for (const rel of copySharedStreams(intent!, action)) params.push(`file=${encodeURIComponent(rel)}`);
+    if (!params.length) return;
+
+    // Scheme is cosmetic here — the URL goes straight into onDeepLink, never through the OS.
+    const scheme = SHELL_CONFIG.urlScheme || 'app';
+    onDeepLink(`${scheme}://share?${params.join('&')}`);
+  } catch (e) {
+    console.warn('AppWrap: share intent read failed', e);
+  }
+}
+
+/** Copy each EXTRA_STREAM content:// URI into `<cacheDir>/appwrap-share/`; return cache-relative paths. */
+function copySharedStreams(intent: android.content.Intent, action: string): string[] {
+  const uris: android.net.Uri[] = [];
+  try {
+    if (action === 'android.intent.action.SEND_MULTIPLE') {
+      const list = intent.getParcelableArrayListExtra?.(android.content.Intent.EXTRA_STREAM);
+      for (let i = 0; list && i < list.size(); i++) uris.push(list.get(i) as android.net.Uri);
+    } else {
+      const one = intent.getParcelableExtra?.(android.content.Intent.EXTRA_STREAM) as android.net.Uri | null;
+      if (one) uris.push(one);
+    }
+  } catch (e) {
+    console.warn('AppWrap: share stream extras read failed', e);
+  }
+
+  const out: string[] = [];
+  if (!uris.length) return out;
+  const ctx = Utils.android.getApplicationContext() as android.content.Context;
+  const dir = new java.io.File(ctx.getCacheDir(), 'appwrap-share');
+  dir.mkdirs();
+  const resolver = ctx.getContentResolver();
+  uris.forEach((uri, i) => {
+    try {
+      const name = fileNameFor(resolver, uri, i);
+      const dest = new java.io.File(dir, name);
+      const input = resolver.openInputStream(uri);
+      if (!input) return;
+      const output = new java.io.FileOutputStream(dest);
+      const buf = Array.create('byte', 64 * 1024);
+      let n: number;
+      while ((n = input.read(buf)) > 0) output.write(buf, 0, n);
+      output.close();
+      input.close();
+      out.push(`appwrap-share/${name}`);
+    } catch (e) {
+      console.warn('AppWrap: shared stream copy failed', e);
+    }
+  });
+  return out;
+}
+
+/** A safe, unique-enough filename: display name when the provider offers one, else mime-derived. */
+function fileNameFor(resolver: android.content.ContentResolver, uri: android.net.Uri, i: number): string {
+  let name = '';
+  try {
+    const c = resolver.query(uri, null, null, null, null);
+    if (c) {
+      const idx = c.getColumnIndex('_display_name');
+      if (idx >= 0 && c.moveToFirst()) name = String(c.getString(idx) ?? '');
+      c.close();
+    }
+  } catch { /* fall through to mime-derived name */ }
+  if (!name) {
+    const mime = String(resolver.getType(uri) ?? '');
+    const ext = mime.startsWith('image/') ? mime.slice(6).replace(/[^a-z0-9]/gi, '') || 'img' : 'bin';
+    name = `shared-${i}.${ext}`;
+  }
+  // Sanitize (providers control display names) + prefix a timestamp so repeated shares don't collide.
+  return `${Date.now()}-${i}-${name.replace(/[^\w.-]/g, '_')}`;
+}

package/runtime/app/shell/handlers.ts

@@ -10,7 +10,7 @@ import { ACTIVE_MODULE_NAMES, PACK_MODULES } from './active-modules.generated';
 import { consumePendingBackgroundTaskId } from './background-context';
 
 /** Build identifier for the native shell bundle — bump per deploy to spot stale bundles. */
-export const SHELL_BUILD = 'apple-signin-1';
+export const SHELL_BUILD = 'share-target-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/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/AppwrapShare.entitlements

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>com.apple.security.application-groups</key>
+	<array>
+		<string>__APP_GROUP__</string>
+	</array>
+</dict>
+</plist>

package/runtime/modules-native/shareTarget/App_Resources/iOS/extensions/AppwrapShare/Info.plist

@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>CFBundleDevelopmentRegion</key>
+	<string>en</string>
+	<key>CFBundleDisplayName</key>
+	<string>__APP_NAME__</string>
+	<key>CFBundleName</key>
+	<string>$(PRODUCT_NAME)</string>
+	<key>CFBundleIdentifier</key>
+	<string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+	<key>CFBundleExecutable</key>
+	<string>$(EXECUTABLE_NAME)</string>
+	<key>CFBundleInfoDictionaryVersion</key>
+	<string>6.0</string>
+	<key>CFBundlePackageType</key>
+	<string>XPC!</string>
+	<key>CFBundleShortVersionString</key>
+	<string>1.0.0</string>
+	<key>CFBundleVersion</key>
+	<string>1</string>
+	<key>NSExtension</key>
+	<dict>
+		<key>NSExtensionPointIdentifier</key>
+		<string>com.apple.share-services</string>
+		<key>NSExtensionPrincipalClass</key>
+		<string>$(PRODUCT_MODULE_NAME).ShareViewController</string>
+		<key>NSExtensionAttributes</key>
+		<dict>
+			<key>NSExtensionActivationRule</key>
+			<dict>
+				<key>NSExtensionActivationSupportsText</key>
+				<true/>
+				<key>NSExtensionActivationSupportsWebURLWithMaxCount</key>
+				<integer>1</integer>
+				<key>NSExtensionActivationSupportsImageWithMaxCount</key>
+				<integer>10</integer>
+			</dict>
+		</dict>
+	</dict>
+</dict>
+</plist>

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

@@ -0,0 +1,338 @@
+import UIKit
+import MobileCoreServices
+
+/// appwrap shareTarget — iOS share extension (`AppwrapShare` target, generated per-app by the CLI).
+///
+/// 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), __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] texts, files in
+            guard let self = self else { return }
+            if texts.isEmpty && files.isEmpty {
+                self.extensionContext?.completeRequest(returningItems: nil, completionHandler: nil)
+                return
+            }
+            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
+
+    /// 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 {
+            for provider in item.attachments ?? [] {
+                if provider.hasItemConformingToTypeIdentifier("public.url") && !provider.hasItemConformingToTypeIdentifier("public.file-url") {
+                    group.enter()
+                    provider.loadItem(forTypeIdentifier: "public.url", options: nil) { data, _ in
+                        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
+                        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
+                        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) { done(texts, files) }
+    }
+
+    /// Write a shared image (URL / Data / UIImage, whatever the provider hands over) into the App
+    /// Group container `appwrap-share/` dir; returns the file name there, or nil on any failure
+    /// (missing group entitlement included — text still goes through).
+    private func stashImage(_ data: Any?) -> String? {
+        guard let root = FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: "__APP_GROUP__") else { return nil }
+        let dir = root.appendingPathComponent("appwrap-share", isDirectory: true)
+        try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+        let stamp = Int(Date().timeIntervalSince1970 * 1000)
+        do {
+            if let src = data as? URL {
+                let name = "\(stamp)-\(src.lastPathComponent.replacingOccurrences(of: "[^\\w.-]", with: "_", options: .regularExpression))"
+                try FileManager.default.copyItem(at: src, to: dir.appendingPathComponent(name))
+                return name
+            }
+            if let d = data as? Data {
+                let name = "\(stamp)-shared.img"
+                try d.write(to: dir.appendingPathComponent(name))
+                return name
+            }
+            if let img = data as? UIImage, let d = img.pngData() {
+                let name = "\(stamp)-shared.png"
+                try d.write(to: dir.appendingPathComponent(name))
+                return name
+            }
+        } catch { return nil }
+        return nil
+    }
+
+    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)
+
+    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
+            }
+            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/modules-native/shareTarget/App_Resources/iOS/extensions/AppwrapShare/extension.json

@@ -0,0 +1,3 @@
+{
+	"frameworks": ["UIKit.framework"]
+}

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
@@ -240,6 +240,7 @@ interface NativeReqs {
   androidGradleDeps: string[];
   androidKotlin: boolean;        // any active module ships Kotlin native source
   androidManifestApp: string[];  // raw XML injected inside AndroidManifest <application>
+  androidManifestActivity: string[];  // raw XML injected inside the main <activity> (intent-filters)
   nativeSrc: string[];           // active BUILT-IN modules' nativeSrc dir names (under runtime/modules-native/)
   packNativeSrc: Array<{ name: string; srcDir: string }>;  // active PACK modules' native source (absolute src dirs)
   packHandlers: Array<{ name: string; source: string; packDir: string; file: string; fn: string }>; // active pack modules with a register handler (for the generated barrel + staging)
@@ -270,6 +271,7 @@ function nativeReqs(cfg: AppwrapConfig): NativeReqs {
   const packHandlers: NativeReqs['packHandlers'] = [];
   const packModules: NativeReqs['packModules'] = [];
   const androidManifestApp: string[] = [];
+  const androidManifestActivity: string[] = [];
   let androidKotlin = false;
 
   if (cfg.modules) {
@@ -285,6 +287,7 @@ function nativeReqs(cfg: AppwrapConfig): NativeReqs {
       Object.assign(iosEntitlements, m.ios?.entitlements ?? {});
       if (m.android?.kotlin) androidKotlin = true;
       if (m.android?.manifestApplication) androidManifestApp.push(m.android.manifestApplication);
+      if (m.android?.manifestActivity) androidManifestActivity.push(m.android.manifestActivity);
       // built-in native source resolves under runtime/modules-native/; pack native source (below)
       // resolves under the pack's own dir, so it must not be conflated with the built-in dir names.
       if (m.nativeSrc && !packInfo(m.name)) nativeSrc.push(m.nativeSrc);
@@ -321,6 +324,7 @@ function nativeReqs(cfg: AppwrapConfig): NativeReqs {
     androidGradleDeps: [...gradle],
     androidKotlin,
     androidManifestApp,
+    androidManifestActivity,
     nativeSrc,
     packNativeSrc,
     packHandlers,
@@ -337,6 +341,7 @@ const OPTIONAL_GROUP_HANDLERS: Record<string, { file: string; fn: string }> = {
   tracking: { file: './handlers-tracking', fn: 'registerTrackingHandlers' },
   appleSignIn: { file: './handlers-apple-signin', fn: 'registerAppleSignInHandlers' },
   backgroundTask: { file: './handlers-background', fn: 'registerBackgroundTaskHandlers' },
+  shareTarget: { file: './handlers-share-target', fn: 'registerShareTargetHandlers' },
   // billing/health/widget live in host-provided module packs (not part of CE) — a consumer opts in via modulePacks.
 };
 
@@ -664,10 +669,18 @@ function copyModuleNativeSrc(outDir: string, req: NativeReqs): Set<string> {
 
 /** Build-time tokens a module's native source / entitlements may reference — resolved from the app
  * 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. Currently `__APP_GROUP__` → the App
- * Group id shared by the app + an extension (e.g. widget); extend here as new app-derived needs arise. */
+ * 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;
+ * `__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}` };
+  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). */
@@ -1598,6 +1611,11 @@ function stampAndroidAppName(outDir: string, cfg: AppwrapConfig, req: NativeReqs
       /<!-- appwrap:application -->[\s\S]*?<!-- \/appwrap:application -->/,
       `<!-- appwrap:application -->\n\t\t${req.androidManifestApp.join('\n\t\t')}\n\t\t<!-- /appwrap:application -->`
     );
+    // Main-<activity> XML from active modules (e.g. shareTarget's ACTION_SEND filter) — idempotent marker.
+    src = src.replace(
+      /<!-- appwrap:activity -->[\s\S]*?<!-- \/appwrap:activity -->/,
+      `<!-- appwrap:activity -->\n\t\t${req.androidManifestActivity.join('\n\t\t')}\n\t\t<!-- /appwrap:activity -->`
+    );
     // <queries> for kit.app.canOpenUrl() visibility probes (API 30+) — idempotent marker. queryPackages
     // → explicit <package>; queryUrlSchemes → a VIEW <intent> per scheme (symmetric with iOS's
     // LSApplicationQueriesSchemes). See stampAndroidQueries.
@@ -2114,6 +2132,11 @@ function regenerateCore(cwd: string, outDir: string, cfg: AppwrapConfig, opts: {
   if (opts.firstRun && !req.explicit) {
     console.log('  ℹ no `modules` in the appwrap config → all capabilities active. Declare `modules` to shrink the store build (strip unused handlers/perms).');
   }
+  // shareTarget forwards the shared payload to the host app over the custom URL scheme — without one
+  // the iOS share extension has no way back into the app (Android delivery still works via intents).
+  if (req.activeOptIn.includes('shareTarget') && !cfg.urlScheme) {
+    console.warn('  ⚠ `shareTarget` is active but `urlScheme` is unset — the iOS share extension cannot forward to the app. Set `urlScheme` in the appwrap config.');
+  }
   // Copy each template root in order — later roots OVERLAY earlier (file-level last-wins), so a
   // consumer template can add or replace shell files without forking CE. Single root (default) is
   // exactly the pre-overlay copy.

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',
 ]);