feat(swift): add SwiftUI rendering layer with Surface, CatalogView, and DataBinding bridge

swift/core/Sources/A2UICore/Extensions/JSONValue+Path.swift

@@ -40,10 +40,7 @@ extension JSONValue {
     switch self {
     case .integer(let value): return value
     case .number(let value):
-      if value >= Double(Int.min) && value <= Double(Int.max) && value == value.rounded() {
-        return Int(value)
-      }
-      return nil
+      return Int(exactly: value)
     default: return nil
     }
   }

swift/core/Sources/A2UICore/Models/SurfaceGroupModel.swift

@@ -0,0 +1,110 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import Combine
+import Foundation
+import OrderedCollections
+import OrderedJSON
+
+/// The root state model managing the collection of active surfaces.
+///
+/// `SurfaceGroupModel` owns the surface dictionary, lifecycle
+/// (add/remove), and cross-surface aggregation such as
+/// `sendDataModel` tracking. It mirrors the `SurfaceGroupModel` type
+/// in the `web_core` reference implementation.
+public final class SurfaceGroupModel: @unchecked Sendable, ObservableObject {
+  private let lock = NSRecursiveLock()
+  private var surfaces: [String: SurfaceViewModel] = [:]
+  private var sendDataModelSurfaces: Set<String> = []
+
+  /// The dictionary of active surfaces, published to the UI on the
+  /// Main Thread.
+  @Published public private(set) var surfacesMap: [String: SurfaceViewModel] = [:]
+
+  public init() {}
+
+  // MARK: - Surface Lifecycle
+
+  /// Adds a surface to the group.
+  ///
+  /// If a surface with the same ID already exists, the call is
+  /// silently ignored (matching `web_core`'s behavior).
+  public func addSurface(_ vm: SurfaceViewModel) {
+    lock.withLock {
+      guard surfaces[vm.surfaceID] == nil else { return }
+      surfaces[vm.surfaceID] = vm
+      publishSnapshot()
+    }
+  }
+
+  /// Removes a surface from the group by its ID.
+  public func removeSurface(id: String) {
+    lock.withLock {
+      guard surfaces[id] != nil else { return }
+      surfaces.removeValue(forKey: id)
+      sendDataModelSurfaces.remove(id)
+      publishSnapshot()
+    }
+  }
+
+  // MARK: - Surface Lookup
+
+  /// Retrieves a surface by its ID.
+  public func surface(id: String) -> SurfaceViewModel? {
+    lock.withLock { surfaces[id] }
+  }
+
+  /// Returns a snapshot of all active surfaces.
+  public func allSurfaces() -> [String: SurfaceViewModel] {
+    lock.withLock { surfaces }
+  }
+
+  // MARK: - send Data Model
+
+  /// Marks a surface as requesting data-model reporting.
+  public func setSendDataModel(surfaceID: String, enabled: Bool) {
+    lock.withLock {
+      if enabled {
+        sendDataModelSurfaces.insert(surfaceID)
+      } else {
+        sendDataModelSurfaces.remove(surfaceID)
+      }
+    }
+  }
+
+  /// Aggregates the data models of all surfaces that have
+  /// `sendDataModel` enabled.
+  ///
+  /// Returns `nil` if no surfaces have the flag set.
+  public func getClientDataModel() -> JSONValue? {
+    lock.withLock {
+      var result: OrderedDictionary<String, JSONValue> = [:]
+      for surfaceID in sendDataModelSurfaces {
+        guard let vm = surfaces[surfaceID] else { continue }
+        result[surfaceID] = vm.dataModel.snapshot()
+      }
+      guard !result.isEmpty else { return nil }
+      return .object(result)
+    }
+  }
+
+  // MARK: - Private
+
+  private func publishSnapshot() {
+    let snapshot = surfaces
+    DispatchQueue.main.async { [weak self] in
+      self?.surfacesMap = snapshot
+    }
+  }
+}

swift/core/Sources/A2UICore/Processing/MessageErrorMapper.swift

