craft-native 0.0.92 → 0.0.94

package/README.md

@@ -453,6 +453,23 @@ See [benchmarks](../../benchmarks) for detailed performance comparisons.
 - **Zero dependencies** - Pure Node.js APIs only
 - **Better DX** - Hot reload and dev tools built-in
 
+## Native bridge error codes
+
+The mobile bridge declarations in `types/craft.d.ts` distinguish canonical
+`NativeBridgeErrorCode` values from the broader compatible `CraftErrorCode` union.
+The native wire vocabulary comes from `packages/zig/src/bridge_error.zig`; SDK
+parity tests fail if the declaration drifts. It includes `INVALID_PARAMETER`,
+`PLATFORM_NOT_SUPPORTED`, `NATIVE_CALL_FAILED`, `WEBVIEW_HANDLE_NOT_SET`, `BUSY`,
+and `CAPABILITY_DISABLED`.
+
+Existing mobile/shim names such as `INVALID_PARAMS` and `NOT_AVAILABLE` remain
+accepted by `CraftErrorCode` for source compatibility. They are not aliases that
+the SDK rewrites on the wire. Applications supporting multiple host versions
+should handle the codes those hosts actually return; new native error handling
+should use the canonical spellings. A capability disabled by app configuration
+is distinct from a user denying permission, and `BUSY` is distinct from a failed
+native call.
+
 ## Requirements
 
 - Bun >= 1.0.0 (for development)

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

@@ -3,6 +3,8 @@
  *
  * Generates native Android apps from web content using WebView.
  */
