@swiftbrowser/native 0.0.0-stage → 0.10.0

package/swift/Package.swift

@@ -0,0 +1,31 @@
+// swift-tools-version: 6.0
+import PackageDescription
+
+// SwiftBrowser Native: the render ops of docs/ops-protocol.md drawn by real
+// SwiftUI, for apps whose logic is JavaScript running in JavaScriptCore
+// (docs/native.md). A separate package from the repository root's: that one
+// has a target named `SwiftUI` and is only ever built for Wasm and Linux.
+//
+// Targets, from the bottom up:
+//
+// - SwiftBrowserProtocol: the ops, events and typed props (Foundation only).
+// - SwiftBrowserTree: the live element tree the ops mutate (Observation).
+//   Both build and test on Linux, so CI without a Mac covers them.
+// - SwiftBrowserNative: the SwiftUI views for each element kind, the
+//   JavaScriptCore host and the app runtime. Apple platforms only; every
+//   file is wrapped in `#if canImport(SwiftUI)` so the package still
+//   resolves and tests elsewhere.
+let package = Package(
+    name: "SwiftBrowserNative",
+    platforms: [.iOS(.v17), .macOS(.v14)],
+    products: [
+        .library(name: "SwiftBrowserNative", targets: ["SwiftBrowserNative"]),
+        .library(name: "SwiftBrowserProtocol", targets: ["SwiftBrowserProtocol"]),
+        .library(name: "SwiftBrowserTree", targets: ["SwiftBrowserTree"]),
+    ],
+    targets: [
+        .target(name: "SwiftBrowserProtocol"),
+        .target(name: "SwiftBrowserTree", dependencies: ["SwiftBrowserProtocol"]),
+        .target(name: "SwiftBrowserNative", dependencies: ["SwiftBrowserProtocol", "SwiftBrowserTree"]),
+    ]
+)

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

