@swiftbrowser/native 0.18.3 → 0.19.0

package/swift/Sources/SwiftBrowserNative/Host/AudioEngineNodes.swift

@@ -0,0 +1,70 @@
+#if canImport(SwiftUI) && !canImport(FoundationBridge)
+import AVFoundation
+import SwiftBrowserProtocol
+
+/// A node of a kind a package adds to the app's `AVAudioEngine`
+/// (AudioEngineBridge.swift): SwiftBrowserDSP's `program`, a synthesizer
+/// rendered on the audio thread. The bridge attaches `node`, gives it the
+/// values the app attaches it with and sets, and hands it the notes a
+/// sampler would take; volume and pan go to the node's `AVAudioMixing`
+/// first, as for the engine's own nodes. An app that adds no such package
+/// pays nothing for this hook.
+@MainActor
+public protocol AudioEngineCustomNode: AnyObject {
+    /// What the engine attaches and connects: a source takes no input.
+    var node: AVAudioNode { get }
+
+    /// A property, from `attach`'s values or a `set`: false for one it does
+    /// not have. Throws a `HostRequestFailure`-shaped error (`kind: detail`)
+    /// for a value it cannot take.
+    func set(_ key: String, _ value: JSONValue) throws -> Bool
+
+    /// `startNote`, `stopNote`, `controller` or `pitchBend`, with the
+    /// command's params (`note`, `velocity`, `controller`, `value`,
+    /// `channel`): false for a node that takes no notes.
+    func note(_ action: String, _ params: JSONObject) throws -> Bool
+
+    /// The engine stopped or reset, or the node was detached: stop sounding.
+    func halt()
+}
+
+public extension AudioEngineCustomNode {
+    func note(_ action: String, _ params: JSONObject) throws -> Bool { false }
+    func halt() {}
+}
+
+/// What a package's node is made with.
+public struct AudioEngineNodeContext {
+    /// The format to render in: stereo at the engine's output rate (or the
+    /// offline rendering's format), the one the engine's players send in.
+    public let format: AVAudioFormat
+}
+
+/// The node kinds packages add, by the name the app attaches them with
+/// (@swiftbrowser/web's `registerAudioNodeKind` is the page's side). Register
+/// at launch, before the bundle loads.
+@MainActor
+public enum AudioEngineNodes {
+    public typealias Make = @MainActor (AudioEngineNodeContext) throws -> any AudioEngineCustomNode
+
+    private static var kinds: [String: Make] = [:]
+
+    /// The engine's own kinds, which a package cannot replace.
+    private static let own: Set<String> = ["player", "sampler", "mixer", "reverb", "delay", "distortion", "eq", "timePitch"]
+
+    /// Adds `kind`, replacing one of the same name a package added before.
+    public static func register(_ kind: String, _ make: @escaping Make) {
+        precondition(!own.contains(kind), "\(kind) is one of the engine's own node kinds")
+        kinds[kind] = make
+    }
+
+    /// Whether a package added `kind`.
+    public static func isRegistered(_ kind: String) -> Bool {
+        kinds[kind] != nil
+    }
+
+    static func make(_ kind: String, _ context: AudioEngineNodeContext) throws -> (any AudioEngineCustomNode)? {
+        try kinds[kind].map { try $0(context) }
+    }
+}
+#endif

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

@@ -136,11 +136,11 @@ struct FilesBridge: Sendable {
             }
             try await ensureDownloaded(url)
             let data = try coordinated(url, writing: nil) { try Data(contentsOf: $0) }
-            return .object(["data": .string(data.base64EncodedString())])
+            return .object(["data": RequestBytes.value(data)])
         case "write":
             let url = try url(params, "url")
-            guard let data = Data(base64Encoded: params["data"]?.string ?? "") else {
-                throw HostRequestFailure("unsupported: files: data is not base64")
+            guard let data = RequestBytes.data(params["data"]) else {
+                throw HostRequestFailure("unsupported: files: data is neither bytes nor base64")
             }
             if isDirectory(url) == true { throw HostRequestFailure("isDirectory: \(url.absoluteString) is a directory") }
             try requireDirectory(url.deletingLastPathComponent(), for: url)

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

@@ -27,7 +27,8 @@ 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 |
 /// | `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 +39,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 |
@@ -192,10 +194,13 @@ final class HostBridge {
             return nil
         }
 
-        host.install("fetch") { [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)
+        // 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
         }
 
@@ -244,10 +249,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 +377,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 +419,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 +561,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 +655,36 @@ 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`;
+    /// `{ 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,9 +694,10 @@ 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
         }
+        let answersBytes = host.carriesBytes && request["bytes"].bool == true
         let task = session.dataTask(with: urlRequest) { [weak self] data, response, error in
             let result: JSONValue
             if let error {
@@ -636,12 +713,13 @@ 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?.callIn("__sbFetchResult", values: [.json(.number(Double(id))), .json(result)] + body)
                 }
             }
         }

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

@@ -33,14 +33,19 @@ import UniformTypeIdentifiers
 /// 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 +57,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 +80,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,6 +123,7 @@ 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.
@@ -172,7 +202,7 @@ 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 }
+            guard let data = RequestBytes.data(file["data"]) else { return nil }
             let name = file["name"].string.flatMap { $0.isEmpty ? nil : $0 } ?? "file"
             let url = folder.appendingPathComponent(name.components(separatedBy: "/").last ?? name)
             try data.write(to: url)
