@use-voltra/ios-client 2.1.1 → 2.3.0

package/ios/shared/DynamicWidgetPropsStore.swift

@@ -0,0 +1,117 @@
+import Foundation
+
+/// Versioned, per-ID Dynamic Widget props shared by the app and widget extension processes.
+struct DynamicWidgetPropsStore {
+  private let storage: Result<any DynamicWidgetPropsStorage, Error>
+
+  init() {
+    guard let groupIdentifier = VoltraConfig.groupIdentifier() else {
+      storage = .failure(DynamicWidgetPropsStoreError.appGroupNotConfigured)
+      return
+    }
+    guard let userDefaults = UserDefaults(suiteName: groupIdentifier) else {
+      storage = .failure(DynamicWidgetPropsStoreError.userDefaultsUnavailable)
+      return
+    }
+    storage = .success(DynamicWidgetPropsUserDefaultsStorage(userDefaults: userDefaults))
+  }
+
+  init(storage: any DynamicWidgetPropsStorage) {
+    self.storage = .success(storage)
+  }
+
+  /// The type-level (widget-scoped) write path — the app's `updateDynamicWidget`.
+  func persistDynamicWidgetProps(_ dynamicWidgetPropsJSON: String, for dynamicWidgetID: String) throws {
+    try persist(dynamicWidgetPropsJSON, storageKey: Self.storageKey(for: dynamicWidgetID))
+  }
+
+  /// The instance write path — a committed per-instance server fetch (ADR 0007).
+  func persistInstanceDynamicWidgetProps(_ dynamicWidgetPropsJSON: String, for scope: WidgetScope) throws {
+    guard case let .instance(widgetId, key) = scope else {
+      try persistDynamicWidgetProps(dynamicWidgetPropsJSON, for: scope.widgetId)
+      return
+    }
+    try persist(dynamicWidgetPropsJSON, storageKey: VoltraStorageKeys.dynamicWidgetInstancePropsV1(scope.storageKey))
+    try addInstanceKeyToIndex(key, for: widgetId)
+  }
+
+  private func persist(_ dynamicWidgetPropsJSON: String, storageKey: String) throws {
+    let storageEntryJSON = try DynamicWidgetPropsCodec.encodeStorageEntry(
+      dynamicWidgetPropsJSON: dynamicWidgetPropsJSON
+    )
+    let resolvedStorage = try storage.get()
+    try resolvedStorage.set(storageEntryJSON, forKey: storageKey)
+  }
+
+  /// The type-level props only, with no instance fallback — used by the trial render.
+  func dynamicWidgetProps(for dynamicWidgetID: String) -> String {
+    read(storageKey: Self.storageKey(for: dynamicWidgetID)) ?? DynamicWidgetPropsCodec.emptyDynamicWidgetPropsJSON
+  }
+
+  /// Props for one placement: the instance slot for `scope`'s key, falling back to the widget slot
+  /// when the instance has not fetched yet or has no configuration (ADR 0007).
+  func dynamicWidgetProps(for scope: WidgetScope) -> String {
+    switch scope {
+    case let .widget(id):
+      return dynamicWidgetProps(for: id)
+    case .instance:
+      if let instanceProps = read(storageKey: VoltraStorageKeys.dynamicWidgetInstancePropsV1(scope.storageKey)) {
+        return instanceProps
+      }
+      return dynamicWidgetProps(for: scope.widgetId)
+    }
+  }
+
+  private func read(storageKey: String) -> String? {
+    guard case let .success(resolvedStorage) = storage else { return nil }
+    guard let storageEntryJSON = (try? resolvedStorage.string(forKey: storageKey)) ?? nil else {
+      return nil
+    }
+
+    return DynamicWidgetPropsCodec.decodeDynamicWidgetProps(storageEntryJSON: storageEntryJSON)
+  }
+
+  /// Clears the widget-level props and every instance slot of `dynamicWidgetID` (ADR 0007):
+  /// `clearWidget` and logout are meant to reset a widget entirely, not leave stale per-instance
+  /// data behind that a fallback would never reveal again.
+  func clearDynamicWidgetProps(for dynamicWidgetID: String) throws {
+    let resolvedStorage = try storage.get()
+    let instanceKeys = instanceKeys(for: dynamicWidgetID)
+
+    try resolvedStorage.removeObject(forKey: Self.storageKey(for: dynamicWidgetID))
+    try resolvedStorage.removeObject(forKey: VoltraStorageKeys.dynamicWidgetPropsInstanceIndexV1(dynamicWidgetID))
+    for key in instanceKeys {
+      let instanceStorageKey = VoltraStorageKeys.dynamicWidgetInstancePropsV1("\(dynamicWidgetID)#\(key)")
+      try resolvedStorage.removeObject(forKey: instanceStorageKey)
+    }
+  }
+
+  /// The instance keys `dynamicWidgetID` has ever fetched into, so callers can clear per-instance
+  /// state that lives in other stores (status, ETag).
+  func instanceKeys(for dynamicWidgetID: String) -> Set<String> {
+    guard
+      case let .success(resolvedStorage) = storage,
+      let raw = try? resolvedStorage.string(forKey: VoltraStorageKeys.dynamicWidgetPropsInstanceIndexV1(dynamicWidgetID)) ?? nil,
+      let data = raw.data(using: .utf8),
+      let keys = try? JSONDecoder().decode([String].self, from: data)
+    else {
+      return []
+    }
+    return Set(keys)
+  }
+
+  private func addInstanceKeyToIndex(_ key: String, for dynamicWidgetID: String) throws {
+    var current = instanceKeys(for: dynamicWidgetID)
+    guard !current.contains(key) else { return }
+    current.insert(key)
+
+    let resolvedStorage = try storage.get()
+    let data = try JSONEncoder().encode(current.sorted())
+    guard let json = String(data: data, encoding: .utf8) else { return }
+    try resolvedStorage.set(json, forKey: VoltraStorageKeys.dynamicWidgetPropsInstanceIndexV1(dynamicWidgetID))
+  }
+
+  static func storageKey(for dynamicWidgetID: String) -> String {
+    VoltraStorageKeys.dynamicWidgetPropsV1(dynamicWidgetID)
+  }
+}

