craft-native 0.0.180 → 0.0.182

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

@@ -35,8 +35,10 @@
         <activity
             android:name=".MainActivity"
             android:exported="true"
-            android:configChanges="orientation|screenSize|screenLayout|keyboardHidden|uiMode|fontScale"
+            android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout|keyboardHidden|uiMode|fontScale"
             android:windowSoftInputMode="adjustResize"
+            android:supportsPictureInPicture="true"
+            android:resizeableActivity="true"
             android:launchMode="singleTask">
             <intent-filter>
                 <action android:name="android.intent.action.MAIN" />

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

@@ -12,6 +12,7 @@ import android.os.Handler
 import android.os.Looper
 import android.provider.Settings
 import android.speech.tts.TextToSpeech
+import android.speech.tts.Voice
 import android.speech.tts.UtteranceProgressListener
 import android.util.Log
 import android.view.WindowManager
@@ -64,6 +65,8 @@ internal class CraftNativeServices(
 
     /** What this host adds to the capability names the screen sees. */
     fun names(): List<String> = buildList {
+        // `craft.animation.next`: the screen's next change animates (MainActivity).
+        add("animation")
         add("dialog")
         add("browser")
         add("linking")
@@ -524,11 +527,22 @@ internal class CraftNativeServices(
                 if (text.isBlank()) return done(failure("INVALID_ARGUMENT", "speech.speak needs some text to say"))
                 val options = args.optJSONObject(1) ?: JSONObject()
                 withSpeech { engine ->
-                    options.optString("language").takeIf { it.isNotBlank() }?.let { engine.language = Locale.forLanguageTag(it) }
-                    if (options.has("rate")) engine.setSpeechRate((options.optDouble("rate", 0.5) * 2).toFloat().coerceIn(0.1f, 4f))
+                    val language = options.optString("language").takeIf { it.isNotBlank() }?.let(Locale::forLanguageTag) ?: Locale.getDefault()
+                    val voice = bestVoice(engine, language)
+                    if (voice != null) engine.setVoice(voice) else engine.setLanguage(language)
+                    // The engine keeps its rate and pitch between calls: each
+                    // cue sets its own, 1 being the voice's normal (as on iOS).
+                    engine.setSpeechRate(speechNumber(options, "rate", 0.5, 2.0))
+                    engine.setPitch(speechNumber(options, "pitch", 0.5, 2.0))
                     val id = UUID.randomUUID().toString()
                     speeches[id] = done
-                    val queue = if (options.optBoolean("interrupt", false)) TextToSpeech.QUEUE_FLUSH else TextToSpeech.QUEUE_ADD
+                    // Interrupting stops everything said or waiting, as on iOS (the default there too).
+                    var queue = if (options.optBoolean("interrupt", true)) TextToSpeech.QUEUE_FLUSH else TextToSpeech.QUEUE_ADD
+                    val quietMs = (speechNumber(options, "preDelay", 0.0, 5.0) * 1000).toLong()
+                    if (quietMs > 0) {
+                        engine.playSilentUtterance(quietMs, queue, "$id-quiet")
+                        queue = TextToSpeech.QUEUE_ADD
+                    }
                     if (engine.speak(text, queue, null, id) != TextToSpeech.SUCCESS) speeches.remove(id)?.invoke(success(false))
                 }
             }
@@ -542,6 +556,30 @@ internal class CraftNativeServices(
         }
     }
 
+    /** A speech option clamped to its range, 1 when it is not given. */
+    private fun speechNumber(options: JSONObject, name: String, low: Double, high: Double): Float {
+        val fallback = if (name == "preDelay") 0.0 else 1.0
+        val value = options.optDouble(name, fallback).takeIf { it.isFinite() } ?: fallback
+        return value.coerceIn(low, high).toFloat()
+    }
+
+    private val voices = mutableMapOf<String, Voice?>()
+
+    /**
+     * The best installed voice for `language`: on the phone (never one that
+     * needs the network mid-workout), of the highest quality, then the
+     * quickest to answer. Remembered per language.
+     */
+    private fun bestVoice(engine: TextToSpeech, language: Locale): Voice? = voices.getOrPut(language.toLanguageTag()) {
+        val installed = runCatching { engine.voices }.getOrNull().orEmpty().filter { voice ->
+            !voice.isNetworkConnectionRequired &&
+                TextToSpeech.Engine.KEY_FEATURE_NOT_INSTALLED !in voice.features.orEmpty() &&
+                voice.locale.language == language.language
+        }
+        val sameCountry = installed.filter { language.country.isBlank() || it.locale.country == language.country }
+        (sameCountry.ifEmpty { installed }).maxWithOrNull(compareBy<Voice>({ it.quality }, { -it.latency }, { it.name }))
+    }
+
     private fun withSpeech(use: (TextToSpeech) -> Unit) {
         val engine = speech
         if (engine != null && speechReady) return use(engine)

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

@@ -10,7 +10,9 @@ import android.content.res.ColorStateList
 import android.content.res.Configuration
 import android.database.ContentObserver
 import android.content.Intent
+import android.app.PictureInPictureParams
 import android.media.AudioAttributes
+import android.media.AudioManager
 import android.media.AudioFormat
 import android.media.MediaPlayer
 import android.media.AudioTrack
@@ -46,6 +48,13 @@ import android.text.SpannableString
 import android.text.style.ReplacementSpan
 import android.util.Log
 import android.util.Base64
+import android.transition.ChangeBounds
+import android.transition.ChangeTransform
+import android.transition.Fade
+import android.transition.Transition
+import android.transition.TransitionManager
+import android.transition.TransitionSet
+import android.util.Rational
 import android.util.TypedValue
 import android.view.Gravity
 import android.view.KeyEvent
@@ -58,6 +67,10 @@ import android.view.ViewGroup
 import android.view.ViewOutlineProvider
 import android.view.ViewParent
 import android.view.ViewTreeObserver
+import android.view.animation.LinearInterpolator
+import android.view.animation.PathInterpolator
+import android.view.SurfaceHolder
+import android.view.SurfaceView
 import android.widget.AdapterView
 import android.widget.ArrayAdapter
 import android.widget.Button
@@ -2390,6 +2403,17 @@ private class CraftNativeDatePickerView(context: Context) : FrameLayout(context)
     }
 }
 
