@swiftbrowser/native 0.18.1 → 0.18.2

package/swift/Sources/SwiftBrowserNative/Host/ICloudBridge.swift

@@ -0,0 +1,112 @@
+#if canImport(SwiftUI) && !canImport(FoundationBridge)
+import Foundation
+
+/// The app's iCloud Drive container, for `fileManager.iCloudDirectory()`
+/// (packages/react/src/fileManager.ts) and the files bridge's roots. The
+/// container is the first one the app's entitlements name
+/// (`com.apple.developer.ubiquity-container-identifiers`); its `Documents`
+/// folder is what the Files app shows under iCloud Drive when the Info.plist
+/// declares it (`NSUbiquitousContainers`). Resolving it asks the daemon, so
+/// it happens off the main thread, once; nil where the app has no
+/// entitlement, the user no iCloud Drive, or the device no account.
+final class ICloudContainer: @unchecked Sendable {
+    static let shared = ICloudContainer()
+
+    private let lock = NSLock()
+    /// nil: not asked yet; `.some(nil)`: asked, unavailable.
+    private var resolved: URL??
+
+    /// The container's URL once resolved; nil before (`resolve()` first) or when unavailable.
+    var cached: URL? {
+        lock.lock()
+        defer { lock.unlock() }
+        return resolved ?? nil
+    }
+
+    /// What was resolved so far (a synchronous read: the lock is not for an async context).
+    private func known() -> URL?? {
+        lock.lock()
+        defer { lock.unlock() }
+        return resolved
+    }
+
+    private func store(_ container: URL?) {
+        lock.lock()
+        defer { lock.unlock() }
+        resolved = .some(container)
+    }
+
+    /// The container's `Documents` folder, made if need be; nil when iCloud Drive is not there for the app.
+    func resolve() async -> URL? {
+        if let known = known() {
+            return known.map { $0.appendingPathComponent("Documents", isDirectory: true) }
+        }
+        let container = await Task.detached(priority: .userInitiated) { () -> URL? in
+            let manager = FileManager.default
+            guard manager.ubiquityIdentityToken != nil, let url = manager.url(forUbiquityContainerIdentifier: nil) else { return nil }
+            try? manager.createDirectory(at: url.appendingPathComponent("Documents", isDirectory: true), withIntermediateDirectories: true)
+            return url.standardizedFileURL
+        }.value
+        store(container)
+        return container.map { $0.appendingPathComponent("Documents", isDirectory: true) }
+    }
+
+    /// Whether `url` is in the container (and so coordinated and possibly not downloaded).
+    func contains(_ url: URL) -> Bool {
+        guard let root = cached else { return false }
+        return url.path == root.path || url.path.hasPrefix(root.path + "/")
+    }
+}
+
+/// Watches the container's documents (`NSMetadataQuery`) and reports the
+/// URLs that changed, so `fileManager.watch` and `useFileStorage` see what
+/// another device wrote; started when the app first asks for iCloud Drive.
+@MainActor
+final class ICloudWatcher {
+    private let query = NSMetadataQuery()
+    private let send: ([String]) -> Void
+    private var observers: [NSObjectProtocol] = []
+
+    /// `send` hands the changed URLs to the app (`__sbFilesChanged`).
+    init(send: @escaping ([String]) -> Void) {
+        self.send = send
+        query.searchScopes = [NSMetadataQueryUbiquitousDocumentsScope]
+        query.predicate = NSPredicate(format: "%K LIKE '*'", NSMetadataItemFSNameKey)
+        query.operationQueue = .main
+        let center = NotificationCenter.default
+        observers.append(center.addObserver(forName: .NSMetadataQueryDidFinishGathering, object: query, queue: .main) { [weak self] _ in
+            MainActor.assumeIsolated { self?.gathered() }
+        })
+        observers.append(center.addObserver(forName: .NSMetadataQueryDidUpdate, object: query, queue: .main) { [weak self] notification in
+            // The items are read on the main queue only, here; the compiler cannot see that.
+            nonisolated(unsafe) let info = notification.userInfo
+            MainActor.assumeIsolated { self?.updated(info) }
+        })
+        query.start()
+    }
+
+    func stop() {
+        query.stop()
+        for observer in observers { NotificationCenter.default.removeObserver(observer) }
+        observers.removeAll()
+    }
+
+    /// The first gathering: every document, so a list made before it refreshes once.
+    private func gathered() {
+        query.disableUpdates()
+        defer { query.enableUpdates() }
+        let urls = (0..<query.resultCount).compactMap { (query.result(at: $0) as? NSMetadataItem)?.value(forAttribute: NSMetadataItemURLKey) as? URL }
+        if !urls.isEmpty { send(urls.map(\.absoluteString)) }
+    }
+
+    private func updated(_ info: [AnyHashable: Any]?) {
+        var urls: [String] = []
+        for key in [NSMetadataQueryUpdateAddedItemsKey, NSMetadataQueryUpdateChangedItemsKey, NSMetadataQueryUpdateRemovedItemsKey] {
+            for item in info?[key] as? [NSMetadataItem] ?? [] {
+                if let url = item.value(forAttribute: NSMetadataItemURLKey) as? URL { urls.append(url.absoluteString) }
+            }
+        }
+        if !urls.isEmpty { send(urls) }
+    }
+}
+#endif