package/ios/shared/DynamicWidgetRenderCoordinator.swift

@@ -0,0 +1,31 @@
+/// Routes a Dynamic Widget's current persisted props and environment to its runtime boundary.
+struct DynamicWidgetRenderCoordinator {
+  typealias DynamicWidgetPropsProvider = (_ dynamicWidgetID: String) -> String
+  typealias DynamicWidgetRuntimeBoundary = (
+    _ dynamicWidgetID: String,
+    _ dynamicWidgetPropsJSON: String,
+    _ dynamicWidgetEnvironmentJSON: String
+  ) -> String?
+
+  private let dynamicWidgetPropsProvider: DynamicWidgetPropsProvider
+  private let dynamicWidgetRuntimeBoundary: DynamicWidgetRuntimeBoundary
+
+  init(
+    dynamicWidgetPropsProvider: @escaping DynamicWidgetPropsProvider,
+    dynamicWidgetRuntimeBoundary: @escaping DynamicWidgetRuntimeBoundary
+  ) {
+    self.dynamicWidgetPropsProvider = dynamicWidgetPropsProvider
+    self.dynamicWidgetRuntimeBoundary = dynamicWidgetRuntimeBoundary
+  }
+
+  func renderDynamicWidget(
+    dynamicWidgetID: String,
+    dynamicWidgetEnvironmentJSON: String
+  ) -> String? {
+    dynamicWidgetRuntimeBoundary(
+      dynamicWidgetID,
+      dynamicWidgetPropsProvider(dynamicWidgetID),
+      dynamicWidgetEnvironmentJSON
+    )
+  }
+}

package/ios/shared/DynamicWidgetServerUpdate/DynamicWidgetServerFetchResolver.swift

@@ -0,0 +1,34 @@
+import Foundation
+
+/// Collapses a burst of timeline requests for one scope into a single fetch.
+///
+/// WidgetKit asks for a timeline once per widget instance per reload, and tapping the refresh
+/// button produces two reloads for one tap (the intent's own reload plus the automatic
+/// post-intent one). Without this, a widget placed twice in two sizes would fetch four times for
+/// what the user experienced as one refresh — and the reload budget is shared across every widget
+/// in the app.
+///
+/// The payload engine already coalesces this way; this is the same window, keyed by scope so it
+/// keeps working when instances arrive.
+public actor DynamicWidgetServerFetchCoordinator {
+  public static let defaultCoalesceInterval: TimeInterval = 3
+
+  public static let shared = DynamicWidgetServerFetchCoordinator()
+
+  private var lastRun: [WidgetScope: Date] = [:]
+  private let coalesceInterval: TimeInterval
+
+  public init(coalesceInterval: TimeInterval = DynamicWidgetServerFetchCoordinator.defaultCoalesceInterval) {
+    self.coalesceInterval = coalesceInterval
+  }
+
+  /// Whether this request should fetch, or ride on one that just happened.
+  public func shouldFetch(_ scope: WidgetScope, now: Date = Date()) -> Bool {
+    if let last = lastRun[scope], now.timeIntervalSince(last) < coalesceInterval {
+      return false
+    }
+
+    lastRun[scope] = now
+    return true
+  }
+}