@@ -0,0 +1,228 @@
+#if canImport(SwiftUI)
+import Foundation
+import os
+import SwiftBrowserProtocol
+import SwiftBrowserTree
+#if canImport(UIKit)
+import UIKit
+#elseif canImport(AppKit)
+import AppKit
+#endif
+#if canImport(FoundationBridge)
+import FoundationBridge // the shim's Foundation stand-ins (ShimAliases.swift)
+#endif
+
+/// The native primitives `@swiftbrowser/native` builds the web globals from
+/// (packages/native/src/runtime.ts), installed on `__sbNative`:
+///
+/// | function | what it does |
+/// |---|---|
+/// | `applyOps(json)` | applies a pass's ops to the tree, synchronously |
+/// | `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)` |
+/// | `storageGet/Set/Remove/Keys/Clear` | `localStorage` over `UserDefaults` |
+/// | `randomBytes(count)` | base64 of random bytes (`crypto.getRandomValues`) |
+/// | `openURL(url)` | the system opener |
+/// | `locale()` | the viewer's locale identifier |
+/// | `launchArguments()` | the process's arguments (`-screen list` from a scheme or `simctl launch`) |
+///
+/// Everything JavaScript-facing runs on the main thread; work that is not
+/// (a fetch) hops back before calling in.
+@MainActor
+final class HostBridge {
+    private let host: JSHost
+    private let tree: OpTree
+    private var timers: [Int: Timer] = [:]
+    private let logger = Logger(subsystem: "swiftbrowser", category: "js")
+    private let session = URLSession(configuration: .default)
+    /// Keys of `localStorage` live under this prefix in `UserDefaults`.
+    static let storagePrefix = "swiftbrowser.storage."
+
+    init(host: JSHost, tree: OpTree) {
+        self.host = host
+        self.tree = tree
+        installAll()
+    }
+
+    /// Stops every timer; the app that owned the bridge is going away.
+    func invalidate() {
+        for timer in timers.values { timer.invalidate() }
+        timers.removeAll()
+    }
+
+    private func installAll() {
+        host.install("applyOps") { [tree] arguments in
+            guard let json = arguments.first?.string else { return .string("applyOps: expected a JSON string") }
+            do {
+                try tree.apply(json: json)
+                return nil
+            } catch {
+                return .string("\(error)")
+            }
+        }
+
+        host.install("log") { [logger] arguments in
+            let level = arguments.first?.string ?? "log"
+            let message = arguments.dropFirst().map { $0.string ?? $0.json }.joined(separator: " ")
+            switch level {
+            case "error": logger.error("\(message, privacy: .public)")
+            case "warn": logger.warning("\(message, privacy: .public)")
+            case "debug": logger.debug("\(message, privacy: .public)")
+            default: logger.info("\(message, privacy: .public)")
+            }
+            #if DEBUG
+            print("[js:\(level)] \(message)")
+            #endif
+            return nil
+        }
+
+        host.install("now") { _ in .number(ProcessInfo.processInfo.systemUptime * 1000) }
+
+        host.install("setTimer") { [weak self] arguments in
+            guard let self, let id = arguments[safe: 0]?.int else { return nil }
+            let delay = max(0, (arguments[safe: 1]?.double ?? 0) / 1000)
+            let repeats = arguments[safe: 2]?.bool ?? false
+            self.timers[id]?.invalidate()
+            let fire: @Sendable (Timer) -> Void = { [weak self] _ in
+                // Scheduled on the main run loop, so it fires on the main thread.
+                MainActor.assumeIsolated {
+                    guard let self else { return }
+                    if !repeats { self.timers[id] = nil }
+                    self.callIn("__sbTimerFired", [.number(Double(id))])
+                }
+            }
+            #if canImport(FoundationBridge)
+            let timer = Timer.scheduledTimer(withTimeInterval: delay, repeats: repeats, block: fire)
+            #else
+            let timer = Timer(timeInterval: delay, repeats: repeats, block: fire)
+            // `.common` so timers keep firing while a scroll view tracks.
+            RunLoop.main.add(timer, forMode: .common)
+            #endif
+            self.timers[id] = timer
+            return nil
+        }
+
+        host.install("clearTimer") { [weak self] arguments in
+            guard let self, let id = arguments[safe: 0]?.int else { return nil }
+            self.timers[id]?.invalidate()
+            self.timers[id] = nil
+            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)
+            return nil
+        }
+
+        host.install("storageGet") { arguments in
+            guard let key = arguments.first?.string else { return .null }
+            return UserDefaults.standard.string(forKey: HostBridge.storagePrefix + key).map(JSONValue.string) ?? .null
+        }
+        host.install("storageSet") { arguments in
+            guard let key = arguments[safe: 0]?.string else { return nil }
+            UserDefaults.standard.set(arguments[safe: 1]?.string ?? "", forKey: HostBridge.storagePrefix + key)
+            return nil
+        }
+        host.install("storageRemove") { arguments in
+            guard let key = arguments.first?.string else { return nil }
+            UserDefaults.standard.removeObject(forKey: HostBridge.storagePrefix + key)
+            return nil
+        }
+        host.install("storageKeys") { _ in
+            let keys = UserDefaults.standard.dictionaryRepresentation().keys
+                .filter { $0.hasPrefix(HostBridge.storagePrefix) }
+                .map { String($0.dropFirst(HostBridge.storagePrefix.count)) }
+                .sorted()
+            return .array(keys.map(JSONValue.string))
+        }
+        host.install("storageClear") { _ in
+            for key in UserDefaults.standard.dictionaryRepresentation().keys where key.hasPrefix(HostBridge.storagePrefix) {
+                UserDefaults.standard.removeObject(forKey: key)
+            }
+            return nil
+        }
+
+        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())
+        }
+
+        host.install("openURL") { arguments in
+            guard let string = arguments.first?.string, let url = URL(string: string) else { return .bool(false) }
+            #if canImport(UIKit)
+            UIApplication.shared.open(url)
+            #elseif canImport(AppKit)
+            NSWorkspace.shared.open(url)
+            #endif
+            return .bool(true)
+        }
+
+        host.install("locale") { _ in .string(Locale.current.identifier) }
+
+        host.install("launchArguments") { _ in .array(ProcessInfo.processInfo.arguments.map(JSONValue.string)) }
+    }
+
+    /// Calls into JavaScript from a timer or a completion, where a throw has nowhere to go but the log.
+    private func callIn(_ function: String, _ arguments: [JSONValue]) {
+        do {
+            try host.call(function, arguments)
+        } catch {
+            logger.error("\(function): \(String(describing: error), privacy: .public)")
+        }
+    }
+
+    // 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) {
+        guard let urlString = request["url"].string, let url = URL(string: urlString) else {
+            callIn("__sbFetchResult", [.number(Double(id)), .object(["error": .string("invalid URL")])])
+            return
+        }
+        var urlRequest = URLRequest(url: url)
+        urlRequest.httpMethod = request["method"].string ?? "GET"
+        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) {
+            urlRequest.httpBody = data
+        }
+        let task = session.dataTask(with: urlRequest) { [weak self] data, response, error in
+            let result: JSONValue
+            if let error {
+                result = .object(["error": .string(error.localizedDescription)])
+            } else {
+                let http = response as? HTTPURLResponse
+                var headers: JSONObject = [:]
+                for (name, value) in http?.allHeaderFields ?? [:] {
+                    headers[String(describing: name).lowercased()] = .string(String(describing: value))
+                }
+                result = .object([
+                    "status": .number(Double(http?.statusCode ?? 200)),
+                    "statusText": .string(http.map { HTTPURLResponse.localizedString(forStatusCode: $0.statusCode) } ?? ""),
+                    "headers": .object(headers),
+                    "url": .string(response?.url?.absoluteString ?? urlString),
+                    "body": .string((data ?? Data()).base64EncodedString()),
+                ])
+            }
+            DispatchQueue.main.async { [weak self] in
+                MainActor.assumeIsolated {
+                    self?.callIn("__sbFetchResult", [.number(Double(id)), result])
+                }
+            }
+        }
+        task.resume()
+    }
+}
+
+extension Array {
+    subscript(safe index: Int) -> Element? { indices.contains(index) ? self[index] : nil }
+}
+#endif

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

