@livx.cc/appwrap 0.58.0 → 0.58.2

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). */
@@ -684,12 +691,10 @@ function substituteBuildTokens(s: string, tokens: Record<string, string>): strin
 }
 
 /** Substitute build-time tokens in copied module native source (after copyModuleNativeSrc) — applied
- * generically to every iOS extension file, so a module's app-agnostic source (e.g. the widget
- * extension's Swift/entitlements/plist) gets the app-specific value stamped in. Idempotent (source is
- * re-copied verbatim each sync, then re-substituted). No-op when no extensions were copied. */
+ * generically to every iOS extension file AND every Android module source file (Kotlin/Java/XML —
+ * e.g. shareTarget's AppwrapShareActivity), so a module's app-agnostic source gets the app-specific
+ * value stamped in. Idempotent (source is re-copied verbatim each sync, then re-substituted). */
 function substituteModuleTokens(outDir: string, cfg: AppwrapConfig): void {
-  const extRoot = join(outDir, 'App_Resources/iOS/extensions');
-  if (!existsSync(extRoot)) return;
   const tokens = buildTokens(cfg);
   let touched = false;
   const subst = (file: string) => {
@@ -697,15 +702,19 @@ function substituteModuleTokens(outDir: string, cfg: AppwrapConfig): void {
     const next = substituteBuildTokens(s, tokens);
     if (next !== s) { writeFileSync(file, next); touched = true; }
   };
-  const walk = (dir: string) => {
+  const walk = (dir: string, exts: RegExp) => {
+    if (!existsSync(dir)) return;
     for (const e of readdirSync(dir, { withFileTypes: true })) {
       const p = join(dir, e.name);
-      if (e.isDirectory()) walk(p);
-      else if (/\.(swift|entitlements|plist|json)$/.test(e.name)) subst(p);
+      if (e.isDirectory()) walk(p, exts);
+      else if (exts.test(e.name)) subst(p);
     }
   };
-  walk(extRoot);
-  if (touched) console.log(`  tokn ← __APP_GROUP__ = ${tokens.__APP_GROUP__} (extension source)`);
+  walk(join(outDir, 'App_Resources/iOS/extensions'), /\.(swift|entitlements|plist|json)$/);
+  // Android module source: only java/ (module-owned code) — NOT the whole src/main (res/ + template
+  // manifest have their own stamping and must not see generic token substitution).
+  walk(join(outDir, 'App_Resources/Android/src/main/java'), /\.(kt|java|xml)$/);
+  if (touched) console.log(`  tokn ← __APP_GROUP__ = ${tokens.__APP_GROUP__} (module native source)`);
 }
 
 /** Hosts to register as Android App Links (autoVerify https intent-filters). Explicit

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