@swiftbrowser/native 0.18.1 → 0.18.3

package/swift/Sources/SwiftBrowserNative/Host/FilesBridge.swift

@@ -1,16 +1,22 @@
 #if canImport(SwiftUI)
 import Foundation
+#if canImport(UniformTypeIdentifiers)
+import UniformTypeIdentifiers
+#endif
 
 #if !canImport(FoundationBridge)
 
 /// The app's files for the page's `fileManager` (@swiftbrowser/react): the
 /// `files` host requests (packages/native/src/hostRequests.ts), answered with
 /// Foundation's `FileManager` in the app's sandbox. A URL must be in one of
-/// the app's directories (`Documents`, `Library`, `tmp`); bytes cross the
+/// the app's directories (`Documents`, `Library`, `tmp`, and the iCloud Drive
+/// container once `iCloud` resolved it: ICloudBridge.swift); bytes cross the
 /// bridge as base64; the standard directories go to the page through the
-/// bridge's `appDirectories()`. Failures are `kind: detail`, as the page's own
-/// host fails: `unsupported`, `notFound`, `exists`, `isDirectory`,
-/// `notDirectory`.
+/// bridge's `appDirectories()`. A file in the container is read and written
+/// through `NSFileCoordinator` (iCloud's daemon is a second writer) and
+/// downloaded first when another device wrote it (`read`, `download`).
+/// Failures are `kind: detail`, as the page's own host fails: `unsupported`,
+/// `notFound`, `exists`, `isDirectory`, `notDirectory`, `unavailable`.
 struct FilesBridge: Sendable {
     /// Not stored: a struct without stored properties is `Sendable`, and `handle` runs off the main actor.
     private var manager: FileManager { .default }
@@ -39,9 +45,45 @@ struct FilesBridge: Sendable {
             if let url = manager.urls(for: directory, in: .userDomainMask).first { roots.append(url.standardizedFileURL) }
         }
         roots.append(manager.temporaryDirectory.standardizedFileURL)
+        if let container = ICloudContainer.shared.cached { roots.append(container) }
         return roots
     }
 