@@ -0,0 +1,42 @@
+#if canImport(SwiftUI)
+import Foundation
+import SwiftBrowserProtocol
+
+/// A JavaScript engine as the runtime needs it: evaluate a script, give it
+/// native functions, call its functions. Narrow on purpose, so JavaScriptCore
+/// (the implementation here) can be swapped for Hermes or QuickJS behind it
+/// (docs/native.md, "The JavaScript engine").
+///
+/// Everything is synchronous and on the main thread: a `call` returns after
+/// the JavaScript ran, including any native functions it called in turn.
+@MainActor
+public protocol JSHost: AnyObject {
+    /// Runs a script at top level. `name` labels it in stack traces.
+    func evaluate(_ script: String, name: String) throws
+
+    /// Installs a native function under `name` on the `__sbNative` object
+    /// JavaScript sees. Arguments arrive as JSON values; the result, when not
+    /// nil, goes back as one.
+    func install(_ name: String, _ body: @escaping ([JSONValue]) -> JSONValue?)
+
+    /// Calls a global function with the arguments and returns what it returned.
+    @discardableResult
+    func call(_ function: String, _ arguments: [JSONValue]) throws -> JSONValue
+
+    /// Whether a global of this name is defined.
+    func hasGlobal(_ name: String) -> Bool
+
+    /// Throws the loaded scripts away: a fresh global object for the next `evaluate`.
+    func reset()
+}
+
+public struct JSError: Error, CustomStringConvertible {
+    public let message: String
+    public let stack: String?
+    public init(message: String, stack: String? = nil) {
+        self.message = message
+        self.stack = stack
+    }
+    public var description: String { stack.map { "\(message)\n\($0)" } ?? message }
+}
+#endif

package/swift/Sources/SwiftBrowserNative/Host/JavaScriptCoreHost.swift