package/swift/Sources/SwiftBrowserNative/Host/ReachabilityBridge.swift

@@ -0,0 +1,47 @@
+#if canImport(Network)
+import Foundation
+import Network
+import SwiftBrowserProtocol
+
+/// `navigator.onLine` (packages/native/src/reachability.ts) over
+/// `NWPathMonitor`: whether the network path is satisfied. The monitor
+/// starts when the app first asks; each change goes to the app as
+/// `__sbOnline(bool)`, which fires its `online` and `offline` events.
+@MainActor
+final class ReachabilityBridge {
+    private let monitor = NWPathMonitor()
+    private let send: (Bool) -> Void
+    private var started = false
+    /// The last status the monitor reported; online until it reports.
+    private(set) var isOnline = true
+
+    /// `send` calls the app's `__sbOnline`.
+    init(send: @escaping (Bool) -> Void) {
+        self.send = send
+    }
+
+    /// Starts the monitor (once); until its first report the app is online.
+    func start() {
+        guard !started else { return }
+        started = true
+        monitor.pathUpdateHandler = { [weak self] path in
+            let online = path.status == .satisfied
+            DispatchQueue.main.async {
+                MainActor.assumeIsolated { self?.update(online) }
+            }
+        }
+        monitor.start(queue: DispatchQueue(label: "swiftbrowser.reachability"))
+    }
+
+    func stop() {
+        guard started else { return }
+        monitor.cancel()
+    }
+
+    private func update(_ online: Bool) {
+        guard online != isOnline else { return }
+        isOnline = online
+        send(online)
+    }
+}
+#endif

package/swift/Sources/SwiftBrowserNative/Host/SpeechBridge.swift