+    /// Runs `body` on `url` under file coordination when the URL is in the iCloud container, else as it is.
+    private func coordinated<T>(_ url: URL, writing: NSFileCoordinator.WritingOptions?, _ body: (URL) throws -> T) throws -> T {
+        guard ICloudContainer.shared.contains(url) else { return try body(url) }
+        let coordinator = NSFileCoordinator()
+        var coordinationError: NSError?
+        var result: Result<T, any Error>?
+        withoutActuallyEscaping(body) { body in
+            let accessor: (URL) -> Void = { coordinatedURL in result = Result { try body(coordinatedURL) } }
+            if let writing {
+                coordinator.coordinate(writingItemAt: url, options: writing, error: &coordinationError, byAccessor: accessor)
+            } else {
+                coordinator.coordinate(readingItemAt: url, options: [], error: &coordinationError, byAccessor: accessor)
+            }
+        }
+        if let coordinationError { throw coordinationError }
+        guard let result else { throw HostRequestFailure("unavailable: \(url.absoluteString) could not be coordinated") }
+        return try result.get()
+    }
+
+    /// A file another device wrote is a placeholder until downloaded: starts the download and waits for it (a minute at most).
+    private func ensureDownloaded(_ url: URL) async throws {
+        guard ICloudContainer.shared.contains(url) else { return }
+        let keys: Set<URLResourceKey> = [.isUbiquitousItemKey, .ubiquitousItemDownloadingStatusKey]
+        guard let values = try? url.resourceValues(forKeys: keys), values.isUbiquitousItem == true else { return }
+        if values.ubiquitousItemDownloadingStatus == .current || values.ubiquitousItemDownloadingStatus == .downloaded { return }
+        try manager.startDownloadingUbiquitousItem(at: url)
+        let deadline = Date().addingTimeInterval(60)
+        while Date() < deadline {
+            try await Task.sleep(nanoseconds: 200_000_000)
+            let status = (try? url.resourceValues(forKeys: [.ubiquitousItemDownloadingStatusKey]))?.ubiquitousItemDownloadingStatus
+            if status == .current || status == .downloaded { return }
+        }
+        throw HostRequestFailure("unavailable: \(url.absoluteString) did not download from iCloud Drive")
+    }
+
     /// The file URL `params[key]` names, under today's container, inside the app's directories.
     private func url(_ params: JSONObject, _ key: String) throws -> URL {
         guard let string = params[key]?.string, let parsed = URL(string: string) else {
@@ -58,8 +100,11 @@ struct FilesBridge: Sendable {
 
     private func isDirectory(_ url: URL) -> Bool? {
         var directory: ObjCBool = false
-        guard manager.fileExists(atPath: url.path, isDirectory: &directory) else { return nil }
-        return directory.boolValue
+        if manager.fileExists(atPath: url.path, isDirectory: &directory) { return directory.boolValue }
+        // A file another device wrote and this one has not downloaded is a `.name.icloud` placeholder beside the path.
+        guard ICloudContainer.shared.contains(url) else { return nil }
+        let placeholder = url.deletingLastPathComponent().appendingPathComponent(".\(url.lastPathComponent).icloud")
+        return manager.fileExists(atPath: placeholder.path) ? false : nil
     }
 
     private func requireDirectory(_ directory: URL, for url: URL) throws {
@@ -72,6 +117,16 @@ struct FilesBridge: Sendable {
 
     func handle(_ params: JSONObject) async throws -> JSONValue {
         switch params["action"]?.string {
+        case "iCloud":
+            // The container's Documents, resolved off the main thread the first time; null without iCloud Drive.
+            guard let documents = await ICloudContainer.shared.resolve() else { return .null }
+            return .object(["url": .string(documents.absoluteString)])
+        case "download":
+            // `loadURL`: the file is on the device once this answers (a placeholder is downloaded first).
+            let url = try url(params, "url")
+            guard isDirectory(url) != nil else { throw HostRequestFailure("notFound: no file at \(url.absoluteString)") }
+            try await ensureDownloaded(url)
+            return .object(["url": .string(url.absoluteString)])
         case "read":
             let url = try url(params, "url")
             switch isDirectory(url) {
@@ -79,7 +134,8 @@ struct FilesBridge: Sendable {
             case true?: throw HostRequestFailure("isDirectory: \(url.absoluteString) is a directory")
             case false?: break
             }
-            let data = try Data(contentsOf: url)
+            try await ensureDownloaded(url)
+            let data = try coordinated(url, writing: nil) { try Data(contentsOf: $0) }
             return .object(["data": .string(data.base64EncodedString())])
         case "write":
             let url = try url(params, "url")
@@ -88,7 +144,7 @@ struct FilesBridge: Sendable {
             }
             if isDirectory(url) == true { throw HostRequestFailure("isDirectory: \(url.absoluteString) is a directory") }
             try requireDirectory(url.deletingLastPathComponent(), for: url)
-            try data.write(to: url, options: .atomic)
+            try coordinated(url, writing: .forReplacing) { try data.write(to: $0, options: .atomic) }
             return .object([:])
         case "remove":
             let url = try url(params, "url")
@@ -96,7 +152,7 @@ struct FilesBridge: Sendable {
             guard !roots.contains(where: { $0.path == url.path }) else {
                 throw HostRequestFailure("unsupported: \(url.absoluteString) is one of the app's directories")
             }
-            try manager.removeItem(at: url)
+            try coordinated(url, writing: .forDeleting) { try manager.removeItem(at: $0) }
             return .object([:])
         case "createDirectory":
             let url = try url(params, "url")
@@ -106,7 +162,11 @@ struct FilesBridge: Sendable {
         case "list":
             let url = try url(params, "url")
             try requireDirectory(url, for: url)
-            let names = try manager.contentsOfDirectory(atPath: url.path).sorted { $0.localizedStandardCompare($1) == .orderedAscending }
+            // A placeholder `.name.icloud` lists as `name`, the file it stands for.
+            let listed = try manager.contentsOfDirectory(atPath: url.path)
+            let names = Set(listed.map { name -> String in
+                name.hasPrefix(".") && name.hasSuffix(".icloud") ? String(name.dropFirst().dropLast(7)) : name
+            }).sorted { $0.localizedStandardCompare($1) == .orderedAscending }
             return .object(["urls": .array(names.map { .string(url.appendingPathComponent($0).absoluteString) })])
         case "attributes":
             let url = try url(params, "url")
@@ -114,7 +174,13 @@ struct FilesBridge: Sendable {
             let attributes = try manager.attributesOfItem(atPath: url.path)
             let size = directory ? 0 : ((attributes[.size] as? NSNumber)?.doubleValue ?? 0)
             let modified = (attributes[.modificationDate] as? Date).map { JSONValue.number(($0.timeIntervalSince1970 * 1000).rounded()) } ?? .null
-            return .object(["size": .number(size), "modified": modified, "directory": .bool(directory)])
+            let created = (attributes[.creationDate] as? Date).map { JSONValue.number(($0.timeIntervalSince1970 * 1000).rounded()) } ?? .null
+            #if canImport(UniformTypeIdentifiers)
+            let type = directory ? "" : (UTType(filenameExtension: url.pathExtension)?.preferredMIMEType ?? "")
+            #else
+            let type = ""
+            #endif
+            return .object(["size": .number(size), "modified": modified, "created": created, "directory": .bool(directory), "type": .string(type)])
         case "move", "copy":
             let from = try url(params, "from")
             let to = try url(params, "to")
@@ -122,7 +188,12 @@ struct FilesBridge: Sendable {
             guard isDirectory(to) == nil else { throw HostRequestFailure("exists: something is at \(to.absoluteString) already") }
             try requireDirectory(to.deletingLastPathComponent(), for: to)
             if to.path.hasPrefix(from.path + "/") { throw HostRequestFailure("unsupported: \(to.absoluteString) is inside \(from.absoluteString)") }
-            if params["action"]?.string == "move" { try manager.moveItem(at: from, to: to) } else { try manager.copyItem(at: from, to: to) }
+            try await ensureDownloaded(from)
+            if params["action"]?.string == "move" {
+                try coordinated(to, writing: .forReplacing) { target in try coordinated(from, writing: .forMoving) { try manager.moveItem(at: $0, to: target) } }
+            } else {
+                try coordinated(to, writing: .forReplacing) { target in try coordinated(from, writing: nil) { try manager.copyItem(at: $0, to: target) } }
+            }
             return .object([:])
         default:
             throw HostRequestFailure("unsupported: files: unknown action \(params["action"]?.string ?? "")")

package/swift/Sources/SwiftBrowserNative/Host/GeolocationBridge.swift

@@ -0,0 +1,150 @@
+#if canImport(SwiftUI) && canImport(CoreLocation) && !canImport(FoundationBridge)
+import CoreLocation
+import Foundation
+import SwiftBrowserProtocol
+
+/// `navigator.geolocation` (packages/native/src/geolocation.ts) on
+/// `CLLocationManager`. `current` asks for one fix (`requestLocation`),
+/// `watch` for every fix (`startUpdatingLocation`) until `clear`; the first
+/// ask prompts the viewer for when-in-use authorization (the app's
+/// Info.plist names `NSLocationWhenInUseUsageDescription`), and the asks
+/// wait for the answer. Each fix goes to the app as `__sbGeolocation(id,
+/// json)`:
+///
+/// ```
+/// { "position": { "latitude", "longitude", "accuracy", "altitude", "altitudeAccuracy", "heading", "speed", "timestamp" } }
+/// { "error": { "code": 1 | 2, "message": string } }
+/// ```
+///
+/// A denial (code 1) ends a request; a failure to fix (code 2) ends a
+/// `current` ask and lets a `watch` go on. `enableHighAccuracy` asks for the
+/// best accuracy, else a hundred meters; `timeout` is the runtime's.
+@MainActor
+final class GeolocationBridge: NSObject, CLLocationManagerDelegate {
+    private let send: (Int, JSONValue) -> Void
+    private let manager = CLLocationManager()
+    /// The requests under way, by id: whether each is a watch.
+    private var requests: [Int: Bool] = [:]
+    private var updating = false
+
+    /// `send` hands a fix or a failure for request `id` to the app.
+    init(send: @escaping (Int, JSONValue) -> Void) {
+        self.send = send
+        super.init()
+        manager.delegate = self
+    }
+
+    func request(id: Int, action: String, options: JSONObject) {
+        switch action {
+        case "current", "watch":
+            requests[id] = action == "watch"
+            if options["enableHighAccuracy"]?.bool == true { manager.desiredAccuracy = kCLLocationAccuracyBest }
+            else if requests.count == 1 { manager.desiredAccuracy = kCLLocationAccuracyHundredMeters }
+            begin()
+        case "clear":
+            requests[id] = nil
+            settle()
+        default:
+            send(id, ["error": ["code": .number(2), "message": .string("geolocation: unknown action \(action)")]])
+        }
+    }
+
+    /// The app is going away.
+    func stop() {
+        requests.removeAll()
+        settle()
+    }
+
+    /// Asks for authorization first, else starts the fixes the requests want.
+    private func begin() {
+        switch manager.authorizationStatus {
+        case .notDetermined:
+            manager.requestWhenInUseAuthorization()
+        case .denied, .restricted:
+            fail(code: 1, message: "geolocation: location access was not allowed", endingWatches: true)
+        default:
+            fix()
+        }
+    }
+
+    private func fix() {
+        guard !requests.isEmpty else { return }
+        if requests.values.contains(true) {
+            if !updating {
+                updating = true
+                manager.startUpdatingLocation()
+            }
+        } else {
+            manager.requestLocation()
+        }
+    }
+
+    /// Stops updating when no watch is left.
+    private func settle() {
+        if updating, !requests.values.contains(true) {
+            updating = false
+            manager.stopUpdatingLocation()
+        }
+    }
+
+    private func fail(code: Int, message: String, endingWatches: Bool) {
+        for (id, watch) in requests {
+            send(id, ["error": ["code": .number(Double(code)), "message": .string(message)]])
+            if !watch || endingWatches { requests[id] = nil }
+        }
+        settle()
+    }
+
+    private func deliver(_ position: JSONValue) {
+        for (id, watch) in requests {
+            send(id, ["position": position])
+            if !watch { requests[id] = nil }
+        }
+        settle()
+    }
+
+    // MARK: CLLocationManagerDelegate (on the main thread, where the manager was made)
+
+    nonisolated func locationManagerDidChangeAuthorization(_ manager: CLLocationManager) {
+        let status = manager.authorizationStatus
+        MainActor.assumeIsolated {
+            switch status {
+            case .notDetermined: break
+            case .denied, .restricted: fail(code: 1, message: "geolocation: location access was not allowed", endingWatches: true)
+            default: fix()
+            }
+        }
+    }
+
+    nonisolated func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
+        guard let last = locations.last else { return }
+        let position = Self.json(last)
+        MainActor.assumeIsolated { deliver(position) }
+    }
+
+    nonisolated func locationManager(_ manager: CLLocationManager, didFailWithError error: Error) {
+        let denied = (error as? CLError)?.code == .denied
+        let message = "geolocation: \(error.localizedDescription)"
+        MainActor.assumeIsolated {
+            if denied { fail(code: 1, message: message, endingWatches: true) }
+            else { fail(code: 2, message: message, endingWatches: false) }
+        }
+    }
+
+    private nonisolated static func json(_ location: CLLocation) -> JSONValue {
+        var fields: JSONObject = [
+            "latitude": .number(location.coordinate.latitude),
+            "longitude": .number(location.coordinate.longitude),
+            "accuracy": .number(location.horizontalAccuracy),
+            "timestamp": .number(location.timestamp.timeIntervalSince1970 * 1000),
+        ]
+        if location.verticalAccuracy > 0 {
+            fields["altitude"] = .number(location.altitude)
+            fields["altitudeAccuracy"] = .number(location.verticalAccuracy)
+        }
+        if location.course >= 0 { fields["heading"] = .number(location.course) }
+        if location.speed >= 0 { fields["speed"] = .number(location.speed) }
+        return .object(fields)
+    }
+}
+#endif

package/swift/Sources/SwiftBrowserNative/Host/HostBridge.swift

@@ -14,6 +14,9 @@ import FoundationBridge // the shim's Foundation stand-ins (ShimAliases.swift)
 #if canImport(CryptoKit)
 import CryptoKit
 #endif
+#if os(macOS)
+import IOKit.pwr_mgt
+#endif
 
 /// The native primitives `@swiftbrowser/native` builds the web globals from
 /// (packages/native/src/runtime.ts), installed on `__sbNative`:
@@ -38,7 +41,13 @@ import CryptoKit
 /// | `wsOpen(id, url, protocols)`, `wsSend(id, json)`, `wsClose(id, code, reason)` | `WebSocket` on `URLSessionWebSocketTask` (WebSocketBridge.swift); what a socket receives comes to `__sbWebSocketEvent(id, json)` |
 /// | `digest(algorithm, base64)`, `hmac(algorithm, key, base64)` | `crypto.subtle` on CryptoKit, synchronously: the base64 digest or HMAC, or nothing when the algorithm is not one of SHA-1, SHA-256, SHA-384 and SHA-512 |
 /// | `haptic(kind)` | `navigator.vibrate`: a feedback generator's `impact`, `selection`, `success`, `warning` or `error` |
-/// | `hostRequest(id, kind, json)` | the web renderer's `share`, `pickFiles`, `clipboard`, `pickColor` and `webAuth` requests, answered with the system's share sheet, pickers, pasteboard and sign-in session (HostRequestBridge.swift); the answer comes to `__sbHostResponse(id, result)` |
+/// | `geolocation(id, action, json)` | `navigator.geolocation` on `CLLocationManager` (GeolocationBridge.swift): `current` for one fix, `watch` for every fix until `clear`; each fix or the failure comes to `__sbGeolocation(id, json)`. Apple platforms only |
+/// | `speak(id, json)`, `speechControl(action)` | `speechSynthesis` on `AVSpeechSynthesizer` (SpeechBridge.swift): an utterance's `text`, `lang`, `voice`, `rate`, `pitch` and `volume`; `cancel`, `pause` and `resume`; the events come to `__sbSpeechEvent(id, json)`. Apple platforms only |
+/// | `recognize(id, action, json)` | `SpeechRecognition` on `SFSpeechRecognizer` over the microphone (SpeechRecognitionBridge.swift): `start` with `{ lang, continuous, interimResults }`, `stop`, `abort`; the results come to `__sbRecognition(id, json)`. Apple platforms only |
+/// | `wakeLock(active)` | `navigator.wakeLock`: the screen stays awake while a sentinel is held (`UIApplication.isIdleTimerDisabled`; an `IOPMAssertion` on macOS) |
+/// | `online()` | `navigator.onLine`: whether the network path is satisfied, from `NWPathMonitor` (ReachabilityBridge.swift), which starts on the first ask; a change comes to `__sbOnline(bool)` for the `online` and `offline` events |
+/// | `hostRequest(id, kind, json)` | the web renderer's `share`, `pickFiles`, `exportFiles`, `clipboard`, `pickColor`, `webAuth`, `appleSignIn` and `files` requests, answered with the system's share sheet, pickers (the document picker exports), pasteboard, sign-in session, Sign in with Apple sheet (AppleSignInBridge.swift) and the sandbox (HostRequestBridge.swift, FilesBridge.swift), and `app:<name>`, a function the Swift app registered (NativeFunctions.swift); the answer comes to `__sbHostResponse(id, result)`, and the URLs iCloud Drive changed to `__sbFilesChanged(json)` |
+/// | `nativeFunctions()`, `callNativeSync(name, json)` | the escape hatch's functions (Runtime/NativeFunctions.swift): the names the Swift app registered, and a sync one run inline, answering `{ value }` or `{ error }` as JSON; what the app sends with `NativeFunctions.send` comes to `__sbNativeEvent(name, json)` |
 /// | `secureGet(key)`, `secureSet(key, value)`, `secureRemove(key)` | `secureStorage` over the Keychain (SecureStorage.swift) |
 /// | `undoState(json)` | the app's undo manager's `canUndo`, `canRedo`, `undoActionName` and `redoActionName`, mirrored on the window's `UndoManager` (UndoBridge.swift) so the shake, the three-finger swipe, ⌘Z and the Edit menu reach the app; what the system asks comes to `__sbUndoCommand("undo" \| "redo")` |
 /// | `workerStart(id, name, engine)`, `workerPost(id, text)`, `workerTerminate(id)` | workers (JavaScriptCore only): a `JSContext` on a thread (`"context"`, WorkerHost.swift) or a hidden web view with WebKit's JIT (`"webview"`, WebViewWorkerHost.swift); their messages come to `__sbWorkerMessage(id, text)`, their errors to `__sbWorkerError(id, message)` |
@@ -63,6 +72,24 @@ final class HostBridge {
     #endif
     private var webSockets: WebSocketBridge?
     private var hostRequests: HostRequestBridge?
+    #if canImport(Network)
+    private var reachability: ReachabilityBridge?
+    #endif
+    #if canImport(CoreLocation) && !canImport(FoundationBridge)
+    private var geolocation: GeolocationBridge?
+    #endif
+    #if canImport(AVFoundation) && !canImport(FoundationBridge)
+    private var speech: SpeechBridge?
+    #endif
+    #if canImport(Speech) && !canImport(FoundationBridge)
+    private var recognition: SpeechRecognitionBridge?
+    #endif
+    #if os(macOS)
+    /// The display-sleep assertion held while the app holds a wake lock.
+    private var wakeAssertion: IOPMAssertionID?
+    #endif
+    /// Whether the app holds a wake lock (`isIdleTimerDisabled`), undone with the bridge.
+    private var awake = false
     #if !canImport(FoundationBridge)
     private var undo: UndoBridge?
     /// The window's undo manager, for the undo bridge when the app first sends a state.
@@ -82,6 +109,21 @@ final class HostBridge {
         for timer in timers.values { timer.invalidate() }
         timers.removeAll()
         webSockets?.invalidate()
+        #if canImport(Network)
+        reachability?.stop()
+        #endif
+        setAwake(false)
+        hostRequests?.stop()
+        NativeFunctions.sink = nil
+        #if canImport(CoreLocation) && !canImport(FoundationBridge)
+        geolocation?.stop()
+        #endif
+        #if canImport(AVFoundation) && !canImport(FoundationBridge)
+        speech?.stop()
+        #endif
+        #if canImport(Speech) && !canImport(FoundationBridge)
+        recognition?.stop()
+        #endif
         #if !canImport(FoundationBridge)
         undo?.manager = nil
         #endif
@@ -232,6 +274,63 @@ final class HostBridge {
         host.install("appDirectories") { _ in .string(FilesBridge.directories().json) }
         #endif
 
+        #if canImport(CoreLocation) && !canImport(FoundationBridge)
+        host.install("geolocation") { [weak self] arguments in
+            guard let self, let id = arguments[safe: 0]?.int, let action = arguments[safe: 1]?.string else { return nil }
+            if geolocation == nil {
+                geolocation = GeolocationBridge { [weak self] id, result in self?.callIn("__sbGeolocation", [.number(Double(id)), .string(result.json)]) }
+            }
+            let options = (arguments[safe: 2]?.string).flatMap { try? JSONValue.parse($0) }?.object ?? [:]
+            geolocation?.request(id: id, action: action, options: options)
+            return nil
+        }
+        #endif
+
+        #if canImport(AVFoundation) && !canImport(FoundationBridge)
+        host.install("speak") { [weak self] arguments in
+            guard let self, let id = arguments[safe: 0]?.int else { return nil }
+            if speech == nil {
+                speech = SpeechBridge { [weak self] id, event in self?.callIn("__sbSpeechEvent", [.number(Double(id)), .string(event.json)]) }
+            }
+            let options = (arguments[safe: 1]?.string).flatMap { try? JSONValue.parse($0) }?.object ?? [:]
+            speech?.speak(id: id, options: options)
+            return nil
+        }
+        host.install("speechControl") { [weak self] arguments in
+            self?.speech?.control(arguments.first?.string ?? "")
+            return nil
+        }
+        #endif
+
+        #if canImport(Speech) && !canImport(FoundationBridge)
+        host.install("recognize") { [weak self] arguments in
+            guard let self, let id = arguments[safe: 0]?.int, let action = arguments[safe: 1]?.string else { return nil }
+            if recognition == nil {
+                recognition = SpeechRecognitionBridge { [weak self] id, event in self?.callIn("__sbRecognition", [.number(Double(id)), .string(event.json)]) }
+            }
+            let options = (arguments[safe: 2]?.string).flatMap { try? JSONValue.parse($0) }?.object ?? [:]
+            recognition?.handle(id: id, action: action, options: options)
+            return nil
+        }
+        #endif
+
+        host.install("wakeLock") { [weak self] arguments in
+            self?.setAwake(arguments.first?.bool ?? false)
+            return nil
+        }
+
+        #if canImport(Network)
+        host.install("online") { [weak self] _ in
+            guard let self else { return .bool(true) }
+            if reachability == nil {
+                let bridge = ReachabilityBridge { [weak self] online in self?.callIn("__sbOnline", [.bool(online)]) }
+                bridge.start()
+                reachability = bridge
+            }
+            return .bool(reachability?.isOnline ?? true)
+        }
+        #endif
+
         #if canImport(MediaPlayer)
         host.install("mediaSession") { [weak self] arguments in
             guard let self, let update = arguments.first?.string else { return .string("mediaSession: expected a JSON string") }
@@ -305,10 +404,22 @@ final class HostBridge {
             return nil
         }
 
+        // The escape hatch's functions (NativeFunctions.swift): the async ones go
+        // through `hostRequest` as `app:<name>`; these list them and run a sync one.
+        host.install("nativeFunctions") { _ in .array(NativeFunctions.names.map(JSONValue.string)) }
+        host.install("callNativeSync") { arguments in
+            guard let name = arguments[safe: 0]?.string else { return .string(JSONValue.object(["error": "callNativeSync: expected a name"]).json) }
+            return .string(NativeFunctions.callSync(name, arguments[safe: 1]?.string ?? "{}").json)
+        }
+        NativeFunctions.sink = { [weak self] name, value in self?.callIn("__sbNativeEvent", [.string(name), .string(value.json)]) }
+
         host.install("hostRequest") { [weak self] arguments in
             guard let self, let id = arguments[safe: 0]?.int, let kind = arguments[safe: 1]?.string else { return nil }
             if hostRequests == nil {
-                hostRequests = HostRequestBridge { [weak self] id, result in self?.callIn("__sbHostResponse", [.number(Double(id)), .string(result.json)]) }
+                hostRequests = HostRequestBridge(
+                    answer: { [weak self] id, result in self?.callIn("__sbHostResponse", [.number(Double(id)), .string(result.json)]) },
+                    filesChanged: { [weak self] urls in self?.callIn("__sbFilesChanged", [.string(JSONValue.array(urls.map(JSONValue.string)).json)]) }
+                )
             }
             hostRequests?.perform(id: id, kind: kind, json: arguments[safe: 2]?.string ?? "{}")
             return nil
@@ -452,6 +563,24 @@ final class HostBridge {
         #endif
     }
 
+    /// Keeps the screen awake (`navigator.wakeLock`) or lets it sleep again.
+    private func setAwake(_ active: Bool) {
+        guard active != awake else { return }
+        awake = active
+        #if canImport(UIKit) && !os(watchOS)
+        UIApplication.shared.isIdleTimerDisabled = active
+        #elseif os(macOS)
+        if active {
+            var id = IOPMAssertionID(0)
+            let made = IOPMAssertionCreateWithName(kIOPMAssertionTypePreventUserIdleDisplaySleep as CFString, IOPMAssertionLevel(kIOPMAssertionLevelOn), "SwiftBrowser wake lock" as CFString, &id)
+            if made == kIOReturnSuccess { wakeAssertion = id }
+        } else if let id = wakeAssertion {
+            IOPMAssertionRelease(id)
+            wakeAssertion = nil
+        }
+        #endif
+    }
+
     static func haptic(_ kind: String) {
         #if canImport(UIKit) && !os(tvOS)
         switch kind {

package/swift/Sources/SwiftBrowserNative/Host/HostRequestBridge.swift

@@ -33,7 +33,9 @@ import UniformTypeIdentifiers
 /// color picker; `{ color }`), `webAuth` (`url`, `callbackScheme`,
 /// `ephemeral`: `ASWebAuthenticationSession`; `{ url }`) and, on iOS,
 /// `audioRecord` (`action`: the microphone with `AVAudioRecorder`,
-/// AudioRecorderBridge.swift). Against the shim
+/// AudioRecorderBridge.swift). `app:<name>` is a function the Swift app
+/// registered with `NativeFunctions` (Runtime/NativeFunctions.swift), the
+/// escape hatch's function half, on every platform. Against the shim
 /// (the round trip) the page answers the first four itself, and the sign-in
 /// runs on the shim's session; the rest answers `unsupported`.
 @MainActor
@@ -45,14 +47,31 @@ final class HostRequestBridge {
     /// The microphone (`audioRecord`), one recording at a time.
     private lazy var recorder = AudioRecorderBridge()
     #endif
+    #if canImport(AuthenticationServices) && !canImport(FoundationBridge)
+    /// Sign in with Apple (`appleSignIn`), one sheet at a time.
+    private lazy var appleSignIn = AppleSignInBridge()
+    #endif
     #if !canImport(FoundationBridge)
     /// The app's files (`files`) for `fileManager`.
     private let files = FilesBridge()
+    /// iCloud Drive's changes, watched once the app asks for the container (ICloudBridge.swift).
+    private var iCloud: ICloudWatcher?
     #endif
+    /// Hands the URLs iCloud Drive changed to the app (`__sbFilesChanged`).
+    private let filesChanged: ([String]) -> Void
 
-    /// `answer` hands a request's result to the app.
-    init(answer: @escaping (Int, JSONValue) -> Void) {
+    /// `answer` hands a request's result to the app; `filesChanged` the URLs another device changed in iCloud Drive.
+    init(answer: @escaping (Int, JSONValue) -> Void, filesChanged: @escaping ([String]) -> Void = { _ in }) {
         self.answer = answer
+        self.filesChanged = filesChanged
+    }
+
+    /// The app is going away.
+    func stop() {
+        #if !canImport(FoundationBridge)
+        iCloud?.stop()
+        iCloud = nil
+        #endif
     }
 
     func perform(id: Int, kind: String, json: String) {
@@ -68,18 +87,29 @@ final class HostRequestBridge {
 
     private func handle(_ kind: String, _ params: JSONObject) async throws -> JSONValue {
         switch kind {
-        case "webAuth": try await webAuth(params)
+        case "webAuth": return try await webAuth(params)
         #if !canImport(FoundationBridge)
-        case "share": try await share(params)
-        case "pickFiles": try await pickFiles(params)
-        case "clipboard": try clipboard(params)
-        case "pickColor": try await pickColor(params)
-        case "files": try await files.handle(params)
+        case "share": return try await share(params)
+        case "pickFiles": return try await pickFiles(params)
+        case "exportFiles": return try await exportFiles(params)
+        case "clipboard": return try clipboard(params)
+        case "pickColor": return try await pickColor(params)
+        case "files":
+            let value = try await files.handle(params)
+            // The container resolved: from now on its changes reach the app.
+            if params["action"]?.string == "iCloud", value != .null, iCloud == nil { iCloud = ICloudWatcher(send: filesChanged) }
+            return value
+        #endif
+        #if canImport(AuthenticationServices) && !canImport(FoundationBridge)
+        case "appleSignIn": return try await appleSignIn.handle(params)
         #endif
         #if os(iOS) && !canImport(FoundationBridge)
-        case "audioRecord": try await recorder.handle(params)
+        case "audioRecord": return try await recorder.handle(params)
         #endif
-        default: throw HostRequestFailure("unsupported: the native app cannot answer a \(kind) request")
+        default:
+            // `app:<name>`: a function the Swift app registered (NativeFunctions.swift).
+            if kind.hasPrefix("app:") { return try await NativeFunctions.call(String(kind.dropFirst(4)), params) }
+            throw HostRequestFailure("unsupported: the native app cannot answer a \(kind) request")
         }
     }
 
@@ -237,6 +267,27 @@ final class HostRequestBridge {
         return .object(["files": .array(files)])
     }
 
+    /// `fileExporter`: the files are written to the temporary directory and the
+    /// document picker saves copies where the viewer chooses (the Files app);
+    /// answers `{ outcome: "saved", urls }` or `{ outcome: "cancelled" }`.
+    private func exportFiles(_ params: JSONObject) async throws -> JSONValue {
+        let urls = try writeFiles(params["files"]?.array ?? [])
+        guard !urls.isEmpty else { throw HostRequestFailure("exportFiles: nothing to export") }
+        let presenter = try presenter()
+        let saved: [URL] = await withCheckedContinuation { continuation in
+            let delegate = DocumentPickerDelegate { [weak self] delegate, urls in
+                self?.release(delegate)
+                continuation.resume(returning: urls)
+            }
+            keep(delegate)
+            let picker = UIDocumentPickerViewController(forExporting: urls, asCopy: true)
+            picker.delegate = delegate
+            presenter.present(picker, animated: true)
+        }
+        guard !saved.isEmpty else { return .object(["outcome": .string("cancelled")]) }
+        return .object(["outcome": .string("saved"), "urls": .array(saved.map { .string($0.absoluteString) })])
+    }
+
     private func clipboard(_ params: JSONObject) throws -> JSONValue {
         let pasteboard = UIPasteboard.general
         if params["action"]?.string == "readText" { return .object(["text": .string(pasteboard.string ?? "")]) }
@@ -297,6 +348,25 @@ final class HostRequestBridge {
         return .object(["files": .array(files)])
     }
 
+    /// `fileExporter`: a save panel per file; answers `{ outcome: "saved", urls }`, or `cancelled` at the first panel dismissed.
+    private func exportFiles(_ params: JSONObject) async throws -> JSONValue {
+        let files = params["files"]?.array ?? []
+        guard !files.isEmpty else { throw HostRequestFailure("exportFiles: nothing to export") }
+        var saved: [JSONValue] = []
+        for file in files {
+            guard let encoded = file["data"].string, let data = Data(base64Encoded: encoded) else { continue }
+            let panel = NSSavePanel()
+            let name = file["name"].string.flatMap { $0.isEmpty ? nil : $0 } ?? "file"
+            panel.nameFieldStringValue = name.components(separatedBy: "/").last ?? name
+            if let type = file["type"].string.flatMap({ UTType(mimeType: $0) }) { panel.allowedContentTypes = [type] }
+            let response = await panel.begin()
+            guard response == .OK, let url = panel.url else { return .object(["outcome": .string("cancelled")]) }
+            try data.write(to: url)
+            saved.append(.string(url.absoluteString))
+        }
+        return .object(["outcome": .string("saved"), "urls": .array(saved)])
+    }
+
     private func clipboard(_ params: JSONObject) throws -> JSONValue {
         let pasteboard = NSPasteboard.general
         if params["action"]?.string == "readText" { return .object(["text": .string(pasteboard.string(forType: .string) ?? "")]) }