@@ -185,7 +215,7 @@ final class HostRequestBridge {
     }
 
     private static func fileValue(name: String, type: String, data: Data) -> JSONValue {
-        .object(["name": .string(name), "type": .string(type), "data": .string(data.base64EncodedString())])
+        .object(["name": .string(name), "type": .string(type), "data": RequestBytes.value(data)])
     }
 
     #if canImport(UIKit)
@@ -295,7 +325,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) {
@@ -354,7 +384,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 +405,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) {

package/swift/Sources/SwiftBrowserNative/Host/JSHost.swift

@@ -28,6 +28,122 @@ public protocol JSHost: AnyObject {
 
     /// Throws the loaded scripts away: a fresh global object for the next `evaluate`.
     func reset()
+
+    /// Whether `installBytes` and `call(_:values:)` carry bytes as typed
+    /// arrays. An engine without it is given base64 in JSON instead
+    /// (docs/notes/bytes.md): the bridge installs `hostRequestBytes` only here.
+    var carriesBytes: Bool { get }
+
+    /// `install`, the arguments as `HostValue`s: a typed array or an
+    /// `ArrayBuffer` arrives as `.bytes`, copied out, anything else as
+    /// `.json`; a `.bytes` result goes back as a typed array of its kind.
+    func installBytes(_ name: String, _ body: @escaping ([HostValue]) -> HostValue?)
+
+    /// `call`, a `.bytes` argument made into a typed array of its kind.
+    @discardableResult
+    func call(_ function: String, values: [HostValue]) throws -> JSONValue
+}
+
+/// A JavaScript value at the engine boundary: JSON, or bytes crossing as a
+/// typed array (`Float32Array`, `Uint8Array`, …) or an `ArrayBuffer`.
+public enum HostValue: Sendable {
+    case json(JSONValue)
+    case bytes(HostBytes)
+}
+
+/// Bytes crossing the bridge, and the view they came from or go back as.
+public struct HostBytes: Sendable {
+    public var data: Data
+    public var kind: BytesKind
+    public init(_ data: Data, kind: BytesKind) {
+        self.data = data
+        self.kind = kind
+    }
+}
+
+/// The typed arrays JavaScript has, and a bare `ArrayBuffer`.
+public enum BytesKind: String, Sendable {
+    case int8, uint8, uint8Clamped, int16, uint16, int32, uint32, float32, float64, bigInt64, bigUint64, arrayBuffer
+}
+
+extension JSHost {
+    public var carriesBytes: Bool { false }
+
+    /// An engine without bytes: the arguments are JSON, as `install(_:_:)`
+    /// gives them, and a `.bytes` result goes back as base64.
+    public func installBytes(_ name: String, _ body: @escaping ([HostValue]) -> HostValue?) {
+        install(name, { (arguments: [JSONValue]) -> JSONValue? in
+            switch body(arguments.map(HostValue.json)) {
+            case .json(let json)?: return json
+            case .bytes(let bytes)?: return .string(bytes.data.base64EncodedString())
+            case nil: return nil
+            }
+        })
+    }
+
+    /// An engine without bytes: `.bytes` goes as base64, the form JavaScript
+    /// reads where a host has no `hostRequestBytes`.
+    @discardableResult
+    public func call(_ function: String, values: [HostValue]) throws -> JSONValue {
+        try call(function, values.map { value in
+            switch value {
+            case .json(let json): return json
+            case .bytes(let bytes): return .string(bytes.data.base64EncodedString())
+            }
+        })
+    }
+}
+
+/// The bytes a host request carries beside its JSON, and those its answer
+/// collects, for the request's task (`RequestBytes.$current`): a bridge reads
+/// a byte field with `data(_:)` and writes one with `value(_:)` without being
+/// handed either list. An app that sent no views (a host without
+/// `hostRequestBytes`, an older bundle) is answered in base64, as before.
+final class RequestBytes: @unchecked Sendable {
+    @TaskLocal static var current: RequestBytes?
+
+    let incoming: [HostBytes]
+    /// Whether the app reads an answer's bytes beside its JSON.
+    let answers: Bool
+    private let lock = NSLock()
+    private var collected: [HostBytes] = []
+
+    init(incoming: [HostBytes], answers: Bool) {
+        self.incoming = incoming
+        self.answers = answers
+    }
+
+    /// The bytes the answer collected, in the order its JSON names them.
+    var outgoing: [HostBytes] {
+        lock.lock()
+        defer { lock.unlock() }
+        return collected
+    }
+
+    /// A request field's bytes: a view sent beside it (`{ "$bytes": n }`), or base64.
+    static func data(_ value: JSONValue?) -> Data? {
+        value?.bytes(from: Self.current?.incoming ?? [])
+    }
+
+    /// Bytes for an answer's field: a view beside the JSON where the app reads them so, else base64.
+    static func value(_ data: Data) -> JSONValue {
+        guard let current = Self.current, current.answers else { return .string(data.base64EncodedString()) }
+        current.lock.lock()
+        defer { current.lock.unlock() }
+        current.collected.append(HostBytes(data, kind: .uint8))
+        return .object(["$bytes": .number(Double(current.collected.count - 1))])
+    }
+}
+
+extension JSONValue {
+    /// The bytes a request's field holds: `{ "$bytes": n }` names the nth
+    /// view sent beside the JSON (`hostRequestBytes`), and a string is base64,
+    /// the form a host without bytes is given.
+    public func bytes(from bytes: [HostBytes]) -> Data? {
+        if let index = self["$bytes"].int { return bytes.indices.contains(index) ? bytes[index].data : nil }
+        if let encoded = string { return Data(base64Encoded: encoded) }
+        return nil
+    }
 }
 
 public struct JSError: Error, CustomStringConvertible {