@tokamakdev/platform-ios-simulator-x64 0.1.1-beta.81 → 0.1.1-beta.83

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

@@ -23,19 +23,19 @@ typedef struct {
 
 void *tokamak_runtime_start(const char *packaged_dir, const char *state_dir,
                             const char *storage_dir, const char *host,
-                            char *error, size_t error_len);
+                            bool foreground, 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,
+                                     const char *session_token,
+                                     bool foreground, 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);
 
 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,22 +1,43 @@
 import Foundation
 import TokamakRuntime
 
+#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 {
+final class TokamakApp {
   private(set) var plugins: [any TokamakPlugin] = []
   private var runtime: Result<RuntimeHandle, Error>?
   private var waiting: [(Result<RuntimeHandle, Error>) -> Void] = []
+  /// 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.
+    private var foregroundScenes = 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)
+    plugins = tokamakPlugins(app: self)
+  }
+
+  /// 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))
     DispatchQueue.global(qos: .userInitiated).async {
-      let result = Result { try RuntimeHandle() }
+      let result = Result { try RuntimeHandle(foreground: foreground) }
       DispatchQueue.main.async { self.started(result) }
     }
   }
@@ -32,15 +53,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 +71,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,6 +81,59 @@ final class TokamakHost {
     }
   }
 
+  /// Delivers `resume` when the app moves into the foreground and `suspend`
+  /// when it moves out. 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
+    emit(name, event: [String: Any](), timeout: timeout, on: 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() {
+      foregroundScenes += 1
+      if foregroundScenes == 1 {
+        moved(toForeground: true)
+      }
+    }
+
+    /// Delivers `suspend` as the last scene leaves the foreground.
+    func sceneDidEnterBackground() {
+      foregroundScenes -= 1
+      if foregroundScenes == 0 {
+        moved(toForeground: false)
+      }
+    }
+
+    /// Whether a scene is in the foreground.
+    var isInForeground: Bool {
+      foregroundScenes > 0
+    }
+  #endif
+
   func didRegisterForRemoteNotifications(deviceToken: Data) {
     for plugin in plugins {
       plugin.didRegisterForRemoteNotifications(deviceToken: deviceToken)
@@ -147,7 +223,8 @@ final class RuntimeHandle {
   let appHost: String
   private var handle: UnsafeMutableRawPointer?
 
-  init() throws {
+  /// Starts the runtime, which delivers `start` with `foreground`.
+  init(foreground: Bool) throws {
     guard
       let appHost = Bundle.main.object(forInfoDictionaryKey: "TokamakHost") as? String,
       !appHost.isEmpty
@@ -172,6 +249,7 @@ final class RuntimeHandle {
                   appHost,
                   endpoint,
                   sessionToken,
+                  foreground,
                   error.baseAddress,
                   error.count
                 )
@@ -196,6 +274,7 @@ final class RuntimeHandle {
                   statePath,
                   storagePath,
                   appHost,
+                  foreground,
                   error.baseAddress,
                   error.count
                 )
@@ -232,38 +311,40 @@ 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
   }
 
   func serverAuthority(host: String) -> AuthenticationMaterial<Data> {

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

@@ -12,6 +12,31 @@ struct TokamakPluginError: Error {
 
 typealias TokamakPluginReply = (Result<Any?, TokamakPluginError>) -> Void
 
+/// 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
+  }
+
+  /// 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.
 protocol TokamakPlugin: AnyObject {
   var id: String { get }

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.81",
+  "version": "0.1.1-beta.83",
   "description": "The tokamak platform pack for ios-simulator-x64",
   "repository": {
     "type": "git",