@swiftbrowser/native 0.18.3 → 0.21.0

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

@@ -27,7 +27,10 @@ import IOKit.pwr_mgt
 /// | `log(level, message)` | the console |
 /// | `now()` | milliseconds, monotonic |
 /// | `setTimer(id, delayMs, repeats)`, `clearTimer(id)` | timers on the main run loop; fire `__sbTimerFired(id)` |
-/// | `fetch(id, requestJSON)` | `URLSession`; answers `__sbFetchResult(id, resultJSON)` |
+/// | `hostRequestBytes(id, kind, json, ...views)` | `hostRequest` with typed arrays beside the JSON, which names each as `{ "$bytes": n }` (docs/notes/bytes.md); only where the engine carries bytes (JavaScriptCore), and an answer's bytes follow `__sbHostResponse`'s JSON the same way |
+/// | `fetch(id, requestJSON, ...views)` | `URLSession`; answers `__sbFetchResult(id, resultJSON, ...bytes)`: a body as a typed array beside the JSON where the engine carries bytes and the request says `bytes: true`, else base64 |
+/// | `fetchCancel(id)` | cancels the request's task (an `AbortController`'s abort); it answers nothing |
+/// | `fetchStreams()` | true: `fetch` takes `bodyParts`, typed arrays beside the request and ranges of files on disk, streamed in order (BodyStream.swift) |
 /// | `probeImage(id, url)` | the image's pixel size through the image loader (ImageLoader.swift), which keeps the bytes for the `image` that follows; answers `__sbImageProbed(id, {width, height} or {error})`. The runtime's `Image` (a page's `new Image()`). Apple platforms only |
 /// | `storageGet/Set/Remove/Keys/Clear` | `localStorage` over `UserDefaults` |
 /// | `randomBytes(count)` | base64 of random bytes (`crypto.getRandomValues`) |
@@ -38,7 +41,8 @@ import IOKit.pwr_mgt
 /// | `appDirectories()` | the app's standard directories as `file:` URLs, a JSON object `{ documents, applicationSupport, caches, temporary }`, for `fileManager` (FilesBridge.swift); its `files` requests go through `hostRequest`. Apple platforms only |
 /// | `mediaSession(update)` | `navigator.mediaSession`: the lock screen's now-playing info and the remote commands the app handles, on MediaPlayer (NowPlayingBridge.swift); a command the viewer gives comes to `__sbMediaSessionCommand(json)` |
 /// | `notificationsReady()`, `notificationPermission(id, request)`, `notificationShow(json)`, `notificationClose(json)`, `setBadge(count)`, `pushRegister(id, key?)` | notifications on UserNotifications (NotificationBridge.swift): the permission answers `__sbNotificationPermission(id, state)`, a registration `__sbPushRegistered(id, result)`, and what the viewer opens or what arrives comes to `__sbNotification(json)` |
-/// | `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)` |
+/// | `wsOpen(id, url, protocols, bytes)`, `wsSend(id, json, ...views)`, `wsClose(id, code, reason)` | `WebSocket` on `URLSessionWebSocketTask` (WebSocketBridge.swift); what a socket receives comes to `__sbWebSocketEvent(id, json, ...bytes)`, binary as a `Uint8Array` where `wsOpen` said `bytes` |
+/// | `randomValues(count)`, `digestBytes(algorithm, data)`, `hmacBytes(algorithm, key, data)`, `decodeUTF8(bytes)`, `encodeUTF8(text)` | `randomBytes`, `digest` and `hmac` with typed arrays in and out, and UTF-8 for encoding.ts; only where the engine carries bytes |
 /// | `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` |
 /// | `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 |
