craft-native 0.0.91 → 0.0.92

package/dist/android/src/index.d.ts

@@ -37,6 +37,14 @@ export interface InitOptions {
     packageName?: string;
     output: string;
     config?: Partial<CraftAndroidConfig>;
+    /**
+     * Where to find the Zig runtime's `<abi>/libcraft.so`.
+     *
+     * `null` means no runtime regardless of the environment; `undefined` falls
+     * through to `CRAFT_ANDROID_RUNTIME`. Same shape as the iOS builder's
+     * `runtimeDir`.
+     */
+    runtimeDir?: string | null;
 }
 export interface BuildOptions {
     htmlPath?: string;
@@ -44,6 +52,8 @@ export interface BuildOptions {
     output: string;
     release?: boolean;
     compile?: boolean;
+    /** Same meaning as `InitOptions.runtimeDir`; refreshes what init installed. */
+    runtimeDir?: string | null;
 }
 export interface OpenOptions {
     output: string;
@@ -56,8 +66,33 @@ export declare function syncAndroidWebAssets(source: string, output: string): vo
 export declare function renderAndroidPermissions(config: CraftAndroidConfig): string;
 export declare function renderAndroidDeepLinks(config: CraftAndroidConfig): string;
 /**
- * Initialize a new Android project
+ * Where the runtime directory comes from when the caller does not say.
+ *
+ * The same shape as `CRAFT_BIN` and the iOS builder's `CRAFT_IOS_RUNTIME`: an
+ * explicit override for the monorepo dev loop, not a lookup path. Shipping the
+ * runtime to real apps means putting these libraries in the pantry package
+ * beside the `craft` binary, which is a distribution decision this function
+ * does not make.
+ */
+export declare function resolveRuntimeDir(override?: string | null): string | null;
+/**
+ * Copy the Zig runtime into the generated project as
+ * `app/src/main/jniLibs/<abi>/libcraft.so`.
+ *
+ * That path is AGP's default `jniLibs.srcDirs`, so nothing in the Gradle
+ * templates has to know about it — the library is packaged into the APK and
+ * `System.loadLibrary("craft")` finds it because the file is named for the
+ * `craft` it asks for.
+ *
+ * Until this existed, nothing put the library anywhere. `CraftNative` caught
+ * the `UnsatisfiedLinkError`, set `isAvailable = false`, and every action fell
+ * through to the Kotlin shim — by design, so an app with no runtime still
+ * works, which is also why nobody noticed that *every* generated app was in
+ * that state and the whole Android half of the Zig bridge had never run.
+ *
+ * Returns true when a runtime was installed.
  */
+export declare function installRuntime(output: string, runtimeDir: string): boolean;
 export declare function init(options: InitOptions): Promise<void>;
 /**
  * Build Android project

package/dist/android/src/index.js

@@ -318,6 +318,37 @@ function renderAndroidDeepLinks(config) {
             </intent-filter>`).join(`
 `);
 }
+var RUNTIME_ABIS = ["arm64-v8a", "x86_64"];
+function resolveRuntimeDir(override) {
+  if (override === null)
+    return null;
+  const dir = override ?? process.env.CRAFT_ANDROID_RUNTIME;
+  if (!dir)
+    return null;
+  if (!existsSync(dir)) {
+    const source = override === undefined ? "CRAFT_ANDROID_RUNTIME points at" : "runtimeDir is";
+    throw new Error(`${source} ${dir}, which does not exist.`);
+  }
+  return dir;
+}
+function installRuntime(output, runtimeDir) {
+  const found = RUNTIME_ABIS.map((abi) => ({ abi, source: join(runtimeDir, abi, "libcraft.so") })).filter((entry) => existsSync(entry.source));
+  if (found.length === 0) {
+    throw new Error(`${runtimeDir} has no <abi>/libcraft.so for any of ${RUNTIME_ABIS.join(", ")}. ` + "Run `zig build build-android-all -Doptimize=ReleaseSafe` in packages/zig and point at its zig-out/android.");
+  }
+  if (found.length < RUNTIME_ABIS.length) {
+    const missing = RUNTIME_ABIS.filter((abi) => !found.some((entry) => entry.abi === abi));
+    console.warn(`   \u26A0 only ${found.map((entry) => entry.abi).join(", ")} was found; ${missing.join(", ")} is missing. ` + "The app will fall back to the Kotlin shim on those devices.");
+  }
+  const dest = join(output, "app/src/main/jniLibs");
+  rmSync(dest, { force: true, recursive: true });
+  for (const { abi, source } of found) {
+    const abiDir = join(dest, abi);
+    mkdirSync(abiDir, { recursive: true });
+    cpSync(source, join(abiDir, "libcraft.so"));
+  }
+  return true;
+}
 async function init(options) {
   const { name, packageName, output } = options;
   console.log(`
@@ -537,6 +568,11 @@ zipStorePath=wrapper/dists
 </body>
 </html>`;
   writeFileSync(join(output, "app/src/main/assets/index.html"), placeholderHtml);
+  const runtimeDir = resolveRuntimeDir(options.runtimeDir);
+  if (runtimeDir) {
+    installRuntime(output, runtimeDir);
+    console.log("   Installed the Zig runtime from", runtimeDir);
+  }
   console.log("\u2705 Project initialized");
   console.log("");
   console.log("Next steps:");
@@ -555,6 +591,15 @@ async function build(options) {
     throw new Error(`No craft.config.json found in ${output}. Run 'craft android init' first.`);
   }
   const config = JSON.parse(readFileSync(configPath, "utf-8"));
+  if (existsSync(join(output, "app/src/main/jniLibs"))) {
+    const runtimeDir = resolveRuntimeDir(options.runtimeDir);
+    if (runtimeDir) {
+      installRuntime(output, runtimeDir);
+      console.log("   Refreshed the Zig runtime from", runtimeDir);
+    } else {
+      console.log("   Keeping the Zig runtime installed at init (no runtime directory configured)");
+    }
+  }
   if (devServer) {
     const url = androidWebUrl(devServer, "Android dev server URL");
     config.devServerURL = url.toString();
@@ -641,9 +686,11 @@ async function run(options) {
 export {
   syncAndroidWebAssets,
   run,
+  resolveRuntimeDir,
   renderAndroidPermissions,
   renderAndroidDeepLinks,
   open,
+  installRuntime,
   init,
   build
 };

package/dist/android/templates/CraftBridge.kt.template

@@ -2,10 +2,13 @@ package {{PACKAGE_NAME}}
 
 import android.Manifest
 import android.app.Activity
+import android.content.BroadcastReceiver
 import android.content.ClipData
 import android.content.ClipboardManager
 import android.content.Context
 import android.content.Intent
+import android.content.IntentFilter
+import android.content.IntentSender
 import android.content.pm.PackageManager
 import android.graphics.Bitmap
 import android.hardware.camera2.CameraAccessException
@@ -218,6 +221,14 @@ class CraftBridge(
     private var bridgeReady = false
     private val pendingEvents = mutableListOf<Pair<String, Map<String, Any>>>()
 
+    // Deep links (#215), on the UI thread only, the way iOS's DeepLinkManager
+    // holds them: a link that arrives before the first page has its bridge is
+    // the launch link, and every link waits for an injected bridge.
+    private var hasBeenReady = false
+    private var initialAssigned = false
+    private var launchURL: String? = null
+    private val pendingDeepLinks = mutableListOf<Pair<String, Boolean>>()
+
     // Location tracking
     private var fusedLocationClient: FusedLocationProviderClient? = null
     private val locationCallbacks = mutableMapOf<Int, LocationCallback>()
@@ -307,6 +318,10 @@ class CraftBridge(
         // still loading has somewhere to go rather than being counted as
         // dropped.
         installNativeDeliverer()
+        // A page is about to exist, so no later link launched the app, even
+        // one that arrives before this script's completion runs. iOS marks
+        // the same moment.
+        hasBeenReady = true
 
         val script = """
 {{PROMISE_RUNTIME}}
@@ -365,9 +380,14 @@ class CraftBridge(
                     CraftAndroid.stopListening();
                 },
 
-                // Share
+                // Share. Resolves true when the person picks an app, false
+                // when they dismiss the menu, and rejects when there is
+                // nothing to share or the menu cannot open. No timeout: the
+                // menu waits on a person, not on the device.
                 share: function(text, title) {
-                    CraftAndroid.share(text, title || '');
+                    return window.__craftPromise('share', '_craftShareResolve', '_craftShareReject', function() {
+                        CraftAndroid.share(text == null ? '' : String(text), title == null ? '' : String(title));
+                    });
                 },
 
                 // Camera
@@ -590,7 +610,7 @@ class CraftBridge(
 
                 // Deep Links
                 onDeepLink: function(callback) {
-                    window.addEventListener('craftDeepLink', function(e) { callback(e.detail); });
+                    return window.craft._subscribeDeepLinks(callback);
                 },
 
                 // QR/Barcode Scanner
@@ -991,12 +1011,13 @@ class CraftBridge(
                 // Deep Links
                 deepLinks: {
                     getInitialURL: function() {
+                        window.craft._claimInitialDeepLink();
                         return window.__craftPromise('initial URL', '_craftDeepLinkResolve', '_craftDeepLinkReject', function() {
                             CraftAndroid.getInitialURL();
                         });
                     },
                     onLink: function(callback) {
-                        window.addEventListener('craftDeepLink', function(e) { callback(e.detail); });
+                        return window.craft._subscribeDeepLinks(callback);
                     }
                 },
 
@@ -1346,6 +1367,62 @@ class CraftBridge(
                 }
             };
 
+            // Links that arrive before anything is listening (#215, as iOS
+            // does since #198).
+            //
+            // Native dispatches a link once this script has run, and on a cold
+            // start that is the link the app was opened with. Only a craftReady
+            // handler can have called onLink by then, since onLink is defined
+            // by this very script. So such a link used to reach nobody, and a
+            // page that subscribes later, rather than asking getInitialURL,
+            // never learned how it was opened.
+            //
+            // Held here instead, and handed to the first subscriber on the
+            // next turn, so an unsubscribe returned in the same tick still
+            // applies. The launch link belongs to getInitialURL once the page
+            // has called it, whether native has dispatched it yet or not, so a
+            // page that does both in the same tick or in a craftReady handler,
+            // in either order, gets it once. A page that asks getInitialURL
+            // only later, after an await, should skip `initial` in onLink.
+            //
+            // The state lives on window, not in this function, because this
+            // script can run twice in one document, and a second copy must
+            // neither reset it nor buffer every link a second time.
+            (function installDeepLinkReplay(craft) {
+                var replay = window.__craftDeepLinkReplay;
+                if (!replay) {
+                    replay = window.__craftDeepLinkReplay = {undelivered: [], subscribed: false, initialClaimed: false};
+                    window.addEventListener('craftDeepLink', function(e) {
+                        if (!replay.subscribed && !claimed(e.detail)) replay.undelivered.push(e.detail);
+                    });
+                }
+                function claimed(detail) {
+                    return replay.initialClaimed && detail && detail.initial;
+                }
+                craft._subscribeDeepLinks = function(callback) {
+                    var active = true;
+                    var listener = function(e) { if (!claimed(e.detail)) callback(e.detail); };
+                    window.addEventListener('craftDeepLink', listener);
+                    if (!replay.subscribed) {
+                        replay.subscribed = true;
+                        setTimeout(function() {
+                            var pending = replay.undelivered;
+                            replay.undelivered = [];
+                            if (!active) return;
+                            pending.forEach(function(detail) { callback(detail); });
+                        }, 0);
+                    }
+                    return function() {
+                        active = false;
+                        window.removeEventListener('craftDeepLink', listener);
+                    };
+                };
+                craft._claimInitialDeepLink = function() {
+                    replay.initialClaimed = true;
+                    replay.undelivered = replay.undelivered.filter(function(detail) { return !(detail && detail.initial); });
+                };
+            })(window.craft);
+
             (function installCraftMobileContract(craft) {
                 var legacyShare = craft.share.bind(craft);
                 var legacyOpenCamera = craft.openCamera.bind(craft);
@@ -1477,6 +1554,11 @@ class CraftBridge(
                 val events = pendingEvents.toList()
                 pendingEvents.clear()
                 events.forEach { (name, data) -> sendEvent(name, data) }
+                // After the script, so the page's replay listener exists and
+                // the native deliverer is installed.
+                val links = pendingDeepLinks.toList()
+                pendingDeepLinks.clear()
+                links.forEach { (url, initial) -> dispatchDeepLink(url, initial) }
             }
         }
     }
@@ -1610,18 +1692,95 @@ class CraftBridge(
 
     // ==================== Share ====================
 
+    // Whether the person picked an app from the share menu that is open now.
+    //
+    // The chooser says so through the IntentSender below and says nothing at
+    // all when it is dismissed, while its activity result comes back
+    // RESULT_CANCELED either way. Neither signal answers on its own, so the
+    // pick marks this and the result, which always arrives, settles the page's
+    // promise with it. Everything that touches it runs on the main thread: the
+    // launch is posted there, and receivers and results are delivered there.
+    private var shareChosen = false
+    private var shareReceiverRegistered = false
+    private val shareChosenAction by lazy { "${activity.packageName}.CRAFT_SHARE_CHOSEN" }
+    private val shareChosenReceiver = object : BroadcastReceiver() {
+        override fun onReceive(context: Context, intent: Intent) {
+            shareChosen = true
+        }
+    }
+
     @JavascriptInterface
     fun share(text: String, title: String) {
-        if (CraftNative.share(activity, text, title)) return
+        // The same line iOS draws: an empty string is nothing to share, and a
+        // chooser opened over nothing would offer apps a blank message.
+        if (text.isEmpty()) {
+            rejectShare("Nothing to share")
+            return
+        }
+
+        activity.runOnUiThread {
+            if (closed) return@runOnUiThread
+            shareChosen = false
+
+            val chosen = try {
+                shareChosenSender()
+            } catch (error: Exception) {
+                rejectShare(error.message ?: "Unable to open the share menu")
+                return@runOnUiThread
+            }
 
-        val intent = Intent(Intent.ACTION_SEND).apply {
-            type = "text/plain"
-            putExtra(Intent.EXTRA_TEXT, text)
-            if (title.isNotEmpty()) {
-                putExtra(Intent.EXTRA_SUBJECT, title)
+            // Zig launches the same chooser for the same result; the answer
+            // still comes back through onActivityResult below.
+            if (CraftNative.share(activity, text, title, chosen, REQUEST_SHARE)) return@runOnUiThread
+
+            val intent = Intent(Intent.ACTION_SEND).apply {
+                type = "text/plain"
+                putExtra(Intent.EXTRA_TEXT, text)
+                if (title.isNotEmpty()) {
+                    putExtra(Intent.EXTRA_SUBJECT, title)
+                }
+            }
+            try {
+                activity.startActivityForResult(Intent.createChooser(intent, "Share", chosen), REQUEST_SHARE)
+            } catch (error: Exception) {
+                rejectShare(error.message ?: "Unable to open the share menu")
             }
         }
-        activity.startActivity(Intent.createChooser(intent, "Share"))
+    }
+
+    // The IntentSender the chooser fires on a pick.
+    //
+    // Immutable: the chooser adds the chosen component to the intent it
+    // fires, and this only needs to know that it fired. Explicit, by package,
+    // so the broadcast reaches this app and nothing else, and so the
+    // not-exported receiver accepts it.
+    private fun shareChosenSender(): IntentSender {
+        if (!shareReceiverRegistered) {
+            ContextCompat.registerReceiver(
+                activity,
+                shareChosenReceiver,
+                IntentFilter(shareChosenAction),
+                ContextCompat.RECEIVER_NOT_EXPORTED
+            )
+            shareReceiverRegistered = true
+        }
+        val pick = Intent(shareChosenAction).setPackage(activity.packageName)
+        return PendingIntent.getBroadcast(
+            activity,
+            REQUEST_SHARE,
+            pick,
+            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
+        ).intentSender
+    }
+
+    private fun handleShareResult() {
+        val chosen = shareChosen
+        shareChosen = false
+        evaluatePromiseJavascript("window._craftShareResolve && window._craftShareResolve($chosen)")
+    }
+
+    private fun rejectShare(message: String) {
+        evaluatePromiseJavascript("window._craftShareReject && window._craftShareReject(${jsQuote(message)})")
     }
 
     // ==================== Camera & Gallery ====================
@@ -2366,10 +2525,49 @@ class CraftBridge(
                     activity.packageManager.getPackageInfo(activity.packageName, 0).versionCode
                 }
             } catch (e: Exception) { 0 })
-            put("isEmulator", Build.FINGERPRINT.contains("generic") || Build.FINGERPRINT.contains("emulator"))
+            put("isEmulator", isEmulator())
         }.toString()
     }
 
+    /**
+     * Whether this is an emulator rather than a phone.
+     *
+     * This used to be `FINGERPRINT.contains("generic") ||
+     * FINGERPRINT.contains("emulator")`, and it answered false on the AVDs
+     * anyone actually runs. A current Google APIs image fingerprints as
+     *
+     *     google/sdk_gphone64_x86_64/emu64xa:14/UE1A.230829.036/...:user/release-keys
+     *
+     * which contains neither word. The mobile E2E suite caught it on an API 34
+     * x86_64 emulator, reporting `isEmulator is false` from inside one.
+     *
+     * `HARDWARE` is the reliable signal and leads here: the AVD's virtual board
+     * is `goldfish` on the old QEMU pipeline and `ranchu` on the current one,
+     * and has been one of those two for over a decade. The rest are kept as
+     * secondary evidence for images that report something else - Genymotion,
+     * and the older `generic`/`sdk` products.
+     *
+     * Note this is a hint, not a security boundary. Anything that can rewrite
+     * these properties can defeat it, and nothing here should be treated as
+     * proof of where the code is running.
+     */
+    private fun isEmulator(): Boolean {
+        val hardware = Build.HARDWARE.lowercase()
+        if (hardware.startsWith("goldfish") || hardware.startsWith("ranchu")) return true
+
+        val fingerprint = Build.FINGERPRINT.lowercase()
+        if (fingerprint.startsWith("generic") || fingerprint.startsWith("unknown")) return true
+        if (fingerprint.contains("emulator") || fingerprint.contains("sdk_gphone")) return true
+
+        val product = Build.PRODUCT.lowercase()
+        if (product.startsWith("sdk") || product.contains("_sdk") || product.contains("sdk_")) return true
+
+        val model = Build.MODEL.lowercase()
+        if (model.contains("google_sdk") || model.contains("emulator") || model.contains("android sdk built for")) return true
+
+        return Build.MANUFACTURER.contains("Genymotion") || Build.BRAND.startsWith("generic")
+    }
+
     // ==================== Network Status ====================
 
     @JavascriptInterface
@@ -3190,18 +3388,6 @@ class CraftBridge(
         return true
     }
 
-    // ==================== Deep Links ====================
-
-    fun handleDeepLink(uri: android.net.Uri) {
-        sendEvent("craftDeepLink", mapOf(
-            "url" to uri.toString(),
-            "scheme" to (uri.scheme ?: ""),
-            "host" to (uri.host ?: ""),
-            "path" to (uri.path ?: ""),
-            "query" to (uri.query ?: "")
-        ))
-    }
-
     // ==================== QR/Barcode Scanner ====================
 
     @JavascriptInterface
@@ -3659,7 +3845,7 @@ class CraftBridge(
     fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?): Boolean {
         if (closed) return requestCode == REQUEST_CAMERA || requestCode == REQUEST_GALLERY ||
             requestCode == REQUEST_FILE_PICKER || requestCode == REQUEST_VIDEO ||
-            requestCode == REQUEST_PICK_CONTACT
+            requestCode == REQUEST_PICK_CONTACT || requestCode == REQUEST_SHARE
 
         return when (requestCode) {
             REQUEST_CAMERA, REQUEST_GALLERY -> {
@@ -3678,6 +3864,10 @@ class CraftBridge(
                 handleContactPickerResult(resultCode, data)
                 true
             }
+            REQUEST_SHARE -> {
+                handleShareResult()
+                true
+            }
             else -> healthConnect.onActivityResult(requestCode, resultCode, data)
         }
     }
@@ -3697,6 +3887,11 @@ class CraftBridge(
         CraftNative.close(activity)
         healthConnect.close()
 
+        if (shareReceiverRegistered) {
+            runCatching { activity.unregisterReceiver(shareChosenReceiver) }
+            shareReceiverRegistered = false
+        }
+
         runCatching { speechRecognizer?.cancel() }
         runCatching { speechRecognizer?.destroy() }
         speechRecognizer = null
@@ -3756,6 +3951,7 @@ class CraftBridge(
         isKeepingAwake = false
         pendingPermissionRequests.clear()
         pendingEvents.clear()
+        pendingDeepLinks.clear()
     }
 
     // ==================== Screen Capture ====================
@@ -4529,13 +4725,44 @@ class CraftBridge(
         }
     }
 
-    fun dispatchDeepLink(url: String) {
-        if (nativeDeepLinks && CraftNative.dispatchDeepLink(url)) return
-
-        // Store as initial URL if this is the first one
-        if (initialURL == null) {
-            initialURL = url
+    /**
+     * A link the activity received. The first one before any page was ready
+     * launched the app: it becomes getInitialURL's answer and is dispatched
+     * with `initial: true`. Every later link is `initial: false` and leaves
+     * getInitialURL alone, as on iOS.
+     */
+    fun receiveDeepLink(url: String) {
+        val initial = !hasBeenReady && !initialAssigned
+        if (initial) {
+            initialAssigned = true
+            launchURL = url
+            setInitialURL(url)
         }
+        if (bridgeReady) dispatchDeepLink(url, false) else pendingDeepLinks.add(url to initial)
+    }
+
+    fun saveDeepLinks(outState: Bundle) {
+        outState.putBoolean(STATE_LAUNCH_ASSIGNED, initialAssigned)
+        outState.putBoolean(STATE_PAGE_WAS_READY, hasBeenReady)
+        outState.putString(STATE_LAUNCH_URL, launchURL)
+    }
+
+    /**
+     * A recreated activity loads a new WebView and a fresh document, so the
+     * launch link is queued again for that document's first subscriber, the
+     * way it was for the first one; a page that called getInitialURL claims
+     * it as before. Links that arrive now are never the launch link.
+     */
+    fun restoreDeepLinks(savedState: Bundle) {
+        initialAssigned = savedState.getBoolean(STATE_LAUNCH_ASSIGNED, true)
+        hasBeenReady = savedState.getBoolean(STATE_PAGE_WAS_READY, true)
+        launchURL = savedState.getString(STATE_LAUNCH_URL)
+        setInitialURL(launchURL)
+        launchURL?.let { pendingDeepLinks.add(it to true) }
+    }
+
+    private fun dispatchDeepLink(url: String, initial: Boolean) {
+        if (nativeDeepLinks && CraftNative.dispatchDeepLink(url, initial)) return
 
         val uri = Uri.parse(url)
         val json = JSONObject().apply {
@@ -4550,6 +4777,7 @@ class CraftBridge(
                 queryParams.put(name, uri.getQueryParameter(name) ?: "")
             }
             put("queryParams", queryParams)
+            put("initial", initial)
         }
 
         evaluateJavascriptUnlessClosed(
@@ -4620,6 +4848,9 @@ class CraftBridge(
     }
 
     companion object {
+        private const val STATE_LAUNCH_ASSIGNED = "craft.deepLinks.launchAssigned"
+        private const val STATE_PAGE_WAS_READY = "craft.deepLinks.pageWasReady"
+        private const val STATE_LAUNCH_URL = "craft.deepLinks.launchURL"
         private val MIME_TYPE = Regex("^[^\\s/]+/[^\\s/]+$")
         const val REQUEST_CAMERA = 1001
         const val REQUEST_GALLERY = 1002
@@ -4631,6 +4862,7 @@ class CraftBridge(
         const val REQUEST_VIDEO = 1008
         const val REQUEST_BLUETOOTH = 1009
         const val REQUEST_PICK_CONTACT = 1010
+        const val REQUEST_SHARE = 1011
         private const val PERMISSION_REQUEST_START = 2000
         private const val PERMISSION_REQUEST_END = 2999
         private const val LOCATION_REQUEST_TIMEOUT_MS = 15_000L

package/dist/android/templates/CraftNative.kt.template

@@ -1,6 +1,7 @@
 package com.craft.runtime
 
 import android.app.Activity
+import android.content.IntentSender
 import com.google.android.gms.location.Priority
 import com.google.android.gms.location.LocationServices
 import com.google.android.gms.location.LocationResult
@@ -110,10 +111,24 @@ object CraftNative {
      */
     val isAvailable: Boolean = try {
         System.loadLibrary("craft")
+        // Said out loud, because the two outcomes below are otherwise
+        // indistinguishable from outside: a library that never shipped and a
+        // library that loaded and then failed to bind both end with the shim
+        // answering every call. Zig logs its own registration under the same
+        // tag, so the pair reads as a sequence.
+        android.util.Log.i("CraftNative", "craft: libcraft.so loaded")
         true
     } catch (e: UnsatisfiedLinkError) {
+        // The reason, not just the fact. This used to be a bare `false`, and
+        // the first time the runtime was genuinely shipped and genuinely
+        // failed to load, the only evidence anywhere was that nothing
+        // happened — no linker line, no exception, nothing in logcat at all.
+        // The message carries the dynamic linker's own complaint, which is the
+        // one thing that says *why*.
+        android.util.Log.w("CraftNative", "craft: libcraft.so did not load: ${e.message}")
         false
     } catch (e: SecurityException) {
+        android.util.Log.w("CraftNative", "craft: libcraft.so was refused: ${e.message}")
         false
     }
 
@@ -213,7 +228,7 @@ object CraftNative {
     private external fun nativeClipboardRead(activity: Activity): String?
     private external fun nativeClipboardWrite(activity: Activity, text: String): Boolean
     private external fun nativeOpenUrl(activity: Activity, url: String): Boolean
-    private external fun nativeShare(activity: Activity, text: String, title: String): Boolean
+    private external fun nativeShare(activity: Activity, text: String, title: String, chosen: IntentSender, requestCode: Int): Boolean
     private external fun nativeOpenCamera(activity: Activity): Boolean
     private external fun nativePickImage(activity: Activity): Boolean
     private external fun nativePickFile(activity: Activity): Boolean
@@ -235,7 +250,7 @@ object CraftNative {
     private external fun nativeResetDeepLinks(): Boolean
     private external fun nativeSetInitialURL(url: String?): Boolean
     private external fun nativeGetInitialURL(): Boolean
-    private external fun nativeDispatchDeepLink(url: String): Boolean
+    private external fun nativeDispatchDeepLink(url: String, initial: Boolean): Boolean
     private external fun nativeScreenshotReady(bytes: ByteArray)
     private external fun nativeScreenshotError(message: String)
     private external fun nativeTakeScreenshot(activity: Activity, webView: WebView): Boolean
@@ -411,11 +426,15 @@ object CraftNative {
         }
     }
 
-    /** Returns whether Zig launched the share sheet; false falls through. */
-    fun share(activity: Activity, text: String, title: String): Boolean {
+    /**
+     * Returns whether Zig launched the share menu for a result; false falls
+     * through. `chosen` fires on a pick and `requestCode` routes the result
+     * back to CraftBridge, which settles the page's promise from the two.
+     */
+    fun share(activity: Activity, text: String, title: String, chosen: IntentSender, requestCode: Int): Boolean {
         if (!isAvailable) return false
         return try {
-            nativeShare(activity, text, title)
+            nativeShare(activity, text, title, chosen, requestCode)
         } catch (e: UnsatisfiedLinkError) {
             false
         }
@@ -697,9 +716,9 @@ object CraftNative {
         return try { nativeGetInitialURL() } catch (e: UnsatisfiedLinkError) { false }
     }
 
-    fun dispatchDeepLink(url: String): Boolean {
+    fun dispatchDeepLink(url: String, initial: Boolean): Boolean {
         if (!isAvailable) return false
-        return try { nativeDispatchDeepLink(url) } catch (e: UnsatisfiedLinkError) { false }
+        return try { nativeDispatchDeepLink(url, initial) } catch (e: UnsatisfiedLinkError) { false }
     }
 
     @JvmStatic