@use-voltra/ios-client 2.2.0 → 2.3.1

package/ios/target/VoltraDynamicWidgetServerUpdateProvider.swift

@@ -0,0 +1,204 @@
+import Foundation
+import SwiftUI
+import WidgetKit
+
+/// Timeline provider for a Dynamic Widget that has a `serverUpdate`.
+///
+/// It wraps `VoltraClientWidgetProvider` rather than replacing it: the bundle load, the render and
+/// the fallback to the prerendered initial state are exactly what they are for any Dynamic Widget.
+/// What this adds is a fetch on `getTimeline`, a commit of the fetched props into the widget's
+/// existing props slot, and a schedule — a plain Dynamic Widget's timeline is `.never`, so without
+/// one nothing would ever ask again.
+///
+/// `placeholder` and `getSnapshot` stay local. Apple's guidance is to keep the gallery preview off
+/// the network, and a snapshot that waited for a fetch would show a spinner in the widget picker.
+public struct VoltraDynamicWidgetServerUpdateProvider: TimelineProvider {
+  public let widgetId: String
+  public let initialState: Data?
+
+  public init(widgetId: String, initialState: Data? = nil) {
+    self.widgetId = widgetId
+    self.initialState = initialState
+  }
+
+  /// The scope for one placement's merged configuration (ADR 0007): `.instance` when WidgetKit
+  /// handed this timeline request a non-empty configuration, `.widget` when it did not — which is
+  /// also the scope of every widget before this ADR. WidgetKit derives the key itself; there is no
+  /// separate placement id to key off, so this is the only identity an iOS placement can have.
+  private func scope(for configuration: [String: String]) -> WidgetScope {
+    .of(widgetId, configuration: configuration)
+  }
+
+  public func placeholder(in _: Context) -> VoltraClientWidgetEntry {
+    VoltraClientWidgetEntry(date: Date(), widgetId: widgetId, bundleReady: false)
+  }
+
+  public func getSnapshot(in _: Context, completion: @escaping (VoltraClientWidgetEntry) -> Void) {
+    Task { completion(await localEntry(configuration: [:])) }
+  }
+
+  public func getTimeline(in context: Context, completion: @escaping (Timeline<VoltraClientWidgetEntry>) -> Void) {
+    Task {
+      completion(await timeline(family: context.family, configuration: [:]))
+    }
+  }
+
+  /// Shared with the generated `AppIntentTimelineProvider`s, which pass the user-configured
+  /// parameters as `configuration`.
+  public static func timeline(
+    widgetId: String,
+    family: WidgetFamily,
+    configuration: [String: String]
+  ) async -> Timeline<VoltraClientWidgetEntry> {
+    await VoltraDynamicWidgetServerUpdateProvider(widgetId: widgetId).timeline(
+      family: family,
+      configuration: configuration
+    )
+  }
+
+  func timeline(family: WidgetFamily, configuration: [String: String]) async -> Timeline<VoltraClientWidgetEntry> {
+    let scope = scope(for: configuration)
+    let settings = VoltraWidgetServer.resolver.resolve(scope)
+
+    guard settings.shouldFetch else {
+      // No URL yet, or the app has taken the widget over. Either way there is nothing to schedule:
+      // the app reloads the widget itself, and setting a URL later queues a reload of its own.
+      DynamicWidgetServerPropsStore().markDisabledIfNeeded(enabled: settings.enabled, for: scope)
+
+      return Timeline(entries: [await localEntry(configuration: configuration)], policy: .never)
+    }
+
+    var nextIntervalMinutes = settings.intervalMinutes
+
+    if await shouldFetch(scope) {
+      let result = await runner(family: family, configuration: configuration).run(scope)
+
+      // What the server asked for wins over the configured interval: `Cache-Control: max-age` on a
+      // success, `Retry-After` on a 429 or 503.
+      if let asked = result.nextIntervalMinutes {
+        nextIntervalMinutes = asked
+      } else if result.outcome == .retry || result.outcome == .failed {
+        // A failure the server did not put a number on. Coming back sooner than the widget's own
+        // interval would spend the reload budget on an endpoint that is already unhappy, so the
+        // floor is used rather than the configured value only when that is shorter.
+        nextIntervalMinutes = max(settings.intervalMinutes, WidgetServerUpdateDefaults.minIntervalMinutes)
+      }
+    }
+
+    let entry = await localEntry(configuration: configuration)
+    let nextUpdate = Date().addingTimeInterval(TimeInterval(nextIntervalMinutes * 60))
+
+    return Timeline(entries: [entry], policy: .after(nextUpdate))
+  }
+
+  /// Whether this timeline request should fetch, or ride on one that just happened.
+  ///
+  /// Skipped for a moment after `updateDynamicWidget` writes props, so an optimistic update is not
+  /// wiped out by the very reload it triggered. ADR 0002 says the *next scheduled* fetch overwrites
+  /// app-written props, not the one the write itself caused.
+  ///
+  /// Keyed by `scope`, so two placements with different configurations coalesce independently
+  /// (ADR 0007) — WidgetKit calling the timeline once per placement per family collapses onto one
+  /// fetch per distinct configuration, not one fetch total.
+  private func shouldFetch(_ scope: WidgetScope) async -> Bool {
+    if let writtenAt = DynamicWidgetServerPropsStore().appWriteAt(for: scope),
+       Date().timeIntervalSince(writtenAt) < DynamicWidgetServerFetchCoordinator.defaultCoalesceInterval
+    {
+      return false
+    }
+
+    return await DynamicWidgetServerFetchCoordinator.shared.shouldFetch(scope)
+  }
+
+  /// The entry a widget renders from: the bundle, the configuration, and how the last fetch went.
+  /// The props themselves are read by the view from the same slot `updateDynamicWidget` writes, so
+  /// the render path does not know where they came from.
+  private func localEntry(configuration: [String: String]) async -> VoltraClientWidgetEntry {
+    let entry = await VoltraClientWidgetProvider.loadEntry(widgetId: widgetId, configuration: configuration)
+
+    return entry.withServerUpdate(DynamicWidgetServerPropsStore().status(for: scope(for: configuration)).toJSON())
+  }
+
+  private func runner(family: WidgetFamily, configuration: [String: String]) -> DynamicWidgetServerUpdateRunner {
+    let statuses = DynamicWidgetServerPropsStore()
+
+    return DynamicWidgetServerUpdateRunner(
+      resolveSettings: { VoltraWidgetServer.resolver.resolve($0) },
+      currentRevision: { VoltraWidgetServer.resolver.revision($0) },
+      readEtag: { WidgetServerEtagStore.etag(for: $0, url: $1) },
+      fetch: { scope, settings, etag in
+        guard let request = WidgetServerRequestBuilder.build(
+          scope: scope,
+          settings: settings,
+          // No `family`: one fetch serves every size and instance of a Dynamic Widget, so its
+          // props must be size-agnostic and the entry picks its layout from env.widgetFamily.
+          context: VoltraWidgetAppearance.requestContext(),
+          etag: etag,
+          configuration: configuration
+        ) else {
+          return .networkFailure(message: "Could not build a request")
+        }
+
+        return await WidgetServerFetcher.fetch(request)
+      },
+      writeEtag: { WidgetServerEtagStore.put($2, for: $0, url: $1) },
+      trialRender: { scope, props in
+        VoltraDynamicWidgetTrialRender.canRender(
+          widgetId: scope.widgetId,
+          propsJSON: props,
+          family: family,
+          configuration: configuration
+        )
+      },
+      // Instance-aware (ADR 0007): commits to the instance slot for a `.instance` scope, and the
+      // widget slot for `.widget` — a widget with no configuration parameters keeps writing
+      // exactly where it always has.
+      commitProps: { scope, props in
+        try DynamicWidgetPropsStore().persistInstanceDynamicWidgetProps(props, for: scope)
+      },
+      recordSuccess: { statuses.recordSuccess(fetchedAt: $1, httpStatus: $2, for: $0) },
+      recordFailure: { statuses.recordFailure($1, httpStatus: $2, for: $0) },
+      markDisabled: { statuses.markDisabledIfNeeded(enabled: $1, for: $0) }
+    )
+  }
+}
+
+/// Renders fetched props once, off screen, before they are allowed anywhere near the widget.
+///
+/// The trial uses one environment — the family WidgetKit asked the timeline for, in the current
+/// appearance. A widget that only throws for another family slips through, and ADR 0002 accepts
+/// that: rendering every supported family on every fetch would cost more than the failure it
+/// prevents, inside a 30 MB extension.
+enum VoltraDynamicWidgetTrialRender {
+  static func canRender(
+    widgetId: String,
+    propsJSON: String,
+    family: WidgetFamily,
+    configuration: [String: String]
+  ) -> Bool {
+    // env.serverUpdate is deliberately absent here. The trial asks whether the props render, and a
+    // widget that only fails when told the fetch went badly is a different problem from props that
+    // cannot be drawn.
+    let envJSON = VoltraClientWidgetEnvBuilder.build(
+      date: Date(),
+      widgetFamily: family,
+      colorScheme: nil,
+      widgetRenderingMode: .fullColor,
+      showsWidgetContainerBackground: true,
+      locale: Locale.current,
+      configuration: configuration
+    )
+
+    guard let resolved = VoltraJSRenderer.render(widgetId: widgetId, propsJSON: propsJSON, envJSON: envJSON),
+          let json = try? JSONValue.parse(from: resolved)
+    else {
+      return false
+    }
+
+    if case .empty = VoltraNode.parse(from: json) {
+      return false
+    }
+
+    return true
+  }
+}