@@ -63,7 +67,15 @@ final class HostBridge {
     private var workers: [Int: any WorkerEngine] = [:]
     #endif
     private let logger = Logger(subsystem: "swiftbrowser", category: "js")
+    #if canImport(FoundationBridge)
     private let session = URLSession(configuration: .default)
+    #else
+    /// Streamed bodies are rebuilt from their parts when a redirect or a challenge asks for the body again (`needNewBodyStream`).
+    private let bodyStreams = BodyStreams()
+    private lazy var session = URLSession(configuration: .default, delegate: bodyStreams, delegateQueue: nil)
+    #endif
+    /// The requests under way, by id, for `fetchCancel`.
+    private var fetchTasks: [Int: URLSessionDataTask] = [:]
     #if canImport(MediaPlayer)
     private var nowPlaying: NowPlayingBridge?
     #endif
@@ -192,13 +204,28 @@ final class HostBridge {
             return nil
         }
 
-        host.install("fetch") { [weak self] arguments in
+        // A body as a typed array beside the request (`{ "$bytes": 0 }`), and
+        // the response's as one too where the request says `bytes: true`.
+        host.installBytes("fetch") { [weak self] arguments in
+            guard let self, case .json(let first)? = arguments[safe: 0], let id = first.int else { return nil }
+            var request = JSONValue.null
+            if case .json(let second)? = arguments[safe: 1] { request = second.string.flatMap { try? JSONValue.parse($0) } ?? second }
+            self.fetch(id: id, request: request, bytes: Self.bytes(in: arguments.dropFirst(2)))
+            return nil
+        }
+
+        // An `AbortController`'s abort: the task is cancelled and answers nothing.
+        host.install("fetchCancel") { [weak self] arguments in
             guard let self, let id = arguments[safe: 0]?.int else { return nil }
-            let request = arguments[safe: 1] ?? .null
-            self.fetch(id: id, request: request)
+            self.fetchTasks.removeValue(forKey: id)?.cancel()
             return nil
         }
 
+        #if !canImport(FoundationBridge)
+        // A body as parts (`bodyParts`): typed arrays beside the request and ranges of files on disk, streamed in order.
+        host.install("fetchStreams") { _ in .bool(true) }
+        #endif
+
         #if !canImport(FoundationBridge)
         host.install("probeImage") { [weak self] arguments in
             guard let self, let id = arguments[safe: 0]?.int, let string = arguments[safe: 1]?.string else { return nil }
@@ -244,10 +271,7 @@ final class HostBridge {
         }
 
         host.install("randomBytes") { arguments in
-            let count = max(0, min(arguments.first?.int ?? 0, 65536))
-            var generator = SystemRandomNumberGenerator()
-            let bytes = (0..<count).map { _ in UInt8.random(in: .min ... .max, using: &generator) }
-            return .string(Data(bytes).base64EncodedString())
+            .string(Self.random(arguments.first?.int ?? 0).base64EncodedString())
         }
 
         host.install("openURL") { arguments in
@@ -375,12 +399,14 @@ final class HostBridge {
         host.install("wsOpen") { [weak self] arguments in
             guard let self, let id = arguments[safe: 0]?.int, let url = arguments[safe: 1]?.string else { return nil }
             let protocols = arguments[safe: 2]?.array?.compactMap(\.string) ?? []
-            webSocketBridge.open(id: id, url: url, protocols: protocols)
+            // A fourth argument `true`: the app reads binary messages as bytes (and the engine carries them).
+            webSocketBridge.open(id: id, url: url, protocols: protocols, bytes: host.carriesBytes && arguments[safe: 3]?.bool == true)
             return nil
         }
-        host.install("wsSend") { [weak self] arguments in
-            guard let self, let id = arguments[safe: 0]?.int, let json = arguments[safe: 1]?.string else { return nil }
-            webSocketBridge.send(id: id, json: json)
+        host.installBytes("wsSend") { [weak self] arguments in
+            guard let self, case .json(let first)? = arguments[safe: 0], let id = first.int,
+                  case .json(let second)? = arguments[safe: 1], let json = second.string else { return nil }
+            webSocketBridge.send(id: id, json: json, bytes: Self.bytes(in: arguments.dropFirst(2)))
             return nil
         }
         host.install("wsClose") { [weak self] arguments in
@@ -415,15 +441,46 @@ final class HostBridge {
 
         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(
-                    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 ?? "{}")
+            requestBridge().perform(id: id, kind: kind, json: arguments[safe: 2]?.string ?? "{}")
             return nil
         }
+        // The same, with typed arrays beside the JSON where it says `{ "$bytes": n }` (docs/notes/bytes.md).
+        if host.carriesBytes {
+            host.installBytes("hostRequestBytes") { [weak self] arguments in
+                guard let self, case .json(let first)? = arguments[safe: 0], let id = first.int,
+                      case .json(let second)? = arguments[safe: 1], let kind = second.string else { return nil }
+                var json = "{}"
+                if case .json(let third)? = arguments[safe: 2], let text = third.string { json = text }
+                requestBridge().perform(id: id, kind: kind, json: json, bytes: Self.bytes(in: arguments.dropFirst(3)), answersBytes: true)
+                return nil
+            }
+
+            // Bytes back as typed arrays: random bytes, digests and HMACs
+            // (`crypto`, subtle.ts), and UTF-8 both ways for `TextDecoder`,
+            // `TextEncoder` and a response's text (encoding.ts), which in
+            // JavaScript would be a loop over every byte.
+            host.installBytes("randomValues") { arguments in
+                guard case .json(let count)? = arguments.first else { return nil }
+                return .bytes(HostBytes(Self.random(count.int ?? 0), kind: .uint8))
+            }
+            host.installBytes("digestBytes") { arguments in
+                guard case .json(let algorithm)? = arguments[safe: 0], let name = algorithm.string, case .bytes(let data)? = arguments[safe: 1] else { return nil }
+                return Self.digest(name, data.data).map { .bytes(HostBytes($0, kind: .uint8)) }
+            }
+            host.installBytes("hmacBytes") { arguments in
+                guard case .json(let algorithm)? = arguments[safe: 0], let name = algorithm.string,
+                      case .bytes(let key)? = arguments[safe: 1], case .bytes(let data)? = arguments[safe: 2] else { return nil }
+                return Self.hmac(name, key: key.data, data.data).map { .bytes(HostBytes($0, kind: .uint8)) }
+            }
+            host.installBytes("decodeUTF8") { arguments in
+                guard case .bytes(let bytes)? = arguments.first else { return .json(.string("")) }
+                return .json(.string(String(decoding: bytes.data, as: UTF8.self)))
+            }
+            host.installBytes("encodeUTF8") { arguments in
+                guard case .json(let text)? = arguments.first, let string = text.string else { return nil }
+                return .bytes(HostBytes(Data(string.utf8), kind: .uint8))
+            }
+        }
 
         #if !canImport(FoundationBridge)
         host.install("undoState") { [weak self] arguments in
@@ -526,11 +583,27 @@ final class HostBridge {
     /// The WebSocket bridge, made when the app opens its first socket.
     private var webSocketBridge: WebSocketBridge {
         if let webSockets { return webSockets }
-        let bridge = WebSocketBridge(session: session) { [weak self] id, event in self?.callIn("__sbWebSocketEvent", [.number(Double(id)), .string(event.json)]) }
+        let bridge = WebSocketBridge(session: session) { [weak self] id, event, bytes in
+            self?.callIn("__sbWebSocketEvent", values: [.json(.number(Double(id))), .json(.string(event.json))] + bytes.map(HostValue.bytes))
+        }
         webSockets = bridge
         return bridge
     }
 
+    /// The typed arrays among a call's arguments, in order.
+    private static func bytes(in arguments: ArraySlice<HostValue>) -> [HostBytes] {
+        arguments.compactMap { value in
+            if case .bytes(let bytes) = value { return bytes }
+            return nil
+        }
+    }
+
+    /// `count` random bytes (at most 64 KiB, as `crypto.getRandomValues` allows).
+    private static func random(_ count: Int) -> Data {
+        var generator = SystemRandomNumberGenerator()
+        return Data((0..<max(0, min(count, 65536))).map { _ in UInt8.random(in: .min ... .max, using: &generator) })
+    }
+
     // MARK: crypto.subtle and haptics
 
     static func digest(_ algorithm: String, _ data: Data) -> Data? {
@@ -604,11 +677,38 @@ final class HostBridge {
         }
     }
 
+    private func callIn(_ function: String, values: [HostValue]) {
+        do {
+            try host.call(function, values: values)
+        } catch {
+            logger.error("\(function): \(String(describing: error), privacy: .public)")
+        }
+    }
+
+    /// The host requests' bridge, made at the first request. An answer with
+    /// bytes goes back as typed arrays after the JSON.
+    private func requestBridge() -> HostRequestBridge {
+        if let hostRequests { return hostRequests }
+        let bridge = HostRequestBridge(
+            answer: { [weak self] id, result, bytes in
+                self?.callIn("__sbHostResponse", values: [.json(.number(Double(id))), .json(.string(result.json))] + bytes.map(HostValue.bytes))
+            },
+            filesChanged: { [weak self] urls in self?.callIn("__sbFilesChanged", [.string(JSONValue.array(urls.map(JSONValue.string)).json)]) }
+        )
+        hostRequests = bridge
+        return bridge
+    }
+
     // MARK: fetch
 
-    /// `{ url, method, headers: {name: value}, body: base64 | null }` in,
-    /// `{ status, statusText, headers, url, body: base64 }` or `{ error }` out.
-    private func fetch(id: Int, request: JSONValue) {
+    /// `{ url, method, headers: {name: value}, body, bytes }` in, the body
+    /// base64 or `{ "$bytes": 0 }` naming a view in `bytes`, or `bodyParts`
+    /// (`fetchStreams`): views and ranges of files on disk, streamed in
+    /// order without reading the files into memory;
+    /// `{ status, statusText, headers, url, body }` or `{ error }` out, the
+    /// body base64, or a `Uint8Array` after the JSON where the request said
+    /// `bytes: true` (docs/notes/bytes.md).
+    private func fetch(id: Int, request: JSONValue, bytes: [HostBytes] = []) {
         guard let urlString = request["url"].string, let url = URL(string: urlString) else {
             callIn("__sbFetchResult", [.number(Double(id)), .object(["error": .string("invalid URL")])])
             return
@@ -618,10 +718,28 @@ final class HostBridge {
         for (name, value) in request["headers"].object ?? [:] {
             if let value = value.string { urlRequest.setValue(value, forHTTPHeaderField: name) }
         }
-        if let body = request["body"].string, let data = Data(base64Encoded: body) {
+        if let data = request["body"].bytes(from: bytes) {
             urlRequest.httpBody = data
         }
+        #if !canImport(FoundationBridge)
+        var streamedParts: [BodyPart]?
+        if let parts = request["bodyParts"].array {
+            do {
+                streamedParts = try parts.map { try BodyPart(part: $0, bytes: bytes) }
+            } catch {
+                callIn("__sbFetchResult", [.number(Double(id)), .object(["error": .string(error.localizedDescription)])])
+                return
+            }
+            urlRequest.httpBodyStream = PartsInputStream(parts: streamedParts!)
+            if urlRequest.value(forHTTPHeaderField: "Content-Length") == nil {
+                urlRequest.setValue(String(streamedParts!.reduce(0) { $0 + $1.length }), forHTTPHeaderField: "Content-Length")
+            }
+        }
+        #endif
+        let answersBytes = host.carriesBytes && request["bytes"].bool == true
         let task = session.dataTask(with: urlRequest) { [weak self] data, response, error in
+            // Cancelled (`fetchCancel`): the app rejected its promise already and hears nothing more.
+            if let error, (error as NSError).code == NSURLErrorCancelled, (error as NSError).domain == NSURLErrorDomain { return }
             let result: JSONValue
             if let error {
                 result = .object(["error": .string(error.localizedDescription)])
@@ -636,15 +754,21 @@ final class HostBridge {
                     "statusText": .string(http.map { HTTPURLResponse.localizedString(forStatusCode: $0.statusCode) } ?? ""),
                     "headers": .object(headers),
                     "url": .string(response?.url?.absoluteString ?? urlString),
-                    "body": .string((data ?? Data()).base64EncodedString()),
+                    "body": answersBytes ? .object(["$bytes": .number(0)]) : .string((data ?? Data()).base64EncodedString()),
                 ])
             }
+            let body = error == nil && answersBytes ? [HostValue.bytes(HostBytes(data ?? Data(), kind: .uint8))] : []
             DispatchQueue.main.async { [weak self] in
                 MainActor.assumeIsolated {
-                    self?.callIn("__sbFetchResult", [.number(Double(id)), result])
+                    self?.fetchTasks.removeValue(forKey: id)
+                    self?.callIn("__sbFetchResult", values: [.json(.number(Double(id))), .json(result)] + body)
                 }
             }
         }
+        fetchTasks[id] = task
+        #if !canImport(FoundationBridge)
+        if let streamedParts { bodyStreams.register(task, parts: streamedParts) }
+        #endif
         task.resume()
     }
 }

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

@@ -28,19 +28,25 @@ import UniformTypeIdentifiers
 /// are the web renderer's (docs/ops-protocol.md): `share` (`title`, `text`,
 /// `url`, `files`: a share sheet; `{ outcome }`), `pickFiles` (`accept`,
 /// `multiple`: the photo picker for pictures and videos, else the document
-/// picker; `{ files: [{ name, type, data }] }`), `clipboard` (`write` with
+/// picker, or with `public.folder` a folder's files, named by their paths in
+/// it; `{ files: [{ name, type, data }] }`), `clipboard` (`write` with
 /// `text` or `files`, `readText`; `{ text }`), `pickColor` (`color`: the
 /// color picker; `{ color }`), `webAuth` (`url`, `callbackScheme`,
 /// `ephemeral`: `ASWebAuthenticationSession`; `{ url }`) and, on iOS,
 /// `audioRecord` (`action`: the microphone with `AVAudioRecorder`,
-/// AudioRecorderBridge.swift). `app:<name>` is a function the Swift app
+/// AudioRecorderBridge.swift); `audioEngine` (the app's `AVAudioEngine`
+/// commands, AudioEngineBridge.swift) on iOS and macOS, handled as each
+/// arrives rather than on a later turn, so they keep their order and a note
+/// sounds at once; `languageModel` (the app's `LanguageModelSession`s on
+/// FoundationModels where Apple Intelligence answers, else on the app's
+/// `LanguageModels.fallback`; LanguageModelBridge.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
 final class HostRequestBridge {
-    private let answer: (Int, JSONValue) -> Void
+    private let answer: (Int, JSONValue, [HostBytes]) -> Void
     /// Delegates and sessions kept alive until they answer.
     private var active: [ObjectIdentifier: AnyObject] = [:]
     #if os(iOS) && !canImport(FoundationBridge)
@@ -52,16 +58,20 @@ final class HostRequestBridge {
     private lazy var appleSignIn = AppleSignInBridge()
     #endif
     #if !canImport(FoundationBridge)
+    /// The app's audio engines (`audioEngine`).
+    private lazy var audioEngine = AudioEngineBridge()
     /// 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?
+    /// The language model's sessions (`languageModel`, LanguageModelBridge.swift).
+    private lazy var languageModel = LanguageModelBridge()
     #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; `filesChanged` the URLs another device changed in iCloud Drive.
-    init(answer: @escaping (Int, JSONValue) -> Void, filesChanged: @escaping ([String]) -> Void = { _ in }) {
+    init(answer: @escaping (Int, JSONValue, [HostBytes]) -> Void, filesChanged: @escaping ([String]) -> Void = { _ in }) {
         self.answer = answer
         self.filesChanged = filesChanged
     }
@@ -71,16 +81,36 @@ final class HostRequestBridge {
         #if !canImport(FoundationBridge)
         iCloud?.stop()
         iCloud = nil
+        audioEngine.stop()
+        languageModel.stop()
         #endif
     }
 
-    func perform(id: Int, kind: String, json: String) {
+    /// Performs the request; `bytes` are the typed arrays sent beside the
+    /// JSON (`hostRequestBytes`), which it names as `{ "$bytes": n }`, and
+    /// `answersBytes` says the app reads an answer's bytes the same way.
+    func perform(id: Int, kind: String, json: String, bytes: [HostBytes] = [], answersBytes: Bool = false) {
         let params = (try? JSONValue.parse(json))?.object ?? [:]
+        #if !canImport(FoundationBridge)
+        if kind == "audioEngine" {
+            audioEngine.perform(params, bytes: bytes) { [weak self] result in
+                switch result {
+                case .success(let value): self?.answer(id, .object(["value": value]), [])
+                case .failure(let error): self?.answer(id, .object(["error": .string("\(error)")]), [])
+                }
+            }
+            return
+        }
+        #endif
+        let carried = RequestBytes(incoming: bytes, answers: answersBytes)
         Task { @MainActor in
-            do {
-                answer(id, .object(["value": try await handle(kind, params)]))
-            } catch {
-                answer(id, .object(["error": .string("\(error)")]))
+            await RequestBytes.$current.withValue(carried) {
+                do {
+                    let value = try await handle(kind, params)
+                    answer(id, .object(["value": value]), carried.outgoing)
+                } catch {
+                    answer(id, .object(["error": .string("\(error)")]), [])
+                }
             }
         }
     }
@@ -94,10 +124,18 @@ final class HostRequestBridge {
         case "exportFiles": return try await exportFiles(params)
         case "clipboard": return try clipboard(params)
         case "pickColor": return try await pickColor(params)
+        case "languageModel": return try await languageModel.handle(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) }
+            // What the app itself wrote, made, moved or removed: `fileManager.watch` hears it, as the page's host tells its watchers.
+            switch params["action"]?.string {
+            case "write", "remove", "createDirectory": if let url = params["url"]?.string { filesChanged([url]) }
+            case "move", "copy": filesChanged([params["from"]?.string, params["to"]?.string].compactMap { $0 })
+            case "importItem": if let url = params["to"]?.string { filesChanged([url]) }
+            default: break
+            }
             return value
         #endif
         #if canImport(AuthenticationServices) && !canImport(FoundationBridge)
@@ -172,9 +210,14 @@ final class HostRequestBridge {
         let folder = FileManager.default.temporaryDirectory.appendingPathComponent("swiftbrowser-share-\(UUID().uuidString)", isDirectory: true)
         try FileManager.default.createDirectory(at: folder, withIntermediateDirectories: true)
         return try files.compactMap { file -> URL? in
-            guard let encoded = file["data"].string, let data = Data(base64Encoded: encoded) else { return nil }
             let name = file["name"].string.flatMap { $0.isEmpty ? nil : $0 } ?? "file"
             let url = folder.appendingPathComponent(name.components(separatedBy: "/").last ?? name)
+            // A picked file still on disk (its `url`) is copied; bytes are written.
+            if let source = file["url"].string.flatMap(URL.init(string:)), source.isFileURL, PickedFiles.shared.contains(source) {
+                try PickedFiles.shared.accessing(source) { try FileManager.default.copyItem(at: source, to: url) }
+                return url
+            }
+            guard let data = RequestBytes.data(file["data"]) else { return nil }
             try data.write(to: url)
             return url
         }
@@ -184,8 +227,43 @@ final class HostRequestBridge {
         UTType(filenameExtension: url.pathExtension)?.preferredMIMEType ?? "application/octet-stream"
     }
 
-    private static func fileValue(name: String, type: String, data: Data) -> JSONValue {
-        .object(["name": .string(name), "type": .string(type), "data": .string(data.base64EncodedString())])
+    /// A file still on disk, as the page's `LazyFile` reads it: its URL and size, no bytes (docs/notes/bytes.md).
+    static func fileReference(name: String, url: URL) -> JSONValue {
+        let values = try? url.resourceValues(forKeys: [.fileSizeKey, .contentModificationDateKey])
+        var value: JSONObject = [
+            "name": .string(name),
+            "type": .string(mimeType(of: url)),
+            "url": .string(url.standardizedFileURL.absoluteString),
+            "size": .number(Double(values?.fileSize ?? 0)),
+        ]
+        if let modified = values?.contentModificationDate { value["lastModified"] = .number((modified.timeIntervalSince1970 * 1000).rounded()) }
+        return .object(value)
+    }
+
+    /// A chosen folder's files, at any depth, that `types` allow (any when none), each named by its path from the
+    /// folder, the folder's own name first (`Bank/Leads/Saw.fxp`), as the page's folder chooser names them. The
+    /// files stay on disk: the folder's security scope is kept open (PickedFiles) and the page reads what it needs.
+    static func folderFiles(_ folder: URL, types: [UTType]) -> [JSONValue] {
+        let scoped = folder.startAccessingSecurityScopedResource()
+        defer { if scoped { folder.stopAccessingSecurityScopedResource() } }
+        let root = folder.resolvingSymlinksInPath().standardizedFileURL.pathComponents
+        guard let walker = FileManager.default.enumerator(at: folder, includingPropertiesForKeys: [.isRegularFileKey, .fileSizeKey], options: [.skipsHiddenFiles, .skipsPackageDescendants]) else { return [] }
+        var files: [JSONValue] = []
+        var urls: [URL] = []
+        for case let url as URL in walker {
+            guard (try? url.resourceValues(forKeys: [.isRegularFileKey]))?.isRegularFile == true else { continue }
+            if !types.isEmpty {
+                guard let type = UTType(filenameExtension: url.pathExtension), types.contains(where: { type.conforms(to: $0) }) else { continue }
+            }
+            let components = url.resolvingSymlinksInPath().standardizedFileURL.pathComponents
+            guard components.count > root.count, Array(components.prefix(root.count)) == root else { continue }
+            let path = ([folder.lastPathComponent] + components.dropFirst(root.count)).joined(separator: "/")
+            files.append(fileReference(name: path, url: url))
+            urls.append(url)
+        }
+        // Scoped again for as long as the app reads the files: `accessing` opens it per read, `release` ends it.
+        PickedFiles.shared.register(urls, scoped: scoped ? folder : nil)
+        return files
     }
 
     #if canImport(UIKit)
@@ -255,16 +333,18 @@ final class HostRequestBridge {
                 continuation.resume(returning: urls)
             }
             keep(delegate)
-            let picker = UIDocumentPickerViewController(forOpeningContentTypes: accept.types.isEmpty ? [.item] : accept.types, asCopy: true)
-            picker.allowsMultipleSelection = multiple
+            // A folder is opened in place (a folder cannot be copied in), its files read while its scope is open.
+            let picker = accept.folder
+                ? UIDocumentPickerViewController(forOpeningContentTypes: [.folder], asCopy: false)
+                : UIDocumentPickerViewController(forOpeningContentTypes: accept.types.isEmpty ? [.item] : accept.types, asCopy: true)
+            picker.allowsMultipleSelection = multiple && !accept.folder
             picker.delegate = delegate
             presenter.present(picker, animated: true)
         }
-        let files = urls.compactMap { url -> JSONValue? in
-            guard let data = try? Data(contentsOf: url) else { return nil }
-            return Self.fileValue(name: url.lastPathComponent, type: Self.mimeType(of: url), data: data)
-        }
-        return .object(["files": .array(files)])
+        if accept.folder { return .object(["files": .array(urls.first.map { Self.folderFiles($0, types: accept.types) } ?? [])]) }
+        // Copied into the app's tmp by the picker (`asCopy: true`): the page gets their URLs and reads them a piece at a time.
+        PickedFiles.shared.register(urls)
+        return .object(["files": .array(urls.map { Self.fileReference(name: $0.lastPathComponent, url: $0) })])
     }
 
     /// `fileExporter`: the files are written to the temporary directory and the
@@ -295,7 +375,7 @@ final class HostRequestBridge {
             pasteboard.string = text
             return .object([:])
         }
-        guard let file = params["files"]?.array?.first, let encoded = file["data"].string, let data = Data(base64Encoded: encoded) else {
+        guard let file = params["files"]?.array?.first, let data = RequestBytes.data(file["data"]) else {
             throw HostRequestFailure("clipboard: nothing to copy")
         }
         if let image = UIImage(data: data) {
@@ -336,16 +416,15 @@ final class HostRequestBridge {
     private func pickFiles(_ params: JSONObject) async throws -> JSONValue {
         let accept = Self.parseAccept(params["accept"]?.string ?? "")
         let panel = NSOpenPanel()
-        panel.allowsMultipleSelection = params["multiple"]?.bool ?? false
-        panel.canChooseDirectories = false
-        if !accept.types.isEmpty { panel.allowedContentTypes = accept.types }
+        panel.allowsMultipleSelection = !accept.folder && (params["multiple"]?.bool ?? false)
+        panel.canChooseDirectories = accept.folder
+        panel.canChooseFiles = !accept.folder
+        if !accept.folder, !accept.types.isEmpty { panel.allowedContentTypes = accept.types }
         let response = await panel.begin()
         guard response == .OK else { return .object(["files": .array([])]) }
-        let files = panel.urls.compactMap { url -> JSONValue? in
-            guard let data = try? Data(contentsOf: url) else { return nil }
-            return Self.fileValue(name: url.lastPathComponent, type: Self.mimeType(of: url), data: data)
-        }
-        return .object(["files": .array(files)])
+        if accept.folder { return .object(["files": .array(panel.urls.first.map { Self.folderFiles($0, types: accept.types) } ?? [])]) }
+        PickedFiles.shared.register(panel.urls)
+        return .object(["files": .array(panel.urls.map { Self.fileReference(name: $0.lastPathComponent, url: $0) })])
     }
 
     /// `fileExporter`: a save panel per file; answers `{ outcome: "saved", urls }`, or `cancelled` at the first panel dismissed.
@@ -354,7 +433,7 @@ final class HostRequestBridge {
         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 }
+            guard let data = RequestBytes.data(file["data"]) else { continue }
             let panel = NSSavePanel()
             let name = file["name"].string.flatMap { $0.isEmpty ? nil : $0 } ?? "file"
             panel.nameFieldStringValue = name.components(separatedBy: "/").last ?? name
@@ -375,7 +454,7 @@ final class HostRequestBridge {
             pasteboard.setString(text, forType: .string)
             return .object([:])
         }
-        guard let file = params["files"]?.array?.first, let encoded = file["data"].string, let data = Data(base64Encoded: encoded) else {
+        guard let file = params["files"]?.array?.first, let data = RequestBytes.data(file["data"]) else {
             throw HostRequestFailure("clipboard: nothing to copy")
         }
         if let image = NSImage(data: data) {
@@ -391,12 +470,15 @@ final class HostRequestBridge {
     }
     #endif
 
-    /// What a chooser's `accept` asks for: the content types, and whether they are all pictures or videos (the photo library's).
-    static func parseAccept(_ accept: String) -> (types: [UTType], photos: Bool, images: Bool, videos: Bool) {
-        let entries = accept.split(separator: ",").map { $0.trimmingCharacters(in: .whitespaces) }.filter { !$0.isEmpty }
+    /// What a chooser's `accept` asks for: the content types, and whether they are all pictures or videos (the
+    /// photo library's), or a folder (`public.folder`, `UTType.folder`), its files then those the other types allow.
+    static func parseAccept(_ accept: String) -> (types: [UTType], photos: Bool, images: Bool, videos: Bool, folder: Bool) {
+        var entries = accept.split(separator: ",").map { $0.trimmingCharacters(in: .whitespaces) }.filter { !$0.isEmpty }
+        let folder = entries.contains(UTType.folder.identifier)
+        entries.removeAll { $0 == UTType.folder.identifier }
         let images = entries.contains { $0.hasPrefix("image/") }
         let videos = entries.contains { $0.hasPrefix("video/") }
-        let photos = !entries.isEmpty && entries.allSatisfy { $0.hasPrefix("image/") || $0.hasPrefix("video/") }
+        let photos = !folder && !entries.isEmpty && entries.allSatisfy { $0.hasPrefix("image/") || $0.hasPrefix("video/") }
         let types = entries.compactMap { entry -> UTType? in
             if entry.hasPrefix(".") { return UTType(filenameExtension: String(entry.dropFirst())) }
             switch entry {
@@ -406,7 +488,7 @@ final class HostRequestBridge {
             default: return UTType(mimeType: entry)
             }
         }
-        return (types, photos, images, videos)
+        return (types, photos, images, videos, folder)
     }
 
     /// A picked photo or video as a file: its first picture (or movie) representation, named after the item.
@@ -416,14 +498,31 @@ final class HostRequestBridge {
             ?? identifiers.first(where: { UTType($0)?.conforms(to: .movie) == true })
             ?? identifiers.first else { return nil }
         let type = UTType(identifier)
-        let data: Data? = await withCheckedContinuation { continuation in
-            _ = provider.loadDataRepresentation(forTypeIdentifier: identifier) { data, _ in continuation.resume(returning: data) }
-        }
-        guard let data else { return nil }
         let ext = type?.preferredFilenameExtension ?? "bin"
         let suggested = provider.suggestedName ?? "photo"
         let name = suggested.contains(".") ? suggested : "\(suggested).\(ext)"
-        return fileValue(name: name, type: type?.preferredMIMEType ?? "application/octet-stream", data: data)
+        // The file the library hands over lives only while the completion runs: copied into a tmp folder of
+        // its own, registered (PickedFiles) and answered as a reference, so the page reads it a piece at a time.
+        let folder = FileManager.default.temporaryDirectory.appendingPathComponent("swiftbrowser-picks-\(UUID().uuidString)", isDirectory: true)
+        let copied: URL? = await withCheckedContinuation { continuation in
+            _ = provider.loadFileRepresentation(forTypeIdentifier: identifier) { url, _ in
+                guard let url else {
+                    continuation.resume(returning: nil)
+                    return
+                }
+                do {
+                    try FileManager.default.createDirectory(at: folder, withIntermediateDirectories: true)
+                    let target = folder.appendingPathComponent(name)
+                    try FileManager.default.copyItem(at: url, to: target)
+                    continuation.resume(returning: target)
+                } catch {
+                    continuation.resume(returning: nil)
+                }
+            }
+        }
+        guard let copied else { return nil }
+        PickedFiles.shared.register([copied], temporary: folder)
+        return fileReference(name: name, url: copied)
     }
     #endif
 }