@use-voltra/ios-client 2.2.0 → 2.3.1

package/ios/shared/dynamic-live-activity/VoltraDynamicLiveActivityRenderer.swift

@@ -0,0 +1,370 @@
+import ActivityKit
+import Foundation
+import SwiftUI
+import WidgetKit
+
+/// Renders generated Dynamic Live Activity configurations through their bundled
+/// JavaScript definitions. Failures intentionally become `EmptyView`: a remote
+/// ActivityKit start may already exist and a later update can recover it.
+public enum VoltraDynamicLiveActivityRenderer {
+  public static func lockScreen<Attributes: VoltraDynamicLiveActivityDefinition>(
+    definitionId: String,
+    context: ActivityViewContext<Attributes>
+  ) -> some View {
+    if #available(iOS 18.0, *) {
+      return VoltraDynamicLiveActivityAdaptiveLockScreenView(definitionId: definitionId, context: context)
+    }
+    return VoltraDynamicLiveActivityLockScreenView(definitionId: definitionId, context: context)
+  }
+
+  public static func dynamicIsland<Attributes: VoltraDynamicLiveActivityDefinition>(
+    definitionId: String,
+    context: ActivityViewContext<Attributes>
+  ) -> DynamicIsland {
+    DynamicIsland {
+      DynamicIslandExpandedRegion(.leading) {
+        VoltraDynamicLiveActivityDynamicIslandRegionView(
+          definitionId: definitionId,
+          context: context,
+          region: .islandExpandedLeading
+        )
+      }
+      DynamicIslandExpandedRegion(.trailing) {
+        VoltraDynamicLiveActivityDynamicIslandRegionView(
+          definitionId: definitionId,
+          context: context,
+          region: .islandExpandedTrailing
+        )
+      }
+      DynamicIslandExpandedRegion(.center) {
+        VoltraDynamicLiveActivityDynamicIslandRegionView(
+          definitionId: definitionId,
+          context: context,
+          region: .islandExpandedCenter
+        )
+      }
+      DynamicIslandExpandedRegion(.bottom) {
+        VoltraDynamicLiveActivityDynamicIslandRegionView(
+          definitionId: definitionId,
+          context: context,
+          region: .islandExpandedBottom
+        )
+      }
+    } compactLeading: {
+      VoltraDynamicLiveActivityDynamicIslandRegionView(
+        definitionId: definitionId,
+        context: context,
+        region: .islandCompactLeading
+      )
+    } compactTrailing: {
+      VoltraDynamicLiveActivityDynamicIslandRegionView(
+        definitionId: definitionId,
+        context: context,
+        region: .islandCompactTrailing
+      )
+    } minimal: {
+      VoltraDynamicLiveActivityDynamicIslandRegionView(
+        definitionId: definitionId,
+        context: context,
+        region: .islandMinimal
+      )
+    }
+
+    // DynamicIsland itself is not a View and cannot read SwiftUI Environment.
+    // Do not execute a definition against fabricated values solely to obtain a
+    // keyline tint; its region views below read the actual environment.
+  }
+
+  fileprivate static func resolve<Attributes: VoltraDynamicLiveActivityDefinition>(
+    definitionId: String,
+    context: ActivityViewContext<Attributes>,
+    activityFamily: String?,
+    colorScheme: ColorScheme? = nil,
+    locale: Locale = .current,
+    widgetRenderingMode: WidgetRenderingMode = .fullColor
+  ) -> VoltraDynamicLiveActivityResolvedContent {
+    guard VoltraDynamicLiveActivityRegistry.shared.contains(definitionId) else {
+      logFailure(definitionId: definitionId, activityName: context.attributes.name, message: "Definition is missing from the installed catalog")
+      return .empty
+    }
+    guard let propsJSON = DynamicLiveActivityPropsCodec.encode(context.state.props) else {
+      logFailure(definitionId: definitionId, activityName: context.attributes.name, message: "Could not encode content-state props")
+      return .empty
+    }
+    // WidgetKit asks each Dynamic Island region (and each presentation) to render
+    // independently, all with identical state/environment. Cache the resolved
+    // variants shape so those siblings share one bundle load, one JS evaluation,
+    // and one failure diagnostic. `revision` changes on every hot reload, so a
+    // DEBUG reload busts the cache; in release it is constant.
+    let cacheKey = VoltraDynamicLiveActivityRenderCache.Key(
+      activityId: context.activityID,
+      definitionId: definitionId,
+      revision: VoltraDynamicLiveActivityBundleSource.revision(definitionId: definitionId),
+      props: propsJSON,
+      activityFamily: activityFamily,
+      colorScheme: String(describing: colorScheme ?? .light),
+      locale: locale.identifier,
+      widgetRenderingMode: String(describing: widgetRenderingMode),
+      isStale: context.isStale
+    )
+    return VoltraDynamicLiveActivityRenderCache.shared.resolve(cacheKey) {
+      resolveUncached(
+        definitionId: definitionId,
+        context: context,
+        propsJSON: propsJSON,
+        activityFamily: activityFamily,
+        colorScheme: colorScheme,
+        locale: locale,
+        widgetRenderingMode: widgetRenderingMode
+      )
+    }
+  }
+
+  private static func resolveUncached<Attributes: VoltraDynamicLiveActivityDefinition>(
+    definitionId: String,
+    context: ActivityViewContext<Attributes>,
+    propsJSON: String,
+    activityFamily: String?,
+    colorScheme: ColorScheme?,
+    locale: Locale,
+    widgetRenderingMode: WidgetRenderingMode
+  ) -> VoltraDynamicLiveActivityResolvedContent {
+    let environmentJSON = VoltraDynamicLiveActivityEnvironmentBuilder.build(
+      date: Date(),
+      colorScheme: colorScheme,
+      locale: locale,
+      widgetRenderingMode: widgetRenderingMode,
+      isStale: context.isStale,
+      activityFamily: activityFamily
+    )
+
+    do {
+      let source = try VoltraDynamicLiveActivityBundleSource.load(definitionId: definitionId)
+      guard VoltraJSRenderer.ensureLiveActivityEvaluated(definitionId: definitionId, source: source) else {
+        logFailure(definitionId: definitionId, activityName: context.attributes.name, message: "Could not evaluate definition bundle")
+        return .empty
+      }
+      guard let renderedJSON = VoltraJSRenderer.renderLiveActivity(
+        definitionId: definitionId,
+        propsJSON: propsJSON,
+        envJSON: environmentJSON
+      ) else {
+        logFailure(definitionId: definitionId, activityName: context.attributes.name, message: "Definition render failed")
+        return .empty
+      }
+      let payload = try VoltraLiveActivityPayload(jsonString: renderedJSON)
+      return VoltraDynamicLiveActivityResolvedContent(payload: payload)
+    } catch {
+      logFailure(definitionId: definitionId, activityName: context.attributes.name, message: error.localizedDescription)
+      return .empty
+    }
+  }
+
+  fileprivate static func logFailure(definitionId: String, activityName: String, message: String) {
+    VoltraDynamicLiveActivityRenderFailureReporter.record(
+      activityName: activityName,
+      definitionId: definitionId,
+      message: message
+    )
+  }
+}
+
+private struct VoltraDynamicLiveActivityDynamicIslandRegionView<Attributes: VoltraDynamicLiveActivityDefinition>: View {
+  let definitionId: String
+  let context: ActivityViewContext<Attributes>
+  let region: VoltraRegion
+
+  @Environment(\.colorScheme) private var colorScheme
+  @Environment(\.locale) private var locale
+  @Environment(\.widgetRenderingMode) private var widgetRenderingMode
+
+  var body: some View {
+    VoltraDynamicLiveActivityRenderer.resolve(
+      definitionId: definitionId,
+      context: context,
+      activityFamily: nil,
+      colorScheme: colorScheme,
+      locale: locale,
+      widgetRenderingMode: widgetRenderingMode
+    )
+    .view(for: region, activityId: context.activityID, deepLink: context.attributes.deepLinkUrl)
+  }
+}
+
+private struct VoltraDynamicLiveActivityLockScreenView<Attributes: VoltraDynamicLiveActivityDefinition>: View {
+  let definitionId: String
+  let context: ActivityViewContext<Attributes>
+
+  @Environment(\.colorScheme) private var colorScheme
+  @Environment(\.locale) private var locale
+  @Environment(\.widgetRenderingMode) private var widgetRenderingMode
+
+  var body: some View {
+    let content = VoltraDynamicLiveActivityRenderer.resolve(
+      definitionId: definitionId,
+      context: context,
+      activityFamily: nil,
+      colorScheme: colorScheme,
+      locale: locale,
+      widgetRenderingMode: widgetRenderingMode
+    )
+    if let tint = content.payload?.activityBackgroundTint, let color = JSColorParser.parse(tint) {
+      content.view(for: .lockScreen, activityId: context.activityID, deepLink: context.attributes.deepLinkUrl)
+        .activityBackgroundTint(color)
+    } else {
+      content.view(for: .lockScreen, activityId: context.activityID, deepLink: context.attributes.deepLinkUrl)
+    }
+  }
+}
+
+@available(iOS 18.0, *)
+private struct VoltraDynamicLiveActivityAdaptiveLockScreenView<Attributes: VoltraDynamicLiveActivityDefinition>: View {
+  let definitionId: String
+  let context: ActivityViewContext<Attributes>
+
+  @Environment(\.activityFamily) private var activityFamily
+  @Environment(\.colorScheme) private var colorScheme
+  @Environment(\.locale) private var locale
+  @Environment(\.widgetRenderingMode) private var widgetRenderingMode
+
+  var body: some View {
+    let content = VoltraDynamicLiveActivityRenderer.resolve(
+      definitionId: definitionId,
+      context: context,
+      activityFamily: String(describing: activityFamily),
+      colorScheme: colorScheme,
+      locale: locale,
+      widgetRenderingMode: widgetRenderingMode
+    )
+    familyContent(content: content)
+      .voltraIfLet(content.payload?.activityBackgroundTint.flatMap { JSColorParser.parse($0) }) { view, color in
+        view.activityBackgroundTint(color)
+      }
+  }
+
+  @ViewBuilder
+  private func familyContent(content: VoltraDynamicLiveActivityResolvedContent) -> some View {
+    if activityFamily == .small {
+      smallFamilyContent(content: content)
+    } else {
+      content.view(for: .lockScreen, activityId: context.activityID, deepLink: context.attributes.deepLinkUrl)
+    }
+  }
+
+  @ViewBuilder
+  private func smallFamilyContent(content: VoltraDynamicLiveActivityResolvedContent) -> some View {
+    if content.hasContent(for: .supplementalActivityFamiliesSmall) {
+      content.view(
+        for: .supplementalActivityFamiliesSmall,
+        activityId: context.activityID,
+        deepLink: context.attributes.deepLinkUrl
+      )
+    } else if content.hasContent(for: .islandCompactLeading) || content.hasContent(for: .islandCompactTrailing) {
+      HStack(spacing: 0) {
+        content.view(for: .islandCompactLeading, activityId: context.activityID, deepLink: context.attributes.deepLinkUrl)
+        Spacer()
+        content.view(for: .islandCompactTrailing, activityId: context.activityID, deepLink: context.attributes.deepLinkUrl)
+      }
+      .frame(maxWidth: .infinity)
+    }
+  }
+}
+
+private struct VoltraDynamicLiveActivityResolvedContent {
+  static let empty = VoltraDynamicLiveActivityResolvedContent(payload: nil)
+
+  let payload: VoltraLiveActivityPayload?
+
+  func hasContent(for region: VoltraRegion) -> Bool {
+    !(payload?.regions[region] ?? []).isEmpty
+  }
+
+  @ViewBuilder
+  func view(for region: VoltraRegion, activityId: String, deepLink: String?) -> some View {
+    if let nodes = payload?.regions[region], !nodes.isEmpty {
+      let root: VoltraNode = nodes.count == 1 ? nodes[0] : .array(nodes)
+      Voltra(root: root, activityId: activityId)
+        .voltraIfLet(deepLink.flatMap(VoltraDeepLinkResolver.resolveUrl)) { view, url in view.widgetURL(url) }
+    }
+  }
+}
+
+/// WidgetKit may independently ask each Dynamic Island region to render. Cache
+/// the complete variants shape per ActivityKit state/environment so all regions
+/// share one JS evaluation and one failure diagnostic. `Key.revision` ties each
+/// entry to the bundle bytes it was rendered from, so a hot reload (which
+/// rewrites the source) never serves a stale render.
+private final class VoltraDynamicLiveActivityRenderCache: @unchecked Sendable {
+  struct Key: Hashable {
+    let activityId: String
+    let definitionId: String
+    let revision: String
+    let props: String
+    let activityFamily: String?
+    let colorScheme: String
+    let locale: String
+    let widgetRenderingMode: String
+    let isStale: Bool
+  }
+
+  static let shared = VoltraDynamicLiveActivityRenderCache()
+  private let lock = NSLock()
+  private var values: [Key: VoltraDynamicLiveActivityResolvedContent] = [:]
+
+  func resolve(_ key: Key, render: () -> VoltraDynamicLiveActivityResolvedContent) -> VoltraDynamicLiveActivityResolvedContent {
+    lock.lock()
+    defer { lock.unlock() }
+    if let existing = values[key] {
+      return existing
+    }
+    let resolved = render()
+    if values.count >= 100 {
+      values.removeAll(keepingCapacity: true)
+    }
+    values[key] = resolved
+    return resolved
+  }
+}
+
+private enum VoltraDynamicLiveActivityEnvironmentBuilder {
+  static func build(
+    date: Date,
+    colorScheme: ColorScheme?,
+    locale: Locale,
+    widgetRenderingMode: WidgetRenderingMode,
+    isStale: Bool,
+    activityFamily: String?
+  ) -> String {
+    #if DEBUG
+      let isDev = true
+      let metroURL: String? = VoltraWidgetDefaults.devServerURL() ?? "http://localhost:8081"
+    #else
+      let isDev = false
+      let metroURL: String? = nil
+    #endif
+    let build: [String: Any] = [
+      "isDev": isDev,
+      "metroUrl": metroURL as Any,
+      "appVersion": Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "unknown",
+      "voltraVersion": VoltraConfig.voltraVersion(),
+    ]
+    var environment: [String: Any] = [
+      "date": Int(date.timeIntervalSince1970 * 1000),
+      "colorScheme": String(describing: colorScheme ?? .light),
+      "locale": locale.identifier,
+      "widgetRenderingMode": String(describing: widgetRenderingMode),
+      "build": build,
+      "isStale": isStale,
+    ]
+    if let activityFamily {
+      environment["activityFamily"] = activityFamily
+    }
+    guard
+      let data = try? JSONSerialization.data(withJSONObject: environment),
+      let json = String(data: data, encoding: .utf8)
+    else {
+      return "{}"
+    }
+    return json
+  }
+}