+/** Oldest Android API level supported by the generated Kotlin runtime. */
+export declare const ANDROID_MIN_SDK = 26;
 export interface CraftAndroidConfig {
     appName: string;
     packageName: string;
@@ -28,6 +30,7 @@ export interface CraftAndroidConfig {
     googleServicesFile?: string;
     devServerURL?: string;
     hasBundledFallback?: boolean;
+    /** Android API level, at least ANDROID_MIN_SDK (26). */
     minSdk?: number;
     compileSdk?: number;
     targetSdk?: number;

package/dist/android/src/index.js

@@ -110,6 +110,7 @@ var KOTLIN_KEYWORDS = new Set([
   "when",
   "while"
 ]);
+var ANDROID_MIN_SDK = 26;
 var DEFAULT_CONFIG = {
   version: "1.0.0",
   versionCode: 1,
@@ -129,7 +130,7 @@ var DEFAULT_CONFIG = {
   enableDeepLinks: false,
   urlSchemes: [],
   trustedOrigins: [],
-  minSdk: 26,
+  minSdk: ANDROID_MIN_SDK,
   compileSdk: 36,
   targetSdk: 35
 };
@@ -228,6 +229,9 @@ function validateAndroidConfig(config) {
       throw new Error(`Android ${name} must be a positive integer`);
     }
   }
+  if (Number(config.minSdk) < ANDROID_MIN_SDK) {
+    throw new Error(`Android minSdk must be at least ${ANDROID_MIN_SDK} (Android 8.0) for the Craft runtime`);
+  }
   if (Number(config.minSdk) > Number(config.targetSdk)) {
     throw new Error("Android minSdk must not exceed targetSdk");
   }
@@ -366,7 +370,6 @@ async function init(options) {
   if (config.enableBackgroundLocation)
     config.enableGeolocation = true;
   if (config.enableHealthConnect) {
-    config.minSdk = Math.max(config.minSdk ?? 26, 26);
     config.compileSdk = Math.max(config.compileSdk ?? 36, 36);
   }
   normalizeAndroidNetworkConfig(config);
@@ -450,7 +453,7 @@ async function init(options) {
   const projectGradleTemplate = readFileSync(join(TEMPLATES_DIR, "build.gradle.kts.project.template"), "utf-8");
   writeFileSync(join(output, "build.gradle.kts"), projectGradleTemplate.replace(/\{\{GOOGLE_SERVICES_PLUGIN\}\}/g, hasGoogleServices ? '    id("com.google.gms.google-services") version "4.4.2" apply false' : ""));
   const appGradleTemplate = readFileSync(join(TEMPLATES_DIR, "build.gradle.kts.app.template"), "utf-8");
-  const appGradle = appGradleTemplate.replace(/\{\{PACKAGE_NAME\}\}/g, finalPackageName).replace(/\{\{VERSION_NAME\}\}/g, escapeKotlinString(config.version || "1.0.0")).replace(/\{\{VERSION_CODE\}\}/g, String(config.versionCode || 1)).replace(/\{\{MIN_SDK\}\}/g, String(config.minSdk || 24)).replace(/\{\{COMPILE_SDK\}\}/g, String(config.compileSdk || 36)).replace(/\{\{TARGET_SDK\}\}/g, String(config.targetSdk || 35)).replace(/\{\{GOOGLE_SERVICES_PLUGIN\}\}/g, hasGoogleServices ? '    id("com.google.gms.google-services")' : "").replace(/\{\{FIREBASE_MESSAGING_DEPENDENCY\}\}/g, config.enablePushNotifications ? '    implementation("com.google.firebase:firebase-messaging:24.1.0")' : "").replace(/\{\{HEALTH_CONNECT_DEPENDENCIES\}\}/g, config.enableHealthConnect ? `    implementation("androidx.health.connect:connect-client:1.1.0")
+  const appGradle = appGradleTemplate.replace(/\{\{PACKAGE_NAME\}\}/g, finalPackageName).replace(/\{\{VERSION_NAME\}\}/g, escapeKotlinString(config.version || "1.0.0")).replace(/\{\{VERSION_CODE\}\}/g, String(config.versionCode || 1)).replace(/\{\{MIN_SDK\}\}/g, String(config.minSdk ?? ANDROID_MIN_SDK)).replace(/\{\{COMPILE_SDK\}\}/g, String(config.compileSdk || 36)).replace(/\{\{TARGET_SDK\}\}/g, String(config.targetSdk || 35)).replace(/\{\{GOOGLE_SERVICES_PLUGIN\}\}/g, hasGoogleServices ? '    id("com.google.gms.google-services")' : "").replace(/\{\{FIREBASE_MESSAGING_DEPENDENCY\}\}/g, config.enablePushNotifications ? '    implementation("com.google.firebase:firebase-messaging:24.1.0")' : "").replace(/\{\{HEALTH_CONNECT_DEPENDENCIES\}\}/g, config.enableHealthConnect ? `    implementation("androidx.health.connect:connect-client:1.1.0")
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1")` : "");
   writeFileSync(join(output, "app/build.gradle.kts"), appGradle);
   const proguardTemplate = readFileSync(join(TEMPLATES_DIR, "proguard-rules.pro.template"), "utf-8");
@@ -692,5 +695,6 @@ export {
   open,
   installRuntime,
   init,
-  build
+  build,
+  ANDROID_MIN_SDK
 };

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

@@ -219,8 +219,35 @@ 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.
@@ -313,6 +340,24 @@ 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
@@ -367,17 +412,29 @@ 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. Resolves true when the person picks an app, false
@@ -512,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
@@ -1367,6 +1424,70 @@ 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).
             //
@@ -1434,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); },
@@ -1548,8 +1684,15 @@ 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()
@@ -1565,13 +1708,23 @@ class CraftBridge(
 
     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
@@ -1597,97 +1750,126 @@ 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 ====================
@@ -1711,6 +1893,11 @@ class CraftBridge(
 
     @JavascriptInterface
     fun share(text: String, title: String) {
+        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()) {
@@ -2163,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
@@ -2741,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
@@ -2764,8 +2959,10 @@ class CraftBridge(
                 @Suppress("DEPRECATION")
                 vibrator.vibrate(timings, -1)
             }
+            return true
         } catch (e: Exception) {
             log("Vibration error: ${e.message}")
+            return false
         }
     }
 
@@ -3342,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.
@@ -4863,6 +5061,7 @@ class CraftBridge(
         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

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

@@ -212,14 +212,20 @@ object CraftNative {
     /**
      * Run `script` in the page. Called from Zig, on any thread.
      *
-     * Silent when no deliverer is installed — which is every moment before the
-     * WebView exists, and after it is torn down. A throw here would cross back
-     * into Zig as a pending exception on a thread that has nowhere to report
-     * it, and the caller already counts what it could not deliver.
+     * Returns whether a deliverer took it. False is every moment before the
+     * WebView exists and after it is torn down, and it used to be
+     * indistinguishable from a delivery: the script was dropped, Zig's caller
+     * reported success, and the page waited on a promise nothing would settle
+     * (#231). Zig counts a false, and says so once.
+     *
+     * Still no throw. A throw here would cross back into Zig as a pending
+     * exception on a thread with nowhere to report it; false says the same
+     * thing and the caller can act on it.
      */
     @JvmStatic
-    fun deliver(script: String) {
-        runCatching { deliverer?.invoke(script) }
+    fun deliver(script: String): Boolean {
+        val target = deliverer ?: return false
+        return runCatching { target(script); true }.getOrDefault(false)
     }
 
     private external fun nativeGetDeviceInfo(activity: Activity): String?