package/ios/shared/DynamicWidgetServerUpdate/DynamicWidgetServerProps.swift

@@ -0,0 +1,55 @@
+import Foundation
+
+/// What a `200` body turned out to be.
+public enum DynamicWidgetPropsParseResult: Equatable {
+  case props(String)
+  case invalid(reason: String)
+}
+
+/// Reads a server response as Dynamic Widget props.
+///
+/// The whole point of ADR 0002 is that the server returns data, not UI, so the only thing accepted
+/// here is a JSON object. The one shape called out specially is a Voltra payload: `serverUpdate`
+/// is the same config key for both engines, so pointing a widget with an `entry` at a payload
+/// endpoint is the easy mistake to make, and it has to fail loudly rather than look like unusable
+/// props.
+public enum DynamicWidgetServerProps {
+  public static func parse(_ body: Data) -> DynamicWidgetPropsParseResult {
+    guard !body.isEmpty else {
+      return .invalid(reason: "response body was empty")
+    }
+
+    guard let parsed = try? JSONSerialization.jsonObject(with: body) else {
+      return .invalid(reason: "response body is not JSON; a Dynamic Widget's props must be a JSON object")
+    }
+
+    guard let object = parsed as? [String: Any] else {
+      return .invalid(reason: "response body is not a JSON object; a Dynamic Widget's props must be a JSON object")
+    }
+
+    if looksLikeVoltraPayload(object) {
+      return .invalid(reason: """
+      response body looks like a Voltra payload (top-level 'v' with 'variants' or 'e'). This widget \
+      has an entry, so it renders on the device: return the props it should render, not a rendered \
+      payload.
+      """)
+    }
+
+    guard let normalized = try? JSONSerialization.data(withJSONObject: object),
+          let json = String(data: normalized, encoding: .utf8)
+    else {
+      return .invalid(reason: "response body could not be re-encoded as props")
+    }
+
+    return .props(json)
+  }
+
+  /// A Voltra payload always carries a version under `v` alongside either the size variants a
+  /// widget renders or the shared element table. Props that happen to have a `v` key are not
+  /// mistaken for one.
+  private static func looksLikeVoltraPayload(_ body: [String: Any]) -> Bool {
+    guard body["v"] is Int else { return false }
+
+    return body["variants"] is [String: Any] || body["e"] is [Any]
+  }
+}

package/ios/shared/DynamicWidgetServerUpdate/DynamicWidgetServerPropsStore.swift