@@ -0,0 +1,106 @@
+#if canImport(SwiftUI) && canImport(AVFoundation) && !canImport(FoundationBridge)
+import AVFoundation
+import Foundation
+import SwiftBrowserProtocol
+
+/// `speechSynthesis` (packages/native/src/speech.ts) on `AVSpeechSynthesizer`:
+/// `speak` queues an utterance (`text`, `lang` as the voice's language, `voice`
+/// by name, `rate` with 1 the default rate, `pitch`, `volume`), `cancel`,
+/// `pause` and `resume` act on the queue. Each utterance's events go to the
+/// app as `__sbSpeechEvent(id, json)`:
+///
+/// ```
+/// { "type": "start" | "end" | "cancel" | "pause" | "resume" | "boundary", "charIndex"?: n, "charLength"?: n }
+/// ```
+@MainActor
+final class SpeechBridge: NSObject, AVSpeechSynthesizerDelegate {
+    private let send: (Int, JSONValue) -> Void
+    private let synthesizer = AVSpeechSynthesizer()
+    /// The utterances under way, by the synthesizer's object.
+    private var ids: [ObjectIdentifier: Int] = [:]
+
+    /// `send` hands an event for utterance `id` to the app.
+    init(send: @escaping (Int, JSONValue) -> Void) {
+        self.send = send
+        super.init()
+        synthesizer.delegate = self
+    }
+
+    func speak(id: Int, options: JSONObject) {
+        let utterance = AVSpeechUtterance(string: options.string("text") ?? "")
+        if let name = options.string("voice"), let voice = AVSpeechSynthesisVoice.speechVoices().first(where: { $0.name == name }) {
+            utterance.voice = voice
+        } else if let lang = options.string("lang"), let voice = AVSpeechSynthesisVoice(language: lang.replacingOccurrences(of: "_", with: "-")) {
+            utterance.voice = voice
+        }
+        // The API's rate is a multiple of the default; the synthesizer's runs from its minimum to its maximum around it.
+        let rate = Float(options["rate"]?.double ?? 1)
+        let base = AVSpeechUtteranceDefaultSpeechRate
+        utterance.rate = rate >= 1
+            ? min(AVSpeechUtteranceMaximumSpeechRate, base + (AVSpeechUtteranceMaximumSpeechRate - base) * min(rate - 1, 9) / 9)
+            : max(AVSpeechUtteranceMinimumSpeechRate, AVSpeechUtteranceMinimumSpeechRate + (base - AVSpeechUtteranceMinimumSpeechRate) * max(rate, 0.1))
+        utterance.pitchMultiplier = Float(min(max(options["pitch"]?.double ?? 1, 0.5), 2))
+        utterance.volume = Float(min(max(options["volume"]?.double ?? 1, 0), 1))
+        ids[ObjectIdentifier(utterance)] = id
+        synthesizer.speak(utterance)
+    }
+
+    func control(_ action: String) {
+        switch action {
+        case "cancel": synthesizer.stopSpeaking(at: .immediate)
+        case "pause": synthesizer.pauseSpeaking(at: .word)
+        case "resume": synthesizer.continueSpeaking()
+        default: break
+        }
+    }
+
+    /// The app is going away.
+    func stop() {
+        synthesizer.stopSpeaking(at: .immediate)
+    }
+
+    private func emit(_ key: ObjectIdentifier, _ type: String, _ range: NSRange? = nil, done: Bool = false) {
+        guard let id = ids[key] else { return }
+        var event: JSONObject = ["type": .string(type)]
+        if let range {
+            event["charIndex"] = .number(Double(range.location))
+            event["charLength"] = .number(Double(range.length))
+        }
+        if done { ids[key] = nil }
+        send(id, .object(event))
+    }
+
+    // MARK: AVSpeechSynthesizerDelegate (hopped to the main actor; the utterance is named by identity)
+
+    private nonisolated func report(_ utterance: AVSpeechUtterance, _ type: String, _ range: NSRange? = nil, done: Bool = false) {
+        let key = ObjectIdentifier(utterance)
+        DispatchQueue.main.async { [weak self] in
+            MainActor.assumeIsolated { self?.emit(key, type, range, done: done) }
+        }
+    }
+
+    nonisolated func speechSynthesizer(_ synthesizer: AVSpeechSynthesizer, didStart utterance: AVSpeechUtterance) {
+        report(utterance, "start")
+    }
+
+    nonisolated func speechSynthesizer(_ synthesizer: AVSpeechSynthesizer, didFinish utterance: AVSpeechUtterance) {
+        report(utterance, "end", done: true)
+    }
+
+    nonisolated func speechSynthesizer(_ synthesizer: AVSpeechSynthesizer, didCancel utterance: AVSpeechUtterance) {
+        report(utterance, "cancel", done: true)
+    }
+
+    nonisolated func speechSynthesizer(_ synthesizer: AVSpeechSynthesizer, didPause utterance: AVSpeechUtterance) {
+        report(utterance, "pause")
+    }
+
+    nonisolated func speechSynthesizer(_ synthesizer: AVSpeechSynthesizer, didContinue utterance: AVSpeechUtterance) {
+        report(utterance, "resume")
+    }
+
+    nonisolated func speechSynthesizer(_ synthesizer: AVSpeechSynthesizer, willSpeakRangeOfSpeechString characterRange: NSRange, utterance: AVSpeechUtterance) {
+        report(utterance, "boundary", characterRange)
+    }
+}
+#endif

