craft-native 0.0.115 → 0.0.118

package/dist/android/templates/AndroidManifest.xml.template

@@ -5,6 +5,14 @@
 {{PERMISSIONS}}
 {{HEALTH_CONNECT_QUERIES}}
 
+    <!-- craft.speech: from Android 11 an app cannot see, and so cannot bind,
+         a text-to-speech engine it has not declared it will look for. -->
+    <queries>
+        <intent>
+            <action android:name="android.intent.action.TTS_SERVICE" />
+        </intent>
+    </queries>
+
     <!-- Camera feature (optional) -->
     <uses-feature android:name="android.hardware.camera" android:required="false" />
     <uses-feature android:name="android.hardware.camera.autofocus" android:required="false" />

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

@@ -36,6 +36,11 @@ import android.provider.Settings
 import android.speech.RecognitionListener
 import android.speech.RecognizerIntent
 import android.speech.SpeechRecognizer
+import android.speech.tts.TextToSpeech
+import android.speech.tts.UtteranceProgressListener
+import android.media.AudioAttributes
+import android.media.AudioFocusRequest
+import android.media.AudioManager
 import android.util.DisplayMetrics
 import android.webkit.JavascriptInterface
 import android.webkit.WebView
@@ -199,6 +204,17 @@ internal object CraftPermissionPolicy {
             isGranted(Manifest.permission.ACCESS_COARSE_LOCATION)
 }
 