package/ios/shared/dynamic-live-activity/VoltraDynamicLiveActivityTypes.swift

@@ -0,0 +1,87 @@
+import Foundation
+
+#if os(iOS)
+  import ActivityKit
+#endif
+
+/// The JSON-compatible value type used by Dynamic Live Activity props.
+///
+/// This deliberately models only values that can cross the ActivityKit and
+/// JavaScript boundaries without a definition-specific schema.
+public indirect enum VoltraDynamicLiveActivityJSONValue: Codable, Hashable {
+  case null
+  case bool(Bool)
+  case number(Double)
+  case string(String)
+  case array([VoltraDynamicLiveActivityJSONValue])
+  case object([String: VoltraDynamicLiveActivityJSONValue])
+
+  public init(from decoder: Decoder) throws {
+    let container = try decoder.singleValueContainer()
+    if container.decodeNil() {
+      self = .null
+    } else if let value = try? container.decode(Bool.self) {
+      self = .bool(value)
+    } else if let value = try? container.decode(Double.self) {
+      self = .number(value)
+    } else if let value = try? container.decode(String.self) {
+      self = .string(value)
+    } else if let value = try? container.decode([VoltraDynamicLiveActivityJSONValue].self) {
+      self = .array(value)
+    } else if let value = try? container.decode([String: VoltraDynamicLiveActivityJSONValue].self) {
+      self = .object(value)
+    } else {
+      throw DecodingError.dataCorruptedError(
+        in: container,
+        debugDescription: "Expected a JSON-compatible value"
+      )
+    }
+  }
+
+  public func encode(to encoder: Encoder) throws {
+    var container = encoder.singleValueContainer()
+    switch self {
+    case .null:
+      try container.encodeNil()
+    case let .bool(value):
+      try container.encode(value)
+    case let .number(value):
+      try container.encode(value)
+    case let .string(value):
+      try container.encode(value)
+    case let .array(value):
+      try container.encode(value)
+    case let .object(value):
+      try container.encode(value)
+    }
+  }
+}
+
+/// The generic state shared by every generated Dynamic Live Activity type.
+/// Every ActivityKit update replaces the complete props record.
+public struct VoltraDynamicLiveActivityContentState: Codable, Hashable {
+  public let props: [String: VoltraDynamicLiveActivityJSONValue]
+
+  public init(props: [String: VoltraDynamicLiveActivityJSONValue]) {
+    self.props = props
+  }
+}
+
+public enum VoltraDynamicLiveActivityError: Error {
+  case unknownDefinition(String)
+  case payloadTooLarge(size: Int)
+  case rendererMismatch
+  case resourceUnavailable(Error)
+}
+
+// ActivityKit is unavailable to the macOS SwiftPM test target. The JSON props
+// contract above remains independently testable there.
+#if os(iOS)
+  /// Metadata and static attributes supplied by each generated definition.
+  public protocol VoltraDynamicLiveActivityDefinition: ActivityAttributes where ContentState == VoltraDynamicLiveActivityContentState {
+    static var definitionId: String { get }
+    var name: String { get }
+    var deepLinkUrl: String? { get }
+    init(name: String, deepLinkUrl: String?)
+  }
+#endif