@@ -0,0 +1,146 @@
+import Foundation
+
+/// What the widget is told about the server side of its props, as `env.serverUpdate`.
+///
+/// Deliberately not the props themselves: fetched props are committed to the Dynamic Widget's
+/// existing props slot, so the render path cannot tell whether they came from a fetch or from
+/// `updateDynamicWidget`. This record is only the story around them.
+public struct DynamicWidgetServerStatus: Equatable, Codable {
+  public static let fresh = "fresh"
+  public static let stale = "stale"
+  public static let never = "never"
+  public static let disabled = "disabled"
+
+  public static let errorNetwork = "network"
+  public static let errorHttp = "http"
+  public static let errorUnauthorized = "unauthorized"
+  public static let errorParse = "parse"
+  public static let errorRender = "render"
+
+  public let status: String
+  public let fetchedAt: Int?
+  public let error: String?
+  public let httpStatus: Int?
+
+  public init(status: String, fetchedAt: Int? = nil, error: String? = nil, httpStatus: Int? = nil) {
+    self.status = status
+    self.fetchedAt = fetchedAt
+    self.error = error
+    self.httpStatus = httpStatus
+  }
+
+  /// What a widget sees before any fetch has succeeded.
+  public static let neverFetched = DynamicWidgetServerStatus(status: never)
+
+  public func toJSON() -> String {
+    var fields = ["\"status\": \(jsonString(status))"]
+
+    fetchedAt.map { fields.append("\"fetchedAt\": \($0)") }
+    error.map { fields.append("\"error\": \(jsonString($0))") }
+    httpStatus.map { fields.append("\"httpStatus\": \($0)") }
+
+    return "{ \(fields.joined(separator: ", ")) }"
+  }
+
+  private func jsonString(_ value: String) -> String {
+    let escaped = value
+      .replacingOccurrences(of: "\\", with: "\\\\")
+      .replacingOccurrences(of: "\"", with: "\\\"")
+
+    return "\"\(escaped)\""
+  }
+}
+
+/// Per-scope record of how the last fetch went, in the App Group so the app and the widget
+/// extension agree on it.
+///
+/// Kept apart from the props themselves so that clearing a widget's props — logout,
+/// `clearWidget` — and clearing its fetch history stay separate decisions.
+public struct DynamicWidgetServerPropsStore {
+  private let defaults: UserDefaults?
+
+  public init(defaults: UserDefaults? = VoltraConfig.groupIdentifier().flatMap { UserDefaults(suiteName: $0) }) {
+    self.defaults = defaults
+  }
+
+  public func status(for scope: WidgetScope) -> DynamicWidgetServerStatus {
+    guard let data = defaults?.data(forKey: key(scope)),
+          let status = try? JSONDecoder().decode(DynamicWidgetServerStatus.self, from: data)
+    else {
+      return .neverFetched
+    }
+
+    return status
+  }
+
+  public func put(_ status: DynamicWidgetServerStatus, for scope: WidgetScope) {
+    guard let data = try? JSONEncoder().encode(status) else { return }
+
+    defaults?.set(data, forKey: key(scope))
+  }
+
+  /// Records a failure without losing the fact that a fetch once worked. `stale` is only
+  /// meaningful next to the `fetchedAt` of the last success, so that is carried forward.
+  public func recordFailure(_ error: String, httpStatus: Int? = nil, for scope: WidgetScope) {
+    let previous = status(for: scope)
+
+    put(
+      DynamicWidgetServerStatus(
+        status: previous.fetchedAt == nil ? DynamicWidgetServerStatus.never : DynamicWidgetServerStatus.stale,
+        fetchedAt: previous.fetchedAt,
+        error: error,
+        httpStatus: httpStatus
+      ),
+      for: scope
+    )
+  }
+
+  public func recordSuccess(fetchedAt: Int, httpStatus: Int, for scope: WidgetScope) {
+    put(
+      DynamicWidgetServerStatus(status: DynamicWidgetServerStatus.fresh, fetchedAt: fetchedAt, httpStatus: httpStatus),
+      for: scope
+    )
+  }
+
+  /// Reports `disabled` once, keeping the last `fetchedAt` so a widget that comes back under app
+  /// control can still say when the server last spoke.
+  public func markDisabledIfNeeded(enabled: Bool, for scope: WidgetScope) {
+    guard !enabled else { return }
+
+    let previous = status(for: scope)
+
+    guard previous.status != DynamicWidgetServerStatus.disabled else { return }
+
+    put(
+      DynamicWidgetServerStatus(status: DynamicWidgetServerStatus.disabled, fetchedAt: previous.fetchedAt),
+      for: scope
+    )
+  }
+
+  /// Records that the app just wrote props itself, so the reload that write triggers renders them
+  /// instead of racing a fetch that would immediately overwrite them.
+  public func noteAppWrite(for scope: WidgetScope, at date: Date = Date()) {
+    defaults?.set(date.timeIntervalSince1970, forKey: appWriteKey(scope))
+  }
+
+  public func appWriteAt(for scope: WidgetScope) -> Date? {
+    guard let seconds = defaults?.object(forKey: appWriteKey(scope)) as? TimeInterval else {
+      return nil
+    }
+
+    return Date(timeIntervalSince1970: seconds)
+  }
+
+  public func clear(_ scope: WidgetScope) {
+    defaults?.removeObject(forKey: key(scope))
+    defaults?.removeObject(forKey: appWriteKey(scope))
+  }
+
+  private func key(_ scope: WidgetScope) -> String {
+    "Voltra_DynamicWidgetServer_v1_\(scope.storageKey)"
+  }
+
+  private func appWriteKey(_ scope: WidgetScope) -> String {
+    "Voltra_DynamicWidgetServer_AppWrite_v1_\(scope.storageKey)"
+  }
+}