package/swift/Sources/SwiftBrowserNative/Host/SpeechRecognitionBridge.swift

@@ -0,0 +1,198 @@
+#if canImport(SwiftUI) && canImport(Speech) && !canImport(FoundationBridge)
+import AVFoundation
+import Foundation
+import Speech
+import SwiftBrowserProtocol
+
+/// `SpeechRecognition` (packages/native/src/speech.ts) on `SFSpeechRecognizer`
+/// over the microphone (`AVAudioEngine`): `start` asks for speech recognition
+/// and the microphone the first time (`NSSpeechRecognitionUsageDescription`,
+/// `NSMicrophoneUsageDescription` in the app's Info.plist) and listens, with
+/// partial results when `interimResults` or `continuous`; `stop` ends the
+/// audio and lets the recognizer finish; `abort` ends it all. One session at
+/// a time: a second `start` ends with `error: aborted`. The events go to the
+/// app as `__sbRecognition(id, json)`:
+///
+/// ```
+/// { "type": "start" }
+/// { "type": "result", "transcript": string, "isFinal": bool, "confidence": n }
+/// { "type": "error", "error": "not-allowed" | "audio-capture" | "network" | "no-speech" | "aborted", "message": string }
+/// { "type": "end" }
+/// ```
+@MainActor
+final class SpeechRecognitionBridge {
+    private let send: (Int, JSONValue) -> Void
+    private var engine: AVAudioEngine?
+    private var request: SFSpeechAudioBufferRecognitionRequest?
+    private var task: SFSpeechRecognitionTask?
+    private var recognizer: SFSpeechRecognizer?
+    /// The session under way: its id and whether it goes on after a final result.
+    private var current: (id: Int, continuous: Bool)?
+
+    /// `send` hands an event for recognition `id` to the app.
+    init(send: @escaping (Int, JSONValue) -> Void) {
+        self.send = send
+    }
+
+    func handle(id: Int, action: String, options: JSONObject) {
+        switch action {
+        case "start": start(id: id, options: options)
+        case "stop": if current?.id == id { request?.endAudio(); stopAudio() }
+        case "abort": if current?.id == id { finish(error: nil) }
+        default: break
+        }
+    }
+
+    /// The app is going away.
+    func stop() {
+        if current != nil { finish(error: nil) }
+    }
+
+    private func start(id: Int, options: JSONObject) {
+        if current != nil {
+            send(id, ["type": .string("error"), "error": .string("aborted"), "message": .string("another recognition is listening")])
+            send(id, ["type": .string("end")])
+            return
+        }
+        current = (id, options["continuous"]?.bool ?? false)
+        // Asking for speech or the microphone without the usage string in the
+        // app's Info.plist ends the app (iOS's privacy check): an error instead.
+        if let key = Self.missingUsageDescription() {
+            finish(error: ("not-allowed", "the app's Info.plist has no \(key)"))
+            return
+        }
+        let partial = (options["interimResults"]?.bool ?? false) || (options["continuous"]?.bool ?? false)
+        let locale = options.string("lang").map { Locale(identifier: $0.replacingOccurrences(of: "_", with: "-")) }
+        Task { @MainActor [weak self] in
+            guard let self else { return }
+            let authorized = await Self.authorize()
+            guard self.current?.id == id else { return }
+            guard authorized else {
+                self.finish(error: ("not-allowed", "speech recognition was not allowed"))
+                return
+            }
+            let found = locale.flatMap { SFSpeechRecognizer(locale: $0) } ?? SFSpeechRecognizer()
+            guard let recognizer = found, recognizer.isAvailable else {
+                self.finish(error: ("network", "the speech recognizer is not available"))
+                return
+            }
+            self.recognizer = recognizer
+            do {
+                try self.listen(recognizer, partial: partial, id: id)
+                self.send(id, ["type": .string("start")])
+            } catch {
+                self.finish(error: ("audio-capture", "the microphone could not be started: \(error.localizedDescription)"))
+            }
+        }
+    }
+
+    /// The usage description the app's Info.plist lacks, if any: iOS ends an
+    /// app that asks for speech recognition or the microphone without one.
+    private static func missingUsageDescription() -> String? {
+        var keys = ["NSSpeechRecognitionUsageDescription"]
+        #if os(iOS)
+        keys.append("NSMicrophoneUsageDescription")
+        #endif
+        return keys.first { Bundle.main.object(forInfoDictionaryKey: $0) == nil }
+    }
+
+    private nonisolated static func authorize() async -> Bool {
+        let speech = await withCheckedContinuation { (continuation: CheckedContinuation<SFSpeechRecognizerAuthorizationStatus, Never>) in
+            SFSpeechRecognizer.requestAuthorization { continuation.resume(returning: $0) }
+        }
+        guard speech == .authorized else { return false }
+        #if os(iOS)
+        return await AVAudioApplication.requestRecordPermission()
+        #else
+        return true
+        #endif
+    }
+
+    private func listen(_ recognizer: SFSpeechRecognizer, partial: Bool, id: Int) throws {
+        #if os(iOS)
+        let session = AVAudioSession.sharedInstance()
+        try session.setCategory(.record, mode: .measurement, options: .duckOthers)
+        try session.setActive(true, options: .notifyOthersOnDeactivation)
+        #endif
+        let engine = AVAudioEngine()
+        let request = SFSpeechAudioBufferRecognitionRequest()
+        request.shouldReportPartialResults = partial
+        let input = engine.inputNode
+        let format = input.outputFormat(forBus: 0)
+        nonisolated(unsafe) let sink = request
+        input.installTap(onBus: 0, bufferSize: 1024, format: format) { buffer, _ in sink.append(buffer) }
+        engine.prepare()
+        try engine.start()
+        self.engine = engine
+        self.request = request
+        task = recognizer.recognitionTask(with: request, resultHandler: handler(id: id, partial: partial))
+    }
+
+    /// What the recognizer reports, hopped to the main actor: a result to the
+    /// app (a final one ends a one-shot session or starts a continuous one's
+    /// next request), a failure as the end.
+    private func handler(id: Int, partial: Bool) -> @Sendable (SFSpeechRecognitionResult?, (any Error)?) -> Void {
+        { result, error in
+            let heard = result.map { ($0.bestTranscription.formattedString, $0.isFinal, Double($0.bestTranscription.segments.last?.confidence ?? 0)) }
+            let failure = error?.localizedDescription
+            let code = (error as NSError?).map { ($0.domain, $0.code) }
+            DispatchQueue.main.async { [weak self] in
+                MainActor.assumeIsolated {
+                    guard let self, let current = self.current, current.id == id else { return }
+                    if let heard {
+                        self.send(id, ["type": .string("result"), "transcript": .string(heard.0), "isFinal": .bool(heard.1), "confidence": .number(heard.2)])
+                        if heard.1, !current.continuous { self.finish(error: nil) }
+                        else if heard.1 { self.restart(partial: partial, id: id) }
+                    }
+                    if let failure {
+                        // The recognizer ending after `stop` (no more audio) is the end, not an error; a session without a word is `no-speech`.
+                        let assistant = code?.0 == "kAFAssistantErrorDomain"
+                        let silent = assistant && code?.1 == 1110
+                        let ended = assistant && code?.1 == 216
+                        self.finish(error: ended ? nil : (silent ? "no-speech" : "network", failure))
+                    }
+                }
+            }
+        }
+    }
+
+    /// A continuous session goes on after a final result with a fresh request on the same engine.
+    private func restart(partial: Bool, id: Int) {
+        guard let engine, let recognizer else { return }
+        task?.cancel()
+        let request = SFSpeechAudioBufferRecognitionRequest()
+        request.shouldReportPartialResults = partial
+        let input = engine.inputNode
+        input.removeTap(onBus: 0)
+        nonisolated(unsafe) let sink = request
+        input.installTap(onBus: 0, bufferSize: 1024, format: input.outputFormat(forBus: 0)) { buffer, _ in sink.append(buffer) }
+        self.request = request
+        task = recognizer.recognitionTask(with: request, resultHandler: handler(id: id, partial: partial))
+    }
+
+    private func stopAudio() {
+        engine?.inputNode.removeTap(onBus: 0)
+        engine?.stop()
+        engine = nil
+        #if os(iOS)
+        try? AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
+        #endif
+    }
+
+    /// Ends the session: the audio, the task, and `error` (if any) then `end` to the app.
+    private func finish(error: (String, String)?) {
+        guard let current else { return }
+        let id = current.id
+        self.current = nil
+        stopAudio()
+        task?.cancel()
+        task = nil
+        request = nil
+        recognizer = nil
+        if let error {
+            send(id, ["type": .string("error"), "error": .string(error.0), "message": .string(error.1)])
+        }
+        send(id, ["type": .string("end")])
+    }
+}
+#endif