@@ -0,0 +1,102 @@
+#if canImport(SwiftUI) && canImport(JavaScriptCore)
+import Foundation
+import JavaScriptCore
+import SwiftBrowserProtocol
+
+/// `JSHost` over JavaScriptCore's `JSContext`. It ships in the OS, costs no
+/// binary size, and its API is synchronous from Swift with no C++ between:
+/// a block installed with `install` runs on the thread that called into
+/// JavaScript, and `call` returns when the JavaScript did.
+///
+/// Promise jobs (microtasks) run when the outermost call into the context
+/// returns, so a `setState` inside a `then` reaches its render pass before
+/// the native side continues.
+@MainActor
+public final class JavaScriptCoreHost: JSHost {
+    public private(set) var context: JSContext
+    private var native: JSValue
+    /// The last uncaught exception, taken by the `call` or `evaluate` it interrupted.
+    private var pendingError: JSError?
+    /// Called for every uncaught exception, before the call that caused it throws.
+    public var onError: ((JSError) -> Void)?
+
+    public init() {
+        (context, native) = JavaScriptCoreHost.makeContext()
+        installExceptionHandler()
+    }
+
+    private static func makeContext() -> (JSContext, JSValue) {
+        let context = JSContext()!
+        context.name = "SwiftBrowser"
+        let native = JSValue(newObjectIn: context)!
+        context.setObject(native, forKeyedSubscript: "__sbNative" as NSString)
+        return (context, native)
+    }
+
+    private func installExceptionHandler() {
+        context.exceptionHandler = { [weak self] _, exception in
+            guard let self else { return }
+            let message = exception?.toString() ?? "unknown error"
+            let stack = exception?.objectForKeyedSubscript("stack")?.toString()
+            let error = JSError(message: message, stack: stack == "undefined" ? nil : stack)
+            self.pendingError = error
+            self.onError?(error)
+        }
+    }
+
+    public func reset() {
+        context.exceptionHandler = nil
+        (context, native) = JavaScriptCoreHost.makeContext()
+        pendingError = nil
+        installExceptionHandler()
+    }
+
+    public func evaluate(_ script: String, name: String) throws {
+        pendingError = nil
+        context.evaluateScript(script, withSourceURL: URL(string: "sb://\(name)"))
+        if let error = pendingError {
+            pendingError = nil
+            throw error
+        }
+    }
+
+    public func install(_ name: String, _ body: @escaping ([JSONValue]) -> JSONValue?) {
+        // A block with no declared parameters reads its arguments through the
+        // context, so one shape serves every native function.
+        let block: @convention(block) () -> Any? = {
+            let arguments = (JSContext.currentArguments() as? [JSValue]) ?? []
+            return body(arguments.map(JavaScriptCoreHost.json(from:)))?.anyObject
+        }
+        native.setObject(unsafeBitCast(block, to: AnyObject.self), forKeyedSubscript: name as NSString)
+    }
+
+    @discardableResult
+    public func call(_ function: String, _ arguments: [JSONValue]) throws -> JSONValue {
+        guard let callee = context.objectForKeyedSubscript(function), !callee.isUndefined else {
+            throw JSError(message: "\(function) is not defined")
+        }
+        pendingError = nil
+        let result = callee.call(withArguments: arguments.map(\.anyObject))
+        if let error = pendingError {
+            pendingError = nil
+            throw error
+        }
+        return result.map(JavaScriptCoreHost.json(from:)) ?? .null
+    }
+
+    public func hasGlobal(_ name: String) -> Bool {
+        guard let value = context.objectForKeyedSubscript(name) else { return false }
+        return !value.isUndefined
+    }
+
+    /// A JavaScript value as JSON. Strings stay strings without a copy
+    /// through `toObject`, the common case (the ops of a pass, an event).
+    static func json(from value: JSValue) -> JSONValue {
+        if value.isUndefined || value.isNull { return .null }
+        if value.isString { return .string(value.toString()) }
+        if value.isBoolean { return .bool(value.toBool()) }
+        if value.isNumber { return .number(value.toDouble()) }
+        return JSONValue(any: value.toObject())
+    }
+}
+#endif

package/swift/Sources/SwiftBrowserNative/Host/ShimAliases.swift