package/ios/shared/DynamicWidgetServerUpdate/DynamicWidgetServerUpdateRunner.swift

@@ -0,0 +1,193 @@
+import Foundation
+
+/// What one server-update run decided, before it becomes a timeline.
+public enum DynamicWidgetServerUpdateOutcome: Equatable {
+  /// Props were committed, or the server said `304` and what we have is still current.
+  case committed
+  /// Nothing to do: the widget has no URL, the app turned fetching off, or another request in the
+  /// same burst just fetched.
+  case skipped
+  /// The fetch failed in a way that waiting could fix. Previous props stay on screen.
+  case retry
+  /// The fetch or the response failed in a way waiting will not fix. Previous props stay.
+  case failed
+  /// The settings the response was built from are no longer current, so it was dropped.
+  case dropped
+}
+
+/// The outcome plus what the server asked about the next fetch.
+public struct DynamicWidgetServerUpdateResult: Equatable {
+  public let outcome: DynamicWidgetServerUpdateOutcome
+  /// `Cache-Control: max-age` on a success, `Retry-After` on a `429` or `503`, in minutes and
+  /// already clamped to what WidgetKit can honour. Nil when the server said nothing and the
+  /// widget's own interval stands.
+  public let nextIntervalMinutes: Int?
+
+  public init(_ outcome: DynamicWidgetServerUpdateOutcome, nextIntervalMinutes: Int? = nil) {
+    self.outcome = outcome
+    self.nextIntervalMinutes = nextIntervalMinutes
+  }
+}
+
+/// Fetch, parse, trial-render, commit — the four steps ADR 0002 requires of every server-driven
+/// widget, with every collaborator injected so the failure table can be tested without a network,
+/// a JS runtime, or WidgetKit.
+///
+/// The rule the ordering exists for: props that do not render are never committed. A server that
+/// starts returning a shape the widget throws on leaves the last good props on screen instead of
+/// replacing them with a blank tile.
+public struct DynamicWidgetServerUpdateRunner {
+  public typealias Fetch = (WidgetScope, ResolvedWidgetServerSettings, String?) async -> WidgetServerFetchResult
+
+  private let resolveSettings: (WidgetScope) -> ResolvedWidgetServerSettings
+  private let currentRevision: (WidgetScope) -> Int
+  private let readEtag: (WidgetScope, String?) -> String?
+  private let fetch: Fetch
+  private let writeEtag: (WidgetScope, String, String?) -> Void
+  private let trialRender: (WidgetScope, String) -> Bool
+  private let commitProps: (WidgetScope, String) throws -> Void
+  private let recordSuccess: (WidgetScope, Int, Int) -> Void
+  private let recordFailure: (WidgetScope, String, Int?) -> Void
+  private let markDisabled: (WidgetScope, Bool) -> Void
+  private let now: () -> Date
+
+  public init(
+    resolveSettings: @escaping (WidgetScope) -> ResolvedWidgetServerSettings,
+    currentRevision: @escaping (WidgetScope) -> Int,
+    readEtag: @escaping (WidgetScope, String?) -> String?,
+    fetch: @escaping Fetch,
+    writeEtag: @escaping (WidgetScope, String, String?) -> Void,
+    trialRender: @escaping (WidgetScope, String) -> Bool,
+    commitProps: @escaping (WidgetScope, String) throws -> Void,
+    recordSuccess: @escaping (WidgetScope, Int, Int) -> Void,
+    recordFailure: @escaping (WidgetScope, String, Int?) -> Void,
+    markDisabled: @escaping (WidgetScope, Bool) -> Void,
+    now: @escaping () -> Date = Date.init
+  ) {
+    self.resolveSettings = resolveSettings
+    self.currentRevision = currentRevision
+    self.readEtag = readEtag
+    self.fetch = fetch
+    self.writeEtag = writeEtag
+    self.trialRender = trialRender
+    self.commitProps = commitProps
+    self.recordSuccess = recordSuccess
+    self.recordFailure = recordFailure
+    self.markDisabled = markDisabled
+    self.now = now
+  }
+
+  public func run(_ scope: WidgetScope) async -> DynamicWidgetServerUpdateResult {
+    let settings = resolveSettings(scope)
+
+    guard settings.shouldFetch, let url = settings.url else {
+      markDisabled(scope, settings.enabled)
+      return DynamicWidgetServerUpdateResult(.skipped)
+    }
+
+    let revision = currentRevision(scope)
+    let result = await fetch(scope, settings, readEtag(scope, url))
+
+    // Settings that moved while we were on the network make this response answer a question
+    // nobody is asking any more.
+    guard currentRevision(scope) == revision else {
+      VoltraLogger.widget.debug("Dropping server update for '\(scope.widgetId, privacy: .public)': settings changed mid-fetch")
+      return DynamicWidgetServerUpdateResult(.dropped)
+    }
+
+    switch result {
+    case let .notModified(nextIntervalMinutes):
+      recordSuccess(scope, epochMs(), 304)
+      return DynamicWidgetServerUpdateResult(.committed, nextIntervalMinutes: clamped(nextIntervalMinutes))
+
+    case let .networkFailure(message):
+      VoltraLogger.widget.error("Server update for '\(scope.widgetId, privacy: .public)' failed: \(message, privacy: .public)")
+      recordFailure(scope, DynamicWidgetServerStatus.errorNetwork, nil)
+      return DynamicWidgetServerUpdateResult(.retry)
+
+    case let .tooLarge(httpStatus):
+      // The server answered, with a body the extension will not hold. Asking again returns the
+      // same one, so this is a parse failure rather than something to back off from.
+      VoltraLogger.widget.error("Server update for '\(scope.widgetId, privacy: .public)' returned a body that is too large")
+      recordFailure(scope, DynamicWidgetServerStatus.errorParse, httpStatus)
+      return DynamicWidgetServerUpdateResult(.failed)
+
+    case let .httpFailure(httpStatus, retryAfterMinutes):
+      let error = result.isUnauthorized ? DynamicWidgetServerStatus.errorUnauthorized : DynamicWidgetServerStatus.errorHttp
+
+      VoltraLogger.widget.error("Server update for '\(scope.widgetId, privacy: .public)' got HTTP \(httpStatus, privacy: .public)")
+      recordFailure(scope, error, httpStatus)
+
+      // A 401 will keep being a 401 until the app sets a fresh token, and setting one reloads the
+      // widget. Retrying sooner would only spend the reload budget.
+      guard result.isTransient else {
+        return DynamicWidgetServerUpdateResult(.failed)
+      }
+
+      return DynamicWidgetServerUpdateResult(.retry, nextIntervalMinutes: clamped(retryAfterMinutes))
+
+    case let .success(body, etag, httpStatus, nextIntervalMinutes):
+      return commit(
+        scope: scope,
+        url: url,
+        body: body,
+        etag: etag,
+        httpStatus: httpStatus,
+        nextIntervalMinutes: clamped(nextIntervalMinutes)
+      )
+    }
+  }
+
+  /// What the server asked for, held to what WidgetKit can honour: never sooner than 15 minutes,
+  /// never further out than a day.
+  private func clamped(_ minutes: Int?) -> Int? {
+    minutes.map { WidgetServerUpdateDefaults.clampIntervalMinutes($0) }
+  }
+
+  private func commit(
+    scope: WidgetScope,
+    url: String,
+    body: Data,
+    etag: String?,
+    httpStatus: Int,
+    nextIntervalMinutes: Int?
+  ) -> DynamicWidgetServerUpdateResult {
+    switch DynamicWidgetServerProps.parse(body) {
+    case let .invalid(reason):
+      VoltraLogger.widget.error("Server update for '\(scope.widgetId, privacy: .public)' rejected: \(reason, privacy: .public)")
+      recordFailure(scope, DynamicWidgetServerStatus.errorParse, httpStatus)
+      // Asking again returns the same body, so this is not something to retry.
+      return DynamicWidgetServerUpdateResult(.failed)
+
+    case let .props(json):
+      guard trialRender(scope, json) else {
+        VoltraLogger.widget.error(
+          "Server update for '\(scope.widgetId, privacy: .public)' did not render; keeping the previous props"
+        )
+        recordFailure(scope, DynamicWidgetServerStatus.errorRender, httpStatus)
+        return DynamicWidgetServerUpdateResult(.failed)
+      }
+
+      do {
+        try commitProps(scope, json)
+      } catch {
+        // Storage is not something the server can fix, and there is no error kind for it, so it is
+        // reported as a render failure: the props arrived and could not be put on screen.
+        VoltraLogger.widget.error(
+          "Could not store fetched props for '\(scope.widgetId, privacy: .public)': \(error.localizedDescription, privacy: .public)"
+        )
+        recordFailure(scope, DynamicWidgetServerStatus.errorRender, httpStatus)
+        return DynamicWidgetServerUpdateResult(.failed)
+      }
+
+      writeEtag(scope, url, etag)
+      recordSuccess(scope, epochMs(), httpStatus)
+
+      return DynamicWidgetServerUpdateResult(.committed, nextIntervalMinutes: nextIntervalMinutes)
+    }
+  }
+
+  private func epochMs() -> Int {
+    Int(now().timeIntervalSince1970 * 1000)
+  }
+}

