craft-native 0.0.166 → 0.0.168

package/dist/cli.js

@@ -3303,7 +3303,7 @@ function pinCraftNativeDependency(packagePath, craftVersion) {
 `);
 }
 // package.json
-var version = "0.0.166";
+var version = "0.0.168";
 
 // 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.166";
+var version = "0.0.168";
 
 // 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.166";
+var version = "0.0.168";
 
 // src/sdk-version.ts
 var SDK_VERSION = version;

package/dist/ios/templates/CraftApp.swift

@@ -1712,14 +1712,22 @@ 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.
+        // Speech synthesis. Each utterance not finished yet is held beside the
+        // call waiting on it. A cue that interrupts one still sounding speaks
+        // on a fresh synthesizer: AVSpeechSynthesizer can drop an utterance
+        // handed to it straight after `stopSpeaking(at: .immediate)`, which
+        // lost the "2" of a "3, 2, 1" countdown. The stopped one is kept in
+        // `retiredSpeechSynthesizers` until it reports the cancel.
         private lazy var speechSynthesizer: AVSpeechSynthesizer = {
             let synthesizer = AVSpeechSynthesizer()
             synthesizer.delegate = self
             return synthesizer
         }()
+        private var retiredSpeechSynthesizers: [AVSpeechSynthesizer] = []
+        /// The session is handed back this long after the last word, so a
+        /// countdown ducks the music once rather than between every number.
+        private static let speechReleaseAfterSilence: TimeInterval = 1.5
+        private var pendingSpeechRelease: DispatchWorkItem?
         private var pendingUtterances: [(utterance: AVSpeechUtterance, callbackId: String?)] = []
         /// What the session was before speech claimed it; nil while speech
         /// does not hold it.
@@ -6715,8 +6723,13 @@ struct CraftWebView: UIViewRepresentable {
 
         private func speak(_ text: String, body: [String: Any], callbackId: String?) {
             DispatchQueue.main.async {
-                if body["interrupt"] as? Bool ?? true {
-                    self.cancelPendingSpeech()
+                self.pendingSpeechRelease?.cancel()
+                self.pendingSpeechRelease = nil
+                if body["interrupt"] as? Bool ?? true, self.cancelPendingSpeech() {
+                    self.retiredSpeechSynthesizers.append(self.speechSynthesizer)
+                    let fresh = AVSpeechSynthesizer()
+                    fresh.delegate = self
+                    self.speechSynthesizer = fresh
                 }
 
                 let utterance = AVSpeechUtterance(string: text)
@@ -6818,8 +6831,20 @@ struct CraftWebView: UIViewRepresentable {
         /// 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) {
+        private func releaseAudioSessionIfSilent(retry: Bool = true, after delay: TimeInterval = Coordinator.speechReleaseAfterSilence) {
             guard pendingUtterances.isEmpty else { return }
+            pendingSpeechRelease?.cancel()
+            let work = DispatchWorkItem { [weak self] in
+                guard let self else { return }
+                self.pendingSpeechRelease = nil
+                guard self.pendingUtterances.isEmpty, !self.speechSynthesizer.isSpeaking else { return }
+                self.deactivateSpeechAudioSession(retry: retry)
+            }
+            pendingSpeechRelease = work
+            DispatchQueue.main.asyncAfter(deadline: .now() + delay, execute: work)
+        }
+
+        private func deactivateSpeechAudioSession(retry: Bool) {
             speechAudioQueue.async {
                 guard let previous = self.speechAudioSessionToRestore else { return }
                 let session = AVAudioSession.sharedInstance()
@@ -6832,8 +6857,8 @@ struct CraftWebView: UIViewRepresentable {
                     // 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)
+                        DispatchQueue.main.async {
+                            self.releaseAudioSessionIfSilent(retry: false, after: 0.5)
                         }
                         return
                     }
@@ -6844,11 +6869,14 @@ struct CraftWebView: UIViewRepresentable {
             }
         }
 
-        fileprivate func speechDidEnd(_ utterance: AVSpeechUtterance, spoken: Bool) {
+        fileprivate func speechDidEnd(_ synthesizer: AVSpeechSynthesizer, _ utterance: AVSpeechUtterance, spoken: Bool) {
             if let index = pendingUtterances.firstIndex(where: { $0.utterance === utterance }) {
                 let entry = pendingUtterances.remove(at: index)
                 resolveCallback(entry.callbackId, result: spoken)
             }
+            if synthesizer !== speechSynthesizer, !synthesizer.isSpeaking {
+                retiredSpeechSynthesizers.removeAll { $0 === synthesizer }
+            }
             releaseAudioSessionIfSilent()
         }
 
@@ -8480,11 +8508,11 @@ extension CraftWebView.Coordinator: WKUIDelegate {
 
 extension CraftWebView.Coordinator: AVSpeechSynthesizerDelegate {
     func speechSynthesizer(_ synthesizer: AVSpeechSynthesizer, didFinish utterance: AVSpeechUtterance) {
-        DispatchQueue.main.async { self.speechDidEnd(utterance, spoken: true) }
+        DispatchQueue.main.async { self.speechDidEnd(synthesizer, utterance, spoken: true) }
     }
 
     func speechSynthesizer(_ synthesizer: AVSpeechSynthesizer, didCancel utterance: AVSpeechUtterance) {
-        DispatchQueue.main.async { self.speechDidEnd(utterance, spoken: false) }
+        DispatchQueue.main.async { self.speechDidEnd(synthesizer, utterance, spoken: false) }
     }
 }
 

package/dist/ios/templates/CraftNativeScreen.swift

@@ -2694,7 +2694,7 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     }
 
     private func refreshTraitDefaults() {
-        view.backgroundColor = config.resolvedBackgroundColor
+        view.backgroundColor = screenBackgroundColor ?? config.resolvedBackgroundColor
         if let document = mutationDocument.node("root") {
             renderCommitted(document)
         } else {
@@ -2895,8 +2895,8 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     /// - `craft.secureStorage.getSync(key)`: the Keychain item the web page's
     ///   `craft.secureStorage.set` wrote.
     /// - `craft.navigation.setOptions({ title, largeTitle, hidden, backTitle,
-    ///   tabBarHidden, contentSwipeBack, tabSwipeEnabled, rightButtons })`; a right button's
-    ///   tap is the event `navButton`.
+    ///   tabBarHidden, contentSwipeBack, tabSwipeEnabled, backgroundColor, rightButtons })`;
+    ///   a right button's tap is the event `navButton`.
     ///
     /// A runtime that assigns `craft.storage` (or the others) afterwards keeps
     /// these: each namespace is a property whose setter adds them back to the
@@ -3148,6 +3148,10 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
     /// own horizontal pager or chart gesture.
     private(set) var tabSwipeEnabled = true
     private var prefersLargeTitle: Bool?
+    /// The screen's own colour (`backgroundColor`), under the status bar and
+    /// the home indicator too, where its content never reaches: a black
+    /// full-screen timer is black edge to edge. nil is the app's.
+    private var screenBackgroundColor: UIColor?
 
     /// Whether this screen asked for a bar of its own through `setOptions`: a
     /// title, a large title or buttons, and not `hidden`. A tab's root screen
@@ -3188,6 +3192,10 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         if let tabSwipeEnabled = options["tabSwipeEnabled"] as? Bool {
             self.tabSwipeEnabled = tabSwipeEnabled
         }
+        if options.keys.contains("backgroundColor") {
+            screenBackgroundColor = color(options["backgroundColor"])
+            view.backgroundColor = screenBackgroundColor ?? config.resolvedBackgroundColor
+        }
         if let hidden = options["hidden"] as? Bool {
             navigationBarHidden = hidden
             if navigationController?.topViewController === self {
@@ -3345,12 +3353,26 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
             }
             return nil
         }
+        /// The scroll view the screen starts with, when nothing sits above it:
+        /// the root's first child, its first, and so on, none padded on top.
+        func leading(_ node: RenderedNode) -> UIScrollView? {
+            if let scroll = node.view as? CraftNativeScrollView { return scroll.isVertical && scroll.isScrollEnabled ? scroll : nil }
+            if let list = node.view as? CraftNativeFlatList {
+                return list.isScrollEnabled && (list.collectionViewLayout as? UICollectionViewFlowLayout)?.scrollDirection != .horizontal ? list : nil
+            }
+            guard paddingInsets(node.style).top == 0,
+                  let first = node.children.first(where: { $0.type != "Modal" && !$0.view.isHidden }) else { return nil }
+            return leading(first)
+        }
         let scroll = find(renderedRoot)
         // Under a large title the screen runs edge to edge, as UIKit's own
         // screens do: the scroll view starts under the bar and insets its
         // content by it, so the title collapses and pull to refresh draws
-        // in the bar's space. Other screens stay inside the safe area.
-        let edgeToEdge = scroll != nil && prefersLargeTitle == true
+        // in the bar's space. So does a screen that starts with its scroll
+        // view: its content scrolls up under the bar behind iOS's scroll edge
+        // effect, rather than over the bar's back button. Other screens stay
+        // inside the safe area.
+        let edgeToEdge = scroll != nil && (prefersLargeTitle == true || scroll === leading(renderedRoot))
         if rootTopToView?.isActive != edgeToEdge {
             rootTopToSafeArea?.isActive = !edgeToEdge
             rootTopToView?.isActive = edgeToEdge
@@ -4924,6 +4946,10 @@ final class CraftNativeScreenController: UIViewController, UIScrollViewDelegate,
         )
         // A label paints its background inside its own bounds, so a rounded
         // chip of text clips to its corners.
+        // A scroll view does not clip either: its content runs on under the
+        // floating tab bar and the home indicator, as iOS 26's own screens'
+        // does. At the top, a screen that starts with one runs edge to edge
+        // (trackContentScrollView), so nothing scrolls over the bar.
         view.clipsToBounds = style["overflow"] as? String == "hidden"
             || (view is UILabel && (view.craftRequestedCornerRadius ?? 0) > 0)
         view.layer.masksToBounds = view.clipsToBounds

package/dist/ios/templates/CraftNativeServices.swift

@@ -13,12 +13,32 @@ import UserNotifications
 /// `craft.speech` on a native screen: AVSpeechSynthesizer, set up the way the
 /// page's own speech is (CraftApp.swift). The music ducks rather than stops,
 /// the silent switch does not mute a cue, and the session is handed back once
-/// nothing is left to say.
+/// nothing has been said for a moment.
+///
+/// Three things a workout's countdown ("3", "2", "1", a second apart) needs:
+/// - An interrupting cue is never lost. AVSpeechSynthesizer can drop an
+///   utterance handed to it straight after `stopSpeaking(at: .immediate)`,
+///   so a cue that cuts another off speaks on a fresh synthesizer while the
+///   stopped one winds down.
+/// - The session stays claimed for `releaseAfterSilence` after the last word,
+///   so the music ducks once for a countdown instead of swelling back up
+///   between every number, and the next number does not wait on the audio
+///   hardware again.
+/// - Activating and deactivating the session blocks until the hardware
+///   answers, so it happens on a queue of its own, never the main thread the
+///   screens' JavaScript and their timers run on.
 final class CraftNativeSpeech: NSObject, AVSpeechSynthesizerDelegate {
     static let shared = CraftNativeSpeech()
+    /// How long the session is kept after the last word.
+    static let releaseAfterSilence: TimeInterval = 1.5
 
-    private let synthesizer = AVSpeechSynthesizer()
+    private var synthesizer = AVSpeechSynthesizer()
+    /// Synthesizers stopped by an interruption, kept until they report it.
+    private var retired: [AVSpeechSynthesizer] = []
     private var pending: [(utterance: AVSpeechUtterance, done: (Bool) -> Void)] = []
+    private var pendingRelease: DispatchWorkItem?
+    /// The audio session's work, in order. `sessionToRestore` is only touched here.
+    private let sessionQueue = DispatchQueue(label: "dev.craft.native.speech-session")
     private var sessionToRestore: (AVAudioSession.Category, AVAudioSession.Mode, AVAudioSession.CategoryOptions)?
 
     private override init() {
@@ -27,9 +47,12 @@ final class CraftNativeSpeech: NSObject, AVSpeechSynthesizerDelegate {
     }
 
     /// Says `text`; `done` hears true once it was spoken, false when it was
-    /// stopped or interrupted. Main thread.
+    /// 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) {
-        if interrupt { cancelPending() }
+        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.
@@ -37,8 +60,14 @@ final class CraftNativeSpeech: NSObject, AVSpeechSynthesizerDelegate {
             utterance.voice = voice
         }
         pending.append((utterance, done))
-        claimSession()
-        synthesizer.speak(utterance)
+        sessionQueue.async {
+            self.claimSession()
+            DispatchQueue.main.async {
+                // Stopped while the session was being set up: say nothing.
+                guard self.pending.contains(where: { $0.utterance === utterance }) else { return }
+                self.synthesizer.speak(utterance)
+            }
+        }
     }
 
     func stop() {
@@ -58,6 +87,14 @@ final class CraftNativeSpeech: NSObject, AVSpeechSynthesizerDelegate {
         return sounding
     }
 
+    /// The stopped synthesizer winds down on its own; the next cue gets a new one.
+    private func retireSynthesizer() {
+        retired.append(synthesizer)
+        let fresh = AVSpeechSynthesizer()
+        fresh.delegate = self
+        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.
     static func utteranceRate(_ rate: Double) -> Float {
@@ -69,6 +106,7 @@ final class CraftNativeSpeech: NSObject, AVSpeechSynthesizerDelegate {
         return min(max(mapped, AVSpeechUtteranceMinimumSpeechRate), AVSpeechUtteranceMaximumSpeechRate)
     }
 
+    /// Session queue.
     private func claimSession() {
         guard sessionToRestore == nil else { return }
         let session = AVAudioSession.sharedInstance()
@@ -83,37 +121,52 @@ final class CraftNativeSpeech: NSObject, AVSpeechSynthesizerDelegate {
         }
     }
 
-    private func releaseSessionIfSilent(retry: Bool = true) {
-        guard pending.isEmpty, let previous = sessionToRestore else { return }
-        let session = AVAudioSession.sharedInstance()
-        do {
-            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.
-            if retry {
-                DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) { self.releaseSessionIfSilent(retry: false) }
-                return
+    /// Hand the session back once nothing has been said for a moment. Main thread.
+    private func releaseSessionIfSilent(retry: Bool = true, after delay: TimeInterval = CraftNativeSpeech.releaseAfterSilence) {
+        guard pending.isEmpty else { return }
+        pendingRelease?.cancel()
+        let work = DispatchWorkItem { [weak self] in
+            guard let self else { return }
+            self.pendingRelease = nil
+            guard self.pending.isEmpty, !self.synthesizer.isSpeaking else { return }
+            self.sessionQueue.async {
+                guard let previous = self.sessionToRestore else { return }
+                let session = AVAudioSession.sharedInstance()
+                do {
+                    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.
+                    if retry {
+                        DispatchQueue.main.async { self.releaseSessionIfSilent(retry: false, after: 0.5) }
+                        return
+                    }
+                }
+                self.sessionToRestore = nil
+                try? session.setCategory(previous.0, mode: previous.1, options: previous.2)
+                DispatchQueue.main.async { CraftNativeSounds.reclaimSessionIfPlaying() }
             }
         }
-        sessionToRestore = nil
-        try? session.setCategory(previous.0, mode: previous.1, options: previous.2)
-        CraftNativeSounds.reclaimSessionIfPlaying()
+        pendingRelease = work
+        DispatchQueue.main.asyncAfter(deadline: .now() + delay, execute: work)
     }
 
-    private func finished(_ utterance: AVSpeechUtterance, spoken: Bool) {
+    private func finished(_ synthesizer: AVSpeechSynthesizer, _ utterance: AVSpeechUtterance, spoken: Bool) {
         if let index = pending.firstIndex(where: { $0.utterance === utterance }) {
             pending.remove(at: index).done(spoken)
         }
+        if synthesizer !== self.synthesizer, !synthesizer.isSpeaking {
+            retired.removeAll { $0 === synthesizer }
+        }
         releaseSessionIfSilent()
     }
 
     func speechSynthesizer(_ synthesizer: AVSpeechSynthesizer, didFinish utterance: AVSpeechUtterance) {
-        DispatchQueue.main.async { self.finished(utterance, spoken: true) }
+        DispatchQueue.main.async { self.finished(synthesizer, utterance, spoken: true) }
     }
 
     func speechSynthesizer(_ synthesizer: AVSpeechSynthesizer, didCancel utterance: AVSpeechUtterance) {
-        DispatchQueue.main.async { self.finished(utterance, spoken: false) }
+        DispatchQueue.main.async { self.finished(synthesizer, utterance, spoken: false) }
     }
 }
 

package/package.json

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