+/**
+ * A native screen's `<Video>`: the platform's VideoView.
+ *
+ * It plays without taking audio focus, so the person's music carries on
+ * under it, as on iOS. `onLoad`, `onPlay`, `onPause`, `onEnd` and `onError`
+ * reach the screen in the web's names, from the controls as well as from
+ * props. With `pictureInPicture` the activity takes it into a floating
+ * window when the person leaves the app while it plays (MainActivity
+ * `updatePictureInPicture`), drawn there on a surface of the activity's own
+ * while this view keeps its place.
+ */
 private class CraftNativeVideoView(context: Context) : VideoView(context) {
     private var sourceUri = ""
     private var shouldLoop = false
@@ -2397,8 +2421,24 @@ private class CraftNativeVideoView(context: Context) : VideoView(context) {
     private var muted = false
     private var resizeMode = "contain"
     private var preparedPlayer: MediaPlayer? = null
+    /** The screen's handlers by event name, and how an event reaches them. */
+    var handlers: JSONObject = JSONObject()
+    var emit: ((handler: String, nativeEvent: JSONObject) -> Unit)? = null
+    /** May float in Picture in Picture while it plays. */
+    var pictureInPicture = false
+        private set
+    /** Playing now, by the controls or by props. */
+    var playing = false
+        private set
+    /** Playback started or stopped, or the choice changed: the activity's PiP params follow. */
+    var onPictureInPictureChanged: (() -> Unit)? = null
+
+    init {
+        // Mixed with the music rather than pausing it.
+        setAudioFocusRequest(AudioManager.AUDIOFOCUS_NONE)
+    }
 
-    fun configure(source: Any?, autoplay: Boolean, paused: Boolean, loop: Boolean, muted: Boolean, controls: Boolean, resizeMode: String?) {
+    fun configure(source: Any?, autoplay: Boolean, paused: Boolean, loop: Boolean, muted: Boolean, controls: Boolean, resizeMode: String?, pictureInPicture: Boolean = false) {
         val uri = when (source) {
             is String -> source
             is JSONObject -> craftNativeOptionalString(source.opt("uri")).orEmpty()
@@ -2407,12 +2447,18 @@ private class CraftNativeVideoView(context: Context) : VideoView(context) {
         shouldLoop = loop
         shouldPlay = autoplay && !paused
         this.muted = muted
+        val floating = pictureInPicture && !muted
+        if (floating != this.pictureInPicture) {
+            this.pictureInPicture = floating
+            onPictureInPictureChanged?.invoke()
+        }
         this.resizeMode = resizeMode?.lowercase()?.takeIf { it in setOf("cover", "contain", "stretch", "center") } ?: "contain"
         applyScalingMode()
         setMediaController(if (controls) MediaController(context).also { it.setAnchorView(this) } else null)
         if (uri != sourceUri) {
             sourceUri = uri
             stopPlayback()
+            setPlaying(false)
             preparedPlayer = null
             if (uri.isBlank()) return
             // A copy kept on the phone (craft.media.keep) plays in place of
@@ -2425,9 +2471,19 @@ private class CraftNativeVideoView(context: Context) : VideoView(context) {
                 mediaPlayer.isLooping = shouldLoop
                 val volume = if (this.muted) 0f else 1f
                 mediaPlayer.setVolume(volume, volume)
+                fire("onLoad", JSONObject().put("duration", duration / 1000.0))
                 if (shouldPlay) start()
             }
-            setOnCompletionListener { if (shouldLoop && !isPlaying) start() }
+            setOnCompletionListener {
+                if (shouldLoop && !isPlaying) start()
+                else setPlaying(false)
+                fire("onEnd")
+            }
+            setOnErrorListener { _, what, extra ->
+                setPlaying(false)
+                fire("onError", JSONObject().put("message", "The video could not be played ($what, $extra)"))
+                true
+            }
         }
         if (uri.isBlank()) return
         runCatching {
@@ -2436,10 +2492,55 @@ private class CraftNativeVideoView(context: Context) : VideoView(context) {
         }
     }
 
+    override fun start() {
+        super.start()
+        setPlaying(true)
+    }
+
+    override fun pause() {
+        super.pause()
+        setPlaying(false)
+    }
+
+    private fun setPlaying(value: Boolean) {
+        if (playing == value) return
+        playing = value
+        fire(if (value) "onPlay" else "onPause")
+        onPictureInPictureChanged?.invoke()
+    }
+
+    private fun fire(event: String, nativeEvent: JSONObject = JSONObject()) {
+        val handler = craftNativeEventName(handlers, event)
+        if (handler.isNotBlank()) emit?.invoke(handler, nativeEvent)
+    }
+
+    /** Its width over height once known, inside what Picture in Picture allows. */
+    fun aspectRatio(): Rational? {
+        val player = preparedPlayer ?: return null
+        val width = runCatching { player.videoWidth }.getOrDefault(0)
+        val height = runCatching { player.videoHeight }.getOrDefault(0)
+        if (width <= 0 || height <= 0) return null
+        val ratio = (width.toDouble() / height).coerceIn(1 / 2.39, 2.39)
+        return Rational((ratio * 1000).roundToInt(), 1000)
+    }
+
+    /** Draws on `holder` (the floating window's surface), or back on its own with null. */
+    fun showOn(holder: SurfaceHolder?): Boolean {
+        val player = preparedPlayer ?: return false
+        return runCatching { player.setDisplay(holder ?: this.holder) }.isSuccess
+    }
+
     fun stop() {
+        // Released with its screen: nothing more is told to it.
+        emit = null
         stopPlayback()
+        setPlaying(false)
         sourceUri = ""
         preparedPlayer = null
+        if (pictureInPicture) {
+            pictureInPicture = false
+            onPictureInPictureChanged?.invoke()
+        }
     }
 
     private fun applyScalingMode() {
@@ -3845,6 +3946,7 @@ class MainActivity : AppCompatActivity() {
                     if (visibleScreen === screen) applyChrome(screen)
                 }
             }
+            "ANIMATE_NEXT" -> if (screen !== appScreen && visibleScreen === screen) animateNextChange(screen, payload)
             "SYNC_WRITE" -> syncWrite(screen, payload)
             "TIMER" -> {
                 val id = payload.optInt("id")
@@ -4541,14 +4643,20 @@ class MainActivity : AppCompatActivity() {
                 reconcileChildren(screen, content, children, path, next, style, previousControls)
             }
             "Video" -> (previous as? CraftNativeVideoView ?: CraftNativeVideoView(this)).apply {
+                handlers = events
+                emit = { handler, nativeEvent ->
+                    send(screen, "EVENT", JSONObject().put("handlerName", handler).put("nativeEvent", nativeEvent))
+                }
+                onPictureInPictureChanged = { updatePictureInPicture() }
                 configure(
-                    source = props.opt("source"),
+                    source = props.opt("source") ?: props.opt("src"),
                     autoplay = props.optBoolean("autoplay", props.optBoolean("autoPlay", false)),
                     paused = props.optBoolean("paused", false),
                     loop = props.optBoolean("loop", false),
                     muted = props.optBoolean("muted", false),
                     controls = props.optBoolean("controls", false),
                     resizeMode = craftNativeResizeMode(style, props),
+                    pictureInPicture = props.optBoolean("pictureInPicture", false),
                 )
             }
             "Map" -> (previous as? CraftNativeMapView ?: CraftNativeMapView(this)).apply {
@@ -4767,6 +4875,8 @@ class MainActivity : AppCompatActivity() {
             control.isLongClickable = false
         }
         applyAccessibility(control, props, type, explicitKey ?: protocolId ?: path)
+        // One element across an animated change (craft.animation.next).
+        control.transitionName = craftNativeOptionalString(props.opt("transitionID"))?.takeIf { it.isNotBlank() }
         val layoutHandler = craftNativeEventName(events, "onLayout")
         if (layoutHandler.isNotBlank()) {
             if (screen.layoutHandlers[control] != layoutHandler) screen.lastLayoutBounds.remove(control)
@@ -5914,6 +6024,114 @@ class MainActivity : AppCompatActivity() {
         .filterIsInstance<CraftNativeMapView>()
         .toSet()
 
+    // MARK: Animated changes
+
+    /**
+     * `craft.animation.next(options)`: the screen's next change animates,
+     * views that stay moving to their new places, new ones fading in and
+     * removed ones fading out, and two with the same `transitionID` moving as
+     * one. Android's own transitions, which follow the person's animation
+     * scale: with animations off it is a cut, as the system's own are.
+     */
+    private fun animateNextChange(screen: Screen, payload: JSONObject) {
+        val seconds = payload.optDouble("duration", 0.35).takeIf { it.isFinite() } ?: 0.35
+        val curve = payload.optString("curve", "spring")
+        val transition = TransitionSet()
+        transition.setOrdering(TransitionSet.ORDERING_TOGETHER)
+        listOf(ChangeBounds(), ChangeTransform(), Fade()).forEach { part ->
+            part.setMatchOrder(Transition.MATCH_NAME, Transition.MATCH_INSTANCE)
+            transition.addTransition(part)
+        }
+        transition.setDuration((seconds.coerceIn(0.1, 1.0) * 1000).toLong())
+        transition.setInterpolator(
+            when (curve) {
+                "linear" -> LinearInterpolator()
+                "easeInOut" -> PathInterpolator(0.42f, 0f, 0.58f, 1f)
+                // A spring with no bounce reads as a decelerating curve.
+                else -> PathInterpolator(0.2f, 0f, 0f, 1f)
+            },
+        )
+        TransitionManager.beginDelayedTransition(screen.view, transition)
+    }
+
+    // MARK: Picture in Picture
+
+    /** The floating window's own surface, over everything while it shows. */
+    private var pictureInPictureLayer: FrameLayout? = null
+    private var pictureInPictureVideo: CraftNativeVideoView? = null
+
+    /** A video that asked for Picture in Picture and is playing on a screen in view. */
+    private fun floatingVideo(): CraftNativeVideoView? = allScreens()
+        .filter { !it.headless }
+        .flatMap { retainedViews(it) }
+        .filterIsInstance<CraftNativeVideoView>()
+        .firstOrNull { it.pictureInPicture && it.playing && it.isShown }
+
+    private fun pictureInPictureAllowed(): Boolean =
+        packageManager.hasSystemFeature(PackageManager.FEATURE_PICTURE_IN_PICTURE)
+
+    /**
+     * Picture in Picture follows the playing video: on Android 12 and later
+     * the system floats it by itself as the person leaves the app (gesture
+     * navigation included); before that `onUserLeaveHint` asks.
+     */
+    private fun updatePictureInPicture() {
+        if (!pictureInPictureAllowed() || isInPictureInPictureMode) return
+        val video = floatingVideo()
+        val params = PictureInPictureParams.Builder()
+        video?.aspectRatio()?.let { params.setAspectRatio(it) }
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) params.setAutoEnterEnabled(video != null)
+        runCatching { setPictureInPictureParams(params.build()) }
+    }
+
+    override fun onUserLeaveHint() {
+        super.onUserLeaveHint()
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S || !pictureInPictureAllowed()) return
+        val video = floatingVideo() ?: return
+        val params = PictureInPictureParams.Builder()
+        video.aspectRatio()?.let { params.setAspectRatio(it) }
+        runCatching { enterPictureInPictureMode(params.build()) }
+    }
+
+    override fun onPictureInPictureModeChanged(isInPictureInPictureMode: Boolean, newConfig: Configuration) {
+        super.onPictureInPictureModeChanged(isInPictureInPictureMode, newConfig)
+        if (isInPictureInPictureMode) showVideoAlone() else putVideoBack()
+    }
+
+    /**
+     * The floating window shows the whole activity, so the video is drawn
+     * alone on a surface over it, black around it. The video keeps playing
+     * through the change: only where its frames go moves.
+     */
+    private fun showVideoAlone() {
+        val video = floatingVideo() ?: return
+        val host = window.decorView as? ViewGroup ?: return
+        val surface = SurfaceView(this).apply {
+            setZOrderMediaOverlay(true)
+            holder.addCallback(object : SurfaceHolder.Callback {
+                override fun surfaceCreated(holder: SurfaceHolder) { video.showOn(holder) }
+                override fun surfaceChanged(holder: SurfaceHolder, format: Int, width: Int, height: Int) = Unit
+                override fun surfaceDestroyed(holder: SurfaceHolder) { video.showOn(null) }
+            })
+        }
+        val layer = FrameLayout(this).apply {
+            setBackgroundColor(Color.BLACK)
+            addView(surface, FrameLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT, Gravity.CENTER))
+        }
+        host.addView(layer, ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT))
+        pictureInPictureLayer = layer
+        pictureInPictureVideo = video
+    }
+
+    /** Back in the app: the video draws in its place again. */
+    private fun putVideoBack() {
+        pictureInPictureVideo?.showOn(null)
+        pictureInPictureVideo = null
+        pictureInPictureLayer?.let { (it.parent as? ViewGroup)?.removeView(it) }
+        pictureInPictureLayer = null
+        updatePictureInPicture()
+    }
+
     private fun releaseFlatList(
         screen: Screen,
         list: CraftNativeFlatList,

package/dist/api/mobile.d.ts

@@ -737,6 +737,13 @@ export interface SpeechOptions {
     language?: string;
     /** Stop whatever is being said first. Defaults to true; false queues behind it. */
     interrupt?: boolean;
+    /** Voice pitch, 0.5 to 2. 1 is the voice's own; lower sounds calmer. */
+    pitch?: number;
+    /**
+     * Seconds of quiet before the words (up to 5), after whatever was said
+     * before them: a pause between two queued cues.
+     */
+    preDelay?: number;
 }
 export declare const brightness: {
     isAvailable(): boolean;

package/dist/cli.js

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

package/dist/components/index.d.ts

@@ -417,6 +417,13 @@ export interface VideoProps extends BaseProps {
     muted?: boolean;
     paused?: boolean;
     resizeMode?: 'contain' | 'cover' | 'stretch';
+    /**
+     * Carries on in a floating window (Picture in Picture) when the app goes to
+     * the background or another app opens while it plays, and comes back into
+     * its place with the app. iOS needs `enableBackgroundAudio`. A video with
+     * sound plays mixed with the person's music either way.
+     */
+    pictureInPicture?: boolean;
     onLoad?: (event: {
         duration: number;
     }) => void;
@@ -430,6 +437,9 @@ export interface VideoProps extends BaseProps {
     onError?: (event: {
         message: string;
     }) => void;
+    /** It went into the floating window, and came back out (iOS). */
+    onPictureInPictureStart?: () => void;
+    onPictureInPictureStop?: () => void;
 }
 export interface MapRegion {
     center: {

package/dist/index.cjs

@@ -310,7 +310,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.180";
+var version = "0.0.182";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;

package/dist/index.js

@@ -58,7 +58,7 @@ function craftBinaryNotFoundMessage(triedPath) {
 `);
 }
 // package.json
-var version = "0.0.180";
+var version = "0.0.182";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;

package/dist/ios/src/index.js

@@ -197,7 +197,7 @@ function resolveCraftVersion(startDir = import.meta.dir) {
   while (true) {
     try {
       const packageJSON = JSON.parse(readFileSync2(join3(directory, "package.json"), "utf8"));
-      if (packageJSON.name === "@craft-native/ios" && typeof packageJSON.version === "string" && packageJSON.version.length > 0)
+      if ((packageJSON.name === "@craft-native/ios" || packageJSON.name === "craft-native") && typeof packageJSON.version === "string" && packageJSON.version.length > 0)
         return packageJSON.version;
     } catch {}
     const parent = dirname2(directory);

package/dist/ios/templates/CraftApp.swift

@@ -6812,14 +6812,16 @@ struct CraftWebView: UIViewRepresentable {
                     self.speechSynthesizer = fresh
                 }
 
-                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
-                }
+                // Set up as a native screen's is (CraftNativeServices.swift):
+                // the rate, the pitch, the quiet before it, and the best voice
+                // installed for the language.
+                let utterance = CraftNativeSpeech.utterance(
+                    text,
+                    language: body["language"] as? String,
+                    rate: (body["rate"] as? NSNumber)?.doubleValue,
+                    pitch: (body["pitch"] as? NSNumber)?.doubleValue,
+                    preDelay: (body["preDelay"] as? NSNumber)?.doubleValue
+                )
 
                 self.pendingUtterances.append((utterance, callbackId))
                 self.claimAudioSessionForSpeech {
@@ -6859,21 +6861,6 @@ struct CraftWebView: UIViewRepresentable {
             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.
         ///

package/dist/ios/templates/CraftNativeActions.swift

@@ -41,7 +41,7 @@ enum CraftNativeActions {
     static func capabilities(config: CraftConfig) -> [String] {
         // `speech`, `audio` (background sound) and `eventStream` (a fetch read
         // as it arrives) need nothing the app has to declare.
-        var values = ["device", "clipboard", "haptics", "storage", "lifecycle", "fetch", "dialog", "speech", "audio", "eventStream", "linking", "badge"]
+        var values = ["device", "clipboard", "haptics", "storage", "lifecycle", "fetch", "dialog", "speech", "audio", "eventStream", "linking", "badge", "animation"]
         if config.enableBiometric { values.append("biometric") }
         if config.enableSecureStorage { values.append("secureStorage") }
         if config.enableLocalDatabase { values.append("database") }
@@ -474,6 +474,8 @@ enum CraftNativeActions {
                     text,
                     language: options["language"] as? String,
                     rate: (options["rate"] as? NSNumber)?.doubleValue,
+                    pitch: (options["pitch"] as? NSNumber)?.doubleValue,
+                    preDelay: (options["preDelay"] as? NSNumber)?.doubleValue,
                     interrupt: options["interrupt"] as? Bool ?? true
                 ) { spoken in complete(requestToken, .success(spoken), completion) }
             }

package/dist/ios/templates/CraftNativeScreen.swift

@@ -450,7 +450,17 @@ private func craftNativeAlignContentCode(_ value: String) -> UInt32 {
     }
 }
 
-private final class CraftNativeVideoView: UIView {
+/// A native screen's `<Video>`: AVPlayerViewController in place.
+///
+/// With sound, a video takes the audio session as a playing sound does
+/// (`CraftNativeSounds`): playback, mixed with the person's music, heard
+/// through the silent switch, and with speech ducking the music under a cue
+/// as it does for any other sound. With `pictureInPicture` it carries on in
+/// the system's floating player when the app goes to the background or
+/// another app opens (the app needs the `audio` background mode, which
+/// `enableBackgroundAudio` writes), and comes back into its place when the
+/// app does.
+private final class CraftNativeVideoView: UIView, AVPlayerViewControllerDelegate {
     private let playerController = AVPlayerViewController()
     private var player: AVPlayer?
     private var sourceURI = ""
@@ -460,6 +470,8 @@ private final class CraftNativeVideoView: UIView {
     private var timeObserver: Any?
     private var loops = false
     private var wasPlaying: Bool?
+    /// This video holds a claim on the audio session (`CraftNativeSounds`).
+    private var claimedSession = false
     /// The screen's handlers by event name (`onEnd`, `onPlay`, `onPause`,
     /// `onProgress`, `onLoad`, `onError`), and how an event reaches them.
     var handlers: [String: String] = [:]
@@ -477,6 +489,8 @@ private final class CraftNativeVideoView: UIView {
         // to UI tests and assistive technology.
         playerController.view.isAccessibilityElement = false
         playerController.view.accessibilityElementsHidden = true
+        playerController.delegate = self
+        playerController.allowsPictureInPicturePlayback = false
     }
 
     required init?(coder: NSCoder) {
@@ -515,9 +529,24 @@ private final class CraftNativeVideoView: UIView {
         wasPlaying = nil
         player?.pause()
         player = nil
+        releaseSession()
     }
 
-    func configure(source: Any?, autoplay: Bool, paused: Bool, loop: Bool, muted: Bool, controls: Bool, resizeMode: String?) {
+    /// Playback, mixed with the music, before the player first makes a sound:
+    /// an AVPlayer started under the app's default session stops the music.
+    private func claimSession() {
+        guard !claimedSession else { return }
+        claimedSession = true
+        CraftNativeSounds.claimSession(respectSilentSwitch: false)
+    }
+
+    private func releaseSession() {
+        guard claimedSession else { return }
+        claimedSession = false
+        CraftNativeSounds.releaseSession()
+    }
+
+    func configure(source: Any?, autoplay: Bool, paused: Bool, loop: Bool, muted: Bool, controls: Bool, resizeMode: String?, pictureInPicture: Bool = false) {
         let uri = (source as? String) ?? (source as? [String: Any])?["uri"] as? String ?? ""
         if uri != sourceURI {
             detachPlayer()
@@ -545,14 +574,43 @@ private final class CraftNativeVideoView: UIView {
         }
         guard let player else { return }
         player.isMuted = muted
+        // A muted video makes no sound, so it leaves the session as it is.
+        if muted { releaseSession() } else { claimSession() }
         playerController.showsPlaybackControls = controls
         playerController.videoGravity = resizeMode == "cover" ? .resizeAspectFill
             : resizeMode == "stretch" ? .resize
             : .resizeAspect
+        // Picture in Picture needs the playback session, so a muted video has none.
+        let floating = pictureInPicture && !muted
+        playerController.allowsPictureInPicturePlayback = floating
+        if #available(iOS 14.2, *) {
+            playerController.canStartPictureInPictureAutomaticallyFromInline = floating
+        }
         loops = loop
         if paused || !autoplay { player.pause() } else { player.play() }
     }
 
+    // MARK: AVPlayerViewControllerDelegate
+
+    /// The video stays in its place on the screen while it floats.
+    func playerViewControllerShouldAutomaticallyDismissAtPictureInPictureStart(_ playerViewController: AVPlayerViewController) -> Bool {
+        false
+    }
+
+    /// Back from the floating player (the app came back, or its button was
+    /// tapped): the video is still in its place, so there is nothing to put back.
+    func playerViewController(_ playerViewController: AVPlayerViewController, restoreUserInterfaceForPictureInPictureStopWithCompletionHandler completionHandler: @escaping (Bool) -> Void) {
+        completionHandler(player != nil)
+    }
+
+    func playerViewControllerWillStartPictureInPicture(_ playerViewController: AVPlayerViewController) {
+        fire("onPictureInPictureStart")
+    }
+
+    func playerViewControllerDidStopPictureInPicture(_ playerViewController: AVPlayerViewController) {
+        fire("onPictureInPictureStop")
+    }
+
     /// Load, play and pause, time, the end and failure, as the web's video
     /// element reports them, so `@ended` and `@timeupdate` work as on the page.
     private func observe(_ player: AVPlayer) {
@@ -1296,6 +1354,22 @@ private class CraftNativeFlowView: UIStackView {
         }
     }
 
+    // MARK: Touches
+
+    /// A child drawn outside this view's bounds still takes its touches, as an
+    /// overflowing element is clickable on the web, unless the view clips
+    /// (`overflow: hidden`). UIKit only asks a view's children when the point
+    /// is inside the view, so a floating button absolutely positioned out of a
+    /// zero-height parent (a component's wrapper) drew but could not be tapped.
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        if let hit = super.hitTest(point, with: event) { return hit }
+        guard !clipsToBounds, !isHidden, alpha > 0.01, isUserInteractionEnabled else { return nil }
+        for child in subviews.reversed() where !child.isHidden && child.alpha > 0.01 && child.isUserInteractionEnabled {
+            if let hit = child.hitTest(child.convert(point, from: self), with: event) { return hit }
+        }
+        return nil
+    }
+
     // MARK: Children
 
     override var arrangedSubviews: [UIView] { flowChildren }
@@ -3116,6 +3190,12 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     /// The compiler can emit an anchor as `TouchableOpacity`, so this map is
     /// intentionally shared by Link and the generic pressable path.
     private var linkTargets: [ObjectIdentifier: String] = [:]
+    /// Views by their `transitionID`: one element across an animated change.
+    private var transitionIDs: [ObjectIdentifier: String] = [:]
+    /// `craft.animation.next`: the screen as it was, waiting for the change.
+    private var animationTransaction: CraftNativeAnimationTransaction?
+    /// The animation of the last change, still running.
+    private var runningAnimation: CraftNativeRunningAnimation?
     private var renderedRoot: RenderedNode?
     private weak var lastFocusedInput: UIView?
 
@@ -4399,6 +4479,9 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             }
         case "NAVIGATION_SET_OPTIONS":
             applyNavigationOptions(payload)
+        case "ANIMATE_NEXT":
+            // The next change the screen makes animates (craft.animation.next).
+            beginAnimatedChange(payload)
         case "NAVIGATE_OPEN":
             // A path rather than a screen: the hybrid shell opens it, natively
             // or in the web view.
@@ -4712,6 +4795,11 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             linkTargets.removeValue(forKey: ObjectIdentifier(result))
         }
         result.accessibilityIdentifier = accessibilityIdentifier(node, props: props) ?? path
+        if let transitionID = props["transitionID"] as? String, !transitionID.isEmpty {
+            transitionIDs[ObjectIdentifier(result)] = transitionID
+        } else {
+            transitionIDs.removeValue(forKey: ObjectIdentifier(result))
+        }
         if type != "View" && type != "SafeAreaView" && type != "KeyboardAvoidingView" && type != "ScrollView" && type != "SectionList" && type != "FlatList" && type != "Modal" {
             result.setContentHuggingPriority(.required, for: .vertical)
         }
@@ -5046,7 +5134,8 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
                 loop: (props["loop"] as? Bool) == true,
                 muted: (props["muted"] as? Bool) == true,
                 controls: (props["controls"] as? Bool) == true,
-                resizeMode: style["resizeMode"] as? String ?? props["resizeMode"] as? String
+                resizeMode: style["resizeMode"] as? String ?? props["resizeMode"] as? String,
+                pictureInPicture: (props["pictureInPicture"] as? Bool) == true
             )
         case "Map":
             let map = result as! CraftNativeMapView
@@ -5454,6 +5543,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         }
         handlers.removeValue(forKey: id)
         linkTargets.removeValue(forKey: id)
+        transitionIDs.removeValue(forKey: id)
         pressInHandlers.removeValue(forKey: id)
         pressOutHandlers.removeValue(forKey: id)
         layoutHandlers.removeValue(forKey: id)
@@ -6771,6 +6861,317 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     }
 }
 
+// MARK: - Animated changes
+
+/// What `craft.animation.next(options)` asked for. `duration` in seconds
+/// (0.1 to 1, 0.35 when left out); `curve` "spring" (the default, iOS's own
+/// smooth spring with no bounce unless `bounce` says), "easeInOut" or
+/// "linear".
+struct CraftNativeAnimationSpec {
+    let duration: TimeInterval
+    let curve: String
+    let bounce: CGFloat
+
+    init(_ payload: [String: Any]) {
+        let asked = (payload["duration"] as? NSNumber)?.doubleValue ?? 0.35
+        duration = min(max(asked.isFinite ? asked : 0.35, 0.1), 1)
+        let name = payload["curve"] as? String ?? "spring"
+        curve = ["spring", "easeInOut", "linear"].contains(name) ? name : "spring"
+        let springiness = (payload["bounce"] as? NSNumber)?.doubleValue ?? 0
+        bounce = CGFloat(min(max(springiness.isFinite ? springiness : 0, 0), 0.5))
+    }
+
+    var timing: UITimingCurveProvider {
+        switch curve {
+        case "linear": return UICubicTimingParameters(animationCurve: .linear)
+        case "easeInOut": return UICubicTimingParameters(animationCurve: .easeInOut)
+        default: return UISpringTimingParameters(dampingRatio: 1 - bounce)
+        }
+    }
+}
+
+/// How long a change animates while one runs on any screen, so what the
+/// app changes beside it (the status bar's style) moves in step.
+enum CraftNativeAnimationClock {
+    static var duration: TimeInterval?
+}
+
+/// A view as it was when the change was asked for.
+final class CraftNativeAnimationRecord {
+    let view: UIView
+    weak var superview: UIView?
+    /// In its parent's coordinates, and in the screen's.
+    let frame: CGRect
+    let frameOnScreen: CGRect
+    let alpha: CGFloat
+    let backgroundColor: UIColor?
+    let fontSize: CGFloat?
+    let textColor: UIColor?
+    let transitionID: String?
+
+    init(view: UIView, screen: UIView, transitionID: String?) {
+        self.view = view
+        superview = view.superview
+        frame = view.frame
+        frameOnScreen = view.superview?.convert(view.frame, to: screen) ?? view.frame
+        alpha = view.alpha
+        backgroundColor = view.backgroundColor
+        fontSize = (view as? UILabel)?.font.pointSize
+        textColor = (view as? UILabel)?.textColor
+        self.transitionID = transitionID
+    }
+}
+
+/// The screen between `craft.animation.next` and the change it animates.
+final class CraftNativeAnimationTransaction {
+    let spec: CraftNativeAnimationSpec
+    let reduceMotion: Bool
+    var records: [ObjectIdentifier: CraftNativeAnimationRecord] = [:]
+    var screenBackground: UIColor?
+    /// Reduce Motion: the screen as it was, crossfaded into the new one.
+    var picture: UIView?
+
+    init(spec: CraftNativeAnimationSpec, reduceMotion: Bool) {
+        self.spec = spec
+        self.reduceMotion = reduceMotion
+    }
+}
+
+/// An animation under way: finished at once if another change comes first.
+final class CraftNativeRunningAnimation {
+    var animators: [UIViewPropertyAnimator] = []
+    var cleanup: [() -> Void] = []
+    private var done = false
+
+    func finish() {
+        guard !done else { return }
+        done = true
+        for animator in animators where animator.state == .active {
+            animator.stopAnimation(false)
+            animator.finishAnimation(at: .end)
+        }
+        cleanup.forEach { $0() }
+        cleanup.removeAll()
+    }
+}
+
+extension CraftNativeScreenController {
+    /// `craft.animation.next(options)`: what the screen changes next (a
+    /// render, a patch, its own background and bar) animates instead of
+    /// cutting, as SwiftUI's `withAnimation` or React Native's
+    /// `LayoutAnimation`. Views that stay move and resize to their new
+    /// places; new views fade in and removed ones fade out where they were; a
+    /// view whose font size changed scales into it. Two views with the same
+    /// `transitionID`, one going and one coming, are one element: it moves and
+    /// scales from the old one's place to the new one's, crossfading the two.
+    /// With Reduce Motion on, the whole screen crossfades instead.
+    func beginAnimatedChange(_ payload: [String: Any]) {
+        guard !isAppScript, isViewLoaded else { return }
+        // The last change's animation lands where it was going first.
+        runningAnimation?.finish()
+        runningAnimation = nil
+        if animationTransaction != nil { return }
+        let transaction = CraftNativeAnimationTransaction(spec: CraftNativeAnimationSpec(payload), reduceMotion: UIAccessibility.isReduceMotionEnabled)
+        transaction.screenBackground = view.backgroundColor
+        if transaction.reduceMotion {
+            transaction.picture = view.window == nil ? nil : view.snapshotView(afterScreenUpdates: false)
+        } else {
+            view.layoutIfNeeded()
+            recordAnimationState(renderedRoot, into: transaction)
+        }
+        animationTransaction = transaction
+        CraftNativeAnimationClock.duration = transaction.spec.duration
+        // The change comes from the same turn of the script (the state it
+        // changed renders in a microtask); a slow one still animates.
+        DispatchQueue.main.async { [weak self] in self?.commitAnimatedChange() }
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.15) { [weak self] in self?.commitAnimatedChange() }
+    }
+
+    private func recordAnimationState(_ node: RenderedNode?, into transaction: CraftNativeAnimationTransaction) {
+        guard let node else { return }
+        let id = ObjectIdentifier(node.view)
+        transaction.records[id] = CraftNativeAnimationRecord(view: node.view, screen: view, transitionID: transitionIDs[id])
+        node.children.forEach { recordAnimationState($0, into: transaction) }
+    }
+
+    private func renderedViews(_ node: RenderedNode?, into views: inout [UIView]) {
+        guard let node else { return }
+        views.append(node.view)
+        node.children.forEach { renderedViews($0, into: &views) }
+    }
+
+    private func commitAnimatedChange() {
+        guard let transaction = animationTransaction else { return }
+        animationTransaction = nil
+        let spec = transaction.spec
+        let running = CraftNativeRunningAnimation()
+        runningAnimation = running
+        running.cleanup.append { CraftNativeAnimationClock.duration = nil }
+
+        if transaction.reduceMotion {
+            guard let picture = transaction.picture else { running.finish(); return }
+            picture.frame = view.bounds
+            picture.isUserInteractionEnabled = false
+            view.addSubview(picture)
+            let fade = UIViewPropertyAnimator(duration: 0.3, curve: .easeInOut) { picture.alpha = 0 }
+            fade.addCompletion { _ in running.finish() }
+            running.animators.append(fade)
+            running.cleanup.append { picture.removeFromSuperview() }
+            fade.startAnimation()
+            return
+        }
+
+        UIView.performWithoutAnimation { view.layoutIfNeeded() }
+        var after: [UIView] = []
+        renderedViews(renderedRoot, into: &after)
+        let present = Set(after.map(ObjectIdentifier.init))
+        let records = transaction.records
+
+        // Going: no longer drawn. Only the topmost of a removed subtree moves
+        // to the overlay; what is under it goes with it.
+        let removed = records.values.filter { !present.contains(ObjectIdentifier($0.view)) }
+        let removedIds = Set(removed.map { ObjectIdentifier($0.view) })
+        let removedRoots = removed.filter { record in
+            guard let parent = record.superview else { return true }
+            return !removedIds.contains(ObjectIdentifier(parent))
+        }
+        // Coming: not there before.
+        let inserted = after.filter { records[ObjectIdentifier($0)] == nil }
+        let insertedIds = Set(inserted.map(ObjectIdentifier.init))
+
+        // One element across the change: the old view going, the new one coming.
+        var oldShared: [String: CraftNativeAnimationRecord] = [:]
+        for record in removed { if let tag = record.transitionID { oldShared[tag] = record } }
+        var pairs: [(old: CraftNativeAnimationRecord, new: UIView)] = []
+        for candidate in inserted {
+            if let tag = transitionIDs[ObjectIdentifier(candidate)], let old = oldShared.removeValue(forKey: tag) {
+                pairs.append((old, candidate))
+            }
+        }
+        let pairedNew = Set(pairs.map { ObjectIdentifier($0.new) })
+
+        let overlay = UIView(frame: view.bounds)
+        overlay.isUserInteractionEnabled = false
+        overlay.backgroundColor = .clear
+        view.addSubview(overlay)
+        running.cleanup.append { overlay.removeFromSuperview() }
+
+        let main = UIViewPropertyAnimator(duration: spec.duration, timingParameters: spec.timing)
+        // Fades take the first part, so nothing is half there for long.
+        let fadeOut = UIViewPropertyAnimator(duration: spec.duration * 0.5, curve: .easeOut)
+        let fadeIn = UIViewPropertyAnimator(duration: spec.duration * 0.6, curve: .easeInOut)
+        running.animators = [main, fadeOut, fadeIn]
+
+        // Removed views fade where they were, over what replaced them.
+        for record in removedRoots {
+            let going = record.view
+            going.translatesAutoresizingMaskIntoConstraints = true
+            going.transform = .identity
+            going.frame = record.frameOnScreen
+            overlay.addSubview(going)
+            fadeOut.addAnimations { going.alpha = 0 }
+        }
+
+        // The background, the screen's own included, goes from the old colour.
+        if let before = transaction.screenBackground, let now = view.backgroundColor, !before.isEqual(now) {
+            view.backgroundColor = before
+            main.addAnimations { self.view.backgroundColor = now }
+        }
+
+        // Shared elements: the new view starts where the old one was, at its
+        // size, and the old one travels with it as it fades.
+        for (old, new) in pairs {
+            let target = new.superview?.convert(new.frame, to: view) ?? new.frame
+            let move = morph(from: old.frameOnScreen, to: target, uniform: true)
+            let finalAlpha = new.alpha
+            let base = new.transform
+            new.transform = base.concatenating(move)
+            new.alpha = 0
+            main.addAnimations { new.transform = base }
+            fadeIn.addAnimations { new.alpha = finalAlpha }
+            let going = old.view
+            going.translatesAutoresizingMaskIntoConstraints = true
+            going.transform = .identity
+            going.frame = old.frameOnScreen
+            going.alpha = old.alpha
+            overlay.addSubview(going)
+            main.addAnimations { going.transform = move.inverted() }
+            fadeOut.addAnimations { going.alpha = 0 }
+            running.cleanup.append { new.transform = base; new.alpha = finalAlpha }
+        }
+
+        // New views fade in. A new container holding a shared element keeps it
+        // in sight: only the rest of it fades, and its colour comes up.
+        for added in inserted where !(added.superview.map { insertedIds.contains(ObjectIdentifier($0)) } ?? false) {
+            fadeInInserted(added, pairedNew: pairedNew, animator: fadeIn, running: running)
+        }
+
+        // Views that stay go to their new places and sizes.
+        for record in records.values where present.contains(ObjectIdentifier(record.view)) {
+            let stays = record.view
+            if let label = stays as? UILabel, let before = record.fontSize, abs(before - label.font.pointSize) > 0.5 {
+                let base = label.transform
+                let target = label.superview?.convert(label.frame, to: view) ?? label.frame
+                label.transform = base.concatenating(morph(from: record.frameOnScreen, to: target, uniform: true))
+                main.addAnimations { label.transform = base }
+                running.cleanup.append { label.transform = base }
+            } else if record.superview === stays.superview, record.frame != stays.frame {
+                let final = stays.frame
+                stays.frame = record.frame
+                main.addAnimations { stays.frame = final }
+            }
+            if let before = record.backgroundColor, let now = stays.backgroundColor, !before.isEqual(now) {
+                stays.backgroundColor = before
+                main.addAnimations { stays.backgroundColor = now }
+            }
+            if let label = stays as? UILabel, let before = record.textColor, !before.isEqual(label.textColor) {
+                let now = label.textColor
+                label.textColor = before
+                UIView.transition(with: label, duration: spec.duration * 0.6, options: [.transitionCrossDissolve, .allowAnimatedContent]) { label.textColor = now }
+            }
+        }
+
+        main.addCompletion { _ in running.finish() }
+        fadeOut.startAnimation()
+        fadeIn.startAnimation()
+        main.startAnimation()
+    }
+
+    /// The transform that puts a view at `final` where `start` was: moved
+    /// centre to centre and scaled, by height alone when `uniform`, so text
+    /// keeps its shape.
+    private func morph(from start: CGRect, to final: CGRect, uniform: Bool) -> CGAffineTransform {
+        guard final.width > 0, final.height > 0, start.width > 0, start.height > 0 else { return .identity }
+        let sy = start.height / final.height
+        let sx = uniform ? sy : start.width / final.width
+        let dx = start.midX - final.midX
+        let dy = start.midY - final.midY
+        return CGAffineTransform(translationX: dx, y: dy).scaledBy(x: sx, y: sy)
+    }
+
+    private func fadeInInserted(_ view: UIView, pairedNew: Set<ObjectIdentifier>, animator: UIViewPropertyAnimator, running: CraftNativeRunningAnimation) {
+        if pairedNew.contains(ObjectIdentifier(view)) { return }
+        guard containsShared(view, pairedNew: pairedNew) else {
+            let finalAlpha = view.alpha
+            view.alpha = 0
+            animator.addAnimations { view.alpha = finalAlpha }
+            running.cleanup.append { view.alpha = finalAlpha }
+            return
+        }
+        if let colour = view.backgroundColor, colour != .clear {
+            view.backgroundColor = colour.withAlphaComponent(0)
+            animator.addAnimations { view.backgroundColor = colour }
+            running.cleanup.append { view.backgroundColor = colour }
+        }
+        for child in view.subviews { fadeInInserted(child, pairedNew: pairedNew, animator: animator, running: running) }
+    }
+
+    private func containsShared(_ view: UIView, pairedNew: Set<ObjectIdentifier>) -> Bool {
+        if pairedNew.contains(ObjectIdentifier(view)) { return true }
+        return view.subviews.contains { containsShared($0, pairedNew: pairedNew) }
+    }
+}
+
 /// `console` for native screens: the unified log, subsystem `craft.native`,
 /// category the screen's name. Read it with
 /// `log stream --predicate 'subsystem == "craft.native"'`.

package/dist/ios/templates/CraftNativeServices.swift

@@ -48,18 +48,16 @@ final class CraftNativeSpeech: NSObject, AVSpeechSynthesizerDelegate {
 
     /// Says `text`; `done` hears true once it was spoken, false when it was
     /// stopped or interrupted. With `interrupt` false it waits its turn behind
-    /// what is being said. Main thread.
-    func speak(_ text: String, language: String?, rate: Double?, interrupt: Bool, done: @escaping (Bool) -> Void) {
+    /// what is being said. `pitch` is 0.5 to 2 (1 is the voice's own), and
+    /// `preDelay` is seconds of quiet before the words, after whatever was
+    /// said before them. Main thread.
+    func speak(_ text: String, language: String?, rate: Double?, pitch: Double? = nil, preDelay: Double? = nil, interrupt: Bool, done: @escaping (Bool) -> Void) {
         pendingRelease?.cancel()
         pendingRelease = nil
         if interrupt, cancelPending() { retireSynthesizer() }
-        let utterance = AVSpeechUtterance(string: text)
-        utterance.rate = Self.utteranceRate(rate ?? 1)
-        // An unknown language finds no voice, and a nil voice is the device's own.
-        if let language, !language.isEmpty, let voice = AVSpeechSynthesisVoice(language: language) {
-            utterance.voice = voice
-        }
+        let utterance = Self.utterance(text, language: language, rate: rate, pitch: pitch, preDelay: preDelay)
         pending.append((utterance, done))
+        holdsSession = true
         sessionQueue.async {
             self.claimSession()
             DispatchQueue.main.async {
@@ -70,6 +68,74 @@ final class CraftNativeSpeech: NSObject, AVSpeechSynthesizerDelegate {
         }
     }
 
+    /// Whether speech has the audio session, or is about to: a sound or a
+    /// video starting meanwhile leaves the category to speech, which hands it
+    /// over when it lets go (`CraftNativeSounds.reclaimSessionIfPlaying`).
+    /// Main thread.
+    private(set) var holdsSession = false
+
+    /// One utterance, set up the same way for a native screen and the page
+    /// (CraftApp.swift): the rate on AVSpeechUtterance's scale, the pitch,
+    /// the quiet before it, and the best voice installed for the language.
+    static func utterance(_ text: String, language: String?, rate: Double?, pitch: Double?, preDelay: Double?) -> AVSpeechUtterance {
+        let utterance = AVSpeechUtterance(string: text)
+        utterance.rate = utteranceRate(rate ?? 1)
+        let wantedPitch = pitch.flatMap { $0.isFinite ? $0 : nil } ?? 1
+        utterance.pitchMultiplier = Float(min(max(wantedPitch, 0.5), 2))
+        let quiet = preDelay.flatMap { $0.isFinite ? $0 : nil } ?? 0
+        utterance.preUtteranceDelay = min(max(quiet, 0), 5)
+        // An unknown language finds no voice, and a nil voice is the device's own.
+        if let voice = bestVoice(for: language) { utterance.voice = voice }
+        return utterance
+    }
+
+    private static var voices: [String: AVSpeechSynthesisVoice] = [:]
+    private static var voicesObserver: NSObjectProtocol?
+
+    /// The best voice on this phone for `language` (the device's own when
+    /// nil): a premium voice when one is installed, else an enhanced one,
+    /// else the compact voice iOS would pick. Among voices of one quality the
+    /// one sharing the default voice's name wins ("Anna (Enhanced)" over
+    /// another enhanced voice when Anna is the default), so a download in
+    /// Settings changes how a voice sounds, not who it is. Novelty voices and
+    /// the person's own Personal Voice are never picked. Remembered per
+    /// language until the installed voices change. Main thread.
+    static func bestVoice(for language: String?) -> AVSpeechSynthesisVoice? {
+        let wanted = (language?.isEmpty == false ? language! : AVSpeechSynthesisVoice.currentLanguageCode())
+        if let known = voices[wanted] { return known }
+        if voicesObserver == nil {
+            if #available(iOS 17.0, *) {
+                voicesObserver = NotificationCenter.default.addObserver(forName: AVSpeechSynthesizer.availableVoicesDidChangeNotification, object: nil, queue: .main) { _ in
+                    CraftNativeSpeech.voices.removeAll()
+                }
+            }
+        }
+        guard let standard = AVSpeechSynthesisVoice(language: wanted) else { return nil }
+        let name = Self.baseName(standard.name)
+        let candidates = AVSpeechSynthesisVoice.speechVoices().filter { voice in
+            guard voice.language == standard.language else { return false }
+            if #available(iOS 17.0, *) {
+                if voice.voiceTraits.contains(.isNoveltyVoice) || voice.voiceTraits.contains(.isPersonalVoice) { return false }
+            }
+            return true
+        }
+        let best = candidates.max { lhs, rhs in
+            let left = (lhs.quality.rawValue, Self.baseName(lhs.name) == name ? 1 : 0, lhs.identifier == standard.identifier ? 1 : 0)
+            let right = (rhs.quality.rawValue, Self.baseName(rhs.name) == name ? 1 : 0, rhs.identifier == standard.identifier ? 1 : 0)
+            if left != right { return left < right }
+            // Stable between launches: the same voice every time.
+            return lhs.identifier > rhs.identifier
+        } ?? standard
+        let chosen = best.quality.rawValue >= standard.quality.rawValue ? best : standard
+        voices[wanted] = chosen
+        return chosen
+    }
+
+    /// "Anna (Enhanced)" and "Anna (Premium)" are both Anna.
+    private static func baseName(_ name: String) -> String {
+        name.components(separatedBy: " (").first ?? name
+    }
+
     func stop() {
         // When something was sounding, its didCancel hands the session back
         // once the audio has stopped; deactivating before that fails as busy.
@@ -95,8 +161,13 @@ final class CraftNativeSpeech: NSObject, AVSpeechSynthesizerDelegate {
         synthesizer = fresh
     }
 
-    /// The page's rate, where 1 is normal, on AVSpeechUtterance's scale: the
-    /// same mapping as the page's speech, so a cue sounds alike in both.
+    /// The page's rate, where 1 is normal, on AVSpeechUtterance's scale, for
+    /// a native screen and the page alike.
+    ///
+    /// 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.
     static func utteranceRate(_ rate: Double) -> Float {
         let requested = Float(min(max(rate.isFinite ? rate : 1, 0.5), 2))
         let normal = AVSpeechUtteranceDefaultSpeechRate
@@ -129,11 +200,25 @@ final class CraftNativeSpeech: NSObject, AVSpeechSynthesizerDelegate {
             guard let self else { return }
             self.pendingRelease = nil
             guard self.pending.isEmpty, !self.synthesizer.isSpeaking else { return }
+            let soundsPlaying = CraftNativeSounds.isPlaying
             self.sessionQueue.async {
-                guard let previous = self.sessionToRestore else { return }
+                guard let previous = self.sessionToRestore else {
+                    // The claim failed: there is nothing to hand back.
+                    DispatchQueue.main.async {
+                        guard self.pending.isEmpty else { return }
+                        self.holdsSession = false
+                        CraftNativeSounds.reclaimSessionIfPlaying(handedBack: nil)
+                    }
+                    return
+                }
                 let session = AVAudioSession.sharedInstance()
                 do {
-                    try session.setActive(false, options: .notifyOthersOnDeactivation)
+                    // Deactivating ends the ducking. A video or a sound still
+                    // playing keeps it busy; the category put back below
+                    // carries no ducking, so the music comes back up anyway.
+                    if !soundsPlaying {
+                        try session.setActive(false, options: .notifyOthersOnDeactivation)
+                    }
                 } catch {
                     // Busy: the last of the audio has not drained, or the app
                     // plays something of its own. Once more shortly covers the first.
@@ -144,7 +229,11 @@ final class CraftNativeSpeech: NSObject, AVSpeechSynthesizerDelegate {
                 }
                 self.sessionToRestore = nil
                 try? session.setCategory(previous.0, mode: previous.1, options: previous.2)
-                DispatchQueue.main.async { CraftNativeSounds.reclaimSessionIfPlaying() }
+                DispatchQueue.main.async {
+                    // A cue that came in meanwhile claims the session again.
+                    if self.pending.isEmpty { self.holdsSession = false }
+                    CraftNativeSounds.reclaimSessionIfPlaying(handedBack: previous)
+                }
             }
         }
         pendingRelease = work
@@ -337,12 +426,26 @@ final class CraftNativeSounds {
         RunLoop.main.add(timer, forMode: .common)
     }
 
+    /// Whether a sound, a native screen's Web Audio or a video is playing.
+    static var isPlaying: Bool { playing > 0 }
+    /// A sound started while speech held the session: speech's category was
+    /// left alone (it plays too, ducking the music under the cue), and the
+    /// category to put back later is the one speech hands back.
+    private static var claimedUnderSpeech = false
+
     /// Takes the session for one more playing sound. Native screens' Web
-    /// Audio (CraftWebAudio.swift) counts here too, so speech hands the
-    /// session back to whichever of them still plays.
+    /// Audio (CraftWebAudio.swift) and videos (CraftNativeScreen.swift) count
+    /// here too, so speech hands the session back to whichever of them still
+    /// plays. Main thread.
     static func claimSession(respectSilentSwitch: Bool) {
         playing += 1
-        category = respectSilentSwitch ? .ambient : .playback
+        // Playback outranks ambient: a video heard through the silent switch
+        // is not muted by a breathing exercise's rain starting after it.
+        category = respectSilentSwitch && (playing == 1 || category == .ambient) ? .ambient : .playback
+        if CraftNativeSpeech.shared.holdsSession {
+            if sessionToRestore == nil { claimedUnderSpeech = true }
+            return
+        }
         let session = AVAudioSession.sharedInstance()
         if sessionToRestore == nil { sessionToRestore = (session.category, session.mode, session.categoryOptions) }
         do {
@@ -355,14 +458,28 @@ final class CraftNativeSounds {
 
     static func releaseSession() {
         playing = max(0, playing - 1)
-        guard playing == 0, let previous = sessionToRestore else { return }
+        guard playing == 0 else { return }
+        if claimedUnderSpeech {
+            // Speech still holds the session and puts its own back.
+            claimedUnderSpeech = false
+            return
+        }
+        guard let previous = sessionToRestore else { return }
         sessionToRestore = nil
+        if CraftNativeSpeech.shared.holdsSession { return }
         try? AVAudioSession.sharedInstance().setCategory(previous.0, mode: previous.1, options: previous.2)
     }
 
-    /// Speech handed the session back with the category it found, which may
-    /// predate a sound started while it spoke: take it again for the sound.
-    static func reclaimSessionIfPlaying() {
+    /// Speech handed the session back with the category it found
+    /// (`handedBack`, nil when it never took it), which may predate a sound
+    /// started while it spoke: take it again for the sound. Main thread.
+    static func reclaimSessionIfPlaying(handedBack: (AVAudioSession.Category, AVAudioSession.Mode, AVAudioSession.CategoryOptions)?) {
+        if claimedUnderSpeech {
+            claimedUnderSpeech = false
+            let session = AVAudioSession.sharedInstance()
+            sessionToRestore = handedBack ?? (session.category, session.mode, session.categoryOptions)
+            if playing > 0 { try? session.setActive(true) }
+        }
         guard playing > 0 else { return }
         try? AVAudioSession.sharedInstance().setCategory(category, mode: .default, options: [.mixWithOthers])
     }

package/dist/ios/templates/CraftNativeUI.swift

@@ -522,7 +522,8 @@ enum CraftStatusBar {
         }
         guard let root = CraftPresenter.keyWindow()?.rootViewController else { return false }
         teach(root)
-        UIView.animate(withDuration: 0.2) { root.setNeedsStatusBarAppearanceUpdate() }
+        // In step with a screen's animated change (craft.animation.next) when one runs.
+        UIView.animate(withDuration: CraftNativeAnimationClock.duration ?? 0.2) { root.setNeedsStatusBarAppearanceUpdate() }
         return true
     }
 

package/dist/mobile.js

@@ -688,6 +688,7 @@ var speech = {
     return new Promise((resolve) => {
       const utterance = new Utterance(text);
       utterance.rate = speechRate(options.rate);
+      utterance.pitch = speechRate(options.pitch);
       if (options.language)
         utterance.lang = options.language;
       const settle = (spoken) => {

package/package.json

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