@@ -0,0 +1,25 @@
+#if canImport(FoundationBridge)
+// Built against the SwiftBrowser shim (the round trip, docs/native.md): the
+// shim and Foundation both declare these names, and the CLI's staging settles
+// them for an app with the same aliases (packages/cli/src/appSources.ts).
+// Geometry is the shim's; what the SDK's Foundation lacks on WASI is the bridge's.
+// Public, as `NativeApp.load(resource:extension:bundle:)` takes a `Bundle`.
+import Foundation
+public import FoundationBridge
+public import SwiftUI
+
+public typealias CGFloat = SwiftUI.CGFloat
+public typealias CGPoint = SwiftUI.CGPoint
+public typealias CGSize = SwiftUI.CGSize
+public typealias CGRect = SwiftUI.CGRect
+public typealias Timer = FoundationBridge.Timer
+public typealias RunLoop = FoundationBridge.RunLoop
+public typealias UserDefaults = FoundationBridge.UserDefaults
+public typealias Bundle = FoundationBridge.Bundle
+public typealias URLSession = FoundationBridge.URLSession
+public typealias URLSessionConfiguration = FoundationBridge.URLSessionConfiguration
+public typealias URLRequest = FoundationBridge.URLRequest
+public typealias URLResponse = FoundationBridge.URLResponse
+public typealias HTTPURLResponse = FoundationBridge.HTTPURLResponse
+public typealias DispatchQueue = FoundationBridge.DispatchQueue
+#endif

package/swift/Sources/SwiftBrowserNative/Host/WebHost.swift

