@tokamakdev/platform-macos-x64 0.1.1-beta.128 → 0.1.1-beta.129

package/macos-x64/build/entrypoint

@@ -11,8 +11,71 @@ fi
 if [[ $# -eq 1 && $1 == certs ]]; then
   exec "$apple_tool" inventory
 fi
+
+# Describes the methods PLUGIN/apple/Exports.swift exports on each PLATFORM
+# into OUTPUT/description.json, with the dispatch that serves them,
+# OUTPUT/Exports.generated.swift. The compiler's symbol graph of the plugin,
+# built with the shell for each platform, gives the methods' types.
+describe() {
+  local plugin=$1 output=$2
+  shift 2
+  if ! xcrun --sdk iphonesimulator --show-sdk-path > /dev/null 2>&1; then
+    echo "Describing an Apple plugin needs Xcode" >&2
+    exit 69
+  fi
+  # Global, for the exit trap.
+  temporary=$(mktemp -d "${TMPDIR:-/tmp}/tokamak-describe.XXXXXX")
+  trap 'rm -rf "$temporary"' EXIT
+  printf '%s\n' 'func tokamakPlugins(app: TokamakApp) -> [any TokamakPlugin] { [] }' > "$temporary/registry.swift"
+  local sources=("$pack/native-shell"/*.swift "$temporary/registry.swift") source
+  while IFS= read -r -d '' source; do
+    [[ ${source##*/} == Exports.generated.swift ]] || sources+=("$source")
+  done < <(find "$plugin/apple" -name '*.swift' -print0 | sort -z)
+  local graphs=() compiles=() platform sdk triple
+  for platform in "$@"; do
+    case "$platform" in
+      ios)
+        sdk=iphonesimulator
+        triple=$(uname -m)-apple-ios$(<"$pack/build/ios-deployment-target")-simulator
+        ;;
+      macos)
+        sdk=macosx
+        triple=$(uname -m)-apple-macos$(<"$pack/build/macos-deployment-target")
+        ;;
+      *)
+        echo "Apple plugins run on ios and macos, not $platform" >&2
+        exit 2
+        ;;
+    esac
+    mkdir "$temporary/$platform"
+    # The platforms compile at once, each into its own log.
+    xcrun --sdk "$sdk" swiftc -emit-module -module-name TokamakDescribed -swift-version 5 \
+      -target "$triple" -F "$pack/frameworks" -module-cache-path "$temporary/cache" \
+      -emit-module-path "$temporary/$platform/TokamakDescribed.swiftmodule" \
+      -emit-symbol-graph -emit-symbol-graph-dir "$temporary/$platform" \
+      -symbol-graph-minimum-access-level private "${sources[@]}" > "$temporary/$platform.log" 2>&1 &
+    compiles+=("$!")
+    graphs+=("$platform=$temporary/$platform/TokamakDescribed.symbols.json")
+  done
+  # The platforms report the same diagnostics, so only the first failure's
+  # show, or else the first platform's warnings.
+  local platforms=("$@") index failed=
+  for index in "${!compiles[@]}"; do
+    if ! wait "${compiles[index]}" && [[ -z $failed ]]; then
+      failed=$index
+    fi
+  done
+  cat "$temporary/${platforms[${failed:-0}]}.log" >&2
+  [[ -z $failed ]] || exit 1
+  "$pack/tools/tokamak-swift-describe" "$plugin/apple/Exports.swift" "$output" "${graphs[@]}"
+}
+if [[ $# -ge 4 && $1 == describe ]]; then
+  describe "${@:2}"
+  exit
+fi
+
 if [[ $# -ne 3 || $1 != build ]]; then
-  echo "usage: entrypoint build INPUT OUTPUT | entrypoint certs" >&2
+  echo "usage: entrypoint build INPUT OUTPUT | entrypoint describe PLUGIN OUTPUT PLATFORM... | entrypoint certs" >&2
   exit 2
 fi
 
@@ -169,10 +232,10 @@ if [[ ! -f "$pack/native-shell/TokamakShell.swift" ]]; then
 fi
 
 # A plugin's class is a Swift type name, which the registry creates, and its
-# sources are Swift.
+# sources are the Swift files in its native directory.
 swift_type='^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$'
 # Swift requires unique file names in a module, so a plugin's source
-# <name> compiles as <plugin>-<name>.
+# <directory>/<name> compiles as <plugin>-<directory>-<name>.
 plugin_sources=$temporary/plugin-sources
 mkdir "$plugin_sources"
 registry=$temporary/TokamakPluginRegistry.swift
@@ -185,19 +248,17 @@ for plugin in "$input/plugins"/*/; do
     exit 1
   fi
   printf '    %s(host: TokamakHost(app: app, plugin: "%s")),\n' "$class" "$plugin_id" >> "$registry"
-  for source in "$plugin/sources"/*; do
-    case "$source" in
-      *.swift)
-        named=$plugin_sources/$plugin_id-${source##*/}
-        cp "$source" "$named"
-        swift_sources+=("$named")
-        ;;
-      *)
-        echo "Apple plugin source must be Swift: $source" >&2
-        exit 1
-        ;;
-    esac
-  done
+  [[ -d "$plugin/native" ]] || continue
+  while IFS= read -r -d '' source; do
+    relative=${source#"$plugin/native/"}
+    named=$plugin_sources/$plugin_id-${relative//\//-}
+    if [[ -e "$named" ]]; then
+      echo "plugin '$plugin_id' source $relative stages as ${named##*/}, as another source does; rename one" >&2
+      exit 1
+    fi
+    cp "$source" "$named"
+    swift_sources+=("$named")
+  done < <(find "$plugin/native" -name '*.swift' -print0 | sort -z)
 done
 printf '%s\n' '  ]' '}' >> "$registry"
 

package/macos-x64/native-shell/TokamakExports.swift

@@ -0,0 +1,561 @@
+import Foundation
+
+/// A plugin whose `apple/Exports.swift` lists the methods the Worker calls
+/// and the events it receives. `tok plugin generate apple` reads it and writes
+/// the plugin's dispatch and TypeScript API.
+protocol TokamakExports: TokamakPlugin {
+  /// The plugin's host, whose resources hold the native references methods take.
+  var host: TokamakHost { get }
+
+  /// Lists the exported methods and events. The app never calls it.
+  static func exports(_ e: inout TokamakExporter<Self>)
+
+  /// `event` as the JSON data of the event `name`, which the registration lists.
+  func eventPayload(_ name: String, _ event: Any) throws(TokamakPluginError) -> Data
+
+  /// The listeners' JSON `reply` to the event `name`, which the registration
+  /// lists with a reply, as its type, or nil for null.
+  func eventReply(_ name: String, _ reply: Data) throws(TokamakPluginError) -> Any?
+}
+
+extension TokamakExports {
+  func eventPayload(_ name: String, _ event: Any) throws(TokamakPluginError) -> Data {
+    throw .unlistedEvent(name)
+  }
+
+  func eventReply(_ name: String, _ reply: Data) throws(TokamakPluginError) -> Any? {
+    throw .unlistedReply(name)
+  }
+}
+
+/// What a stream does with values a slow reader has not taken.
+enum TokamakOverflow {
+  /// Ends the stream with `QuotaExceededError`.
+  case error
+  /// Drops the oldest values, for samples where only recent ones matter.
+  case dropOldest
+}
+
+/// Lists a plugin's exported methods and events: method parameters and event
+/// replies are `Decodable`, method results and events `Encodable`, and options
+/// literal values.
+struct TokamakExporter<Plugin> {
+  /// Lists the event `name`, whose listeners receive an `E`.
+  mutating func event<E: Encodable>(_ name: String, _ type: E.Type, doc: String = "") {}
+
+  /// Lists the event `name`, whose listeners receive an `E` and may reply with an `R`.
+  mutating func event<E: Encodable, R: Decodable>(
+    _ name: String, _ type: E.Type, reply: R.Type, doc: String = ""
+  ) {}
+
+  /// Exports `method`, which returns once.
+  mutating func call<each A: Decodable, R: Encodable>(
+    _ method: (Plugin) -> (repeat each A) async throws -> R, doc: String = ""
+  ) {}
+
+  mutating func call<each A: Decodable>(
+    _ method: (Plugin) -> (repeat each A) async throws -> Void, doc: String = ""
+  ) {}
+
+  /// Exports `method`, whose last parameter reads the bytes the Worker streams.
+  mutating func call<each A: Decodable, R: Encodable>(
+    _ method: (Plugin) -> (repeat each A, TokamakPluginBody) async throws -> R, doc: String = ""
+  ) {}
+
+  mutating func call<each A: Decodable>(
+    _ method: (Plugin) -> (repeat each A, TokamakPluginBody) async throws -> Void, doc: String = ""
+  ) {}
+
+  /// Exports `method`, which returns the values it sends until the Worker cancels.
+  mutating func stream<each A: Decodable, S: AsyncSequence>(
+    _ method: (Plugin) -> (repeat each A) throws -> S, overflow: TokamakOverflow = .error,
+    doc: String = ""
+  ) where S.Element: Encodable {}
+
+  /// Exports `method`, which returns a native object the Worker holds as a
+  /// `NativeReference`.
+  mutating func resource<each A: Decodable, R>(
+    _ method: (Plugin) -> (repeat each A) async throws -> R, doc: String = ""
+  ) {}
+}
+
+/// A native object the Worker passes as a `NativeReference`, which another
+/// plugin retained.
+struct TokamakReference<Object>: Decodable {
+  let object: Object
+
+  init(from decoder: any Decoder) throws {
+    let id = try decoder.singleValueContainer().decode(String.self)
+    guard let resources = decoder.userInfo[.tokamakResources] as? TokamakResources else {
+      throw TokamakPluginError(name: "InvalidStateError", message: "No native references here")
+    }
+    object = try resources.get(id, as: Object.self)
+  }
+}
+
+/// Any JSON value, for data a plugin passes through or reads itself.
+enum TokamakJSON: Codable, Equatable {
+  case null
+  case bool(Bool)
+  case number(Double)
+  case string(String)
+  case array([TokamakJSON])
+  case object([String: TokamakJSON])
+
+  init(from decoder: any Decoder) throws {
+    // Each failed attempt throws, so the commonest kinds of value come first.
+    let container = try decoder.singleValueContainer()
+    if container.decodeNil() {
+      self = .null
+    } else if let string = try? container.decode(String.self) {
+      self = .string(string)
+    } else if let number = try? container.decode(Double.self) {
+      self = .number(number)
+    } else if let bool = try? container.decode(Bool.self) {
+      self = .bool(bool)
+    } else if let object = try? container.decode([String: TokamakJSON].self) {
+      self = .object(object)
+    } else {
+      self = .array(try container.decode([TokamakJSON].self))
+    }
+  }
+
+  func encode(to encoder: any Encoder) throws {
+    var container = encoder.singleValueContainer()
+    switch self {
+    case .null: try container.encodeNil()
+    case .bool(let bool): try container.encode(bool)
+    case .number(let number): try container.encode(number)
+    case .string(let string): try container.encode(string)
+    case .array(let array): try container.encode(array)
+    case .object(let object): try container.encode(object)
+    }
+  }
+
+  /// `value` as JSON, which `JSONSerialization` writes it as, or nil when it is not JSON.
+  init?(_ value: Any) {
+    switch value {
+    case is NSNull: self = .null
+    case let number as NSNumber where CFGetTypeID(number) == CFBooleanGetTypeID():
+      self = .bool(number.boolValue)
+    case let number as NSNumber: self = .number(number.doubleValue)
+    case let string as String: self = .string(string)
+    case let array as [Any]:
+      let elements = array.compactMap(TokamakJSON.init)
+      guard elements.count == array.count else { return nil }
+      self = .array(elements)
+    case let object as [String: Any]:
+      let entries = object.compactMapValues(TokamakJSON.init)
+      guard entries.count == object.count else { return nil }
+      self = .object(entries)
+    default: return nil
+    }
+  }
+
+  /// The value as `JSONSerialization` reads it: `NSNull`, an `NSNumber` for a boolean or a
+  /// number, which `as? Int` reads when whole, `String`, arrays and dictionaries.
+  var value: Any {
+    switch self {
+    case .null: NSNull()
+    case .bool(let bool): NSNumber(value: bool)
+    case .number(let number): NSNumber(value: number)
+    case .string(let string): string
+    case .array(let array): array.map(\.value)
+    case .object(let object): object.mapValues(\.value)
+    }
+  }
+}
+
+/// An enum whose cases are the forms its values take: a case without an associated value is
+/// the string of its name, and a case with one unlabeled associated value is that value.
+/// `tok plugin generate apple` writes its coding in place of these defaults, which throw.
+protocol TokamakUnion: Codable {}
+
+/// A `TokamakUnion` whose values are objects that name their case in the field `tag`, with a
+/// struct case's fields.
+protocol TokamakTaggedUnion: TokamakUnion {
+  /// The tag field's name, as a string literal, which `tok plugin generate apple` reads.
+  static var tag: String { get }
+}
+
+extension TokamakUnion {
+  init(from decoder: any Decoder) throws {
+    throw TokamakPluginError.ungenerated(Self.self)
+  }
+
+  func encode(to encoder: any Encoder) throws {
+    throw TokamakPluginError.ungenerated(Self.self)
+  }
+}
+
+/// The JSON value whose kind a union's generated decoder chooses its case by.
+struct TokamakUnionValue {
+  enum Kind {
+    case null, boolean, number, array
+    case string(String)
+    /// An object, with its keys.
+    case object(Set<String>)
+  }
+
+  let kind: Kind
+  private let decoder: any Decoder
+
+  init(_ decoder: any Decoder) throws {
+    self.decoder = decoder
+    let value = try decoder.singleValueContainer()
+    if value.decodeNil() {
+      kind = .null
+    } else if let string = try? value.decode(String.self) {
+      kind = .string(string)
+    } else if (try? value.decode(Bool.self)) != nil {
+      kind = .boolean
+    } else if (try? value.decode(Double.self)) != nil {
+      kind = .number
+    } else if let object = try? decoder.container(keyedBy: TokamakUnionKey.self) {
+      kind = .object(Set(object.allKeys.map(\.stringValue)))
+    } else {
+      kind = .array
+    }
+  }
+
+  /// The value as a `T`.
+  func decode<T: Decodable>(_ type: T.Type) throws -> T {
+    try decoder.singleValueContainer().decode(type)
+  }
+
+  /// The string in the object's field `tag`.
+  func tag(_ tag: String) throws -> String {
+    try decoder.container(keyedBy: TokamakUnionKey.self).decode(String.self, forKey: .init(tag))
+  }
+
+  /// The error of a value that is none of the union `name`'s forms.
+  func mismatch(_ name: String) -> DecodingError {
+    .dataCorrupted(
+      .init(codingPath: decoder.codingPath, debugDescription: "must be one of \(name)'s forms"))
+  }
+}
+
+/// Encodes the case `name` of a tagged union as an object with `value`'s fields, if any, and the
+/// field `tag` naming the case.
+func tokamakEncode(
+  tag: String, _ name: String, _ value: (any Encodable)? = nil, to encoder: any Encoder
+) throws {
+  try value?.encode(to: encoder)
+  var container = encoder.container(keyedBy: TokamakUnionKey.self)
+  try container.encode(name, forKey: .init(tag))
+}
+
+/// A JSON object's key, as a union's coding reads and writes it.
+struct TokamakUnionKey: CodingKey {
+  let stringValue: String
+  var intValue: Int? { nil }
+
+  init(_ stringValue: String) {
+    self.stringValue = stringValue
+  }
+
+  init?(stringValue: String) {
+    self.stringValue = stringValue
+  }
+
+  init?(intValue: Int) {
+    nil
+  }
+}
+
+extension CodingUserInfoKey {
+  /// The resources a `TokamakReference` finds its object in.
+  fileprivate static let tokamakResources = CodingUserInfoKey(rawValue: "tokamak.resources")!
+}
+
+extension TokamakPluginError {
+  /// A `TypeError` naming where the `root` value, such as a call's
+  /// arguments, fails to decode.
+  init(decoding error: DecodingError, in root: String = "arguments") {
+    let (path, problem): ([any CodingKey], String) =
+      switch error {
+      case .keyNotFound(let key, let context): (context.codingPath + [key], "is missing")
+      case .typeMismatch(_, let context), .valueNotFound(_, let context),
+        .dataCorrupted(let context):
+        (context.codingPath, context.debugDescription)
+      @unknown default: ([], "\(error)")
+      }
+    let location = path.reduce("") { location, key in
+      if let index = key.intValue { return "\(location)[\(index)]" }
+      return location.isEmpty ? key.stringValue : "\(location).\(key.stringValue)"
+    }
+    self.init(name: "TypeError", message: "\(location.isEmpty ? root : location) \(problem)")
+  }
+
+  /// A `TokamakUnion` without the coding `tok plugin generate apple` writes.
+  static func ungenerated(_ union: Any.Type) -> Self {
+    Self(name: "TypeError", message: "run tok plugin generate apple to code \(union)")
+  }
+
+  /// The plugin emitted an event its registration does not list.
+  static func unlistedEvent(_ name: String) -> Self {
+    Self(name: "TypeError", message: "apple/Exports.swift lists no event \(name)")
+  }
+
+  /// The plugin asked for the reply to an event its registration lists without one.
+  static func unlistedReply(_ name: String) -> Self {
+    Self(name: "TypeError", message: "apple/Exports.swift lists no reply to event \(name)")
+  }
+}
+
+/// Decodes a call's JSON arguments, or another `root` value, finding the
+/// native references they name in `resources`.
+func tokamakDecode<T: Decodable>(
+  _ type: T.Type, from payload: Data, resources: TokamakResources? = nil,
+  in root: String = "arguments"
+) throws(TokamakPluginError) -> T {
+  let decoder = JSONDecoder()
+  decoder.userInfo[.tokamakResources] = resources
+  do {
+    return try decoder.decode(type, from: payload)
+  } catch let error as DecodingError {
+    throw TokamakPluginError(decoding: error, in: root)
+  } catch {
+    throw TokamakPluginError(error)
+  }
+}
+
+/// `value` as a reply's payload: `Data` as it is, and any other value as the
+/// JSON `encoder` writes.
+func tokamakEncode<T: Encodable>(
+  _ value: T, with encoder: JSONEncoder = JSONEncoder()
+) throws(TokamakPluginError) -> Data {
+  if let data = value as? Data { return data }
+  do {
+    return try encoder.encode(value)
+  } catch {
+    throw TokamakPluginError(name: "DataCloneError", message: "\(error)")
+  }
+}
+
+/// `event` as the JSON data of the event `name`, whose listeners receive a `T`.
+func tokamakEvent<T: Encodable>(
+  _ name: String, _ event: Any, as type: T.Type
+) throws(TokamakPluginError) -> Data {
+  guard let event = event as? T else {
+    throw TokamakPluginError(
+      name: "TypeError", message: "event \(name) takes \(T.self), not \(Swift.type(of: event))")
+  }
+  return try tokamakEncode(event)
+}
+
+/// Replies with what `method` returns. A synchronous method runs on the
+/// call's executor and has nothing to cancel.
+func tokamakCall<T: Encodable>(
+  _ reply: TokamakPluginBytesReply, _ method: () throws -> T
+) -> (() -> Void)? {
+  reply(result { try tokamakEncode(try method()) })
+  return nil
+}
+
+func tokamakCall(_ reply: TokamakPluginBytesReply, _ method: () throws -> Void) -> (() -> Void)? {
+  reply(
+    result {
+      try method()
+      return null
+    })
+  return nil
+}
+
+/// Runs `method` in a task, replying with what it returns. Cancelling the
+/// call cancels the task.
+func tokamakCall<T: Encodable>(
+  _ reply: @escaping TokamakPluginBytesReply, _ method: @escaping () async throws -> T
+) -> (() -> Void)? {
+  task { reply(await awaitResult { try tokamakEncode(try await method()) }) }
+}
+
+func tokamakCall(
+  _ reply: @escaping TokamakPluginBytesReply, _ method: @escaping () async throws -> Void
+) -> (() -> Void)? {
+  task {
+    reply(
+      await awaitResult {
+        try await method()
+        return null
+      })
+  }
+}
+
+/// Replies with each value `method`'s sequence sends, until it ends or the
+/// subscription is cancelled. A synchronous method runs on the
+/// subscription's executor.
+func tokamakStream<S: AsyncSequence>(
+  _ reply: @escaping TokamakPluginBytesReply, _ method: () throws -> S
+) throws(TokamakPluginError) -> () -> Void where S.Element: Encodable {
+  let values = try catching(method)
+  return task { await send(values, reply) }
+}
+
+func tokamakStream<S: AsyncSequence>(
+  _ reply: @escaping TokamakPluginBytesReply, _ method: @escaping () async throws -> S
+) -> () -> Void where S.Element: Encodable {
+  task {
+    do {
+      await send(try await method(), reply)
+    } catch {
+      reply(TokamakPluginResult(.failure(TokamakPluginError(error)), done: true))
+    }
+  }
+}
+
+/// Retains the object `method` returns in `resources`, replying with its
+/// ID, until the subscription is cancelled. A synchronous method runs on the
+/// subscription's executor.
+func tokamakResource(
+  _ resources: TokamakResources, _ reply: @escaping TokamakPluginBytesReply,
+  _ method: () throws -> Any
+) throws(TokamakPluginError) -> () -> Void {
+  resources.retain(try catching(method)) {
+    reply(TokamakPluginResult($0.flatMap(encodePluginValue), done: false))
+  }
+}
+
+func tokamakResource(
+  _ resources: TokamakResources, _ reply: @escaping TokamakPluginBytesReply,
+  _ method: @escaping () async throws -> Any
+) -> () -> Void {
+  let retained = Retained()
+  let cancel = task {
+    do {
+      let object = try await method()
+      retained.hold(
+        resources.retain(object) {
+          reply(TokamakPluginResult($0.flatMap(encodePluginValue), done: false))
+        })
+    } catch {
+      reply(TokamakPluginResult(.failure(TokamakPluginError(error)), done: true))
+    }
+  }
+  return {
+    cancel()
+    retained.end()
+  }
+}
+
+/// How many values listeners keep: those a slow reader has not taken, or those
+/// held for the first.
+private let listenerCapacity = 64
+
+/// The streams of an event's listeners, such as a page's, each of which
+/// receives every value `send` delivers until it ends, keeping the newest 64
+/// that a slow reader has not taken. When `holding`, the newest 64 values sent
+/// while none listen wait for the first listener.
+final class TokamakListeners<Value>: @unchecked Sendable {
+  private let lock = NSLock()
+  private let holding: Bool
+  private var continuations: [UUID: AsyncStream<Value>.Continuation] = [:]
+  private var held: [Value] = []
+
+  init(holding: Bool = false) {
+    self.holding = holding
+  }
+
+  /// A new listener's stream.
+  // Values are yielded under the lock, so one sent while a listener starts
+  // follows the held ones. Yielding only buffers.
+  func stream() -> AsyncStream<Value> {
+    let (stream, continuation) = AsyncStream.makeStream(
+      of: Value.self, bufferingPolicy: .bufferingNewest(listenerCapacity))
+    let key = UUID()
+    continuation.onTermination = { [weak self] _ in
+      self?.lock.withLock { _ = self?.continuations.removeValue(forKey: key) }
+    }
+    lock.withLock {
+      continuations[key] = continuation
+      for value in held {
+        continuation.yield(value)
+      }
+      held = []
+    }
+    return stream
+  }
+
+  func send(_ value: Value) {
+    lock.withLock {
+      if holding && continuations.isEmpty {
+        held.append(value)
+        if held.count > listenerCapacity { held.removeFirst() }
+      }
+      for continuation in continuations.values {
+        continuation.yield(value)
+      }
+    }
+  }
+}
+
+/// The JSON payload of a method that returns nothing.
+private let null = Data("null".utf8)
+
+/// A call's last reply: `payload`'s bytes, or its failure.
+private func result(_ payload: () throws -> Data) -> TokamakPluginResult {
+  TokamakPluginResult(Result { () throws(TokamakPluginError) in try catching(payload) }, done: true)
+}
+
+private func awaitResult(_ payload: () async throws -> Data) async -> TokamakPluginResult {
+  do {
+    return TokamakPluginResult(.success(try await payload()), done: true)
+  } catch {
+    return TokamakPluginResult(.failure(TokamakPluginError(error)), done: true)
+  }
+}
+
+/// What `body` returns, with what it throws as a `TokamakPluginError`.
+private func catching<T>(_ body: () throws -> T) throws(TokamakPluginError) -> T {
+  do {
+    return try body()
+  } catch {
+    throw TokamakPluginError(error)
+  }
+}
+
+/// Runs `body` in a task, returning its cancellation.
+private func task(_ body: @escaping () async -> Void) -> () -> Void {
+  Task { await body() }.cancel
+}
+
+/// Replies with each of `values`, then with the end of the subscription.
+private func send<S: AsyncSequence>(
+  _ values: S, _ reply: TokamakPluginBytesReply
+) async where S.Element: Encodable {
+  // One encoder serves the stream, whose values it encodes one at a time.
+  let encoder = JSONEncoder()
+  do {
+    for try await value in values {
+      reply(TokamakPluginResult(.success(try tokamakEncode(value, with: encoder)), done: false))
+    }
+    reply(TokamakPluginResult(payload: Data(), failed: false, done: true))
+  } catch {
+    reply(TokamakPluginResult(.failure(TokamakPluginError(error)), done: true))
+  }
+}
+
+/// The release of an object a subscription retains, which runs once the
+/// subscription ends, whether the object is retained before or after.
+private final class Retained {
+  private let lock = NSLock()
+  private var release: (() -> Void)?
+  private var ended = false
+
+  func hold(_ release: @escaping () -> Void) {
+    let ended = lock.withLock {
+      if !self.ended { self.release = release }
+      return self.ended
+    }
+    if ended { release() }
+  }
+
+  func end() {
+    let release = lock.withLock {
+      ended = true
+      defer { self.release = nil }
+      return self.release
+    }
+    release?()
+  }
+}

package/macos-x64/native-shell/TokamakPlugins.swift

@@ -140,7 +140,7 @@ final class TokamakHost {
   #endif
 
   /// Delivers the plugin's event `name`, which the Worker's listeners
-  /// receive as `<plugin>.<name>`, with its encoded `payload`, and calls
+  /// receive as `<plugin>.apple.<name>`, with its encoded `payload`, and calls
   /// `completion` on the main thread with their encoded reply, which is empty
   /// when none replied. Fails unless they return within `timeout`, which
   /// includes runtime startup. Call it on the main thread.
@@ -150,33 +150,75 @@ final class TokamakHost {
     timeout: TimeInterval,
     completion: @escaping (Result<Data, Error>) -> Void
   ) {
-    app.emit("\(plugin).\(name)", payload: payload, timeout: timeout, completion: completion)
+    app.emit("\(plugin).apple.\(name)", payload: payload, timeout: timeout, completion: completion)
   }
 
-  /// `emitBytes` with `event` encoded as JSON, calling `completion` with the
-  /// reply parsed from JSON, or nil when none replied.
+  /// Delivers `event` to the Worker's listeners of the plugin's event `name`,
+  /// which `apple/Exports.swift` lists, then calls `completion` on the main
+  /// thread. Fails unless they return within `timeout`, which includes runtime
+  /// startup. Call it on the main thread.
   func emit(
     _ name: String,
-    event: Any,
+    event: some Encodable,
     timeout: TimeInterval,
-    completion: @escaping (Result<Any?, Error>) -> Void
+    completion: @escaping (Result<Void, Error>) -> Void
   ) {
-    let payload: Data
-    switch encodePluginValue(event) {
-    case .success(let encoded): payload = encoded
-    case .failure(let error): return completion(.failure(error))
-    }
-    emitBytes(name, payload: payload, timeout: timeout) { result in
+    send(name, event, timeout: timeout) { completion($0.map { _ in }) }
+  }
+
+  /// `emit` of an event whose listeners may reply, calling `completion` with
+  /// the reply as the plugin's generated dispatch decodes it, which is a
+  /// `Reply`, or nil when none replied.
+  func emit<Reply>(
+    _ name: String,
+    event: some Encodable,
+    reply: Reply.Type,
+    timeout: TimeInterval,
+    completion: @escaping (Result<Reply?, Error>) -> Void
+  ) {
+    send(name, event, timeout: timeout) { result in
       completion(
         result.flatMap { reply in
-          Result { () throws(TokamakPluginError) -> Any? in
-            let value = reply.isEmpty ? NSNull() : try decodePluginValue(reply)
-            return value is NSNull ? nil : value
-          }.mapError { $0 }
+          Result<Reply?, Error> { try self.decoded(reply, to: name, as: Reply.self) }
         })
     }
   }
 
+  /// Delivers `event` as the plugin's generated dispatch encodes it.
+  private func send(
+    _ name: String, _ event: Any, timeout: TimeInterval,
+    completion: @escaping (Result<Data, Error>) -> Void
+  ) {
+    let payload: Data
+    do throws(TokamakPluginError) {
+      payload = try exports(name).eventPayload(name, event)
+    } catch {
+      return completion(.failure(error))
+    }
+    emitBytes(name, payload: payload, timeout: timeout, completion: completion)
+  }
+
+  /// The listeners' `reply` to the event `name` as a `Reply`, or nil when none replied.
+  private func decoded<Reply>(
+    _ reply: Data, to name: String, as type: Reply.Type
+  ) throws(TokamakPluginError) -> Reply? {
+    guard !reply.isEmpty, let value = try exports(name).eventReply(name, reply) else { return nil }
+    guard let reply = value as? Reply else {
+      throw TokamakPluginError(
+        name: "TypeError",
+        message: "event \(name) replies with \(Swift.type(of: value)), not \(Reply.self)")
+    }
+    return reply
+  }
+
+  /// The plugin, whose generated dispatch encodes the event `name`.
+  private func exports(_ name: String) throws(TokamakPluginError) -> any TokamakExports {
+    guard let exports = app.plugins[plugin] as? any TokamakExports else {
+      throw .unlistedEvent(name)
+    }
+    return exports
+  }
+
   /// Fetches what the app serves at `path`, as its WebView would load it: a
   /// file the app ships or the Worker's response. Calls `completion` on the
   /// main thread with the body. Fails unless it arrives within `timeout`,

package/macos-x64/platform-pack.json

@@ -22,7 +22,6 @@
   "pluginKeys": {
     "class": "string",
     "plist": "path",
-    "resources": "paths",
-    "sources": "paths"
+    "resources": "paths"
   }
 }

package/macos-x64/tools/tokamak-swift-describe

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: package/macos-x64/tools/tokamak-swift-describe
+size: 34569672 bytes
+sha256: 131a2a07b15017bbce0064d2eb2bcf22eb1240493d15b85d43e46d69330c6ecc

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamakdev/platform-macos-x64",
-  "version": "0.1.1-beta.128",
+  "version": "0.1.1-beta.129",
   "description": "The tokamak platform pack for macos-x64",
   "repository": {
     "type": "git",