package/ios/shared/DynamicWidgetUpdater.swift

@@ -0,0 +1,30 @@
+protocol DynamicWidgetPropsPersistence {
+  func persistDynamicWidgetProps(_ dynamicWidgetPropsJSON: String, for dynamicWidgetID: String) throws
+}
+
+extension DynamicWidgetPropsStore: DynamicWidgetPropsPersistence {}
+
+/// Persists runtime props before requesting a targeted Dynamic Widget timeline reload.
+struct DynamicWidgetUpdater {
+  private let dynamicWidgetPropsPersistence: any DynamicWidgetPropsPersistence
+  private let dynamicWidgetTimelineReload: (String) async throws -> Void
+
+  init(
+    dynamicWidgetPropsPersistence: any DynamicWidgetPropsPersistence,
+    dynamicWidgetTimelineReload: @escaping (String) async throws -> Void
+  ) {
+    self.dynamicWidgetPropsPersistence = dynamicWidgetPropsPersistence
+    self.dynamicWidgetTimelineReload = dynamicWidgetTimelineReload
+  }
+
+  func updateDynamicWidget(
+    dynamicWidgetID: String,
+    dynamicWidgetPropsJSON: String
+  ) async throws {
+    try dynamicWidgetPropsPersistence.persistDynamicWidgetProps(
+      dynamicWidgetPropsJSON,
+      for: dynamicWidgetID
+    )
+    try await dynamicWidgetTimelineReload(dynamicWidgetID)
+  }
+}