+private data class SpeechRequest(
+    val text: String,
+    val rate: Float,
+    val language: String?,
+    val callbackId: Int,
+    val generation: Int
+)
+
+/** The navigation it belongs to, so a page that has gone hears nothing. */
+private data class PendingUtterance(val callbackId: Int, val generation: Int)
+
 private data class PendingPermissionRequest(
     val callbackId: Int,
     val permission: String,
@@ -279,6 +295,19 @@ class CraftBridge(
     // Keep awake
     private var isKeepingAwake = false
 
+    // Speech synthesis, all of it touched on the main thread only. The engine
+    // is bound on the first speak rather than here, so an app that never
+    // speaks never starts a TTS service. Requests made while it binds wait in
+    // queuedSpeech; each utterance handed to it waits in pendingUtterances,
+    // under the id the engine reports back, for the page call it answers.
+    private var textToSpeech: TextToSpeech? = null
+    private var textToSpeechReady = false
+    private val queuedSpeech = mutableListOf<SpeechRequest>()
+    private val pendingUtterances = linkedMapOf<String, PendingUtterance>()
+    private var nextUtteranceId = 0L
+    private var speechFocusRequest: AudioFocusRequest? = null
+    private val speechHandler = Handler(Looper.getMainLooper())
+
     // Billing clients for in-app purchases
     private var productBillingClient: BillingClient? = null
     private var restoreBillingClient: BillingClient? = null
@@ -388,6 +417,7 @@ class CraftBridge(
                     networkStatus: true,
                     appReview: true,
                     flashlight: {{ENABLE_CAMERA}} && ${hasFlashlight()},
+                    speech: true,
                     openURL: true,
                     vibrationPattern: true,
                     appState: true,
@@ -1642,6 +1672,66 @@ class CraftBridge(
                         return Promise.resolve().then(function() { CraftAndroid.openPermissionSettings(); });
                     }
                 };
+                // Speech synthesis. speak() settles when the utterance ends:
+                // true when it was spoken, false when something stopped it
+                // or the device has no engine to speak with. No timeout, as
+                // on iOS: a long sentence at a slow rate outlasts any
+                // deadline that would be fair to a short cue.
+                var speechRequestSequence = 0;
+                var speechRequests = Object.create(null);
+                var speechRuntimeClosed = false;
+                window.__craftSpeechResult = function(id, spoken) {
+                    if (speechRuntimeClosed) return;
+                    var pending = speechRequests[id];
+                    if (!pending) return;
+                    delete speechRequests[id];
+                    pending.resolve(spoken === true);
+                };
+                window.__craftSpeechError = function(id, message, code) {
+                    if (speechRuntimeClosed) return;
+                    var pending = speechRequests[id];
+                    if (!pending) return;
+                    delete speechRequests[id];
+                    var error = new Error(message);
+                    error.code = code || 'CRAFT_ERROR';
+                    error.bridge = true;
+                    pending.reject(error);
+                };
+                window.__craftRejectSpeechRequests = function(message) {
+                    speechRuntimeClosed = true;
+                    Object.keys(speechRequests).forEach(function(id) {
+                        var pending = speechRequests[id];
+                        delete speechRequests[id];
+                        pending.reject(new Error(message || 'Android bridge closed'));
+                    });
+                };
+                craft.speech = {
+                    speak: function(text, options) {
+                        if (speechRuntimeClosed) {
+                            return Promise.reject(new Error('Android bridge is closed'));
+                        }
+                        options = options || {};
+                        var settings = JSON.stringify({
+                            rate: typeof options.rate === 'number' ? options.rate : null,
+                            language: typeof options.language === 'string' ? options.language : null,
+                            interrupt: options.interrupt !== false
+                        });
+                        return new Promise(function(resolve, reject) {
+                            speechRequestSequence += 1;
+                            var id = speechRequestSequence;
+                            speechRequests[id] = {resolve: resolve, reject: reject};
+                            try {
+                                CraftAndroid.speak(text == null ? '' : String(text), settings, id);
+                            } catch (error) {
+                                delete speechRequests[id];
+                                reject(error);
+                            }
+                        });
+                    },
+                    stop: function() {
+                        return Promise.resolve().then(function() { CraftAndroid.stopSpeaking(); });
+                    }
+                };
                 craft.location = {
                     getCurrentPosition: craft.getCurrentPosition,
                     watchPosition: craft.watchPosition,
@@ -3556,6 +3646,189 @@ class CraftBridge(
         return true
     }
 
+    // ==================== Speech Synthesis ====================
+
+    /**
+     * Say [text], and answer the page's call [callbackId] once it has been
+     * said (`true`) or stopped (`false`).
+     *
+     * The audio is marked as navigation guidance and asks for transient,
+     * may-duck focus, which is what makes the music dip under the cue rather
+     * than stop, and come back once [abandonSpeechFocus] runs. The WebView's
+     * own `speechSynthesis` has no say in either.
+     */
+    @JavascriptInterface
+    fun speak(text: String?, optionsJson: String?, callbackId: Int) {
+        activity.runOnUiThread {
+            if (closed) return@runOnUiThread
+            if (text.isNullOrBlank()) {
+                rejectSpeech(callbackId, "speak needs some text to say", "INVALID_ARGUMENT")
+                return@runOnUiThread
+            }
+            val options = runCatching { JSONObject(optionsJson ?: "{}") }.getOrElse { JSONObject() }
+            val rate = if (options.isNull("rate")) 1.0 else options.optDouble("rate", 1.0)
+            val request = SpeechRequest(
+                text = text,
+                // 1 is normal on both scales, so this only bounds it.
+                rate = (if (rate.isFinite()) rate else 1.0).coerceIn(0.5, 2.0).toFloat(),
+                language = if (options.isNull("language")) null else options.optString("language").ifBlank { null },
+                callbackId = callbackId,
+                generation = navigationGeneration
+            )
+            if (options.optBoolean("interrupt", true)) cancelPendingSpeech()
+
+            val engine = textToSpeech
+            if (engine != null && textToSpeechReady) {
+                startUtterance(engine, request)
+            } else {
+                queuedSpeech.add(request)
+                bindTextToSpeech()
+            }
+        }
+    }
+
+    @JavascriptInterface
+    fun stopSpeaking(): Boolean {
+        activity.runOnUiThread {
+            if (closed) return@runOnUiThread
+            cancelPendingSpeech()
+            abandonSpeechFocus()
+        }
+        return true
+    }
+
+    private val speechAudioAttributes: AudioAttributes by lazy {
+        AudioAttributes.Builder()
+            .setUsage(AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE)
+            .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
+            .build()
+    }
+
+    /** Main thread. Binding takes a moment, and finishes in the listener. */
+    private fun bindTextToSpeech() {
+        if (textToSpeech != null) return
+        var engine: TextToSpeech? = null
+        // Posted, never run inline: an engine that cannot bind reports so
+        // from inside its own constructor, before `engine` has been assigned,
+        // and runOnUiThread on the main thread would run it right there.
+        engine = TextToSpeech(activity.applicationContext) { status ->
+            speechHandler.post { onTextToSpeechBound(engine, status == TextToSpeech.SUCCESS) }
+        }
+        textToSpeech = engine
+    }
+
+    private fun onTextToSpeechBound(engine: TextToSpeech?, succeeded: Boolean) {
+        // An engine that close() or a failed earlier bind has since replaced.
+        if (closed || engine == null || engine !== textToSpeech) return
+        val waiting = queuedSpeech.toList()
+        queuedSpeech.clear()
+        if (!succeeded) {
+            // No engine, or none that would start. Each call settles as
+            // "nothing was said", and the next speak tries binding again.
+            runCatching { engine.shutdown() }
+            textToSpeech = null
+            waiting.forEach { settleSpeech(it.callbackId, it.generation, false) }
+            return
+        }
+        engine.setAudioAttributes(speechAudioAttributes)
+        engine.setOnUtteranceProgressListener(object : UtteranceProgressListener() {
+            override fun onStart(utteranceId: String?) {}
+            override fun onDone(utteranceId: String?) {
+                activity.runOnUiThread { utteranceEnded(utteranceId, true) }
+            }
+            @Deprecated("Deprecated in Java")
+            override fun onError(utteranceId: String?) {
+                activity.runOnUiThread { utteranceEnded(utteranceId, false) }
+            }
+            override fun onError(utteranceId: String?, errorCode: Int) {
+                activity.runOnUiThread { utteranceEnded(utteranceId, false) }
+            }
+            override fun onStop(utteranceId: String?, interrupted: Boolean) {
+                activity.runOnUiThread { utteranceEnded(utteranceId, false) }
+            }
+        })
+        textToSpeechReady = true
+        waiting.forEach { startUtterance(engine, it) }
+    }
+
+    private fun startUtterance(engine: TextToSpeech, request: SpeechRequest) {
+        if (!requestSpeechFocus()) {
+            // A call, or something else that may not be talked over.
+            settleSpeech(request.callbackId, request.generation, false)
+            return
+        }
+        // Both apply to the speak calls after them, so each utterance sets
+        // its own rather than inheriting the last one's.
+        engine.setSpeechRate(request.rate)
+        val locale = request.language?.let { Locale.forLanguageTag(it) }
+        if (locale == null || engine.setLanguage(locale) < TextToSpeech.LANG_AVAILABLE) {
+            engine.setLanguage(Locale.getDefault())
+        }
+
+        nextUtteranceId += 1
+        val utteranceId = "craft-speech-$nextUtteranceId"
+        pendingUtterances[utteranceId] = PendingUtterance(request.callbackId, request.generation)
+        if (engine.speak(request.text, TextToSpeech.QUEUE_ADD, null, utteranceId) != TextToSpeech.SUCCESS) {
+            pendingUtterances.remove(utteranceId)
+            settleSpeech(request.callbackId, request.generation, false)
+            if (pendingUtterances.isEmpty()) abandonSpeechFocus()
+        }
+    }
+
+    private fun utteranceEnded(utteranceId: String?, spoken: Boolean) {
+        val pending = utteranceId?.let { pendingUtterances.remove(it) }
+        if (pending != null) settleSpeech(pending.callbackId, pending.generation, spoken)
+        if (pendingUtterances.isEmpty() && queuedSpeech.isEmpty()) abandonSpeechFocus()
+    }
+
+    /**
+     * Stop the engine and settle every call waiting on it, false.
+     *
+     * Settled here rather than in `onStop`, so that a request still waiting
+     * for the engine to bind, which the engine has never heard of, settles
+     * too.
+     */
+    private fun cancelPendingSpeech() {
+        val waiting = pendingUtterances.values.toList() +
+            queuedSpeech.map { PendingUtterance(it.callbackId, it.generation) }
+        pendingUtterances.clear()
+        queuedSpeech.clear()
+        if (textToSpeechReady) runCatching { textToSpeech?.stop() }
+        waiting.forEach { settleSpeech(it.callbackId, it.generation, false) }
+    }
+
+    private fun requestSpeechFocus(): Boolean {
+        if (speechFocusRequest != null) return true
+        val manager = activity.getSystemService(Context.AUDIO_SERVICE) as? AudioManager ?: return true
+        val request = AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK)
+            .setAudioAttributes(speechAudioAttributes)
+            .build()
+        if (manager.requestAudioFocus(request) == AudioManager.AUDIOFOCUS_REQUEST_FAILED) return false
+        speechFocusRequest = request
+        return true
+    }
+
+    private fun abandonSpeechFocus() {
+        val request = speechFocusRequest ?: return
+        speechFocusRequest = null
+        val manager = activity.getSystemService(Context.AUDIO_SERVICE) as? AudioManager ?: return
+        runCatching { manager.abandonAudioFocusRequest(request) }
+    }
+
+    /** An answer for a page that has since navigated away is dropped. */
+    private fun settleSpeech(callbackId: Int, generation: Int, spoken: Boolean) {
+        if (generation != navigationGeneration) return
+        evaluateJavascriptUnlessClosed(
+            "window.__craftSpeechResult && window.__craftSpeechResult($callbackId, $spoken)"
+        )
+    }
+
+    private fun rejectSpeech(callbackId: Int, message: String, code: String) {
+        evaluateJavascriptUnlessClosed(
+            "window.__craftSpeechError && window.__craftSpeechError($callbackId, ${jsQuote(message)}, ${jsQuote(code)})"
+        )
+    }
+
     // ==================== Orientation Lock ====================
 
     @JavascriptInterface
@@ -4077,7 +4350,8 @@ class CraftBridge(
             runCatching {
                 webView.evaluateJavascript(
                     "window.__craftRejectPendingPromises && window.__craftRejectPendingPromises('Android bridge closed');" +
-                        "window.__craftRejectPermissionRequests && window.__craftRejectPermissionRequests('Android bridge closed')",
+                        "window.__craftRejectPermissionRequests && window.__craftRejectPermissionRequests('Android bridge closed');" +
+                        "window.__craftRejectSpeechRequests && window.__craftRejectSpeechRequests('Android bridge closed')",
                     null
                 )
             }
@@ -4144,6 +4418,16 @@ class CraftBridge(
         runCatching { database?.close() }
         database = null
 
+        // The page's calls were rejected above; this only silences the
+        // engine and gives the music back its volume.
+        queuedSpeech.clear()
+        pendingUtterances.clear()
+        runCatching { textToSpeech?.stop() }
+        runCatching { textToSpeech?.shutdown() }
+        textToSpeech = null
+        textToSpeechReady = false
+        abandonSpeechFocus()
+
         if (isFlashlightOn) setFlashlight(false)
         activity.window.clearFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
         isKeepingAwake = false

package/dist/api/mobile.d.ts

@@ -687,6 +687,34 @@ export declare const keepAwake: {
     enable(): Promise<void>;
     disable(): Promise<void>;
 };
+export interface SpeechOptions {
+    /** Speaking rate, 0.5 to 2. 1 is the voice's normal pace. */
+    rate?: number;
+    /** BCP-47 language tag, such as 'en-US'. Defaults to the device's language. */
+    language?: string;
+    /** Stop whatever is being said first. Defaults to true; false queues behind it. */
+    interrupt?: boolean;
+}
+/**
+ * Short spoken cues: "Rest, 15 seconds. Up next: Dead Bug".
+ *
+ * Inside a Craft app this is native text-to-speech, which ducks the person's
+ * music rather than stopping it and, on iOS, plays with the silent switch on.
+ * In a browser it falls back to the Web Speech API, which does neither, and
+ * where there is no speech at all it answers `false` rather than throwing, so
+ * a cue never breaks the flow around it.
+ */
+export declare const speech: {
+    isAvailable(): boolean;
+    /**
+     * Speak `text`. Resolves when the utterance ends: `true` when it was
+     * spoken, `false` when it was stopped, interrupted or could not be spoken.
+     * Rejects with code `INVALID_ARGUMENT` when `text` is empty.
+     */
+    speak(text: string, options?: SpeechOptions): Promise<boolean>;
+    /** Stop speaking at once. Every pending `speak()` resolves `false`. */
+    stop(): Promise<void>;
+};
 export declare const deepLinks: {
     getInitialURL(): Promise<string | null>;
     /**
@@ -852,6 +880,7 @@ declare const mobile: {
     lifecycle: typeof lifecycle;
     notifications: typeof notifications;
     keepAwake: typeof keepAwake;
+    speech: typeof speech;
     deepLinks: typeof deepLinks;
     network: typeof network;
     appReview: typeof appReview;

package/dist/cli.js

@@ -3303,7 +3303,7 @@ function pinCraftNativeDependency(packagePath, craftVersion) {
 `);
 }
 // package.json
-var version = "0.0.115";
+var version = "0.0.118";
 
 // bin/cli.ts
 var spawnedFrom = process6.env[CRAFT_CLI_SPAWN_MARKER];

package/dist/index.cjs

@@ -310,7 +310,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.115";
+var version = "0.0.118";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;
@@ -5284,6 +5284,7 @@ var notifications = {
     }
   }
 };
+var speakingOnTheWeb = new Set;
 function detectPlatform2() {
   if (typeof window === "undefined")
     return "linux";

package/dist/index.js

@@ -58,7 +58,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.115";
+var version = "0.0.118";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;
@@ -5044,6 +5044,7 @@ var notifications = {
     }
   }
 };
+var speakingOnTheWeb = new Set;
 function detectPlatform2() {
   if (typeof window === "undefined")
     return "linux";

package/dist/ios/templates/CraftApp.swift

@@ -722,6 +722,24 @@ struct CraftWebView: UIViewRepresentable {
         // Keep awake
         private var isKeepingAwake = false
 
+        // Speech synthesis. One synthesizer for the life of the web view, so a
+        // cue can interrupt the one before it; each utterance it has not
+        // finished yet is held beside the call waiting on it.
+        private lazy var speechSynthesizer: AVSpeechSynthesizer = {
+            let synthesizer = AVSpeechSynthesizer()
+            synthesizer.delegate = self
+            return synthesizer
+        }()
+        private var pendingUtterances: [(utterance: AVSpeechUtterance, callbackId: String?)] = []
+        /// What the session was before speech claimed it; nil while speech
+        /// does not hold it.
+        private var speechAudioSessionToRestore: (AVAudioSession.Category, AVAudioSession.Mode, AVAudioSession.CategoryOptions)?
+        /// Activating and deactivating the audio session blocks until the
+        /// audio hardware answers, which iOS flags as a hang risk on the main
+        /// thread. They run here instead, in order, and the session state
+        /// above is only touched here.
+        private let speechAudioQueue = DispatchQueue(label: "craft.speech.audio")
+
         // Orientation lock
         private var lockedOrientation: UIInterfaceOrientationMask?
 
@@ -1058,6 +1076,16 @@ struct CraftWebView: UIViewRepresentable {
                 } else {
                     rejectCallback(callbackId, error: "setFlashlight needs true or false", code: "INVALID_ARGUMENT")
                 }
+            // Speech synthesis. Ungated, like the flashlight: speaking needs no
+            // permission and no entitlement.
+            case "speak":
+                if let text = body["text"] as? String, !text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+                    speak(text, body: body, callbackId: callbackId)
+                } else {
+                    rejectCallback(callbackId, error: "speak needs some text to say", code: "INVALID_ARGUMENT")
+                }
+            case "stopSpeaking":
+                stopSpeaking(callbackId: callbackId)
             // Vibrate pattern
             case "vibrate":
                 if let pattern = body["pattern"] as? [Int] {
@@ -1850,6 +1878,7 @@ struct CraftWebView: UIViewRepresentable {
                     orientationLock: \(config.enableOrientationLock),
                     deepLinks: \(config.enableDeepLinks),
                     flashlight: true,
+                    speech: true,
                     network: true,
                     deviceInfo: true,
                     badge: true,
@@ -2788,6 +2817,37 @@ struct CraftWebView: UIViewRepresentable {
                     });
                 },
 
+                // Speech synthesis. speak() settles when the utterance ends:
+                // true when it was spoken, false when something stopped it.
+                // No timeout, because a long sentence at a slow rate can
+                // outlast any deadline that would be fair to a short one.
+                speech: {
+                    speak: function(text, options) {
+                        var self = window.craft;
+                        var id = 'cb_' + (++self._callbackId);
+                        options = options || {};
+                        window.webkit.messageHandlers.craft.postMessage({
+                            action: 'speak',
+                            text: text == null ? '' : String(text),
+                            rate: typeof options.rate === 'number' ? options.rate : null,
+                            language: typeof options.language === 'string' ? options.language : null,
+                            interrupt: options.interrupt !== false,
+                            callbackId: id
+                        });
+                        return new Promise(function(resolve, reject) {
+                            self._callbacks[id] = {resolve: resolve, reject: reject};
+                        });
+                    },
+                    stop: function() {
+                        var self = window.craft;
+                        var id = 'cb_' + (++self._callbackId);
+                        window.webkit.messageHandlers.craft.postMessage({action: 'stopSpeaking', callbackId: id});
+                        return new Promise(function(resolve, reject) {
+                            self._callbacks[id] = {resolve: resolve, reject: reject};
+                        });
+                    }
+                },
+
                 // Orientation Lock
                 lockOrientation: function(orientation) {
                     var self = this;
@@ -4762,6 +4822,153 @@ struct CraftWebView: UIViewRepresentable {
             }
         }
 
+        // MARK: - Speech Synthesis
+        //
+        // Native rather than the page's own `speechSynthesis`, which in a
+        // WKWebView plays through the default soloAmbient session: it stops
+        // the person's music and the silent switch mutes it. A workout cue has
+        // to do neither, so the session is set up here for as long as there is
+        // something to say, and handed back when there is not.
+
+        private func speak(_ text: String, body: [String: Any], callbackId: String?) {
+            DispatchQueue.main.async {
+                if body["interrupt"] as? Bool ?? true {
+                    self.cancelPendingSpeech()
+                }
+
+                let utterance = AVSpeechUtterance(string: text)
+                utterance.rate = Self.utteranceRate(body["rate"] as? Double ?? 1)
+                // An unknown language finds no voice, and a nil voice is the
+                // device's own, which is the default anyway.
+                if let language = body["language"] as? String, !language.isEmpty,
+                   let voice = AVSpeechSynthesisVoice(language: language) {
+                    utterance.voice = voice
+                }
+
+                self.pendingUtterances.append((utterance, callbackId))
+                self.claimAudioSessionForSpeech {
+                    // Stopped while the session was being set up: say nothing.
+                    guard self.pendingUtterances.contains(where: { $0.utterance === utterance }) else { return }
+                    self.speechSynthesizer.speak(utterance)
+                }
+            }
+        }
+
+        private func stopSpeaking(callbackId: String?) {
+            DispatchQueue.main.async {
+                // When something was playing, its didCancel releases the
+                // session once the audio has actually stopped; deactivating
+                // before that fails as busy and leaves the music ducked.
+                if !self.cancelPendingSpeech() { self.releaseAudioSessionIfSilent() }
+                self.resolveCallback(callbackId, result: true)
+            }
+        }
+
+        /// Stop what is being said and settle every call waiting on it, false.
+        /// Returns whether the synthesizer was making a sound.
+        ///
+        /// Settled here rather than in `didCancel`, because the delegate hears
+        /// about the utterance that was playing and nothing about the ones
+        /// queued behind it, whose calls would otherwise never settle.
+        @discardableResult
+        private func cancelPendingSpeech() -> Bool {
+            let waiting = pendingUtterances
+            pendingUtterances.removeAll()
+            let synthesizer = speechSynthesizer
+            let wasSounding = synthesizer.isSpeaking || synthesizer.isPaused
+            if wasSounding { synthesizer.stopSpeaking(at: .immediate) }
+            for entry in waiting {
+                resolveCallback(entry.callbackId, result: false)
+            }
+            return wasSounding
+        }
+
+        /// The page's rate, where 1 is normal, on AVSpeechUtterance's scale.
+        ///
+        /// Apple's scale is not linear in speed: the default sits at 0.5 and
+        /// the maximum is far faster than twice that. So a slower rate scales
+        /// the default down in proportion, and a faster one climbs toward the
+        /// maximum at half the slope, which keeps 2 brisk but intelligible.
+        private static func utteranceRate(_ rate: Double) -> Float {
+            let requested = Float(min(max(rate.isFinite ? rate : 1, 0.5), 2))
+            let normal = AVSpeechUtteranceDefaultSpeechRate
+            let mapped = requested <= 1
+                ? normal * requested
+                : normal + (AVSpeechUtteranceMaximumSpeechRate - normal) * (requested - 1) / 2
+            return min(max(mapped, AVSpeechUtteranceMinimumSpeechRate), AVSpeechUtteranceMaximumSpeechRate)
+        }
+
+        /// Duck the music rather than stop it, and play through the silent
+        /// switch.
+        ///
+        /// `.playback` is what the switch does not mute, `.duckOthers` lowers
+        /// the music under the cue, and the spoken-audio option pauses a
+        /// podcast rather than talking over it. Left alone while recognition
+        /// or a recording holds the session: switching it to playback would
+        /// cut their microphone off mid-take.
+        ///
+        /// Set up on the speech queue, then `start` runs on the main thread.
+        private func claimAudioSessionForSpeech(then start: @escaping () -> Void) {
+            let microphoneBusy = audioEngine.isRunning || (audioRecorder?.isRecording ?? false)
+            speechAudioQueue.async {
+                if self.speechAudioSessionToRestore == nil && !microphoneBusy {
+                    let session = AVAudioSession.sharedInstance()
+                    let previous = (session.category, session.mode, session.categoryOptions)
+                    do {
+                        try session.setCategory(.playback, mode: .voicePrompt, options: [.duckOthers, .interruptSpokenAudioAndMixWithOthers])
+                        try session.setActive(true)
+                        self.speechAudioSessionToRestore = previous
+                    } catch {
+                        // Still speak, through whatever session the app has: a
+                        // cue that does not duck beats one that never plays.
+                        print("[Craft] Speech audio session failed: \(error.localizedDescription)")
+                    }
+                }
+                DispatchQueue.main.async(execute: start)
+            }
+        }
+
+        /// Hand the audio back once nothing is left to say, so the music
+        /// returns to full volume instead of staying ducked, and put back the
+        /// category the app had, so the page's own media plays as before.
+        ///
+        /// Checked on the main thread, where the queue of utterances lives, and
+        /// done on the speech queue after any setup already asked for, so a
+        /// cue that arrives meanwhile reclaims the session after this.
+        private func releaseAudioSessionIfSilent(retry: Bool = true) {
+            guard pendingUtterances.isEmpty else { return }
+            speechAudioQueue.async {
+                guard let previous = self.speechAudioSessionToRestore else { return }
+                let session = AVAudioSession.sharedInstance()
+                do {
+                    try session.setActive(false, options: .notifyOthersOnDeactivation)
+                } catch {
+                    // Busy: the synthesizer's audio has not quite drained, or
+                    // the page has its own media playing. Once more shortly
+                    // covers the first; for the second, staying active is
+                    // right, and the ducking still ends when the music app
+                    // hears nothing more.
+                    if retry {
+                        DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) {
+                            self.releaseAudioSessionIfSilent(retry: false)
+                        }
+                        return
+                    }
+                    print("[Craft] Speech audio session release failed: \(error.localizedDescription)")
+                }
+                self.speechAudioSessionToRestore = nil
+                try? session.setCategory(previous.0, mode: previous.1, options: previous.2)
+            }
+        }
+
+        fileprivate func speechDidEnd(_ utterance: AVSpeechUtterance, spoken: Bool) {
+            if let index = pendingUtterances.firstIndex(where: { $0.utterance === utterance }) {
+                let entry = pendingUtterances.remove(at: index)
+                resolveCallback(entry.callbackId, result: spoken)
+            }
+            releaseAudioSessionIfSilent()
+        }
+
         // MARK: - Orientation Lock
         private func lockOrientation(_ orientation: String, callbackId: String?) {
             var mask: UIInterfaceOrientationMask = .all
@@ -6698,6 +6905,20 @@ extension URL {
 }
 
 // MARK: - Contact Picker Delegate
+// MARK: - AVSpeechSynthesizerDelegate
+//
+// The end of an utterance is what `craft.speech.speak()` waits for. Hopped to
+// main because every piece of speech state is touched there and nowhere else.
+extension CraftWebView.Coordinator: AVSpeechSynthesizerDelegate {
+    func speechSynthesizer(_ synthesizer: AVSpeechSynthesizer, didFinish utterance: AVSpeechUtterance) {
+        DispatchQueue.main.async { self.speechDidEnd(utterance, spoken: true) }
+    }
+
+    func speechSynthesizer(_ synthesizer: AVSpeechSynthesizer, didCancel utterance: AVSpeechUtterance) {
+        DispatchQueue.main.async { self.speechDidEnd(utterance, spoken: false) }
+    }
+}
+
 extension CraftWebView.Coordinator: CNContactPickerDelegate {
     func contactPicker(_ picker: CNContactPickerViewController, didSelect contact: CNContact) {
         let contactData = formatContact(contact)

package/dist/mobile.js

@@ -559,6 +559,63 @@ var keepAwake = {
     webWakeLock = null;
   }
 };
+function getWebSpeech() {
+  if (typeof window === "undefined")
+    return;
+  const scope = window;
+  if (!scope.speechSynthesis || typeof scope.SpeechSynthesisUtterance !== "function")
+    return;
+  return { synthesis: scope.speechSynthesis, Utterance: scope.SpeechSynthesisUtterance };
+}
+var speakingOnTheWeb = new Set;
+function speechRate(rate) {
+  return typeof rate === "number" && Number.isFinite(rate) ? Math.min(Math.max(rate, 0.5), 2) : 1;
+}
+var speech = {
+  isAvailable() {
+    return Boolean(getCraftRoot()?.speech?.speak) || getWebSpeech() !== undefined;
+  },
+  async speak(text, options = {}) {
+    const native = getCraftRoot()?.speech;
+    const web = native?.speak ? undefined : getWebSpeech();
+    if (!native?.speak && !web)
+      return false;
+    if (typeof text !== "string" || !text.trim()) {
+      throw Object.assign(new Error("speech.speak needs some text to say"), { code: "INVALID_ARGUMENT" });
+    }
+    if (native?.speak)
+      return await native.speak(text, options) === true;
+    const { synthesis, Utterance } = web;
+    if (options.interrupt !== false)
+      synthesis.cancel();
+    return new Promise((resolve) => {
+      const utterance = new Utterance(text);
+      utterance.rate = speechRate(options.rate);
+      if (options.language)
+        utterance.lang = options.language;
+      const settle = (spoken) => {
+        speakingOnTheWeb.delete(utterance);
+        resolve(spoken);
+      };
+      utterance.onend = () => settle(true);
+      utterance.onerror = () => settle(false);
+      speakingOnTheWeb.add(utterance);
+      try {
+        synthesis.speak(utterance);
+      } catch {
+        settle(false);
+      }
+    });
+  },
+  async stop() {
+    const native = getCraftRoot()?.speech;
+    if (native?.stop) {
+      await native.stop();
+      return;
+    }
+    getWebSpeech()?.synthesis.cancel();
+  }
+};
 var deepLinks = {
   async getInitialURL() {
     return normalizeDeepLinkURL(await getCraftRoot()?.deepLinks?.getInitialURL?.());
@@ -797,6 +854,7 @@ function getCraftMobile() {
 }
 export {
   watchConnectivity,
+  speech,
   share,
   secureStorage,
   pushNotifications,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "craft-native",
-  "version": "0.0.115",
+  "version": "0.0.118",
   "type": "module",
   "description": "Build desktop apps with web languages - TypeScript SDK for Craft",
   "author": "Chris Breuer <chris@stacksjs.org>",