craft-native 0.0.91 → 0.0.94

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
@@ -216,8 +219,43 @@ class CraftBridge(
     private val mainExecutor: Executor = ContextCompat.getMainExecutor(activity)
     @Volatile
     private var bridgeReady = false
+
+    /**
+     * Which navigation the bridge belongs to.
+     *
+     * `evaluateJavascript`'s completion is posted, so it can run after the
+     * next navigation has already started. Without this, a completion from
+     * the page that has just left marks the page that has just arrived as
+     * ready, and the queues below flush into a document with no bridge and no
+     * replay listener — where they are lost rather than delivered (#228).
+     *
+     * Main thread only, like everything that touches `bridgeReady`.
+     */
+    private var navigationGeneration = 0
     private val pendingEvents = mutableListOf<Pair<String, Map<String, Any>>>()
 
+    // What the app was built with (#209). The page refuses a disabled call
+    // before it gets here; these are the second check, for a caller that
+    // reaches CraftAndroid directly, on the capabilities Android itself does
+    // not gate with a permission.
+    private val hapticsEnabled = {{ENABLE_HAPTICS}}
+    private val speechEnabled = {{ENABLE_SPEECH}}
+    private val shareEnabled = {{ENABLE_SHARE}}
+    private val keepAwakeEnabled = {{ENABLE_KEEP_AWAKE}}
+
+    private fun disabled(capability: String, call: String): Boolean {
+        android.util.Log.d("CraftBridge", "$call refused: $capability is disabled in craft.config.json")
+        return true
+    }
+
+    // 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>()
@@ -302,11 +340,33 @@ class CraftBridge(
      */
     private fun jsQuote(value: Any?): String = JSONObject.quote(value.toString())
 
+    /**
+     * The script, guarded so a second run in the *same* document does nothing.
+     *
+     * Chromium calls `onPageFinished` without a matching `onPageStarted` for
+     * same-document navigations — a fragment change, a `history.pushState` —
+     * and `MainActivity` injects on every one of them. Running the whole
+     * script again replaces `window.craft`, fires `craftReady` a second time,
+     * and rejects every in-flight promise with "Android bridge reinitialized"
+     * (#228).
+     *
+     * A block, not a function: `var` and function declarations are
+     * function-scoped, so the script behaves exactly as it does unwrapped,
+     * and everything it publishes it publishes on `window` regardless. A real
+     * navigation gets a new `window`, so the flag is absent and it installs.
+     */
+    private fun onlyOnce(script: String): String =
+        "if (!window.__craftBridgeInstalled) {\nwindow.__craftBridgeInstalled = true;\n$script\n}"
+
     fun injectBridge() {
         // Before the script, so a native callback arriving while the page is
         // 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}}
@@ -352,22 +412,39 @@ class CraftBridge(
                     screenCapture: false
                 },
 
-                // Haptic feedback
+                // Haptic feedback.
+                //
+                // These four answer the page, as iOS does since #207. A
+                // @JavascriptInterface method answers its caller
+                // synchronously, so unlike the calls above there is no
+                // channel to park: the Kotlin method's own return value is
+                // the answer. The call goes inside `.then` so that a native
+                // failure rejects rather than throwing at the caller, which
+                // is the shape every other promise here has.
+                //
+                // `=== true` because a WebView reports some failures as
+                // `undefined` rather than as a throw, and `undefined` is
+                // exactly what #219 was about.
                 haptic: function(style) {
-                    CraftAndroid.haptic(style || 'medium');
+                    return Promise.resolve().then(function() { return CraftAndroid.haptic(style || 'medium') === true; });
                 },
 
                 // Speech recognition
                 startListening: function() {
-                    CraftAndroid.startListening();
+                    return Promise.resolve().then(function() { return CraftAndroid.startListening() === true; });
                 },
                 stopListening: function() {
-                    CraftAndroid.stopListening();
+                    return Promise.resolve().then(function() { return CraftAndroid.stopListening() === true; });
                 },
 
-                // 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
@@ -492,7 +569,7 @@ class CraftBridge(
 
                 // Vibration Pattern
                 vibrate: function(pattern) {
-                    CraftAndroid.vibrate(JSON.stringify(pattern));
+                    return Promise.resolve().then(function() { return CraftAndroid.vibrate(JSON.stringify(pattern)) === true; });
                 },
 
                 // App State
@@ -590,7 +667,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 +1068,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 +1424,126 @@ class CraftBridge(
                 }
             };
 
+            // What the app was built with, enforced and not just reported
+            // (#209). iOS refuses a call whose capability is off with
+            // CAPABILITY_DISABLED, in Swift and in Zig; Android shaped the
+            // manifest and craft.capabilities from the same flags and then
+            // served the call anyway, so a page that feature-detected and a
+            // page that just called got different behaviour.
+            //
+            // The refusal is made here, from the same capabilities object the
+            // page can read, because that object is what this bridge promises.
+            // Calls that answer nothing cannot carry a refusal, so they do
+            // nothing and say so on the console, which is what a capability
+            // the app never asked for should do. What is left answering
+            // nothing is flashlight, keepAwake and the flat watch API (#220).
+            //
+            // Kotlin refuses the ungated-by-Android ones a second time, for a
+            // caller that reaches CraftAndroid without going through here.
+            (function installCapabilityGates(craft) {
+                var gated = [
+                    ['haptic', 'haptics', true],
+                    ['vibrate', 'haptics', true],
+                    ['startListening', 'speechRecognition', true],
+                    ['setFlashlight', 'flashlight'],
+                    ['toggleFlashlight', 'flashlight'],
+                    ['setKeepAwake', 'keepAwake'],
+                    ['watchPosition', 'geolocation'],
+                    ['clearWatch', 'geolocation'],
+                    ['share', 'share', true],
+                    ['openCamera', 'camera', true],
+                    ['pickImage', 'camera', true],
+                    ['startVideoRecording', 'camera', true],
+                    ['authenticate', 'biometric', true],
+                    ['registerPush', 'pushNotifications', true],
+                    ['getCurrentPosition', 'geolocation', true],
+                    ['secureStore.set', 'secureStorage', true],
+                    ['secureStore.get', 'secureStorage', true],
+                    ['secureStore.remove', 'secureStorage', true],
+                    ['notifications.schedule', 'localNotifications', true],
+                    ['notifications.cancel', 'localNotifications', true],
+                    ['notifications.cancelAll', 'localNotifications', true],
+                    ['deepLinks.getInitialURL', 'deepLinks', true]
+                ];
+                function refusal(capability) {
+                    var error = new Error(capability + ' is disabled: this app was built without it');
+                    error.code = 'CAPABILITY_DISABLED';
+                    error.bridge = true;
+                    return error;
+                }
+                gated.forEach(function(entry) {
+                    var path = entry[0].split('.');
+                    var capability = entry[1];
+                    var awaited = entry[2] === true;
+                    var owner = path.length > 1 ? craft[path[0]] : craft;
+                    var name = path[path.length - 1];
+                    if (!owner || typeof owner[name] !== 'function') { return; }
+                    var served = owner[name];
+                    owner[name] = function() {
+                        if (craft.capabilities[capability]) { return served.apply(this, arguments); }
+                        if (awaited) { return Promise.reject(refusal(capability)); }
+                        console.warn('craft: ' + name + ' did nothing because ' + capability + ' is disabled');
+                        return undefined;
+                    };
+                });
+            })(window.craft);
+
+            // 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);
@@ -1357,11 +1555,26 @@ class CraftBridge(
                     getInfo: function() { return Promise.resolve().then(function() { return craft.getDeviceInfo(); }); },
                     getCapabilities: function() { return Promise.resolve(Object.assign({}, craft.capabilities)); }
                 };
+                // Haptics are feedback, so an app built without them has
+                // nothing to play here rather than something to fail: `await
+                // haptics.selection()` in the middle of a flow must not stop
+                // the flow. Any other failure still rejects, and
+                // craft.haptic() itself reports the refusal. The same split
+                // iOS draws since #207, which Android could not draw until
+                // craft.haptic() had an answer to give.
+                function hapticFeedback(answer) {
+                    return answer.then(function() {}, function(error) {
+                        if (error && error.code === 'CAPABILITY_DISABLED') return;
+                        throw error;
+                    });
+                }
                 craft.haptics = {
-                    impact: function(style) { return Promise.resolve().then(function() { craft.haptic(style || 'medium'); }); },
-                    notification: function(type) { return Promise.resolve().then(function() { craft.haptic(type === 'error' ? 'heavy' : 'light'); }); },
-                    selection: function() { return Promise.resolve().then(function() { craft.haptic('selection'); }); },
-                    vibrate: function(pattern) { return Promise.resolve().then(function() { craft.vibrate(pattern || []); }); }
+                    impact: function(style) { return hapticFeedback(craft.haptic(style || 'medium')); },
+                    notification: function(type) {
+                        return hapticFeedback(craft.haptic(type === 'error' ? 'heavy' : type === 'warning' ? 'medium' : 'light'));
+                    },
+                    selection: function() { return hapticFeedback(craft.haptic('selection')); },
+                    vibrate: function(pattern) { return hapticFeedback(craft.vibrate(pattern || [])); }
                 };
                 craft.camera = {
                     takePicture: function() { return legacyOpenCamera().then(normalizePhoto); },
@@ -1471,25 +1684,47 @@ class CraftBridge(
 
         activity.runOnUiThread {
             if (closed) return@runOnUiThread
-            webView.evaluateJavascript(script) {
+            // Read here rather than at entry: this is the navigation the
+            // script is actually being injected into.
+            val generation = navigationGeneration
+            webView.evaluateJavascript(onlyOnce(script)) {
                 if (closed) return@evaluateJavascript
+                // A completion for a page that has since navigated away.
+                // Marking ready now would flush into the new document, which
+                // has no bridge yet, and the queues would be spent on it.
+                if (generation != navigationGeneration) return@evaluateJavascript
                 bridgeReady = true
                 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) }
             }
         }
     }
 
     fun markBridgeLoading() {
         bridgeReady = false
+        // A document is on its way out, so any injection still in flight is
+        // for a page that no longer exists.
+        navigationGeneration += 1
     }
 
     // ==================== Haptics ====================
 
+    /**
+     * Whether the device took the call, which is the answer the page awaits
+     * since #219. False is "nothing played": haptics are off, or the vibrator
+     * refused. It is never an error, because haptics decorate a flow rather
+     * than carry it.
+     */
     @JavascriptInterface
-    fun haptic(style: String) {
-        if (CraftNative.haptic(activity, style)) return
+    fun haptic(style: String): Boolean {
+        if (!hapticsEnabled && disabled("haptics", "haptic")) return false
+        if (CraftNative.haptic(activity, style)) return true
 
         val vibrator = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
             val vibratorManager = activity.getSystemService(Context.VIBRATOR_MANAGER_SERVICE) as VibratorManager
@@ -1515,113 +1750,224 @@ class CraftBridge(
             @Suppress("DEPRECATION")
             vibrator.vibrate(20)
         }
+        return true
     }
 
     // ==================== Speech Recognition ====================
 
+    /**
+     * Whether the request was taken, which is what iOS answers too: the
+     * outcome arrives as craftSpeech* events, not here (#207, #219).
+     *
+     * Asking for the microphone counts as taken. iOS starts recording from
+     * inside its authorization callback, so Android does the same from
+     * onRequestPermissionsResult below; before #219 the grant was dropped and
+     * the page heard nothing at all, not even craftSpeechError.
+     */
     @JavascriptInterface
-    fun startListening() {
-        if (CraftNative.startListening(activity)) return
+    fun startListening(): Boolean {
+        if (!speechEnabled && disabled("speechRecognition", "startListening")) return false
+        if (CraftNative.startListening(activity)) return true
 
         if (!SpeechRecognizer.isRecognitionAvailable(activity)) {
             sendEvent("craftSpeechError", mapOf("error" to "Speech recognition not available"))
-            return
+            return false
         }
 
         activity.runOnUiThread {
             if (closed) return@runOnUiThread
             if (ContextCompat.checkSelfPermission(activity, Manifest.permission.RECORD_AUDIO)
                 != PackageManager.PERMISSION_GRANTED) {
-                requestPermissionsBestEffort(arrayOf(Manifest.permission.RECORD_AUDIO), 100)
+                requestPermissionsBestEffort(arrayOf(Manifest.permission.RECORD_AUDIO), REQUEST_SPEECH)
                 return@runOnUiThread
             }
+            beginSpeechRecognition()
+        }
+        return true
+    }
 
-            speechRecognizer = SpeechRecognizer.createSpeechRecognizer(activity)
-            speechRecognizer?.setRecognitionListener(object : RecognitionListener {
-                override fun onReadyForSpeech(params: Bundle?) {
-                    isListening = true
-                    sendEvent("craftSpeechStart", emptyMap())
-                    haptic("light")
-                }
-
-                override fun onBeginningOfSpeech() {}
-                override fun onRmsChanged(rmsdB: Float) {}
-                override fun onBufferReceived(buffer: ByteArray?) {}
-                override fun onEndOfSpeech() {}
-
-                override fun onError(error: Int) {
-                    isListening = false
-                    val errorMsg = when (error) {
-                        SpeechRecognizer.ERROR_AUDIO -> "Audio recording error"
-                        SpeechRecognizer.ERROR_CLIENT -> "Client error"
-                        SpeechRecognizer.ERROR_INSUFFICIENT_PERMISSIONS -> "Insufficient permissions"
-                        SpeechRecognizer.ERROR_NETWORK -> "Network error"
-                        SpeechRecognizer.ERROR_NETWORK_TIMEOUT -> "Network timeout"
-                        SpeechRecognizer.ERROR_NO_MATCH -> "No match"
-                        SpeechRecognizer.ERROR_RECOGNIZER_BUSY -> "Recognizer busy"
-                        SpeechRecognizer.ERROR_SERVER -> "Server error"
-                        SpeechRecognizer.ERROR_SPEECH_TIMEOUT -> "Speech timeout"
-                        else -> "Unknown error"
-                    }
-                    sendEvent("craftSpeechError", mapOf("error" to errorMsg))
-                    haptic("light")
-                }
-
-                override fun onResults(results: Bundle?) {
-                    isListening = false
-                    val matches = results?.getStringArrayList(SpeechRecognizer.RESULTS_RECOGNITION)
-                    val transcript = matches?.firstOrNull() ?: ""
-                    sendEvent("craftSpeechResult", mapOf("transcript" to transcript, "isFinal" to true))
-                    sendEvent("craftSpeechEnd", emptyMap())
-                    haptic("light")
-                }
+    /** The recogniser itself, on the main thread with RECORD_AUDIO granted. */
+    private fun beginSpeechRecognition() {
+        if (closed) return
+        speechRecognizer = SpeechRecognizer.createSpeechRecognizer(activity)
+        speechRecognizer?.setRecognitionListener(object : RecognitionListener {
+            override fun onReadyForSpeech(params: Bundle?) {
+                isListening = true
+                sendEvent("craftSpeechStart", emptyMap())
+                haptic("light")
+            }
 
-                override fun onPartialResults(partialResults: Bundle?) {
-                    val matches = partialResults?.getStringArrayList(SpeechRecognizer.RESULTS_RECOGNITION)
-                    val transcript = matches?.firstOrNull() ?: ""
-                    sendEvent("craftSpeechResult", mapOf("transcript" to transcript, "isFinal" to false))
+            override fun onBeginningOfSpeech() {}
+            override fun onRmsChanged(rmsdB: Float) {}
+            override fun onBufferReceived(buffer: ByteArray?) {}
+            override fun onEndOfSpeech() {}
+
+            override fun onError(error: Int) {
+                isListening = false
+                val errorMsg = when (error) {
+                    SpeechRecognizer.ERROR_AUDIO -> "Audio recording error"
+                    SpeechRecognizer.ERROR_CLIENT -> "Client error"
+                    SpeechRecognizer.ERROR_INSUFFICIENT_PERMISSIONS -> "Insufficient permissions"
+                    SpeechRecognizer.ERROR_NETWORK -> "Network error"
+                    SpeechRecognizer.ERROR_NETWORK_TIMEOUT -> "Network timeout"
+                    SpeechRecognizer.ERROR_NO_MATCH -> "No match"
+                    SpeechRecognizer.ERROR_RECOGNIZER_BUSY -> "Recognizer busy"
+                    SpeechRecognizer.ERROR_SERVER -> "Server error"
+                    SpeechRecognizer.ERROR_SPEECH_TIMEOUT -> "Speech timeout"
+                    else -> "Unknown error"
                 }
+                sendEvent("craftSpeechError", mapOf("error" to errorMsg))
+                haptic("light")
+            }
 
-                override fun onEvent(eventType: Int, params: Bundle?) {}
-            })
+            override fun onResults(results: Bundle?) {
+                isListening = false
+                val matches = results?.getStringArrayList(SpeechRecognizer.RESULTS_RECOGNITION)
+                val transcript = matches?.firstOrNull() ?: ""
+                sendEvent("craftSpeechResult", mapOf("transcript" to transcript, "isFinal" to true))
+                sendEvent("craftSpeechEnd", emptyMap())
+                haptic("light")
+            }
 
-            val intent = Intent(RecognizerIntent.ACTION_RECOGNIZE_SPEECH).apply {
-                putExtra(RecognizerIntent.EXTRA_LANGUAGE_MODEL, RecognizerIntent.LANGUAGE_MODEL_FREE_FORM)
-                putExtra(RecognizerIntent.EXTRA_LANGUAGE, Locale.getDefault())
-                putExtra(RecognizerIntent.EXTRA_PARTIAL_RESULTS, true)
-                putExtra(RecognizerIntent.EXTRA_MAX_RESULTS, 1)
+            override fun onPartialResults(partialResults: Bundle?) {
+                val matches = partialResults?.getStringArrayList(SpeechRecognizer.RESULTS_RECOGNITION)
+                val transcript = matches?.firstOrNull() ?: ""
+                sendEvent("craftSpeechResult", mapOf("transcript" to transcript, "isFinal" to false))
             }
 
-            speechRecognizer?.startListening(intent)
+            override fun onEvent(eventType: Int, params: Bundle?) {}
+        })
+
+        val intent = Intent(RecognizerIntent.ACTION_RECOGNIZE_SPEECH).apply {
+            putExtra(RecognizerIntent.EXTRA_LANGUAGE_MODEL, RecognizerIntent.LANGUAGE_MODEL_FREE_FORM)
+            putExtra(RecognizerIntent.EXTRA_LANGUAGE, Locale.getDefault())
+            putExtra(RecognizerIntent.EXTRA_PARTIAL_RESULTS, true)
+            putExtra(RecognizerIntent.EXTRA_MAX_RESULTS, 1)
         }
+
+        speechRecognizer?.startListening(intent)
     }
 
+    /**
+     * Whether the request was taken. Ungated, as on iOS: stopping something
+     * an app was built without is a no-op, not a refusal, and a page tearing
+     * a screen down should not have to know which build it is running on.
+     */
     @JavascriptInterface
-    fun stopListening() {
-        if (CraftNative.stopListening(activity)) return
+    fun stopListening(): Boolean {
+        if (CraftNative.stopListening(activity)) return true
 
         activity.runOnUiThread {
             speechRecognizer?.stopListening()
             speechRecognizer?.destroy()
             speechRecognizer = null
-            isListening = false
+            // Only when something was listening, so a page that stops twice,
+            // or stops what never started, does not see a session end twice.
+            // iOS sends this from stopSpeechRecognition for the same reason.
+            if (isListening) {
+                isListening = false
+                sendEvent("craftSpeechEnd", emptyMap())
+            }
         }
+        return true
     }
 
     // ==================== 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
+        if (!shareEnabled) {
+            rejectShare("share is disabled: this app was built without it")
+            disabled("share", "share")
+            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
+        }
 
-        val intent = Intent(Intent.ACTION_SEND).apply {
-            type = "text/plain"
-            putExtra(Intent.EXTRA_TEXT, text)
-            if (title.isNotEmpty()) {
-                putExtra(Intent.EXTRA_SUBJECT, title)
+        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
+            }
+
+            // 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 ====================
@@ -2004,6 +2350,12 @@ class CraftBridge(
 
     fun onRequestPermissionsResult(requestCode: Int): Boolean {
         if (closed) return requestCode in PERMISSION_REQUEST_START..PERMISSION_REQUEST_END
+        // startListening asked for the microphone and is waiting on this.
+        if (requestCode == REQUEST_SPEECH) {
+            if (isPermissionGranted(Manifest.permission.RECORD_AUDIO)) beginSpeechRecognition()
+            else sendEvent("craftSpeechError", mapOf("error" to "Microphone permission denied"))
+            return true
+        }
         val pending = pendingPermissionRequests.remove(requestCode) ?: return false
         // Re-read package state instead of interpreting the parallel callback
         // arrays. In particular, an approximate-location choice returns a
@@ -2366,10 +2718,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
@@ -2543,9 +2934,11 @@ class CraftBridge(
 
     // ==================== Vibration Pattern ====================
 
+    /** Whether the pattern played, the same answer haptic() gives (#219). */
     @JavascriptInterface
-    fun vibrate(patternJson: String) {
-        if (CraftNative.vibrate(activity, patternJson)) return
+    fun vibrate(patternJson: String): Boolean {
+        if (!hapticsEnabled && disabled("haptics", "vibrate")) return false
+        if (CraftNative.vibrate(activity, patternJson)) return true
 
         val vibrator = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
             val vibratorManager = activity.getSystemService(Context.VIBRATOR_MANAGER_SERVICE) as VibratorManager
@@ -2566,8 +2959,10 @@ class CraftBridge(
                 @Suppress("DEPRECATION")
                 vibrator.vibrate(timings, -1)
             }
+            return true
         } catch (e: Exception) {
             log("Vibration error: ${e.message}")
+            return false
         }
     }
 
@@ -3144,6 +3539,7 @@ class CraftBridge(
 
     @JavascriptInterface
     fun setKeepAwake(enabled: Boolean): Boolean {
+        if (!keepAwakeEnabled && disabled("keepAwake", "setKeepAwake")) return false
         // Zig queues the same window call on the same looper. isKeepingAwake
         // below is written here and read nowhere, so the Kotlin body not
         // running leaves nothing stale — unlike the flashlight pair.
@@ -3190,18 +3586,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 +4043,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 +4062,10 @@ class CraftBridge(
                 handleContactPickerResult(resultCode, data)
                 true
             }
+            REQUEST_SHARE -> {
+                handleShareResult()
+                true
+            }
             else -> healthConnect.onActivityResult(requestCode, resultCode, data)
         }
     }
@@ -3697,6 +4085,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 +4149,7 @@ class CraftBridge(
         isKeepingAwake = false
         pendingPermissionRequests.clear()
         pendingEvents.clear()
+        pendingDeepLinks.clear()
     }
 
     // ==================== Screen Capture ====================
@@ -4529,13 +4923,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 +4975,7 @@ class CraftBridge(
                 queryParams.put(name, uri.getQueryParameter(name) ?: "")
             }
             put("queryParams", queryParams)
+            put("initial", initial)
         }
 
         evaluateJavascriptUnlessClosed(
@@ -4620,6 +5046,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 +5060,8 @@ class CraftBridge(
         const val REQUEST_VIDEO = 1008
         const val REQUEST_BLUETOOTH = 1009
         const val REQUEST_PICK_CONTACT = 1010
+        const val REQUEST_SHARE = 1011
+        const val REQUEST_SPEECH = 1012
         private const val PERMISSION_REQUEST_START = 2000
         private const val PERMISSION_REQUEST_END = 2999
         private const val LOCATION_REQUEST_TIMEOUT_MS = 15_000L