@swiftbrowser/native 0.12.0 → 0.14.0

package/src/worker.ts

@@ -0,0 +1,236 @@
+/**
+ * Workers for a JavaScriptCore app: a second context on its own thread, as
+ * a page has Web Workers. The host (Native/Sources/SwiftBrowserNative/Host/WorkerHost.swift)
+ * runs each one in a `JSVirtualMachine` of its own with a run loop, the
+ * runtime's globals (timers, `fetch`, `console`, `TextDecoder`) and the
+ * bundle `swiftbrowser-native build --worker <name>=<entry>` wrote next to
+ * app.js (`<name>.worker.js`). Messages cross as text: JSON, with typed
+ * arrays, `ArrayBuffer`s and `Error`s encoded (`encodeMessage`), since
+ * values cannot be shared between virtual machines. Drawn in a page
+ * (`swiftbrowser-native site`), the same app code gets the page's own
+ * `Worker` over the same bundle, published with the site.
+ *
+ * ```ts
+ * import { createWorker } from '@swiftbrowser/native';
+ * const worker = createWorker('render'); // render.worker.js
+ * worker.onmessage = (event) => console.log(event.data);
+ * worker.postMessage({ draw: 'something' });
+ * ```
+ */
+
+import { nativeBridge, type NativeBridge } from './bridge';
+import { base64Decode, base64Encode } from './encoding';
+
+/** The site's published path for worker bundles (`/native/bundle/App/`), defined by `swiftbrowser-native site`; undefined in an Xcode bundle. */
+declare const __SB_WORKER_BASE__: string | undefined;
+
+/** What `Worker` and a worker's `self` have in common, as an app uses them. */
+export interface WorkerLike {
+  postMessage(data: unknown, transfer?: unknown[]): void;
+  terminate(): void;
+  onmessage: ((event: WorkerMessageEvent) => void) | null;
+  onerror: ((event: WorkerErrorEvent) => void) | null;
+  addEventListener(type: 'message', listener: (event: WorkerMessageEvent) => void): void;
+  addEventListener(type: 'error', listener: (event: WorkerErrorEvent) => void): void;
+  removeEventListener(type: 'message' | 'error', listener: (event: never) => void): void;
+}
+
+export interface WorkerMessageEvent {
+  type: 'message';
+  data: unknown;
+}
+
+export interface WorkerErrorEvent {
+  type: 'error';
+  message: string;
+}
+
+// MARK: Messages
+
+const TYPED_ARRAYS = {
+  Uint8Array,
+  Uint8ClampedArray,
+  Int8Array,
+  Uint16Array,
+  Int16Array,
+  Uint32Array,
+  Int32Array,
+  Float32Array,
+  Float64Array,
+} as const;
+type TypedArrayName = keyof typeof TYPED_ARRAYS;
+
+/**
+ * A message as text: JSON, with a typed array or `ArrayBuffer` as
+ * `{ $sbBytes, $sbType }` (base64) and an `Error` as `{ $sbError }`. What
+ * JSON drops (functions, `undefined` in an object, a `Map`) is dropped here
+ * too; a `Date` arrives as its ISO string.
+ */
+export function encodeMessage(data: unknown): string {
+  return JSON.stringify(data === undefined ? null : data, (_key, value: unknown) => {
+    if (value instanceof ArrayBuffer) return { $sbBytes: base64Encode(new Uint8Array(value)), $sbType: 'ArrayBuffer' };
+    if (ArrayBuffer.isView(value)) {
+      const name = (value.constructor as { name?: string }).name;
+      const bytes = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+      return { $sbBytes: base64Encode(bytes), $sbType: name && name in TYPED_ARRAYS ? name : 'Uint8Array' };
+    }
+    if (value instanceof Error) return { $sbError: { name: value.name, message: value.message, stack: value.stack ?? null } };
+    return value;
+  });
+}
+
+/** The value `encodeMessage` encoded. */
+export function decodeMessage(text: string): unknown {
+  return JSON.parse(text, (_key, value: unknown) => {
+    if (value && typeof value === 'object') {
+      const record = value as Record<string, unknown>;
+      if (typeof record['$sbBytes'] === 'string') {
+        const bytes = base64Decode(record['$sbBytes']);
+        const type = record['$sbType'];
+        if (type === 'ArrayBuffer') return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+        const Constructor = TYPED_ARRAYS[(type as TypedArrayName) in TYPED_ARRAYS ? (type as TypedArrayName) : 'Uint8Array'];
+        // A view over the decoded bytes, aligned for the element size.
+        const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+        return new Constructor(buffer);
+      }
+      if (record['$sbError'] && typeof record['$sbError'] === 'object') {
+        const spec = record['$sbError'] as { name?: string; message?: string; stack?: string | null };
+        const error = new Error(spec.message ?? '');
+        if (spec.name) error.name = spec.name;
+        if (spec.stack) error.stack = spec.stack;
+        return error;
+      }
+    }
+    return value;
+  });
+}
+
+// MARK: The app's side
+
+type Listener<E> = (event: E) => void;
+
+/** `Worker` over the bridge, in the app's context. */
+export class NativeWorker implements WorkerLike {
+  private static nextId = 1;
+  private static readonly live = new Map<number, NativeWorker>();
+  readonly #id: number;
+  readonly #native: NativeBridge;
+  #terminated = false;
+  readonly #messageListeners = new Set<Listener<WorkerMessageEvent>>();
+  readonly #errorListeners = new Set<Listener<WorkerErrorEvent>>();
+  onmessage: Listener<WorkerMessageEvent> | null = null;
+  onerror: Listener<WorkerErrorEvent> | null = null;
+
+  /** `name` is the bundle's: `<name>.worker.js` next to app.js. A URL's last path segment serves as the name (`render.worker.js` → `render`). */
+  constructor(name: string | { href: string } | URL, native: NativeBridge | undefined = nativeBridge()) {
+    if (!native?.workerStart || !native.workerPost || !native.workerTerminate) {
+      throw new Error('Worker: this host has no workers (SwiftBrowser Native 0.13 or later)');
+    }
+    this.#native = native;
+    this.#id = NativeWorker.nextId++;
+    NativeWorker.live.set(this.#id, this);
+    const failure = native.workerStart(this.#id, workerName(name));
+    if (failure) {
+      NativeWorker.live.delete(this.#id);
+      throw new Error(failure);
+    }
+  }
+
+  postMessage(data: unknown): void {
+    if (this.#terminated) return;
+    this.#native.workerPost!(this.#id, encodeMessage(data));
+  }
+
+  terminate(): void {
+    if (this.#terminated) return;
+    this.#terminated = true;
+    NativeWorker.live.delete(this.#id);
+    this.#native.workerTerminate!(this.#id);
+  }
+
+  addEventListener(type: 'message', listener: Listener<WorkerMessageEvent>): void;
+  addEventListener(type: 'error', listener: Listener<WorkerErrorEvent>): void;
+  addEventListener(type: 'message' | 'error', listener: Listener<never>): void {
+    if (type === 'message') this.#messageListeners.add(listener as Listener<WorkerMessageEvent>);
+    else this.#errorListeners.add(listener as Listener<WorkerErrorEvent>);
+  }
+
+  removeEventListener(type: 'message' | 'error', listener: Listener<never>): void {
+    if (type === 'message') this.#messageListeners.delete(listener as Listener<WorkerMessageEvent>);
+    else this.#errorListeners.delete(listener as Listener<WorkerErrorEvent>);
+  }
+
+  /** The bridge's `__sbWorkerMessage(id, text)`. */
+  static receive(id: number, text: string): void {
+    const worker = NativeWorker.live.get(id);
+    if (!worker) return;
+    const event: WorkerMessageEvent = { type: 'message', data: decodeMessage(text) };
+    worker.onmessage?.(event);
+    for (const listener of worker.#messageListeners) listener(event);
+  }
+
+  /** The bridge's `__sbWorkerError(id, message)`: an uncaught exception in the worker. */
+  static fail(id: number, message: string): void {
+    const worker = NativeWorker.live.get(id);
+    if (!worker) return;
+    const event: WorkerErrorEvent = { type: 'error', message };
+    worker.onerror?.(event);
+    for (const listener of worker.#errorListeners) listener(event);
+  }
+}
+
+/** The bundle name a worker was asked for: `render`, or the `render` of `.../render.worker.js`. */
+export function workerName(name: string | { href: string } | URL): string {
+  const text = typeof name === 'string' ? name : name.href;
+  const last = text.split('/').pop() ?? text;
+  return last.replace(/\.(m?[jt]sx?)$/, '').replace(/\.worker$/, '');
+}
+
+/**
+ * A worker from the bundle `<name>.worker.js`: the page's own `Worker` when
+ * the app is drawn in a page (the bundle published with the site), else the
+ * host's over the bridge.
+ */
+export function createWorker(name: string): WorkerLike {
+  const base = typeof __SB_WORKER_BASE__ === 'string' ? __SB_WORKER_BASE__ : undefined;
+  const PageWorker = (globalThis as { Worker?: new (url: string) => WorkerLike }).Worker;
+  if (typeof PageWorker === 'function' && base !== undefined) return new PageWorker(`${base}${workerName(name)}.worker.js`);
+  if (nativeBridge()?.workerStart) return new NativeWorker(name);
+  if (typeof PageWorker === 'function') return new PageWorker(`${workerName(name)}.worker.js`);
+  throw new Error(`createWorker: no host for "${name}" (not in a SwiftBrowser Native app or a page)`);
+}
+
+// MARK: The worker's side
+
+/**
+ * A worker's own globals over its bridge: `self`, `postMessage`, `onmessage`
+ * and `onerror` as properties the script assigns, `addEventListener`,
+ * `close`, and `__sbWorkerReceive`, which the host calls with each message.
+ */
+export function installWorkerScope(native: NativeBridge, target: Record<string, unknown>): string[] {
+  const installed: string[] = [];
+  const define = (name: string, value: unknown): void => {
+    Object.defineProperty(target, name, { value, writable: true, configurable: true, enumerable: false });
+    installed.push(name);
+  };
+  const messageListeners = new Set<Listener<WorkerMessageEvent>>();
+  const errorListeners = new Set<Listener<WorkerErrorEvent>>();
+  define('self', target);
+  define('postMessage', (data: unknown) => native.workerPostMessage!(encodeMessage(data)));
+  define('addEventListener', (type: string, listener: Listener<never>) => {
+    if (type === 'message') messageListeners.add(listener as Listener<WorkerMessageEvent>);
+    else if (type === 'error') errorListeners.add(listener as Listener<WorkerErrorEvent>);
+  });
+  define('removeEventListener', (type: string, listener: Listener<never>) => {
+    if (type === 'message') messageListeners.delete(listener as Listener<WorkerMessageEvent>);
+    else if (type === 'error') errorListeners.delete(listener as Listener<WorkerErrorEvent>);
+  });
+  define('close', () => native.log('warn', 'close(): a worker ends when the app terminates it'));
+  define('__sbWorkerReceive', (text: string) => {
+    const event: WorkerMessageEvent = { type: 'message', data: decodeMessage(text) };
+    const handler = target['onmessage'];
+    if (typeof handler === 'function') (handler as Listener<WorkerMessageEvent>)(event);
+    for (const listener of messageListeners) listener(event);
+  });
+  return installed;
+}

package/swift/Package.swift

@@ -27,5 +27,6 @@ let package = Package(
         .target(name: "SwiftBrowserProtocol"),
         .target(name: "SwiftBrowserTree", dependencies: ["SwiftBrowserProtocol"]),
         .target(name: "SwiftBrowserNative", dependencies: ["SwiftBrowserProtocol", "SwiftBrowserTree"]),
+        // Apple platforms only (JavaScriptCore): the workers; empty elsewhere.
     ]
 )

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

@@ -27,14 +27,18 @@ import FoundationBridge // the shim's Foundation stand-ins (ShimAliases.swift)
 /// | `openURL(url)` | the system opener |
 /// | `locale()` | the viewer's locale identifier |
 /// | `launchArguments()` | the process's arguments (`-screen list` from a scheme or `simctl launch`) |
+/// | `workerStart(id, name)`, `workerPost(id, text)`, `workerTerminate(id)` | workers (WorkerHost.swift, JavaScriptCore only); their messages come to `__sbWorkerMessage(id, text)`, their errors to `__sbWorkerError(id, message)` |
 ///
 /// Everything JavaScript-facing runs on the main thread; work that is not
-/// (a fetch) hops back before calling in.
+/// (a fetch, a worker) hops back before calling in.
 @MainActor
 final class HostBridge {
     private let host: JSHost
     private let tree: OpTree
     private var timers: [Int: Timer] = [:]
+    #if canImport(JavaScriptCore)
+    private var workers: [Int: WorkerHost] = [:]
+    #endif
     private let logger = Logger(subsystem: "swiftbrowser", category: "js")
     private let session = URLSession(configuration: .default)
     /// Keys of `localStorage` live under this prefix in `UserDefaults`.
@@ -46,10 +50,14 @@ final class HostBridge {
         installAll()
     }
 
-    /// Stops every timer; the app that owned the bridge is going away.
+    /// Stops every timer and worker; the app that owned the bridge is going away.
     func invalidate() {
         for timer in timers.values { timer.invalidate() }
         timers.removeAll()
+        #if canImport(JavaScriptCore)
+        for worker in workers.values { worker.terminate() }
+        workers.removeAll()
+        #endif
     }
 
     private func installAll() {
@@ -166,6 +174,42 @@ final class HostBridge {
         host.install("locale") { _ in .string(Locale.current.identifier) }
 
         host.install("launchArguments") { _ in .array(ProcessInfo.processInfo.arguments.map(JSONValue.string)) }
+
+        #if canImport(JavaScriptCore)
+        host.install("workerStart") { [weak self] arguments in
+            guard let self, let id = arguments[safe: 0]?.int, let name = arguments[safe: 1]?.string else {
+                return .string("workerStart: expected an id and a name")
+            }
+            do {
+                let worker = try WorkerHost(name: name, onMessage: { [weak self] text in
+                    DispatchQueue.main.async {
+                        MainActor.assumeIsolated { self?.callIn("__sbWorkerMessage", [.number(Double(id)), .string(text)]) }
+                    }
+                }, onError: { [weak self] message in
+                    DispatchQueue.main.async {
+                        MainActor.assumeIsolated { self?.callIn("__sbWorkerError", [.number(Double(id)), .string(message)]) }
+                    }
+                })
+                self.workers[id]?.terminate()
+                self.workers[id] = worker
+                worker.start()
+                return nil
+            } catch {
+                return .string("\(error)")
+            }
+        }
+        host.install("workerPost") { [weak self] arguments in
+            guard let self, let id = arguments[safe: 0]?.int, let text = arguments[safe: 1]?.string else { return nil }
+            self.workers[id]?.post(text)
+            return nil
+        }
+        host.install("workerTerminate") { [weak self] arguments in
+            guard let self, let id = arguments[safe: 0]?.int else { return nil }
+            self.workers[id]?.terminate()
+            self.workers[id] = nil
+            return nil
+        }
+        #endif
     }
 
     /// Calls into JavaScript from a timer or a completion, where a throw has nowhere to go but the log.

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

@@ -91,7 +91,8 @@ public final class JavaScriptCoreHost: JSHost {
 
     /// 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 {
+    /// Any thread's: a worker's context (WorkerHost.swift) uses it too.
+    nonisolated 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()) }

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

@@ -0,0 +1,279 @@
+#if canImport(SwiftUI) && canImport(JavaScriptCore)
+import Foundation
+import JavaScriptCore
+import os
+import SwiftBrowserProtocol
+
+/// A worker of a JavaScriptCore app (packages/native/src/worker.ts): a
+/// second `JSContext` in a `JSVirtualMachine` of its own, on a thread of
+/// its own, so it runs beside the app's context rather than in its turns.
+/// The thread runs a run loop: the worker's timers and `fetch` answers come
+/// through it, and so does the engine's own deferred work (an async
+/// `WebAssembly.instantiate` settles its promise from it, which is what an
+/// emscripten module's glue awaits).
+///
+/// The worker's `__sbNative` has the primitives the runtime builds its
+/// globals from, minus the tree (`applyOps`), plus `workerPostMessage(text)`.
+/// Messages are text both ways (the runtime encodes typed arrays into it):
+/// values cannot cross virtual machines. The app's side (HostBridge.swift)
+/// delivers the worker's messages and errors on the main thread.
+final class WorkerHost: @unchecked Sendable {
+    let name: String
+    private let script: String
+    private let thread: WorkerThread
+    private let onMessage: @Sendable (String) -> Void
+    private let onError: @Sendable (String) -> Void
+    private let logger = Logger(subsystem: "swiftbrowser", category: "worker")
+    private let session = URLSession(configuration: .default)
+    // Touched on the worker's thread only.
+    private var context: JSContext?
+    private var timers: [Int: Timer] = [:]
+
+    /// The script is `<name>.worker.js` in `bundle` (what `swiftbrowser-native
+    /// build --worker <name>=<entry>` writes beside app.js); throws when it is not there.
+    init(name: String, bundle: Bundle = .main, onMessage: @escaping @Sendable (String) -> Void, onError: @escaping @Sendable (String) -> Void) throws {
+        guard let url = bundle.url(forResource: "\(name).worker", withExtension: "js") else {
+            throw JSError(message: "\(name).worker.js is not in the app bundle (build it with `swiftbrowser-native build --worker \(name)=<entry>`)")
+        }
+        self.name = name
+        script = try String(contentsOf: url, encoding: .utf8)
+        self.onMessage = onMessage
+        self.onError = onError
+        thread = WorkerThread(label: "swiftbrowser.worker.\(name)")
+    }
+
+    /// Starts the thread: it creates the context, runs the script, then its
+    /// run loop. Messages posted before the script ran wait for it.
+    func start() {
+        thread.start { [self] in setUp() }
+    }
+
+    /// Delivers an encoded message to the worker's `__sbWorkerReceive`.
+    func post(_ text: String) {
+        thread.perform { [self] in call("__sbWorkerReceive", [.string(text)]) }
+    }
+
+    /// Ends the worker: its timers, context and thread go.
+    func terminate() {
+        thread.perform { [self] in tearDown() }
+        thread.stop()
+    }
+
+    // MARK: On the worker's thread
+
+    private func setUp() {
+        let context = JSContext(virtualMachine: JSVirtualMachine())!
+        context.name = "SwiftBrowser worker \(name)"
+        context.exceptionHandler = { [weak self] _, exception in
+            guard let self else { return }
+            let message = exception?.toString() ?? "unknown error"
+            let stack = exception?.objectForKeyedSubscript("stack")?.toString()
+            let text = stack.flatMap { $0 == "undefined" ? nil : "\(message)\n\($0)" } ?? message
+            self.logger.error("\(self.name): \(text, privacy: .public)")
+            self.onError(text)
+        }
+        self.context = context
+        let native = JSValue(newObjectIn: context)!
+        context.setObject(native, forKeyedSubscript: "__sbNative" as NSString)
+        installPrimitives(on: native)
+        context.evaluateScript(script, withSourceURL: URL(string: "sb://\(name).worker.js"))
+    }
+
+    private func tearDown() {
+        for timer in timers.values { timer.invalidate() }
+        timers.removeAll()
+        context?.exceptionHandler = nil
+        context = nil
+    }
+
+    private func install(_ native: JSValue, _ name: String, _ body: @escaping ([JSONValue]) -> JSONValue?) {
+        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)
+    }
+
+    /// Calls a global function of the worker's; an exception reaches `onError` through the handler.
+    @discardableResult
+    private func call(_ function: String, _ arguments: [JSONValue]) -> JSONValue? {
+        guard let context, let callee = context.objectForKeyedSubscript(function), !callee.isUndefined else { return nil }
+        return callee.call(withArguments: arguments.map(\.anyObject)).map(JavaScriptCoreHost.json(from:))
+    }
+
+    private func installPrimitives(on native: JSValue) {
+        install(native, "workerPostMessage") { [onMessage] arguments in
+            if let text = arguments.first?.string { onMessage(text) }
+            return nil
+        }
+
+        install(native, "log") { [logger, name] 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("\(name): \(message, privacy: .public)")
+            case "warn": logger.warning("\(name): \(message, privacy: .public)")
+            case "debug": logger.debug("\(name): \(message, privacy: .public)")
+            default: logger.info("\(name): \(message, privacy: .public)")
+            }
+            #if DEBUG
+            print("[\(name):\(level)] \(message)")
+            #endif
+            return nil
+        }
+
+        install(native, "now") { _ in .number(ProcessInfo.processInfo.systemUptime * 1000) }
+
+        install(native, "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()
+            // On this thread's run loop, so it fires on this thread.
+            let timer = Timer(timeInterval: delay, repeats: repeats) { [weak self] _ in
+                guard let self else { return }
+                if !repeats { self.timers[id] = nil }
+                self.call("__sbTimerFired", [.number(Double(id))])
+            }
+            RunLoop.current.add(timer, forMode: .default)
+            self.timers[id] = timer
+            return nil
+        }
+
+        install(native, "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
+        }
+
+        install(native, "fetch") { [weak self] arguments in
+            guard let self, let id = arguments[safe: 0]?.int else { return nil }
+            self.fetch(id: id, request: arguments[safe: 1] ?? .null)
+            return nil
+        }
+
+        // No storage of its own: a worker keeps state in its scope.
+        install(native, "storageGet") { _ in .null }
+        install(native, "storageSet") { _ in nil }
+        install(native, "storageRemove") { _ in nil }
+        install(native, "storageKeys") { _ in .array([]) }
+        install(native, "storageClear") { _ in nil }
+
+        install(native, "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())
+        }
+
+        install(native, "openURL") { _ in .bool(false) }
+        install(native, "locale") { _ in .string(Locale.current.identifier) }
+        install(native, "launchArguments") { _ in .array(ProcessInfo.processInfo.arguments.map(JSONValue.string)) }
+    }
+
+    /// As HostBridge's, answering on the worker's thread.
+    private func fetch(id: Int, request: JSONValue) {
+        guard let urlString = request["url"].string, let url = URL(string: urlString) else {
+            call("__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()),
+                ])
+            }
+            guard let self else { return }
+            self.thread.perform { [self] in self.call("__sbFetchResult", [.number(Double(id)), result]) }
+        }
+        task.resume()
+    }
+}
+
+/// A thread with a run loop that runs blocks sent to it, in order, after
+/// the block it started with.
+final class WorkerThread: @unchecked Sendable {
+    private let label: String
+    private let lock = NSLock()
+    private var runLoop: CFRunLoop?
+    private var pending: [@Sendable () -> Void] = []
+    private var stopped = false
+
+    init(label: String) {
+        self.label = label
+    }
+
+    func start(_ setUp: @escaping @Sendable () -> Void) {
+        let thread = Thread { [self] in
+            let loop = RunLoop.current
+            // A port keeps the loop running while nothing else is scheduled.
+            loop.add(Port(), forMode: .default)
+            setUp()
+            lock.lock()
+            runLoop = CFRunLoopGetCurrent()
+            let queued = pending
+            pending = []
+            lock.unlock()
+            for block in queued { block() }
+            while !isStopped {
+                loop.run(mode: .default, before: .distantFuture)
+            }
+        }
+        thread.name = label
+        thread.qualityOfService = .userInitiated
+        thread.start()
+    }
+
+    /// Runs `block` on the thread: at once if it is idle, else after what it is doing.
+    func perform(_ block: @escaping @Sendable () -> Void) {
+        lock.lock()
+        guard let runLoop else {
+            pending.append(block)
+            lock.unlock()
+            return
+        }
+        lock.unlock()
+        CFRunLoopPerformBlock(runLoop, CFRunLoopMode.defaultMode.rawValue, block)
+        CFRunLoopWakeUp(runLoop)
+    }
+
+    private var isStopped: Bool {
+        lock.lock()
+        defer { lock.unlock() }
+        return stopped
+    }
+
+    /// Ends the loop after the blocks already sent ran.
+    func stop() {
+        lock.lock()
+        stopped = true
+        let loop = runLoop
+        lock.unlock()
+        if let loop {
+            CFRunLoopPerformBlock(loop, CFRunLoopMode.defaultMode.rawValue) { CFRunLoopStop(loop) }
+            CFRunLoopWakeUp(loop)
+        }
+    }
+}
+#endif

package/swift/Sources/SwiftBrowserNative/Runtime/NativeApp.swift

@@ -37,6 +37,9 @@ public final class NativeApp {
     public private(set) var colorScheme: String?
     public private(set) var dynamicTypeSize: String?
     public private(set) var horizontalSizeClass: String?
+    /// URLs the app was opened with before its script could take them (a
+    /// universal link that launched it): delivered once it loads.
+    private var pendingURLs: [URL] = []
 
     #if canImport(JavaScriptCore)
     public convenience init() {
@@ -72,11 +75,34 @@ public final class NativeApp {
             isLoaded = host.hasGlobal("__sbDispatch")
             if !isLoaded { error = "\(name) did not call run(): no __sbDispatch" }
             sendEnvironment()
+            deliverPendingURLs()
         } catch {
             self.error = "\(error)"
         }
     }
 
+    /// Hands the app a URL it was opened with (a universal link, a custom
+    /// scheme: SwiftUI's `onOpenURL`). JavaScript's `onOpenURL` listeners
+    /// (`@swiftbrowser/native`) get it; before the bundle loads, it waits.
+    public func open(url: URL) {
+        guard isLoaded, host.hasGlobal("__sbOpenURL") else {
+            pendingURLs.append(url)
+            return
+        }
+        do {
+            try host.call("__sbOpenURL", [.string(url.absoluteString)])
+        } catch {
+            self.error = "\(error)"
+        }
+    }
+
+    private func deliverPendingURLs() {
+        guard isLoaded, !pendingURLs.isEmpty else { return }
+        let urls = pendingURLs
+        pendingURLs = []
+        for url in urls { open(url: url) }
+    }
+
     /// Starts over for a reload: a fresh engine (the old one's globals and
     /// timers go with it) and an empty tree, which the views are observing.
     private func reset() {
@@ -188,6 +214,7 @@ public final class NativeApp {
             isLoaded = host.hasGlobal("__sbDispatch")
             if !isLoaded { error = "the scripts did not call run(): no __sbDispatch" }
             sendEnvironment()
+            deliverPendingURLs()
         } catch {
             self.error = "\(error)"
         }

package/wasm/SwiftBrowserNative.wasm

@@ -1,4 +1,4 @@
 [diffend] Oversized file quarantined before diffing.
 name: package/wasm/SwiftBrowserNative.wasm
-size: 49299172 bytes
-sha256: 4b0ae4bc428d21234784a4c806f021482aa294045f94c5fc80eeea0ad40b5405
+size: 49301069 bytes
+sha256: 644cdf56fe487eb95d2c2c0e40782626f6fb70259a3ea40a6b9e11d2c23c401a