package/ios/shared/ServerWidgetContentResolver.swift

@@ -0,0 +1,60 @@
+import Foundation
+
+/// Decides which server response a server-driven widget renders for one timeline request.
+///
+/// WidgetKit requests a timeline once per widget instance per reload, and an interactive refresh
+/// button produces two reloads for a single tap (the intent's own reload plus the automatic
+/// post-intent reload). The resolver collapses such bursts into one network request and answers
+/// every request in the burst with the same response. When a fetch fails it hands back the last
+/// successful response instead, so the widget never regresses to older or initial content while
+/// the server has already provided something newer.
+struct ServerWidgetContentResolver {
+  enum Outcome {
+    /// Fetched now, or fetched moments ago by another request in the same burst.
+    case current(Data)
+    /// The fetch failed; this is the most recent successful response.
+    case lastKnown(Data, Error)
+    /// The fetch failed and no successful response exists in this process.
+    case unavailable(Error)
+  }
+
+  typealias Fetch = (_ widgetId: String) async throws -> Data
+
+  static let defaultCoalesceInterval: TimeInterval = 3
+
+  private let responseStore: ServerWidgetResponseStore
+  private let fetch: Fetch
+  private let coalesceInterval: TimeInterval
+  private let now: () -> Date
+
+  init(
+    responseStore: ServerWidgetResponseStore,
+    fetch: @escaping Fetch,
+    coalesceInterval: TimeInterval = ServerWidgetContentResolver.defaultCoalesceInterval,
+    now: @escaping () -> Date = Date.init
+  ) {
+    self.responseStore = responseStore
+    self.fetch = fetch
+    self.coalesceInterval = coalesceInterval
+    self.now = now
+  }
+
+  func resolve(widgetId: String) async -> Outcome {
+    if let recent = await responseStore.response(for: widgetId),
+       now().timeIntervalSince(recent.fetchedAt) < coalesceInterval
+    {
+      return .current(recent.data)
+    }
+
+    do {
+      let data = try await fetch(widgetId)
+      await responseStore.store(data, for: widgetId, fetchedAt: now())
+      return .current(data)
+    } catch {
+      if let lastKnown = await responseStore.response(for: widgetId) {
+        return .lastKnown(lastKnown.data, error)
+      }
+      return .unavailable(error)
+    }
+  }
+}