package/ios/target/VoltraHomeWidget.swift

@@ -122,6 +122,14 @@ public struct VoltraHomeWidgetProvider: TimelineProvider {
   public let widgetId: String
   public let initialState: Data?
 
+  /// Last successful server response per widget, shared by every provider instance in this
+  /// extension process. Backs fetch coalescing and the fallback when a fetch fails, without
+  /// depending on an App Group being configured.
+  private static let serverResponseStore = ServerWidgetResponseStore()
+
+  /// How long WidgetKit waits before asking again after a fetch failed.
+  private static let retryInterval: TimeInterval = 900
+
   public init(widgetId: String, initialState: Data? = nil) {
     self.widgetId = widgetId
     self.initialState = initialState
@@ -132,126 +140,107 @@ public struct VoltraHomeWidgetProvider: TimelineProvider {
   }
 
   public func getSnapshot(in context: Context, completion: @escaping (VoltraHomeWidgetEntry) -> Void) {
-    // Prioritize timeline data for consistency with getTimeline
-    if let timeline = VoltraHomeWidgetStore.readTimeline(widgetId: widgetId),
-       let firstEntry = timeline.entries.first
-    {
-      let node = parseJsonToNode(data: firstEntry.json, family: context.family)
-      completion(VoltraHomeWidgetEntry(
-        date: Date(),
-        rootNode: node,
-        widgetId: widgetId,
-        deepLinkUrl: firstEntry.deepLinkUrl
-      ))
-      return
-    }
-
-    // Fallback to single-entry data
-    let data = VoltraHomeWidgetStore.readJson(widgetId: widgetId) ?? initialState
-    let node = data.flatMap { parseJsonToNode(data: $0, family: context.family) }
-    completion(VoltraHomeWidgetEntry(date: Date(), rootNode: node, widgetId: widgetId))
+    // Snapshots come from local data so the gallery preview never waits on the network.
+    completion(localTimeline(in: context, policy: .never).entries.first ?? placeholder(in: context))
   }
 
   public func getTimeline(in context: Context, completion: @escaping (Timeline<VoltraHomeWidgetEntry>) -> Void) {
-    // Prune expired timeline entries if any exist
-    VoltraHomeWidgetStore.pruneExpiredEntries(widgetId: widgetId)
-
-    // Check if server-driven updates are configured for this widget
-    if VoltraWidgetServerFetcher.serverUrl(for: widgetId) != nil {
-      getServerDrivenTimeline(in: context, completion: completion)
+    guard VoltraWidgetServerFetcher.serverUrl(for: widgetId) != nil else {
+      completion(localTimeline(in: context, policy: .never))
       return
     }
 
-    // Local-only mode: use existing data from UserDefaults
-    getLocalTimeline(in: context, completion: completion)
-  }
-
-  // MARK: - Server-Driven Timeline
-
-  private static var lastFetchTimes: [String: Date] = [:]
-  private static let coalesceInterval: TimeInterval = 3 // seconds
-
-  /// Fetch widget content from a remote Voltra SSR server and build a timeline.
-  private func getServerDrivenTimeline(in context: Context, completion: @escaping (Timeline<VoltraHomeWidgetEntry>) -> Void) {
-    let familyKey = familyToKey(context.family)
-    let intervalMinutes = VoltraWidgetServerFetcher.updateInterval(for: widgetId)
+    Task { completion(await serverTimeline(in: context)) }
+  }
+
+  // MARK: - Server-driven timeline
+
+  private func serverTimeline(in context: Context) async -> Timeline<VoltraHomeWidgetEntry> {
+    let resolver = ServerWidgetContentResolver(
+      responseStore: Self.serverResponseStore,
+      fetch: { widgetId in try await fetchServerContent(widgetId: widgetId, in: context) }
+    )
+
+    switch await resolver.resolve(widgetId: widgetId) {
+    case let .current(data):
+      let intervalMinutes = VoltraWidgetServerFetcher.updateInterval(for: widgetId)
+      let nextUpdate = Calendar.current.date(byAdding: .minute, value: intervalMinutes, to: Date()) ?? retryDate
+      return serverTimeline(from: data, in: context, policy: .after(nextUpdate))
+    case let .lastKnown(data, error):
+      // A 304 is not a failure: the server confirmed what we already have is current, so the next
+      // fetch belongs at the normal interval rather than the shorter retry one.
+      if case VoltraWidgetServerFetcher.FetchError.notModified = error {
+        let intervalMinutes = VoltraWidgetServerFetcher.updateInterval(for: widgetId)
+        let nextUpdate = Calendar.current.date(byAdding: .minute, value: intervalMinutes, to: Date()) ?? retryDate
+        return serverTimeline(from: data, in: context, policy: .after(nextUpdate))
+      }
 
-    // Coalesce: if we fetched for this widget very recently, use cached data.
-    // The server returns all families in every response, so subsequent getTimeline
-    // calls for different families can safely use the just-cached response —
-    // selectContentForFamily will pick the correct family-specific content.
-    if let lastFetch = Self.lastFetchTimes[widgetId],
-       Date().timeIntervalSince(lastFetch) < Self.coalesceInterval
-    {
-      VoltraLogger.widget.info("Coalescing fetch for '\(widgetId)' family '\(familyKey)' (last fetch \(Date().timeIntervalSince(lastFetch))s ago)")
-      getLocalTimeline(in: context, completion: completion)
-      return
+      VoltraLogger.widget.error("Server-driven update failed for '\(widgetId)', keeping last server content: \(error.localizedDescription)")
+      return serverTimeline(from: data, in: context, policy: .after(retryDate))
+    case let .unavailable(error):
+      VoltraLogger.widget.error("Server-driven update failed for '\(widgetId)', falling back to local data: \(error.localizedDescription)")
+      return localTimeline(in: context, policy: .after(retryDate))
     }
+  }
 
-    Task {
-      do {
-        let data = try await VoltraWidgetServerFetcher.fetchWidgetContent(
-          widgetId: widgetId,
-          family: familyKey
-        )
-
-        // Record that we just fetched successfully
-        Self.lastFetchTimes[widgetId] = Date()
-
-        let node = parseJsonToNode(data: data, family: context.family)
+  /// Fetch, validate, and persist one server response. Throws on network errors and on responses
+  /// that do not parse into a widget tree, so they are never treated as good content.
+  private func fetchServerContent(widgetId: String, in context: Context) async throws -> Data {
+    let data = try await VoltraWidgetServerFetcher.fetchWidgetContent(
+      widgetId: widgetId,
+      family: familyToKey(context.family)
+    )
 
-        // Only cache the data after successful parsing to avoid overwriting
-        // good cached content with unparseable responses
-        if node != nil, let jsonString = String(data: data, encoding: .utf8) {
-          try? VoltraWidgetDefaults.setWidgetJson(jsonString, for: widgetId, deepLinkUrl: nil)
-        }
+    guard parseJsonToNode(data: data, family: context.family) != nil else {
+      throw UnparseableServerContentError()
+    }
 
-        let entry = VoltraHomeWidgetEntry(date: Date(), rootNode: node, widgetId: widgetId)
+    // Best-effort on-disk copy so a fresh extension process has something to fall back to.
+    // Requires an App Group; without one the in-memory store above still covers this process.
+    if let jsonString = String(data: data, encoding: .utf8) {
+      try? VoltraWidgetDefaults.setWidgetJson(jsonString, for: widgetId, deepLinkUrl: nil)
+    }
 
-        // Schedule next update based on configured interval
-        let nextUpdate = Calendar.current.date(byAdding: .minute, value: intervalMinutes, to: Date()) ?? Date().addingTimeInterval(900)
-        completion(Timeline(entries: [entry], policy: .after(nextUpdate)))
+    VoltraLogger.widget.info("Server-driven update succeeded for '\(widgetId)'")
+    return data
+  }
 
-        VoltraLogger.widget.info("Server-driven update succeeded for '\(widgetId)', next update in \(intervalMinutes)m")
-      } catch {
-        VoltraLogger.widget.error("Server-driven update failed for '\(widgetId)': \(error.localizedDescription)")
+  private func serverTimeline(
+    from data: Data,
+    in context: Context,
+    policy: TimelineReloadPolicy
+  ) -> Timeline<VoltraHomeWidgetEntry> {
+    let node = parseJsonToNode(data: data, family: context.family)
+    let entry = VoltraHomeWidgetEntry(date: Date(), rootNode: node, widgetId: widgetId)
+    return Timeline(entries: [entry], policy: policy)
+  }
 
-        // Fall back to local data on network failure
-        getLocalTimeline(in: context, completion: completion)
-      }
-    }
+  private var retryDate: Date {
+    Date().addingTimeInterval(Self.retryInterval)
   }
 
-  // MARK: - Local Timeline
+  // MARK: - Local timeline
 
   /// Build a timeline from locally stored data (UserDefaults / initial state).
-  private func getLocalTimeline(in context: Context, completion: @escaping (Timeline<VoltraHomeWidgetEntry>) -> Void) {
+  private func localTimeline(in context: Context, policy: TimelineReloadPolicy) -> Timeline<VoltraHomeWidgetEntry> {
+    VoltraHomeWidgetStore.pruneExpiredEntries(widgetId: widgetId)
+
     if let timeline = VoltraHomeWidgetStore.readTimeline(widgetId: widgetId), !timeline.entries.isEmpty {
       let entries = timeline.entries.map { timelineEntry in
-        let node = parseJsonToNode(data: timelineEntry.json, family: context.family)
-        return VoltraHomeWidgetEntry(
+        VoltraHomeWidgetEntry(
           date: timelineEntry.date,
-          rootNode: node,
+          rootNode: parseJsonToNode(data: timelineEntry.json, family: context.family),
           widgetId: widgetId,
           deepLinkUrl: timelineEntry.deepLinkUrl
         )
       }
-      completion(Timeline(entries: entries, policy: .never))
-      return
+      return Timeline(entries: entries, policy: policy)
     }
 
-    // Fallback to single-entry behavior
     let data = VoltraHomeWidgetStore.readJson(widgetId: widgetId) ?? initialState
     let node = data.flatMap { parseJsonToNode(data: $0, family: context.family) }
     let entry = VoltraHomeWidgetEntry(date: Date(), rootNode: node, widgetId: widgetId)
-
-    // If server updates are configured but we're in fallback, retry sooner
-    if VoltraWidgetServerFetcher.serverUrl(for: widgetId) != nil {
-      let retryDate = Date().addingTimeInterval(900) // Retry in 15 minutes
-      completion(Timeline(entries: [entry], policy: .after(retryDate)))
-    } else {
-      completion(Timeline(entries: [entry], policy: .never))
-    }
+    return Timeline(entries: [entry], policy: policy)
   }
 
   /// Parse JSON data into a VoltraNode for the given widget family.
@@ -273,6 +262,12 @@ public struct VoltraHomeWidgetProvider: TimelineProvider {
   }
 }
 
+private struct UnparseableServerContentError: LocalizedError {
+  var errorDescription: String? {
+    "Server response could not be parsed into a widget tree"
+  }
+}
+
 public struct VoltraHomeWidgetView: View {
   public var entry: VoltraHomeWidgetEntry
 

package/ios/ui/Extensions/VoltraNode+View.swift

@@ -0,0 +1,113 @@
+import Foundation
+import SwiftUI
+
+/// The AST itself lives in `shared/` and knows nothing about SwiftUI. Rendering is attached
+/// here so `shared/` stays free of any dependency on `ui/` and can be compiled — and tested —
+/// on its own. Both directories are built into a single module by the podspecs, so call sites
+/// keep using a `VoltraNode` directly as a view.
+extension VoltraNode: View {
+  public var body: some View {
+    switch self {
+    case let .element(element):
+      VoltraElementView(element: element)
+    case let .array(nodes):
+      // Use stable identifiers: prefer element.id, fall back to index
+      let items: [(id: String, node: VoltraNode)] = nodes.enumerated().map { offset, node in
+        let id: String
+        if case let .element(element) = node, let elementId = element.id {
+          id = elementId
+        } else {
+          id = "idx_\(offset)"
+        }
+        return (id: id, node: node)
+      }
+      ForEach(items, id: \.id) { item in
+        item.node
+      }
+    case let .text(text):
+      Text(text)
+    case .empty:
+      EmptyView()
+    }
+  }
+}
+
+/// View that renders a VoltraElement based on its type
+struct VoltraElementView: View {
+  let element: VoltraElement
+
+  var body: some View {
+    switch element.type {
+    case "Button":
+      VoltraButton(element)
+
+    case "Link":
+      VoltraLink(element)
+
+    case "VStack":
+      VoltraVStack(element)
+
+    case "HStack":
+      VoltraHStack(element)
+
+    case "View":
+      VoltraFlexView(element)
+
+    case "ZStack":
+      VoltraZStack(element)
+
+    case "Text":
+      VoltraText(element)
+
+    case "Image":
+      VoltraImage(element)
+
+    case "Symbol":
+      VoltraSymbol(element)
+
+    case "Divider":
+      VoltraDivider(element)
+
+    case "Spacer":
+      VoltraSpacer(element)
+
+    case "Label":
+      VoltraLabel(element)
+
+    case "Toggle":
+      VoltraToggle(element)
+
+    case "Gauge":
+      VoltraGauge(element)
+
+    case "LinearProgressView":
+      VoltraLinearProgressView(element)
+
+    case "CircularProgressView":
+      VoltraCircularProgressView(element)
+
+    case "Timer":
+      VoltraTimer(element)
+
+    case "GroupBox":
+      VoltraGroupBox(element)
+
+    case "LinearGradient":
+      VoltraLinearGradient(element)
+
+    case "GlassContainer":
+      VoltraGlassContainer(element)
+
+    case "Mask":
+      VoltraMask(element)
+
+    case "Chart":
+      if #available(iOS 16.0, macOS 13.0, *) {
+        VoltraChart(element)
+      }
+
+    default:
+      EmptyView()
+    }
+  }
+}

package/ios/ui/Generated/Parameters/ChartParameters.swift

@@ -25,6 +25,9 @@ public struct ChartParameters: ComponentParameters {
   /// Configure y-axis grid line style
   public let yAxisGridStyle: String?
 
+  /// Pin the y-axis lower and/or upper bound
+  public let yScale: String?
+
   /// Show or hide the chart legend
   public let legendVisibility: String?
 

package/ios/ui/Helpers/VoltraDeepLinkResolver.swift

@@ -2,7 +2,7 @@ import ActivityKit
 import Foundation
 import SwiftUI
 
-enum VoltraDeepLinkResolver {
+public enum VoltraDeepLinkResolver {
   static func deepLinkScheme() -> String? {
     if let types = Bundle.main.object(forInfoDictionaryKey: "CFBundleURLTypes") as? [[String: Any]] {
       for t in types {
@@ -26,7 +26,7 @@ enum VoltraDeepLinkResolver {
   /// Resolves a URL string, supporting both absolute and relative paths
   /// - Parameter raw: The URL string (e.g., "myapp://path", "/path", or "path")
   /// - Returns: A resolved URL, or nil if invalid
-  static func resolveUrl(_ raw: String) -> URL? {
+  public static func resolveUrl(_ raw: String) -> URL? {
     guard !raw.isEmpty else { return nil }
 
     // If it's already an absolute URL, use it as-is