@tokamakdev/platform-ios-simulator-x64 0.1.1-beta.82 → 0.1.1-beta.84

package/ios-simulator-x64/build/entrypoint

@@ -172,14 +172,14 @@ fi
 # sources are Swift.
 swift_type='^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$'
 registry=$temporary/TokamakPluginRegistry.swift
-printf '%s\n\n%s\n%s\n' 'import Foundation' 'func tokamakPlugins(host: TokamakHost) -> [any TokamakPlugin] {' '  [' > "$registry"
+printf '%s\n\n%s\n%s\n' 'import Foundation' 'func tokamakPlugins(app: TokamakApp) -> [any TokamakPlugin] {' '  [' > "$registry"
 for plugin in "$input/plugins"/*/; do
   class=$(cat "$plugin/class" 2>/dev/null || true)
   if [[ ! "$class" =~ $swift_type ]]; then
     echo "plugin '$(basename "$plugin")' has invalid $platform class '$class'" >&2
     exit 1
   fi
-  printf '    %s(host: host),\n' "$class" >> "$registry"
+  printf '    %s(host: TokamakHost(app: app, plugin: "%s")),\n' "$class" "$(basename "$plugin")" >> "$registry"
   for source in "$plugin/sources"/*; do
     case "$source" in
       *.swift) swift_sources+=("$source") ;;

package/ios-simulator-x64/frameworks/TokamakRuntime.framework/Headers/TokamakRuntime.h

@@ -21,21 +21,36 @@ typedef struct {
   TokamakBytes private_key;
 } TokamakIdentity;
 
+typedef void (*TokamakPluginRequest)(void *context, uint64_t id,
+                                     const char *plugin, const char *method,
+                                     const char *arguments);
+
+typedef struct {
+  void *context;
+  TokamakPluginRequest call;
+  TokamakPluginRequest subscribe;
+  void (*unsubscribe)(void *context, uint64_t id);
+} TokamakPluginHandler;
+
 void *tokamak_runtime_start(const char *packaged_dir, const char *state_dir,
                             const char *storage_dir, const char *host,
+                            bool foreground, TokamakPluginHandler plugins,
                             char *error, size_t error_len);
 void *tokamak_runtime_start_development(const char *state_dir, const char *host,
                                      const char *endpoint,
-                                     const char *session_token, char *error,
-                                     size_t error_len);
+                                     const char *session_token,
+                                     bool foreground,
+                                     TokamakPluginHandler plugins,
+                                     char *error, size_t error_len);
 uint16_t tokamak_runtime_port(const void *runtime);
 uint16_t tokamak_runtime_restore_gateway(const void *runtime, char *error,
                                       size_t error_len);
 void tokamak_runtime_stop(void *runtime);
-bool tokamak_runtime_call(const void *runtime, const char *name,
-                          const char *body, uint64_t timeout_ms,
-                          TokamakBytes *response, char *error,
-                          size_t error_len);
+bool tokamak_runtime_emit(const void *runtime, const char *name,
+                          const char *event, uint64_t timeout_ms,
+                          TokamakBytes *reply, char *error, size_t error_len);
+bool tokamak_runtime_set_foreground(const void *runtime, bool foreground);
+void tokamak_runtime_reply(const void *runtime, uint64_t id, const char *result);
 
 int32_t tokamak_runtime_server_authority(const void *runtime, const char *host,
                                       TokamakBytes *authority);

package/ios-simulator-x64/native-shell/{TokamakHost.swift → TokamakApp.swift}

@@ -1,26 +1,99 @@
 import Foundation
 import TokamakRuntime
+import os
+
+#if os(iOS)
+  import UIKit
+#endif
 
 private let startupErrorFile = "startup-error.log"
+/// How long the Worker has for `resume` and `suspend`.
+private let lifecycleDeadline: TimeInterval = 10
+#if os(iOS)
+  /// The system gives an app about 30 seconds after it leaves the foreground.
+  private let suspendDeadline: TimeInterval = 25
+#endif
 
 /// The tokamak runtime and native plugins of this process. Both outlive any
 /// WebView, so plugins receive app events before a page loads and a Worker
 /// event can run while no page is loaded.
-final class TokamakHost {
-  private(set) var plugins: [any TokamakPlugin] = []
+final class TokamakApp {
+  /// Every plugin, by ID.
+  private(set) var plugins: [String: any TokamakPlugin] = [:]
   private var runtime: Result<RuntimeHandle, Error>?
   private var waiting: [(Result<RuntimeHandle, Error>) -> Void] = []
+  /// The Worker's calls and subscriptions on the plugins.
+  private lazy var workerRequests = TokamakPluginRequests<UInt64>(plugins: plugins) {
+    [unowned self] id, result in
+    whenStarted { started in
+      if case .success(let runtime) = started {
+        runtime.reply(id, result: result)
+      }
+    }
+  }
+  /// Delivers `resume` and `suspend` one at a time, in order.
+  private let lifecycle = DispatchQueue(label: "tokamak.lifecycle")
+  #if os(iOS)
+    /// The scenes in the foreground, which plugins read on any thread.
+    private let foregroundScenes = OSAllocatedUnfairLock(initialState: 0)
+  #endif
 
-  /// Creates the plugins and starts the runtime in the background. Call it
-  /// before launch finishes.
+  /// Creates the plugins. Call it before launch finishes.
   init() {
-    plugins = tokamakPlugins(host: self)
+    for plugin in tokamakPlugins(app: self) {
+      precondition(plugins.updateValue(plugin, forKey: plugin.id) == nil, "Duplicate plugin ID")
+    }
+  }
+
+  /// Starts the runtime in the background, which delivers `start` with
+  /// `foreground`. Call it once, on the main thread.
+  func start(foreground: Bool) {
+    dispatchPrecondition(condition: .onQueue(.main))
+    let plugins = workerPlugins
     DispatchQueue.global(qos: .userInitiated).async {
-      let result = Result { try RuntimeHandle() }
+      let result = Result { try RuntimeHandle(foreground: foreground, plugins: plugins) }
       DispatchQueue.main.async { self.started(result) }
     }
   }
 
+  /// The plugins as the runtime calls them, on its own threads. The app
+  /// outlives the runtime, which holds it unretained.
+  private var workerPlugins: TokamakPluginHandler {
+    TokamakPluginHandler(
+      context: Unmanaged.passUnretained(self).toOpaque(),
+      call: { context, id, plugin, method, arguments in
+        TokamakApp.receive(context, id, subscribe: false, plugin, method, arguments)
+      },
+      subscribe: { context, id, plugin, method, arguments in
+        TokamakApp.receive(context, id, subscribe: true, plugin, method, arguments)
+      },
+      unsubscribe: { context, id in
+        let app = Unmanaged<TokamakApp>.fromOpaque(context!).takeUnretainedValue()
+        DispatchQueue.main.async { app.workerRequests.cancel(id) }
+      }
+    )
+  }
+
+  /// Runs a call or subscription the Worker made through `context`'s app.
+  private static func receive(
+    _ context: UnsafeMutableRawPointer?,
+    _ id: UInt64,
+    subscribe: Bool,
+    _ plugin: UnsafePointer<CChar>?,
+    _ method: UnsafePointer<CChar>?,
+    _ arguments: UnsafePointer<CChar>?
+  ) {
+    let app = Unmanaged<TokamakApp>.fromOpaque(context!).takeUnretainedValue()
+    let (plugin, method) = (String(cString: plugin!), String(cString: method!))
+    let arguments =
+      (try? JSONSerialization.jsonObject(
+        with: Data(String(cString: arguments!).utf8), options: .fragmentsAllowed)) ?? NSNull()
+    DispatchQueue.main.async {
+      app.workerRequests.run(
+        id, subscribe: subscribe, plugin: plugin, method: method, arguments: arguments)
+    }
+  }
+
   /// Calls `completion` on the main thread once the runtime has started or
   /// failed to start.
   func whenStarted(_ completion: @escaping (Result<RuntimeHandle, Error>) -> Void) {
@@ -32,15 +105,17 @@ final class TokamakHost {
     }
   }
 
-  /// Posts `body`, JSON-serialisable, to the Worker's `/tokamak/<name>`
-  /// endpoint and returns the response body, retrying a failed post. Fails
-  /// unless the Worker responds 200 within `timeout`, which includes runtime
-  /// startup. Call it on the main thread; `completion` runs on the main thread.
-  func call(
+  /// Delivers the event `name` with `event`, JSON-serialisable, to the
+  /// Worker's listeners on `queue`, and calls `completion` on the main thread
+  /// with their reply, parsed from JSON, or nil. Fails unless they return
+  /// within `timeout`, which includes runtime startup. Call it on the main
+  /// thread.
+  func emit(
     _ name: String,
-    body: Any,
+    event: Any,
     timeout: TimeInterval,
-    completion: @escaping (Result<Data, Error>) -> Void
+    on queue: DispatchQueue = .global(qos: .userInitiated),
+    completion: @escaping (Result<Any?, Error>) -> Void
   ) {
     let deadline = Date() + timeout
     whenStarted { result in
@@ -48,9 +123,9 @@ final class TokamakHost {
       case .failure(let error):
         completion(.failure(error))
       case .success(let runtime):
-        DispatchQueue.global(qos: .userInitiated).async {
+        queue.async {
           let outcome = Result {
-            try runtime.call(name, body: body, timeout: deadline.timeIntervalSinceNow)
+            try runtime.emit(name, event: event, timeout: deadline.timeIntervalSinceNow)
           }
           DispatchQueue.main.async { completion(outcome) }
         }
@@ -58,14 +133,80 @@ final class TokamakHost {
     }
   }
 
+  /// Records the app moving into or out of the foreground once the runtime
+  /// has started, and delivers `resume` or `suspend` when that changed its
+  /// stage. Call it on the main thread.
+  func moved(toForeground foreground: Bool) {
+    let name = foreground ? "resume" : "suspend"
+    #if os(iOS)
+      // The system suspends the app soon after it leaves the foreground
+      // unless a background task holds it there.
+      var task = UIBackgroundTaskIdentifier.invalid
+      let finish = {
+        guard task != .invalid else { return }
+        UIApplication.shared.endBackgroundTask(task)
+        task = .invalid
+      }
+      if !foreground {
+        task = UIApplication.shared.beginBackgroundTask(
+          withName: "tokamak suspend", expirationHandler: finish)
+      }
+      let timeout = foreground ? lifecycleDeadline : suspendDeadline
+    #else
+      let finish = {}
+      let timeout = lifecycleDeadline
+    #endif
+    whenStarted { started in
+      guard case .success(let runtime) = started, runtime.setForeground(foreground) else {
+        finish()
+        return
+      }
+      self.emit(name, event: [String: Any](), timeout: timeout, on: self.lifecycle) { result in
+        if case .failure(let error) = result {
+          print("tokamak \(name) failed: \(error)")
+        }
+        finish()
+      }
+    }
+  }
+
+  #if os(iOS)
+    /// Delivers `resume` as the first scene enters the foreground.
+    func sceneWillEnterForeground() {
+      let first = foregroundScenes.withLock { scenes in
+        scenes += 1
+        return scenes == 1
+      }
+      if first {
+        moved(toForeground: true)
+      }
+    }
+
+    /// Delivers `suspend` as the last scene leaves the foreground.
+    func sceneDidEnterBackground() {
+      let last = foregroundScenes.withLock { scenes in
+        scenes -= 1
+        return scenes == 0
+      }
+      if last {
+        moved(toForeground: false)
+      }
+    }
+
+    /// Whether a scene is in the foreground. Read it on any thread.
+    var isInForeground: Bool {
+      foregroundScenes.withLock { $0 > 0 }
+    }
+  #endif
+
   func didRegisterForRemoteNotifications(deviceToken: Data) {
-    for plugin in plugins {
+    for plugin in plugins.values {
       plugin.didRegisterForRemoteNotifications(deviceToken: deviceToken)
     }
   }
 
   func didFailToRegisterForRemoteNotifications(error: Error) {
-    for plugin in plugins {
+    for plugin in plugins.values {
       plugin.didFailToRegisterForRemoteNotifications(error: error)
     }
   }
@@ -78,7 +219,7 @@ final class TokamakHost {
   ) {
     let group = DispatchGroup()
     var results: [TokamakBackgroundResult] = []
-    for plugin in plugins {
+    for plugin in plugins.values {
       group.enter()
       plugin.didReceiveRemoteNotification(userInfo) { result in
         DispatchQueue.main.async {
@@ -147,7 +288,9 @@ final class RuntimeHandle {
   let appHost: String
   private var handle: UnsafeMutableRawPointer?
 
-  init() throws {
+  /// Starts the runtime, which delivers `start` with `foreground`, and whose
+  /// Worker calls `plugins`.
+  init(foreground: Bool, plugins: TokamakPluginHandler) throws {
     guard
       let appHost = Bundle.main.object(forInfoDictionaryKey: "TokamakHost") as? String,
       !appHost.isEmpty
@@ -172,6 +315,8 @@ final class RuntimeHandle {
                   appHost,
                   endpoint,
                   sessionToken,
+                  foreground,
+                  plugins,
                   error.baseAddress,
                   error.count
                 )
@@ -196,6 +341,8 @@ final class RuntimeHandle {
                   statePath,
                   storagePath,
                   appHost,
+                  foreground,
+                  plugins,
                   error.baseAddress,
                   error.count
                 )
@@ -232,38 +379,54 @@ final class RuntimeHandle {
     return port
   }
 
-  /// Posts `body` to the Worker's `/tokamak/<name>` endpoint, retrying a
-  /// failed post, and blocks until it responds 200 or `timeout` passes.
-  func call(_ name: String, body: Any, timeout: TimeInterval) throws -> Data {
-    guard JSONSerialization.isValidJSONObject([body]) else {
-      throw RuntimeError.runtime("the \(name) call body is not JSON")
+  /// Delivers the event `name` with `event`, JSON-serialisable, to the
+  /// Worker's listeners, blocking until they return or `timeout` passes, and
+  /// returns their reply, parsed from JSON, or nil.
+  func emit(_ name: String, event: Any, timeout: TimeInterval) throws -> Any? {
+    guard JSONSerialization.isValidJSONObject([event]) else {
+      throw RuntimeError.runtime("the \(name) event is not JSON")
     }
-    let body = String(
-      decoding: try JSONSerialization.data(withJSONObject: body, options: .fragmentsAllowed),
+    let event = String(
+      decoding: try JSONSerialization.data(withJSONObject: event, options: .fragmentsAllowed),
       as: UTF8.self
     )
-    var response = TokamakBytes()
+    var reply = TokamakBytes()
     var error = [CChar](repeating: 0, count: 1024)
     let succeeded = name.withCString { name in
-      body.withCString { body in
+      event.withCString { event in
         error.withUnsafeMutableBufferPointer { error in
-          tokamak_runtime_call(
+          tokamak_runtime_emit(
             handle,
             name,
-            body,
+            event,
             UInt64(max(timeout, 0) * 1000),
-            &response,
+            &reply,
             error.baseAddress,
             error.count
           )
         }
       }
     }
-    defer { tokamak_bytes_free(response) }
-    guard succeeded else {
+    defer { tokamak_bytes_free(reply) }
+    guard succeeded, let json = reply.contents else {
       throw RuntimeError.runtime(String(cString: error))
     }
-    return response.contents ?? Data()
+    let value = try JSONSerialization.jsonObject(with: json, options: .fragmentsAllowed)
+    return value is NSNull ? nil : value
+  }
+
+  /// Records whether the app is in the foreground, which the Worker's
+  /// `getLifecycleStage()` reports from then on, and returns whether that
+  /// changed.
+  func setForeground(_ foreground: Bool) -> Bool {
+    tokamak_runtime_set_foreground(handle, foreground)
+  }
+
+  /// Passes a plugin's `result`, JSON-serialisable, to the Worker's call or
+  /// subscription `id`.
+  func reply(_ id: UInt64, result: [String: Any]) {
+    guard let json = try? JSONSerialization.data(withJSONObject: result) else { return }
+    String(decoding: json, as: UTF8.self).withCString { tokamak_runtime_reply(handle, id, $0) }
   }
 
   func serverAuthority(host: String) -> AuthenticationMaterial<Data> {

package/ios-simulator-x64/native-shell/TokamakPlugins.swift

@@ -8,11 +8,52 @@ struct TokamakPluginError: Error {
   static func notSupported(_ message: String) -> Self {
     Self(name: "NotSupportedError", message: message)
   }
+
+  /// UI was needed while the app cannot show it.
+  static let needsUI = Self(
+    name: "NeedsUIError",
+    message: "The app cannot show UI while it is in the background"
+  )
 }
 
 typealias TokamakPluginReply = (Result<Any?, TokamakPluginError>) -> Void
 
-/// A native plugin, created once per process when the app launches.
+/// The app as one plugin sees it.
+final class TokamakHost {
+  private unowned let app: TokamakApp
+  private let plugin: String
+
+  init(app: TokamakApp, plugin: String) {
+    self.app = app
+    self.plugin = plugin
+  }
+
+  /// Throws `NeedsUIError` unless the app can show UI now: on iOS, while a
+  /// scene is in the foreground. A hidden or minimised macOS app still shows
+  /// system prompts. Call it where the plugin would show UI, on any thread.
+  func requireUI() throws(TokamakPluginError) {
+    #if os(iOS)
+      guard app.isInForeground else { throw .needsUI }
+    #endif
+  }
+
+  /// Delivers the plugin's event `name`, which the Worker's listeners
+  /// receive as `<plugin>.<name>`, with `event`, JSON-serialisable, and calls
+  /// `completion` on the main thread with their reply, parsed from JSON, or
+  /// nil. Fails unless they return within `timeout`, which includes runtime
+  /// startup. Call it on the main thread.
+  func emit(
+    _ name: String,
+    event: Any,
+    timeout: TimeInterval,
+    completion: @escaping (Result<Any?, Error>) -> Void
+  ) {
+    app.emit("\(plugin).\(name)", event: event, timeout: timeout, completion: completion)
+  }
+}
+
+/// A native plugin, created once per process when the app launches. The page
+/// and the Worker call it on the main thread.
 protocol TokamakPlugin: AnyObject {
   var id: String { get }
 
@@ -24,11 +65,13 @@ protocol TokamakPlugin: AnyObject {
     reply: @escaping TokamakPluginReply
   )
 
+  /// Replies with each value until the returned function is called. Throws
+  /// when the subscription cannot start, which ends it.
   func subscribe(
     method: String,
     arguments: Any,
     reply: @escaping TokamakPluginReply
-  ) -> (() -> Void)
+  ) throws(TokamakPluginError) -> (() -> Void)
 
   func didRegisterForRemoteNotifications(deviceToken: Data)
 
@@ -55,9 +98,8 @@ extension TokamakPlugin {
     method: String,
     arguments: Any,
     reply: @escaping TokamakPluginReply
-  ) -> (() -> Void) {
-    reply(.failure(.notSupported("\(id).\(method) is not supported")))
-    return {}
+  ) throws(TokamakPluginError) -> (() -> Void) {
+    throw .notSupported("\(id).\(method) is not supported")
   }
 
   func didRegisterForRemoteNotifications(deviceToken: Data) {}
@@ -72,6 +114,82 @@ extension TokamakPlugin {
   }
 }
 
+/// Runs one caller's calls and subscriptions, the page's or the Worker's, on
+/// the app's plugins, keyed by `Key`. `send` receives each result on the main
+/// thread, as the JSON object the page's native transport receives without its
+/// session and ID. Use it on the main thread.
+final class TokamakPluginRequests<Key: Hashable> {
+  private let plugins: [String: any TokamakPlugin]
+  private let send: (Key, [String: Any]) -> Void
+  private var cancellations: [Key: () -> Void] = [:]
+
+  init(plugins: [String: any TokamakPlugin], send: @escaping (Key, [String: Any]) -> Void) {
+    self.plugins = plugins
+    self.send = send
+  }
+
+  /// Calls `method` of `plugin`, or subscribes to it when `subscribe`.
+  func run(_ key: Key, subscribe: Bool, plugin: String, method: String, arguments: Any) {
+    guard let target = plugins[plugin], !method.isEmpty else {
+      fail(key, .notSupported("Plugin is not supported"))
+      return
+    }
+    // Plugins reply from any thread.
+    let reply: TokamakPluginReply = { [weak self] result in
+      DispatchQueue.main.async {
+        self?.send(key, Self.result(result, done: !subscribe))
+      }
+    }
+    guard subscribe else {
+      target.call(method: method, arguments: arguments, reply: reply)
+      return
+    }
+    do {
+      cancellations[key] = try target.subscribe(method: method, arguments: arguments, reply: reply)
+    } catch {
+      fail(key, error)
+    }
+  }
+
+  /// Ends the request `key` with `error`.
+  func fail(_ key: Key, _ error: TokamakPluginError) {
+    send(key, Self.result(.failure(error), done: true))
+  }
+
+  /// Ends the subscription `key`.
+  func cancel(_ key: Key) {
+    cancellations.removeValue(forKey: key)?()
+  }
+
+  /// Ends every subscription.
+  func cancelAll() {
+    let cancelAll = Array(cancellations.values)
+    cancellations.removeAll()
+    for cancel in cancelAll {
+      cancel()
+    }
+  }
+
+  /// `result` as JSON, or the failure to make it JSON.
+  private static func result(
+    _ result: Result<Any?, TokamakPluginError>,
+    done: Bool
+  ) -> [String: Any] {
+    switch result {
+    case .success(let value):
+      let json: [String: Any] = ["value": value ?? NSNull(), "done": done]
+      if JSONSerialization.isValidJSONObject(json) {
+        return json
+      }
+      let error = TokamakPluginError(
+        name: "OperationError", message: "The plugin's value is not JSON")
+      return Self.result(.failure(error), done: done)
+    case .failure(let error):
+      return ["error": ["name": error.name, "message": error.message], "done": done]
+    }
+  }
+}
+
 final class TokamakPluginBridge: NSObject, WKScriptMessageHandler {
   private struct RequestKey: Hashable {
     let session: String
@@ -80,17 +198,15 @@ final class TokamakPluginBridge: NSObject, WKScriptMessageHandler {
 
   private let host: String
   private let plugins: [String: any TokamakPlugin]
-  private var cancellations: [RequestKey: () -> Void] = [:]
+  private lazy var requests = TokamakPluginRequests<RequestKey>(plugins: plugins) {
+    [weak self] key, result in
+    self?.deliver(key: key, result: result)
+  }
   weak var webView: WKWebView?
 
-  init(host: String, plugins: [any TokamakPlugin]) {
+  init(host: String, plugins: [String: any TokamakPlugin]) {
     self.host = host
-    var pluginsById: [String: any TokamakPlugin] = [:]
-    for plugin in plugins {
-      precondition(pluginsById[plugin.id] == nil, "Duplicate plugin ID")
-      pluginsById[plugin.id] = plugin
-    }
-    self.plugins = pluginsById
+    self.plugins = plugins
   }
 
   func install(in controller: WKUserContentController) {
@@ -105,11 +221,7 @@ final class TokamakPluginBridge: NSObject, WKScriptMessageHandler {
   }
 
   func close() {
-    let cancelAll = Array(cancellations.values)
-    cancellations.removeAll()
-    for cancel in cancelAll {
-      cancel()
-    }
+    requests.cancelAll()
   }
 
   func userContentController(
@@ -134,66 +246,27 @@ final class TokamakPluginBridge: NSObject, WKScriptMessageHandler {
     }
     guard let id = request["id"] as? Int else { return }
     let key = RequestKey(session: session, id: id)
-    if type == "cancel" {
-      cancellations.removeValue(forKey: key)?()
-      return
-    }
-    dispatch(type: type, key: key, request: request)
-  }
-
-  private func dispatch(type: String, key: RequestKey, request: [String: Any]) {
-    guard
-      let pluginId = request["plugin"] as? String,
-      let method = request["method"] as? String,
-      let plugin = plugins[pluginId]
-    else {
-      send(key: key, result: .failure(.notSupported("Plugin is not supported")), done: true)
-      return
-    }
-    let arguments = request["arguments"] ?? NSNull()
-    let reply: TokamakPluginReply = { [weak self] result in
-      self?.send(key: key, result: result, done: type == "call")
-    }
     switch type {
-    case "call":
-      plugin.call(method: method, arguments: arguments, reply: reply)
-    case "subscribe":
-      let cancellation = plugin.subscribe(
-        method: method,
-        arguments: arguments,
-        reply: reply
+    case "cancel":
+      requests.cancel(key)
+    case "call", "subscribe":
+      requests.run(
+        key,
+        subscribe: type == "subscribe",
+        plugin: request["plugin"] as? String ?? "",
+        method: request["method"] as? String ?? "",
+        arguments: request["arguments"] ?? NSNull()
       )
-      cancellations[key] = cancellation
     default:
-      send(
-        key: key, result: .failure(.notSupported("Plugin operation is not supported")), done: true)
+      requests.fail(key, .notSupported("Plugin operation is not supported"))
     }
   }
 
-  /// Plugins reply from any thread; delivery happens on the main thread.
-  private func send(key: RequestKey, result: Result<Any?, TokamakPluginError>, done: Bool) {
-    DispatchQueue.main.async { [weak self] in
-      self?.deliver(key: key, result: result, done: done)
-    }
-  }
-
-  private func deliver(key: RequestKey, result: Result<Any?, TokamakPluginError>, done: Bool) {
-    if done {
-      cancellations.removeValue(forKey: key)?()
-    }
-    var response: [String: Any] = [
-      "session": key.session,
-      "id": key.id,
-      "done": done,
-    ]
-    switch result {
-    case .success(let value):
-      response["value"] = value ?? NSNull()
-    case .failure(let error):
-      response["error"] = ["name": error.name, "message": error.message]
-    }
+  private func deliver(key: RequestKey, result: [String: Any]) {
+    var response = result
+    response["session"] = key.session
+    response["id"] = key.id
     guard
-      JSONSerialization.isValidJSONObject(response),
       let data = try? JSONSerialization.data(withJSONObject: response),
       let json = String(data: data, encoding: .utf8),
       webView?.url?.isAppOrigin(host) == true

package/ios-simulator-x64/native-shell/TokamakShell.swift

@@ -219,7 +219,7 @@ private final class NavigationDelegate: NSObject, WKNavigationDelegate, WKUIDele
 }
 
 private final class TokamakController {
-  private let host: TokamakHost
+  private let app: TokamakApp
   private var runtime: RuntimeHandle?
   private var navigation: NavigationDelegate?
   private var pluginBridge: TokamakPluginBridge?
@@ -227,8 +227,8 @@ private final class TokamakController {
   private var dataStore: WKWebsiteDataStore?
   private var proxyPort: UInt16?
 
-  init(host: TokamakHost) {
-    self.host = host
+  init(app: TokamakApp) {
+    self.app = app
   }
 
   deinit {
@@ -236,7 +236,7 @@ private final class TokamakController {
   }
 
   func start(frame: CGRect, completion: @escaping (WKWebView) -> Void) {
-    host.whenStarted { result in
+    app.whenStarted { result in
       switch result {
       case .success(let runtime):
         self.runtime = runtime
@@ -274,7 +274,7 @@ private final class TokamakController {
     #endif
     configuration.mediaTypesRequiringUserActionForPlayback = []
 
-    let pluginBridge = TokamakPluginBridge(host: runtime.appHost, plugins: host.plugins)
+    let pluginBridge = TokamakPluginBridge(host: runtime.appHost, plugins: app.plugins)
     pluginBridge.install(in: configuration.userContentController)
     let navigation = NavigationDelegate(runtime: runtime, pluginBridge: pluginBridge)
     self.navigation = navigation
@@ -310,9 +310,11 @@ private final class TokamakController {
 
 #if os(macOS)
   private final class TokamakMacApplicationDelegate: NSObject, NSApplicationDelegate {
-    private lazy var host = TokamakHost()
-    private lazy var controller = TokamakController(host: host)
+    private lazy var app = TokamakApp()
+    private lazy var controller = TokamakController(app: app)
     private var window: NSWindow?
+    /// Whether the app is shown and its window is not miniaturised.
+    private var visible = false
 
     func applicationDidFinishLaunching(_ notification: Notification) {
       let window = NSWindow(
@@ -327,6 +329,9 @@ private final class TokamakController {
       window.makeKeyAndOrderFront(nil)
       NSApplication.shared.activate(ignoringOtherApps: true)
       self.window = window
+      visible = !NSApplication.shared.isHidden
+      app.start(foreground: visible)
+      observeVisibility()
 
       guard let content = window.contentView else { return }
       controller.start(frame: content.bounds) { webView in
@@ -343,21 +348,45 @@ private final class TokamakController {
       _ application: NSApplication,
       didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
     ) {
-      host.didRegisterForRemoteNotifications(deviceToken: deviceToken)
+      app.didRegisterForRemoteNotifications(deviceToken: deviceToken)
     }
 
     func application(
       _ application: NSApplication,
       didFailToRegisterForRemoteNotificationsWithError error: Error
     ) {
-      host.didFailToRegisterForRemoteNotifications(error: error)
+      app.didFailToRegisterForRemoteNotifications(error: error)
     }
 
     func application(
       _ application: NSApplication,
       didReceiveRemoteNotification userInfo: [String: Any]
     ) {
-      host.didReceiveRemoteNotification(userInfo) { _ in }
+      app.didReceiveRemoteNotification(userInfo) { _ in }
+    }
+
+    /// Delivers `resume` and `suspend` as the app is hidden or shown, and as
+    /// its window is miniaturised or restored.
+    private func observeVisibility() {
+      let changes = [
+        NSApplication.didHideNotification,
+        NSApplication.didUnhideNotification,
+        NSWindow.didMiniaturizeNotification,
+        NSWindow.didDeminiaturizeNotification,
+      ]
+      for change in changes {
+        _ = NotificationCenter.default.addObserver(forName: change, object: nil, queue: .main) {
+          [weak self] _ in
+          self?.visibilityChanged()
+        }
+      }
+    }
+
+    private func visibilityChanged() {
+      let visible = !NSApplication.shared.isHidden && window?.isMiniaturized == false
+      guard visible != self.visible else { return }
+      self.visible = visible
+      app.moved(toForeground: visible)
     }
   }
 
@@ -393,20 +422,32 @@ private final class TokamakController {
 
   private class TokamakIOSApplicationDelegate: UIResponder, UIApplicationDelegate {
     /// Exists from launch, whether or not a scene connects.
-    let host = TokamakHost()
+    let app = TokamakApp()
+
+    /// Starts the runtime once launch finishes. A scene a user launches the
+    /// app into has entered the foreground by then.
+    func application(
+      _ application: UIApplication,
+      didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
+    ) -> Bool {
+      DispatchQueue.main.async {
+        self.app.start(foreground: self.app.isInForeground)
+      }
+      return true
+    }
 
     func application(
       _ application: UIApplication,
       didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
     ) {
-      host.didRegisterForRemoteNotifications(deviceToken: deviceToken)
+      app.didRegisterForRemoteNotifications(deviceToken: deviceToken)
     }
 
     func application(
       _ application: UIApplication,
       didFailToRegisterForRemoteNotificationsWithError error: Error
     ) {
-      host.didFailToRegisterForRemoteNotifications(error: error)
+      app.didFailToRegisterForRemoteNotifications(error: error)
     }
   }
 
@@ -416,7 +457,7 @@ private final class TokamakController {
       didReceiveRemoteNotification userInfo: [AnyHashable: Any],
       fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void
     ) {
-      host.didReceiveRemoteNotification(userInfo) { result in
+      app.didReceiveRemoteNotification(userInfo) { result in
         switch result {
         case .newData: completionHandler(.newData)
         case .noData: completionHandler(.noData)
@@ -431,6 +472,9 @@ private final class TokamakController {
   private final class TokamakSceneDelegate: UIResponder, UIWindowSceneDelegate {
     var window: UIWindow?
     private var controller: TokamakController?
+    private var app: TokamakApp {
+      (UIApplication.shared.delegate as! TokamakIOSApplicationDelegate).app
+    }
 
     func scene(
       _ scene: UIScene,
@@ -438,14 +482,13 @@ private final class TokamakController {
       options connectionOptions: UIScene.ConnectionOptions
     ) {
       guard let scene = scene as? UIWindowScene else { return }
-      let host = (UIApplication.shared.delegate as! TokamakIOSApplicationDelegate).host
       let viewController = UIViewController()
       let window = UIWindow(windowScene: scene)
       window.rootViewController = viewController
       window.makeKeyAndVisible()
       self.window = window
 
-      let controller = TokamakController(host: host)
+      let controller = TokamakController(app: app)
       controller.start(frame: viewController.view.bounds) { webView in
         webView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
         viewController.view.addSubview(webView)
@@ -454,9 +497,14 @@ private final class TokamakController {
     }
 
     func sceneWillEnterForeground(_ scene: UIScene) {
+      app.sceneWillEnterForeground()
       controller?.restoreGateway()
     }
 
+    func sceneDidEnterBackground(_ scene: UIScene) {
+      app.sceneDidEnterBackground()
+    }
+
     /// Releases the scene's window and page, which a reconnection recreates.
     func sceneDidDisconnect(_ scene: UIScene) {
       window = nil

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamakdev/platform-ios-simulator-x64",
-  "version": "0.1.1-beta.82",
+  "version": "0.1.1-beta.84",
   "description": "The tokamak platform pack for ios-simulator-x64",
   "repository": {
     "type": "git",