@livx.cc/appwrap 0.58.0 → 0.58.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.58.0",
+  "version": "0.58.2",
   "description": "Wrap any PWA into a native app with native capabilities (appwrap runtime + @livx.cc/native-kit).",
   "license": "MIT",
   "author": "Elya Livshitz",

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

@@ -282,27 +282,47 @@ export const MODULES: ModuleManifest[] = [
   // proven cold-start buffering (handshake `deepLink`) + warm `deeplink.open` event with zero new
   // bridge surface. iOS: a generated share-extension TARGET (`AppwrapShare`, from this module's
   // nativeSrc via NS's App_Resources/iOS/extensions seam — same machinery as the widget pack) that
-  // forwards to the host app over `urlScheme` (REQUIRED in config); images cross via the App Group
-  // container (entitlement below, stamped on both targets) and the host shell relocates them into the
-  // app cache so the JS contract is platform-identical. Consume via `kit.shareTarget.onReceive` (or
-  // raw `kit.lifecycle.onDeepLink`).
+  // PERSISTS the payload as the same `<urlScheme>://share?…` URL into an App-Group UserDefaults
+  // MAILBOX (modern iOS blocks share extensions from launching their host via openURL:, so there is
+  // no live hand-off — the extension shows a brief "Added to <App>" confirmation instead); the host
+  // drains the mailbox on cold launch + every resume (read-once) into the same deep-link path. Images
+  // cross via the App Group container (entitlement below, stamped on both targets) and the host shell
+  // relocates them into the app cache so the JS contract is platform-identical. `urlScheme` REQUIRED. Consume via `kit.shareTarget.onReceive` (or
+  // raw `kit.lifecycle.onDeepLink`). OPTIONAL direct sync: config `shareTarget.directSync` lets the
+  // iOS extension complete the share ITSELF (one templated HTTP call, "Syncing… → Synced" drawer
+  // status) using the app-published context KV (`kit.shareTarget.setContext`) — mailbox stays the
+  // fallback on any failure. See ShareDirectSyncConfig in appwrap-cli config.ts.
   {
     name: 'shareTarget', group: 'shareTarget', nativeSrc: 'shareTarget',
     capabilities: { shareTarget: 'native' },
     ios: { entitlements: { 'com.apple.security.application-groups': ['__APP_GROUP__'] } },
+    // Android UX parity with the iOS drawer: the SEND filters sit on a LIGHTWEIGHT translucent
+    // activity (module Kotlin source, cc.appwrap.share.AppwrapShareActivity) — NOT the main
+    // activity — so a share never boots the full app/WebView. It performs the same config-driven
+    // direct sync (toast status) and only falls back to launching the app (deep-link contract
+    // unchanged) when sync isn't possible. taskAffinity="" keeps it out of the app's task;
+    // noHistory + excludeFromRecents make it invisible to navigation.
     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>`,
+      kotlin: true,
+      manifestApplication:
+        `<activity android:name="cc.appwrap.share.AppwrapShareActivity"\n` +
+        `\t\t\tandroid:exported="true"\n` +
+        `\t\t\tandroid:excludeFromRecents="true"\n` +
+        `\t\t\tandroid:noHistory="true"\n` +
+        `\t\t\tandroid:taskAffinity=""\n` +
+        `\t\t\tandroid:theme="@android:style/Theme.Translucent.NoTitleBar">\n` +
+        `\t\t\t<intent-filter>\n` +
+        `\t\t\t\t<action android:name="android.intent.action.SEND" />\n` +
+        `\t\t\t\t<category android:name="android.intent.category.DEFAULT" />\n` +
+        `\t\t\t\t<data android:mimeType="text/plain" />\n` +
+        `\t\t\t\t<data android:mimeType="image/*" />\n` +
+        `\t\t\t</intent-filter>\n` +
+        `\t\t\t<intent-filter>\n` +
+        `\t\t\t\t<action android:name="android.intent.action.SEND_MULTIPLE" />\n` +
+        `\t\t\t\t<category android:name="android.intent.category.DEFAULT" />\n` +
+        `\t\t\t\t<data android:mimeType="image/*" />\n` +
+        `\t\t\t</intent-filter>\n` +
+        `\t\t</activity>`,
     },
   },
 

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

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

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

@@ -1,14 +1,24 @@
 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.
+ * shareTarget (INBOUND share sheet) — Android. The SEND(_MULTIPLE) intent-filters live on the
+ * LIGHTWEIGHT `cc.appwrap.share.AppwrapShareActivity` (module Kotlin source, translucent — the iOS
+ * drawer's parity): it direct-syncs when configured, and on any failure launches the app with the
+ * `<urlScheme>://share?…` deep link below (a VIEW intent → the normal deep-link path). The SEND
+ * handler here remains for builds whose manifest still carries the filters on the main activity
+ * (pre-parity installs): it reads the intent (cold launch + warm onNewIntent) and re-delivers
+ * through the EXISTING deep-link path as a synthetic URL — inheriting the proven cold-start
+ * buffering (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>…
@@ -17,17 +27,47 @@ import { onDeepLink, setDeepLinkTransformer } from './events';
  *  - `file`  — repeated; each is a path RELATIVE TO THE APP CACHE DIR (`appwrap-share/…`) where the
  *    shared stream (image) was copied — read it via `kit.fs.read(p, { dir: 'cache', encoding: 'base64' })`.
  *
- * iOS: the generated `AppwrapShare` extension (this module's nativeSrc) forwards the payload as the
- * SAME URL over the app's urlScheme — that link enters through the normal openURL delegate path. Text
- * rides in the URL directly; images land in the App Group container as `gfile=<name>` params, which
- * the transformer below relocates into the app cache and rewrites to `file=` (cache-relative) so the
- * contract the web app sees is platform-identical.
+ * iOS: the generated `AppwrapShare` extension (this module's nativeSrc) PERSISTS the payload as the
+ * SAME URL into an App-Group "mailbox" (UserDefaults key `appwrap-share-mailbox`, a string array) —
+ * modern iOS silently blocks a share extension from launching its host via `openURL:`, so there is
+ * no live hand-off; the host drains the mailbox on cold launch and on every foreground/resume
+ * (read-once) and feeds each URL through the normal deep-link path (cold: buffered into the
+ * handshake `deepLink`; warm: `deeplink.open` event). Text rides in the URL directly; images land in
+ * the App Group container as `gfile=<name>` params, which the transformer below relocates into the
+ * app cache and rewrites to `file=` (cache-relative) so the contract the web app sees is
+ * platform-identical.
  */
 export function registerShareTargetHandlers(): void {
+  // Share-context KV (kit.shareTarget.setContext) — generic, app-opaque. iOS persists it in the App
+  // Group (read by the AppwrapShare extension); Android persists it in SharedPreferences
+  // `appwrap-share`/`context` (read by cc.appwrap.share.AppwrapShareActivity's direct sync).
+  bridge.register('shareTarget.setContext', ({ context }: { context?: Record<string, string | number> | null }) => {
+    const json = context && typeof context === 'object' ? JSON.stringify(context) : null;
+    if (isIOS) {
+      const d = NSUserDefaults.alloc().initWithSuiteName(`group.${SHELL_CONFIG.appId}`);
+      if (!d) return;
+      if (json) d.setObjectForKey(json, CONTEXT_KEY);
+      else d.removeObjectForKey(CONTEXT_KEY);
+      return;
+    }
+    if (!isAndroid) return;
+    const prefs = (Utils.android.getApplicationContext() as android.content.Context)
+      .getSharedPreferences('appwrap-share', 0 /* MODE_PRIVATE */);
+    const ed = prefs.edit();
+    if (json) ed.putString('context', json);
+    else ed.remove('context');
+    ed.apply();
+  });
   if (isIOS) {
     // Rewrite share links carrying App-Group files (gfile=) → cache files (file=). Text-only share
     // links (no gfile) pass through untouched.
     setDeepLinkTransformer((url) => (url.includes('://share?') && url.includes('gfile=') ? iosRelocateGroupFiles(url) : url));
+    const drain = () => {
+      try { drainShareMailbox(iosMailboxStore(), onDeepLink); }
+      catch (e) { console.warn('AppWrap: share mailbox drain failed', e); }
+    };
+    drain(); // cold launch — a share made while the app was killed is waiting in the mailbox
+    Application.on(Application.resumeEvent, drain); // warm — user shared, then switched back to the app
     return;
   }
   if (!isAndroid) return;
@@ -38,6 +78,23 @@ export function registerShareTargetHandlers(): void {
   deliverShareIntent(Application.android.startActivity?.getIntent?.());
 }
 
+// ── iOS App-Group mailbox (written by the AppwrapShare extension, drained by the host) ──
+// Drain semantics (read-once, crash-safe) are PURE and live in share-mailbox.ts (bun-tested).
+
+/** The real iOS store: `group.<appId>` suite UserDefaults, string-array under MAILBOX_KEY. */
+function iosMailboxStore(): ShareMailboxStore {
+  const defaults = NSUserDefaults.alloc().initWithSuiteName(`group.${SHELL_CONFIG.appId}`);
+  return {
+    read: () => {
+      const arr = defaults?.arrayForKey(MAILBOX_KEY);
+      const out: string[] = [];
+      for (let i = 0; arr && i < arr.count; i++) out.push(String(arr.objectAtIndex(i)));
+      return out;
+    },
+    clear: () => { defaults?.removeObjectForKey(MAILBOX_KEY); },
+  };
+}
+
 /** iOS: move each `gfile=<name>` from `<AppGroup>/appwrap-share/` into `<Caches>/appwrap-share/` and
  * rewrite the param to `file=appwrap-share/<name>` (the fs `cache` root), matching Android's shape.
  * Any file that can't be moved (missing group container, purged file) is dropped from the link;

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

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

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

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

package/runtime/modules-native/shareTarget/App_Resources/Android/src/main/java/cc/appwrap/share/AppwrapShareActivity.kt

@@ -0,0 +1,307 @@
+package cc.appwrap.share
+
+import android.app.Activity
+import android.content.Intent
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.net.Uri
+import android.os.Bundle
+import android.util.Base64
+import android.widget.Toast
+import org.json.JSONObject
+import java.io.ByteArrayOutputStream
+import java.io.File
+import java.net.HttpURLConnection
+import java.net.URL
+
+/**
+ * appwrap shareTarget — Android lightweight share handler (generated per-app by the CLI, active only
+ * when the `shareTarget` module is on). Declared translucent + no-history in the manifest (see the
+ * module's `manifestApplication` XML), so tapping the app in the share sheet does NOT launch the full
+ * app/WebView — this activity handles the SEND intent invisibly, exactly like the iOS share
+ * extension handles the drawer:
+ *
+ * 1. DIRECT SYNC (config `shareTarget.directSync`, stamped as `__SHARE_SYNC_B64__` — base64 JSON,
+ *    empty = off): one HTTP call to the app's backend with a "Syncing… → ✓ <successMessage>" toast.
+ *    `{key}` placeholders resolve from the SHARE CONTEXT the web app published via
+ *    `kit.shareTarget.setContext(...)` (SharedPreferences `appwrap-share` / key `context` — the
+ *    Android sibling of iOS's App-Group `appwrap-share-context`). `merge:"append"` GETs first,
+ *    appends text (newline-joined) and preserves the existing image unless a new one is shared.
+ *    Oversized images are downscaled (longest edge → maxImageEdge, JPEG jpegQuality) first.
+ *
+ * 2. FALLBACK (any failure: offline, non-2xx, no/unresolved context, >1 image, still-oversized
+ *    image): launch the main activity with the SAME deep link Android shares always used —
+ *    `<urlScheme>://share?text=…&file=<cache-relative>…` — so the share is never lost and the JS
+ *    contract is unchanged (see runtime/app/shell/handlers-share-target.ts).
+ *
+ * Build-time tokens (stamped by `appwrap init`/`sync`): __URL_SCHEME__, __SHARE_SYNC_B64__.
+ */
+class AppwrapShareActivity : Activity() {
+    private val syncB64 = "__SHARE_SYNC_B64__"
+    private val urlScheme = "__URL_SCHEME__"
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        try {
+            handleShare()
+        } catch (e: Exception) {
+            android.util.Log.w("AppwrapShare", "share handling failed", e)
+            finish()
+        }
+    }
+
+    private fun handleShare() {
+        val action = intent?.action
+        if (action != Intent.ACTION_SEND && action != Intent.ACTION_SEND_MULTIPLE) { finish(); return }
+        val text = intent.getStringExtra(Intent.EXTRA_TEXT) ?: ""
+        val title = intent.getStringExtra(Intent.EXTRA_SUBJECT) ?: ""
+        val uris = streamUris(action)
+        if (text.isEmpty() && uris.isEmpty()) { finish(); return }
+
+        val plan = directSyncPlan(text, uris)
+        if (plan == null) {
+            android.util.Log.i("AppwrapShare", "direct sync unavailable (no config/context/resolvable url or multi-image) — falling back to app launch")
+            fallbackToApp(text, title, uris); return
+        }
+        android.util.Log.i("AppwrapShare", "direct sync → ${plan.method} ${plan.url} (append=${plan.append}, image=${plan.imageDataUrl != null})")
+        Toast.makeText(applicationContext, "Syncing…", Toast.LENGTH_SHORT).show()
+        Thread {
+            val ok = runDirectSync(plan)
+            runOnUiThread {
+                if (ok) {
+                    Toast.makeText(applicationContext, "✓ ${plan.successText}", Toast.LENGTH_SHORT).show()
+                    finish()
+                } else {
+                    fallbackToApp(text, title, uris) // never lose a share
+                }
+            }
+        }.start()
+    }
+
+    private fun streamUris(action: String): List<Uri> = try {
+        if (action == Intent.ACTION_SEND_MULTIPLE) {
+            @Suppress("DEPRECATION")
+            intent.getParcelableArrayListExtra<Uri>(Intent.EXTRA_STREAM)?.filterNotNull() ?: emptyList()
+        } else {
+            @Suppress("DEPRECATION")
+            (intent.getParcelableExtra(Intent.EXTRA_STREAM) as? Uri)?.let { listOf(it) } ?: emptyList()
+        }
+    } catch (e: Exception) {
+        android.util.Log.w("AppwrapShare", "stream extras read failed", e)
+        emptyList()
+    }
+
+    // ── direct sync ─────────────────────────────────────────────────────────
+
+    private class SyncPlan(
+        val url: String, val method: String, val textField: String, val imageField: String,
+        val append: Boolean, val text: String, val imageDataUrl: String?, val successText: String,
+    )
+
+    /** Decide whether THIS share can direct-sync: config stamped, context published, url template
+     * fully resolved, ≤1 image, image under the size cap (after downscale). null → fallback. */
+    private fun directSyncPlan(text: String, uris: List<Uri>): SyncPlan? {
+        if (syncB64.isEmpty()) return null
+        if (uris.size > 1) return null // multi-image keeps full fidelity via the app
+        val cfg = try { JSONObject(String(Base64.decode(syncB64, Base64.DEFAULT), Charsets.UTF_8)) }
+            catch (e: Exception) { return null }
+        val ctx = shareContext() ?: return null
+        val url = resolveTemplate(cfg.optString("urlTemplate"), ctx) ?: return null
+        if (!url.startsWith("http")) return null
+
+        var imageDataUrl: String? = null
+        if (uris.isNotEmpty()) {
+            imageDataUrl = encodeImage(
+                uris[0],
+                cfg.optInt("maxImageBytes", 4_000_000),
+                cfg.optInt("maxImageEdge", 2000),
+                cfg.optDouble("jpegQuality", 0.85),
+            ) ?: return null // undecodable / still oversized → fallback keeps the ORIGINAL bytes
+        }
+        val fields = cfg.optJSONObject("fields")
+        return SyncPlan(
+            url = url,
+            method = cfg.optString("method", "PUT").ifEmpty { "PUT" },
+            textField = fields?.optString("text").takeUnless { it.isNullOrEmpty() } ?: "content",
+            imageField = fields?.optString("image").takeUnless { it.isNullOrEmpty() } ?: "image",
+            append = cfg.optString("merge") == "append",
+            text = text,
+            imageDataUrl = imageDataUrl,
+            successText = resolveTemplate(cfg.optString("successMessage").ifEmpty { "Synced" }, ctx) ?: "Synced",
+        )
+    }
+
+    /** The app-published share context (SharedPreferences `appwrap-share`/`context`, JSON KV —
+     * written by the shell's `shareTarget.setContext` handler). Values stringified for templates. */
+    private fun shareContext(): Map<String, String>? = try {
+        val raw = getSharedPreferences("appwrap-share", MODE_PRIVATE).getString("context", null) ?: return null
+        val obj = JSONObject(raw)
+        val out = mutableMapOf<String, String>()
+        for (k in obj.keys()) out[k] = obj.get(k).toString()
+        out
+    } catch (e: Exception) { null }
+
+    /** Replace `{key}` placeholders; null when any stays unresolved — a partially-resolved URL must
+     * never be called. */
+    private fun resolveTemplate(template: String, ctx: Map<String, String>): String? {
+        if (template.isEmpty()) return null
+        var s = template
+        for ((k, v) in ctx) s = s.replace("{$k}", v)
+        return if (Regex("\\{[^}]+\\}").containsMatchIn(s)) null else s
+    }
+
+    /** Shared image → base64 data URL under `maxBytes`; oversized inputs are downscaled (longest
+     * edge → maxEdge px, JPEG at quality) via inSampleSize decode (no full-size bitmap → no OOM).
+     * null on decode failure or still-over-cap. */
+    private fun encodeImage(uri: Uri, maxBytes: Int, maxEdge: Int, quality: Double): String? {
+        try {
+            val raw = contentResolver.openInputStream(uri)?.use { it.readBytes() } ?: return null
+            val asIs = "data:${sniffMime(raw)};base64,${Base64.encodeToString(raw, Base64.NO_WRAP)}"
+            if (asIs.length <= maxBytes) return asIs
+            val bounds = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+            BitmapFactory.decodeByteArray(raw, 0, raw.size, bounds)
+            if (bounds.outWidth <= 0 || bounds.outHeight <= 0) return null
+            val longest = maxOf(bounds.outWidth, bounds.outHeight)
+            var sample = 1
+            while (longest / (sample * 2) >= maxEdge) sample *= 2 // power-of-2 pre-scale keeps memory bounded
+            val opts = BitmapFactory.Options().apply { inSampleSize = sample }
+            var bmp = BitmapFactory.decodeByteArray(raw, 0, raw.size, opts) ?: return null
+            val edge = maxOf(bmp.width, bmp.height)
+            if (edge > maxEdge) { // exact final scale (inSampleSize only gets within 2x)
+                val scale = maxEdge.toFloat() / edge
+                val scaled = Bitmap.createScaledBitmap(
+                    bmp, maxOf(1, (bmp.width * scale).toInt()), maxOf(1, (bmp.height * scale).toInt()), true
+                )
+                if (scaled !== bmp) bmp.recycle()
+                bmp = scaled
+            }
+            val out = ByteArrayOutputStream()
+            bmp.compress(Bitmap.CompressFormat.JPEG, (quality * 100).toInt().coerceIn(1, 100), out)
+            bmp.recycle()
+            val small = "data:image/jpeg;base64,${Base64.encodeToString(out.toByteArray(), Base64.NO_WRAP)}"
+            return if (small.length <= maxBytes) small else null
+        } catch (e: Exception) {
+            android.util.Log.w("AppwrapShare", "image encode failed", e)
+            return null
+        }
+    }
+
+    private fun sniffMime(d: ByteArray): String = when {
+        d.size > 3 && d[0] == 0x89.toByte() && d[1] == 0x50.toByte() -> "image/png"
+        d.size > 1 && d[0] == 0xFF.toByte() && d[1] == 0xD8.toByte() -> "image/jpeg"
+        d.size > 2 && d[0] == 0x47.toByte() && d[1] == 0x49.toByte() -> "image/gif"
+        d.size > 11 && d[8] == 0x57.toByte() && d[9] == 0x45.toByte() -> "image/webp"
+        else -> "image/jpeg"
+    }
+
+    /** Execute the sync on a background thread: (append) GET current → merge → write; else write
+     * as-is. Mirrors ShareViewController.runDirectSync. Returns success. */
+    private fun runDirectSync(plan: SyncPlan): Boolean = try {
+        val existing: JSONObject = if (plan.append) {
+            val (code, body) = http("GET", plan.url, null)
+            android.util.Log.i("AppwrapShare", "direct sync merge GET → HTTP $code")
+            when {
+                code == 404 -> JSONObject() // nothing there yet — first write
+                code in 200..299 -> try { JSONObject(body) } catch (e: Exception) { JSONObject() }
+                else -> return false // offline / server error → fallback
+            }
+        } else JSONObject()
+
+        val oldText = existing.optString(plan.textField)
+        val merged = if (plan.append && oldText.isNotEmpty() && plan.text.isNotEmpty()) "$oldText\n${plan.text}"
+            else plan.text.ifEmpty { oldText }
+        val body = JSONObject().put(plan.textField, merged)
+        // New image replaces; append mode preserves the existing one (the endpoint is a full PUT).
+        when {
+            plan.imageDataUrl != null -> body.put(plan.imageField, plan.imageDataUrl)
+            plan.append && existing.has(plan.imageField) -> body.put(plan.imageField, existing.get(plan.imageField))
+            else -> body.put(plan.imageField, JSONObject.NULL)
+        }
+        val (code, _) = http(plan.method, plan.url, body.toString())
+        android.util.Log.i("AppwrapShare", "direct sync write → HTTP $code")
+        code in 200..299
+    } catch (e: Exception) {
+        android.util.Log.w("AppwrapShare", "direct sync failed", e)
+        false
+    }
+
+    private fun http(method: String, url: String, jsonBody: String?): Pair<Int, String> {
+        val conn = URL(url).openConnection() as HttpURLConnection
+        try {
+            conn.requestMethod = method
+            conn.connectTimeout = 15000
+            conn.readTimeout = 15000
+            if (jsonBody != null) {
+                conn.doOutput = true
+                conn.setRequestProperty("Content-Type", "application/json")
+                conn.outputStream.use { it.write(jsonBody.toByteArray(Charsets.UTF_8)) }
+            }
+            val code = conn.responseCode
+            val stream = if (code in 200..299) conn.inputStream else conn.errorStream
+            val body = stream?.use { it.readBytes().toString(Charsets.UTF_8) } ?: ""
+            return Pair(code, body)
+        } finally {
+            conn.disconnect()
+        }
+    }
+
+    // ── fallback: hand the share to the full app via the existing deep-link path ──
+
+    /** Launch the main activity with `<scheme>://share?…` (the pre-direct-sync contract): text/title
+     * in the URL, streams copied into `<cacheDir>/appwrap-share/` as cache-relative `file=` params —
+     * the same shape handlers-share-target.ts produced when the SEND filter sat on the main activity. */
+    private fun fallbackToApp(text: String, title: String, uris: List<Uri>) {
+        try {
+            val params = mutableListOf<String>()
+            if (text.isNotEmpty()) params.add("text=${Uri.encode(text)}")
+            if (title.isNotEmpty()) params.add("title=${Uri.encode(title)}")
+            for (rel in copyStreamsToCache(uris)) params.add("file=${Uri.encode(rel)}")
+            if (params.isNotEmpty() && urlScheme.isNotEmpty()) {
+                val open = Intent(Intent.ACTION_VIEW, Uri.parse("$urlScheme://share?${params.joinToString("&")}"))
+                open.setPackage(packageName)
+                open.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_SINGLE_TOP)
+                startActivity(open)
+            }
+        } catch (e: Exception) {
+            android.util.Log.w("AppwrapShare", "fallback launch failed", e)
+        }
+        finish()
+    }
+
+    /** Copy each content:// stream into `<cacheDir>/appwrap-share/`; return cache-relative paths. */
+    private fun copyStreamsToCache(uris: List<Uri>): List<String> {
+        val out = mutableListOf<String>()
+        if (uris.isEmpty()) return out
+        val dir = File(cacheDir, "appwrap-share").apply { mkdirs() }
+        uris.forEachIndexed { i, uri ->
+            try {
+                val name = fileNameFor(uri, i)
+                contentResolver.openInputStream(uri)?.use { input ->
+                    File(dir, name).outputStream().use { input.copyTo(it) }
+                    out.add("appwrap-share/$name")
+                }
+            } catch (e: Exception) {
+                android.util.Log.w("AppwrapShare", "stream copy failed", e)
+            }
+        }
+        return out
+    }
+
+    /** Display name when the provider offers one, else mime-derived; sanitized + timestamp-prefixed
+     * so repeated shares don't collide (mirrors handlers-share-target.ts fileNameFor). */
+    private fun fileNameFor(uri: Uri, i: Int): String {
+        var name = ""
+        try {
+            contentResolver.query(uri, null, null, null, null)?.use { c ->
+                val idx = c.getColumnIndex("_display_name")
+                if (idx >= 0 && c.moveToFirst()) name = c.getString(idx) ?: ""
+            }
+        } catch (e: Exception) { /* fall through to mime-derived name */ }
+        if (name.isEmpty()) {
+            val mime = contentResolver.getType(uri) ?: ""
+            val ext = if (mime.startsWith("image/")) mime.substring(6).replace(Regex("[^a-zA-Z0-9]"), "").ifEmpty { "img" } else "bin"
+            name = "shared-$i.$ext"
+        }
+        return "${System.currentTimeMillis()}-$i-${name.replace(Regex("[^\\w.-]"), "_")}"
+    }
+}