@@ -0,0 +1,138 @@
+#if canImport(SwiftUI) && arch(wasm32)
+import Foundation
+import SwiftBrowserProtocol
+
+// The host's JavaScript as the engine (docs/native.md, "The round trip"):
+// one WebAssembly import, `sb_native.request`, carries every request to the
+// page or Node (packages/native/src/wasmHost.ts answers it), and the export
+// `sb_native_invoke` brings the installed native functions' calls back.
+// Strings cross as UTF-8 in linear memory: Swift's own for a request, and
+// for an answer a buffer the host took from `sb_alloc` holding a 4-byte
+// little-endian length and then the bytes, which Swift frees.
+
+@_extern(wasm, module: "sb_native", name: "request")
+@_extern(c)
+private func sb_native_request(
+    _ kind: UnsafePointer<UInt8>, _ kindLength: Int32,
+    _ a: UnsafePointer<UInt8>, _ aLength: Int32,
+    _ b: UnsafePointer<UInt8>, _ bLength: Int32
+) -> Int32
+
+/// `JSHost` over the JavaScript engine the module runs in: the browser's, or
+/// Node's under scripts/run-wasi.mjs. `evaluate` runs the script at the
+/// host's top level (an indirect `eval`), so the bundle's globals are the
+/// page's; `reset` drops the globals a bundle defines and starts `__sbNative`
+/// over, which is as fresh as one realm gets.
+@MainActor
+public final class WebHost: JSHost {
+    /// The functions `install` registered, called back through `sb_native_invoke`.
+    private var functions: [String: ([JSONValue]) -> JSONValue?] = [:]
+    /// The host that answers `sb_native_invoke`: one engine, one host.
+    nonisolated(unsafe) static var current: WebHost?
+
+    public init() {
+        WebHost.current = self
+        _ = request("reset", "", "")
+    }
+
+    public func evaluate(_ script: String, name: String) throws {
+        if let error = request("eval", script, name)["error"].string {
+            throw JSError(message: error)
+        }
+    }
+
+    public func install(_ name: String, _ body: @escaping ([JSONValue]) -> JSONValue?) {
+        functions[name] = body
+        _ = request("install", name, "")
+    }
+
+    @discardableResult
+    public func call(_ function: String, _ arguments: [JSONValue]) throws -> JSONValue {
+        let answer = request("call", function, JSONValue.array(arguments).json)
+        if let error = answer["error"].string { throw JSError(message: error) }
+        return answer["ok"]
+    }
+
+    public func hasGlobal(_ name: String) -> Bool {
+        request("has", name, "")["ok"].bool ?? false
+    }
+
+    public func reset() {
+        _ = request("reset", "", "")
+    }
+
+    /// Runs an installed function for `sb_native_invoke`.
+    func invoke(_ name: String, _ arguments: [JSONValue]) -> JSONValue? {
+        guard let function = functions[name] else { return .object(["error": .string("\(name) is not installed")]) }
+        return function(arguments)
+    }
+
+    /// The host's answer, `{"ok": value}` or `{"error": message}`, or `.null` for none.
+    private func request(_ kind: String, _ a: String, _ b: String) -> JSONValue {
+        var kind = kind, a = a, b = b
+        let pointer = kind.withUTF8 { kindBytes in
+            a.withUTF8 { aBytes in
+                b.withUTF8 { bBytes in
+                    sb_native_request(
+                        kindBytes.baseAddress ?? UnsafePointer(bitPattern: 1)!, Int32(kindBytes.count),
+                        aBytes.baseAddress ?? UnsafePointer(bitPattern: 1)!, Int32(aBytes.count),
+                        bBytes.baseAddress ?? UnsafePointer(bitPattern: 1)!, Int32(bBytes.count)
+                    )
+                }
+            }
+        }
+        guard let text = WebHost.takeBuffer(pointer) else { return .null }
+        return (try? JSONValue.parse(text)) ?? .object(["error": .string("the host answered with malformed JSON: \(text)")])
+    }
+
+    /// Reads and frees a buffer the host allocated with `sb_alloc`: a 4-byte length, then UTF-8.
+    static func takeBuffer(_ pointer: Int32) -> String? {
+        guard pointer != 0, let base = UnsafeMutablePointer<UInt8>(bitPattern: Int(pointer)) else { return nil }
+        let length = Int(UInt32(base[0]) | UInt32(base[1]) << 8 | UInt32(base[2]) << 16 | UInt32(base[3]) << 24)
+        let text = String(decoding: UnsafeBufferPointer(start: base + 4, count: length), as: UTF8.self)
+        base.deallocate()
+        return text
+    }
+
+    /// A buffer in the same layout for the host to read and free with `sb_native_free`.
+    static func makeBuffer(_ text: String) -> Int32 {
+        var text = text
+        return text.withUTF8 { bytes in
+            let base = UnsafeMutablePointer<UInt8>.allocate(capacity: bytes.count + 4)
+            let length = UInt32(bytes.count)
+            base[0] = UInt8(length & 0xff)
+            base[1] = UInt8((length >> 8) & 0xff)
+            base[2] = UInt8((length >> 16) & 0xff)
+            base[3] = UInt8((length >> 24) & 0xff)
+            if let source = bytes.baseAddress { (base + 4).update(from: source, count: bytes.count) }
+            return Int32(Int(bitPattern: base))
+        }
+    }
+}
+
+/// JavaScript calling an installed native function: `name` and the JSON
+/// array of arguments in buffers from `sb_alloc` (freed here). Answers 0
+/// for no result, else a buffer (`WebHost.makeBuffer`) holding the result's JSON.
+@_cdecl("sb_native_invoke")
+public func _sb_native_invoke(_ name: Int32, _ nameLength: Int32, _ arguments: Int32, _ argumentsLength: Int32) -> Int32 {
+    guard let nameBase = UnsafeMutablePointer<UInt8>(bitPattern: Int(name)),
+          let argumentsBase = UnsafeMutablePointer<UInt8>(bitPattern: Int(arguments))
+    else { return 0 }
+    let functionName = String(decoding: UnsafeBufferPointer(start: nameBase, count: Int(nameLength)), as: UTF8.self)
+    let argumentsText = String(decoding: UnsafeBufferPointer(start: argumentsBase, count: Int(argumentsLength)), as: UTF8.self)
+    nameBase.deallocate()
+    argumentsBase.deallocate()
+    return MainActor.assumeIsolated {
+        guard let host = WebHost.current else { return 0 }
+        let parsed = (try? JSONValue.parse(argumentsText))?.array ?? []
+        guard let result = host.invoke(functionName, parsed) else { return 0 }
+        return WebHost.makeBuffer(result.json)
+    }
+}
+
+/// Frees a buffer `sb_native_invoke` answered with.
+@_cdecl("sb_native_free")
+public func _sb_native_free(_ pointer: Int32) {
+    UnsafeMutablePointer<UInt8>(bitPattern: Int(pointer))?.deallocate()
+}
+#endif