@@ -0,0 +1,136 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import Foundation
+
+/// Converts internal Swift errors (e.g. `DecodingError`) into
+/// spec-compliant `ClientServerError` values suitable for sending
+/// to the server.
+///
+/// This type encapsulates the mapping logic that was previously
+/// inlined in `MessageProcessor.handleError`. It is a value type
+/// with no mutable state, making it safe to share across threads.
+public struct MessageErrorMapper: Sendable {
+  public init() {}
+
+  /// Maps an error to a `ClientServerError` suitable for the
+  /// client-to-server `error` message.
+  ///
+  /// - Parameters:
+  ///   - error: The internal error to convert.
+  ///   - surfaceID: The surface ID to attribute the error to.
+  /// - Returns: A `ClientServerError` matching the v0.9.1 wire
+  ///   format.
+  public func map(
+    _ error: Error,
+    surfaceID: String
+  ) -> ClientServerError {
+    if let genericError = error as? GenericError {
+      return .generic(genericError)
+    }
+
+    if let decodingError = error as? DecodingError {
+      return mapDecodingError(decodingError, surfaceID: surfaceID)
+    }
+
+    return .generic(
+      GenericError(
+        code: "PARSING_FAILED",
+        surfaceID: surfaceID,
+        message: error.localizedDescription
+      )
+    )
+  }
+
+  // MARK: - DecodingError Mapping
+
+  private func mapDecodingError(
+    _ error: DecodingError,
+    surfaceID: String
+  ) -> ClientServerError {
+    let codingPath = resolveCodingPath(from: error)
+    let description = resolveDecodingErrorDescription(error)
+
+    switch error {
+    case .typeMismatch, .valueNotFound, .keyNotFound:
+      return .validationFailed(
+        ValidationFailedError(
+          surfaceID: surfaceID,
+          path: codingPath,
+          message: description
+        )
+      )
+    case .dataCorrupted:
+      return .generic(
+        GenericError(
+          code: "PARSING_FAILED",
+          surfaceID: surfaceID,
+          message: description
+        )
+      )
+    @unknown default:
+      return .generic(
+        GenericError(
+          code: "PARSING_FAILED",
+          surfaceID: surfaceID,
+          message: description
+        )
+      )
+    }
+  }
+
+  private func resolveCodingPath(
+    from error: DecodingError
+  ) -> String {
+    let codingPath: [CodingKey]
+    switch error {
+    case .typeMismatch(_, let context),
+      .valueNotFound(_, let context),
+      .keyNotFound(_, let context),
+      .dataCorrupted(let context):
+      codingPath = context.codingPath
+    @unknown default:
+      codingPath = []
+    }
+
+    guard !codingPath.isEmpty else { return "" }
+    let pointer = codingPath.map { key in
+      if let intVal = key.intValue {
+        return String(intVal)
+      } else {
+        return key.stringValue
+          .replacingOccurrences(of: "~", with: "~0")
+          .replacingOccurrences(of: "/", with: "~1")
+      }
+    }.joined(separator: "/")
+    return "/" + pointer
+  }
+
+  private func resolveDecodingErrorDescription(
+    _ error: DecodingError
+  ) -> String {
+    switch error {
+    case .typeMismatch(let type, let context):
+      return "Type mismatch: expected type '\(type)', got '\(context.debugDescription)'"
+    case .valueNotFound(let type, let context):
+      return "Missing value: expected non-nil '\(type)', got '\(context.debugDescription)'"
+    case .keyNotFound(let key, let context):
+      return "Missing required key '\(key.stringValue)': \(context.debugDescription)"
+    case .dataCorrupted(let context):
+      return "JSON syntax error: \(context.debugDescription)"
+    @unknown default:
+      return "Unknown decoding error"
+    }
+  }
+}

swift/core/Sources/A2UICore/Processing/MessageParser.swift

@@ -0,0 +1,63 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import Foundation
+
+/// A thread-safe parser for decoding A2UI server-to-client messages.
+public final class MessageParser: Sendable {
+  private let decoder: JSONDecoder
+
+  public init(decoder: JSONDecoder = JSONDecoder()) {
+    self.decoder = decoder
+  }
+
+  /// Parses a `ServerToClientMessage` from a JSON-encoded string.
+  public func parse(jsonString: String) throws -> ServerToClientMessage {
+    let data = Data(jsonString.utf8)
+    return try decode(jsonData: data)
+  }
+
+  /// Decodes a `ServerToClientMessage` from raw JSON data.
+  public func decode(jsonData: Data) throws -> ServerToClientMessage {
+    try decoder.decode(ServerToClientMessage.self, from: jsonData)
+  }
+
+  /// Best-effort extraction of a `surfaceId` from a raw JSON line.
+  ///
+  /// This is used as a fallback when `parse(jsonString:)` fails, so
+  /// the caller can still attribute the error to the correct
+  /// surface. Returns `nil` if the JSON is malformed or contains no
+  /// `surfaceId` field.
+  public func extractSurfaceID(fromLine line: String) -> String? {
+    guard let data = line.data(using: .utf8),
+      let dict = try? JSONSerialization.jsonObject(with: data)
+        as? [String: Any]
+    else {
+      return nil
+    }
+
+    for value in dict.values {
+      guard let subDict = value as? [String: Any],
+        let rawID = subDict["surfaceId"]
+      else { continue }
+
+      if let strID = rawID as? String {
+        return strID
+      } else if let numID = rawID as? NSNumber {
+        return numID.stringValue
+      }
+    }
+    return nil
+  }
+}