package/swift/Sources/SwiftBrowserNative/Host/WorkerHost.swift

@@ -79,6 +79,8 @@ final class WorkerHost: @unchecked Sendable {
         context.evaluateScript(script, withSourceURL: URL(string: "sb://\(name).worker.js"))
     }
 
+    /// On the thread, in a turn's pool: the context, and with it the virtual
+    /// machine, go at the turn's end, while the thread and its run loop live.
     private func tearDown() {
         for timer in timers.values { timer.invalidate() }
         timers.removeAll()
@@ -234,7 +236,8 @@ protocol WorkerEngine: AnyObject {
 extension WorkerHost: WorkerEngine {}
 
 /// A thread with a run loop that runs blocks sent to it, in order, after
-/// the block it started with.
+/// the block it started with. Each block, and each turn of the loop, runs in
+/// an autorelease pool of its own.
 final class WorkerThread: @unchecked Sendable {
     private let label: String
     private let lock = NSLock()
@@ -251,15 +254,21 @@ final class WorkerThread: @unchecked Sendable {
             let loop = RunLoop.current
             // A port keeps the loop running while nothing else is scheduled.
             loop.add(Port(), forMode: .default)
-            setUp()
+            // Every turn runs in an autorelease pool of its own, so what a turn
+            // autoreleases (each `JSValue` JavaScriptCore hands Swift) is gone
+            // at its end, on this thread, while the loop still runs: the
+            // worker's context dies when `tearDown` drops it, not at the
+            // thread's exit, where the engine's own per-thread state is going
+            // too (an exit-time release of the context has crashed the engine).
+            autoreleasepool { setUp() }
             lock.lock()
             runLoop = CFRunLoopGetCurrent()
             let queued = pending
             pending = []
             lock.unlock()
-            for block in queued { block() }
+            for block in queued { autoreleasepool(invoking: block) }
             while !isStopped {
-                loop.run(mode: .default, before: .distantFuture)
+                autoreleasepool { loop.run(mode: .default, before: .distantFuture) }
             }
         }
         thread.name = label
@@ -276,7 +285,7 @@ final class WorkerThread: @unchecked Sendable {
             return
         }
         lock.unlock()
-        CFRunLoopPerformBlock(runLoop, CFRunLoopMode.defaultMode.rawValue, block)
+        CFRunLoopPerformBlock(runLoop, CFRunLoopMode.defaultMode.rawValue) { autoreleasepool(invoking: block) }
         CFRunLoopWakeUp(runLoop)
     }
 

package/swift/Sources/SwiftBrowserNative/Runtime/NativeFunctions.swift

@@ -0,0 +1,134 @@
+#if canImport(SwiftUI)
+import Foundation
+import SwiftBrowserProtocol
+
+/// What a registered function is called with: the params JavaScript passed,
+/// as JSON. `call["region"]` reads a member; `call.decode()` the whole object
+/// as a `Decodable`.
+public struct NativeFunctionCall: Sendable {
+    /// The name the function was registered under.
+    public let name: String
+    /// The params as JavaScript passed them (an object; `[:]` when none).
+    public let params: JSONValue
+
+    public subscript(key: String) -> JSONValue { params[key] }
+
+    /// The params decoded as a type of the app's.
+    public func decode<T: Decodable>(_ type: T.Type = T.self) throws -> T {
+        let data = try JSONEncoder().encode(params)
+        return try JSONDecoder().decode(type, from: data)
+    }
+}
+
+/// A function throws this to say the viewer cancelled (closed a sheet, said
+/// no): the app's promise rejects with an `AbortError`, as the system
+/// pickers' cancellations do.
+public struct NativeFunctionCancelled: Error, CustomStringConvertible {
+    public let description: String
+    public init(_ reason: String = "the viewer cancelled") { description = "cancelled: \(reason)" }
+}
+
+/// A failure with a message for the app: the promise rejects with it.
+public struct NativeFunctionError: Error, CustomStringConvertible {
+    public let description: String
+    public init(_ description: String) { self.description = description }
+}
+
+/// Swift the app's JavaScript can call: the function half of the escape hatch
+/// (docs/native.md; `NativeRegistry` is the view half). The Swift app
+/// registers functions once, before the app loads, and `@swiftbrowser/native`
+/// calls them: `callNative(name, params)` resolves with what an async function
+/// returns, through the host request `app:<name>` (HostRequestBridge.swift);
+/// `callNativeSync(name, params)` runs a sync one inline; `nativeFunctions()`
+/// lists them. The other way, `send(name, value)` reaches
+/// `onNativeEvent(name, listener)` in JavaScript, for what Swift reports
+/// unasked: a StoreKit transaction, a motion update, a Bluetooth peripheral.
+///
+/// ```swift
+/// NativeFunctions.register("purchase") { call in
+///     let product = try await Product.products(for: [call["id"].string ?? ""]).first
+///     ...
+///     return ["state": "purchased"]
+/// }
+/// NativeFunctions.registerSync("deviceName") { _ in .string(UIDevice.current.name) }
+/// ```
+///
+/// ```ts
+/// const { state } = await callNative<{ state: string }>('purchase', { id: 'pro' });
+/// const name = callNativeSync<string>('deviceName');
+/// const stop = onNativeEvent('transaction', (value) => { ... });
+/// ```
+///
+/// Everything runs on the main actor, as the rest of the bridge does; a
+/// function doing heavy work hops off it itself. Values cross as JSON. An
+/// error a function throws rejects the promise with its description; a
+/// `NativeFunctionCancelled` as an `AbortError`.
+@MainActor
+public enum NativeFunctions {
+    public typealias Handler = (NativeFunctionCall) async throws -> JSONValue
+    public typealias SyncHandler = (NativeFunctionCall) throws -> JSONValue
+
+    private static var handlers: [String: Handler] = [:]
+    private static var syncHandlers: [String: SyncHandler] = [:]
+    /// Where `send` delivers: the running app's bridge (HostBridge.swift sets
+    /// it as it installs, clears it as it goes away). Nothing listening, the
+    /// value is dropped.
+    static var sink: ((String, JSONValue) -> Void)?
+
+    /// Registers an async function under `name`, replacing one registered before.
+    public static func register(_ name: String, _ handler: @escaping Handler) {
+        syncHandlers[name] = nil
+        handlers[name] = handler
+    }
+
+    /// Registers a function JavaScript calls inline with `callNativeSync`,
+    /// replacing one registered before; `callNative` reaches it too.
+    public static func registerSync(_ name: String, _ handler: @escaping SyncHandler) {
+        handlers[name] = nil
+        syncHandlers[name] = handler
+    }
+
+    public static func unregister(_ name: String) {
+        handlers[name] = nil
+        syncHandlers[name] = nil
+    }
+
+    public static func isRegistered(_ name: String) -> Bool {
+        handlers[name] != nil || syncHandlers[name] != nil
+    }
+
+    /// Every registered name, sorted: what `nativeFunctions()` answers.
+    public static var names: [String] {
+        Array(Set(handlers.keys).union(syncHandlers.keys)).sorted()
+    }
+
+    /// Hands `value` to the app's `onNativeEvent(name)` listeners.
+    public static func send(_ name: String, _ value: JSONValue) {
+        sink?(name, value)
+    }
+
+    /// The host request `app:<name>`: the async function, or the sync one.
+    static func call(_ name: String, _ params: JSONObject) async throws -> JSONValue {
+        let call = NativeFunctionCall(name: name, params: .object(params))
+        if let handler = handlers[name] { return try await handler(call) }
+        if let handler = syncHandlers[name] { return try handler(call) }
+        throw NativeFunctionError("unsupported: no native function named \(name)")
+    }
+
+    /// `callNativeSync(name, json)`: `{ value }` or `{ error }`, as a host
+    /// request answers, for a sync function; an async one is an error here.
+    static func callSync(_ name: String, _ json: String) -> JSONValue {
+        let params = (try? JSONValue.parse(json))?.object ?? [:]
+        guard let handler = syncHandlers[name] else {
+            let reason = handlers[name] == nil ? "no native function named \(name)" : "\(name) is async: call it with callNative"
+            return .object(["error": .string("unsupported: \(reason)")])
+        }
+        do {
+            let value = try handler(NativeFunctionCall(name: name, params: .object(params)))
+            return .object(["value": value])
+        } catch {
+            return .object(["error": .string("\(error)")])
+        }
+    }
+}
+#endif

package/swift/Sources/SwiftBrowserNative/Views/ElementView.swift

@@ -53,6 +53,7 @@ struct ElementView: View {
         case "stepper": return AnyView(StepperElement(node: node))
         case "tapgesture": return AnyView(TapGestureElement(node: node))
         case "gesture": return AnyView(GestureElement(node: node))
+        case "touches": return AnyView(TouchesElement(node: node))
         case "gauge": return AnyView(GaugeElement(node: node))
         case "datepicker": return AnyView(DatePickerElement(node: node))
         case "menu": return AnyView(MenuElement(node: node))

package/swift/Sources/SwiftBrowserNative/Views/Kinds/Controls.swift

@@ -127,6 +127,8 @@ struct TextFieldElement: View {
             })
         }
         if let label = props.submitLabel { styled = AnyView(styled.submitLabel(SubmitLabel(name: label))) }
+        // The keyboard, what autofill offers, capitalization and correction (TextInputHints.swift).
+        styled = AnyView(styled.textInputHints(props))
         // Backspace at the start of the text (DeleteBackward.swift).
         if props.deleteBackward { styled = AnyView(styled.onDeleteBackward(true) { app?.dispatch(.deleteBackward(node.id)) }) }
         if props.focused != nil {