package/ios/shared/dynamic-live-activity/VoltraLiveActivityOrder.swift

@@ -0,0 +1,19 @@
+import Foundation
+
+/// Reconciles a persisted cross-engine creation order with ActivityKit's
+/// currently active IDs, pruning ended activities and appending new discoveries.
+public enum VoltraLiveActivityOrder {
+  public static func reconcile(previous: [String], active: [String]) -> [String] {
+    let activeIds = Set(active)
+    var seen = Set<String>()
+    var result: [String] = []
+
+    for id in previous where activeIds.contains(id) && seen.insert(id).inserted {
+      result.append(id)
+    }
+    for id in active where seen.insert(id).inserted {
+      result.append(id)
+    }
+    return result
+  }
+}

package/ios/target/VoltraClientWidgetRuntime.swift

@@ -41,6 +41,12 @@ public struct VoltraClientWidgetEntry: TimelineEntry {
   /// process, where the provider's process-static JSContext is empty. The View re-evaluates from
   /// this source so `render()` always has the widget's function available in its own process.
   public let bundleSource: String?
+  /// How the last server fetch went, as `env.serverUpdate`, for a widget that has a `serverUpdate`
+  /// in app.json. `nil` for every other Dynamic Widget, and the reason `env.serverUpdate` is
+  /// `undefined` there. Carried on the entry rather than read at render time because the provider
+  /// is the thing that knows the fetch outcome, and WidgetKit re-renders archived entries in a
+  /// fresh process.
+  public let serverUpdateJSON: String?
 
   public init(
     date: Date,
@@ -48,7 +54,8 @@ public struct VoltraClientWidgetEntry: TimelineEntry {
     bundleReady: Bool,
     errorMessage: String? = nil,
     configuration: [String: String] = [:],
-    bundleSource: String? = nil
+    bundleSource: String? = nil,
+    serverUpdateJSON: String? = nil
   ) {
     self.date = date
     self.widgetId = widgetId
@@ -56,6 +63,20 @@ public struct VoltraClientWidgetEntry: TimelineEntry {
     self.errorMessage = errorMessage
     self.configuration = configuration
     self.bundleSource = bundleSource
+    self.serverUpdateJSON = serverUpdateJSON
+  }
+
+  /// The same entry, told how the server side is doing.
+  public func withServerUpdate(_ serverUpdateJSON: String?) -> VoltraClientWidgetEntry {
+    VoltraClientWidgetEntry(
+      date: date,
+      widgetId: widgetId,
+      bundleReady: bundleReady,
+      errorMessage: errorMessage,
+      configuration: configuration,
+      bundleSource: bundleSource,
+      serverUpdateJSON: serverUpdateJSON
+    )
   }
 }
 
@@ -234,10 +255,12 @@ public enum VoltraClientWidgetEnvBuilder {
     widgetRenderingMode: WidgetRenderingMode,
     showsWidgetContainerBackground: Bool,
     locale: Locale,
-    configuration: [String: String]
+    configuration: [String: String],
+    serverUpdateJSON: String? = nil
   ) -> String {
     let timestampMs = Int(date.timeIntervalSince1970 * 1000)
     let appVersion = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "unknown"
+    let voltraVersion = VoltraConfig.voltraVersion()
 
     #if DEBUG
       let isDev = true
@@ -253,7 +276,7 @@ public enum VoltraClientWidgetEnvBuilder {
       "isDev": \(isDev),
       "metroUrl": \(metroUrlLiteral),
       "appVersion": \(jsonString(appVersion)),
-      "voltraVersion": \(jsonString("1.4.1"))
+      "voltraVersion": \(jsonString(voltraVersion))
     }
     """
 
@@ -267,6 +290,15 @@ public enum VoltraClientWidgetEnvBuilder {
       configurationJSON = "{ \(entries) }"
     }
 
+    // Only a server-driven widget gets env.serverUpdate; leaving the key out entirely is what
+    // makes it `undefined` for every other Dynamic Widget.
+    let serverUpdateEntry = serverUpdateJSON.map { ",\n  \"serverUpdate\": \($0)" } ?? ""
+
+    // The instance key (ADR 0007): the hash of this placement's merged configuration, or absent
+    // for a widget with no configuration parameters at all — matching what the request builder
+    // sends and what WidgetScope.of(widgetId, configuration:) resolves to.
+    let instanceEntry = WidgetCanonicalConfiguration.key(configuration).map { ",\n  \"instance\": \(jsonString($0))" } ?? ""
+
     return """
     {
       "date": \(timestampMs),
@@ -276,7 +308,7 @@ public enum VoltraClientWidgetEnvBuilder {
       "widgetRenderingMode": \(jsonString(renderingModeString(widgetRenderingMode))),
       "showsWidgetContainerBackground": \(showsWidgetContainerBackground),
       "configuration": \(configurationJSON),
-      "build": \(buildJSON)
+      "build": \(buildJSON)\(serverUpdateEntry)\(instanceEntry)
     }
     """
   }
@@ -349,11 +381,17 @@ public struct VoltraClientWidgetContentView: View {
         widgetRenderingMode: widgetRenderingMode,
         showsWidgetContainerBackground: showsWidgetContainerBackground,
         locale: locale,
-        configuration: entry.configuration
+        configuration: entry.configuration,
+        serverUpdateJSON: entry.serverUpdateJSON
       )
+      // This placement's scope (ADR 0007): an instance of its merged configuration, or the plain
+      // widget scope when it has none — which is also every widget's scope before this ADR.
+      let scope = WidgetScope.of(entry.widgetId, configuration: entry.configuration)
       let dynamicWidgetPropsStore = DynamicWidgetPropsStore()
       let dynamicWidgetRenderCoordinator = DynamicWidgetRenderCoordinator(
-        dynamicWidgetPropsProvider: dynamicWidgetPropsStore.dynamicWidgetProps(for:),
+        // Reads the instance slot for `scope`'s key, falling back to the widget slot when the
+        // placement has not fetched yet or has no configuration.
+        dynamicWidgetPropsProvider: { _ in dynamicWidgetPropsStore.dynamicWidgetProps(for: scope) },
         dynamicWidgetRuntimeBoundary: { dynamicWidgetID, dynamicWidgetPropsJSON, dynamicWidgetEnvironmentJSON in
           VoltraJSRenderer.render(
             widgetId: dynamicWidgetID,