@use-voltra/ios-client 2.2.0 → 2.3.1

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/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)
+    }
+  }
+}

package/ios/shared/ServerWidgetResponseStore.swift

@@ -0,0 +1,25 @@
+import Foundation
+
+/// In-memory record of the last successful server response for each server-driven widget.
+///
+/// Lives for the lifetime of the widget extension process. It is the source of truth for
+/// "the last content the server actually sent", independent of whether an App Group is
+/// configured for on-disk persistence.
+actor ServerWidgetResponseStore {
+  struct Response: Equatable {
+    let data: Data
+    let fetchedAt: Date
+  }
+
+  private var responses: [String: Response] = [:]
+
+  init() {}
+
+  func response(for widgetId: String) -> Response? {
+    responses[widgetId]
+  }
+
+  func store(_ data: Data, for widgetId: String, fetchedAt: Date) {
+    responses[widgetId] = Response(data: data, fetchedAt: fetchedAt)
+  }
+}

package/ios/shared/ShortNames.swift

@@ -77,6 +77,7 @@ public enum ShortNames {
     "g": "gap",
     "gs": "gaugeStyle",
     "ge": "glassEffect",
+    "gc": "gradientColors",
     "h": "height",
     "halig": "horizontalAlignment",
     "hp": "horizontalPadding",
@@ -92,6 +93,7 @@ public enum ShortNames {
     "l": "left",
     "lgv": "legendVisibility",
     "ls": "letterSpacing",
+    "lc": "lineCap",
     "lh": "lineHeight",
     "ll": "lineLimit",
     "lsp": "lineSpacing",
@@ -149,12 +151,15 @@ public enum ShortNames {
     "smc": "smallCaps",
     "src": "source",
     "sp": "spacing",
+    "sa": "startAngle",
     "start": "startAtMs",
     "sic": "startIcon",
     "stp": "startPoint",
     "sts": "stops",
     "st": "strikethrough",
+    "sw": "strokeWidth",
     "s": "style",
+    "swa": "sweepAngle",
     "si": "systemImage",
     "txt": "text",
     "ta": "textAlign",
@@ -184,6 +189,7 @@ public enum ShortNames {
     "xav": "xAxisVisibility",
     "ygs": "yAxisGridStyle",
     "yav": "yAxisVisibility",
+    "ysc": "yScale",
     "zi": "zIndex",
   ]
 

package/ios/shared/VoltraConfig.swift

@@ -15,4 +15,45 @@ public enum VoltraConfig {
   public static func keychainGroup() -> String? {
     Bundle.main.object(forInfoDictionaryKey: VoltraStorageKeys.keychainGroup) as? String
   }
+
+  /// Reported when `Voltra_Version` is missing or unusable, mirroring the `appVersion` fallback.
+  public static let unknownVoltraVersion = "unknown"
+
+  /// Get the installed Voltra client package version from Info.plist
+  /// Written at prebuild (`expo prebuild`) or apply (`voltra apply`) time from the installed
+  /// `@use-voltra/{ios,android}-client` manifest, and surfaced to widgets as `env.build.voltraVersion`.
+  public static func voltraVersion(bundle: Bundle = .main) -> String {
+    normalizeVoltraVersion(bundle.object(forInfoDictionaryKey: VoltraStorageKeys.voltraVersion))
+  }
+
+  /// Value handling for `voltraVersion(bundle:)`, split out so every malformed shape the plist can
+  /// hold is covered without building a bundle per case.
+  static func normalizeVoltraVersion(_ rawValue: Any?) -> String {
+    guard let version = rawValue as? String, !version.isEmpty else {
+      return unknownVoltraVersion
+    }
+
+    return version
+  }
+
+  /// Get the `{ widgetId: kind }` map of widgets that pin a custom WidgetKit kind from Info.plist
+  /// Written at prebuild (`expo prebuild`) or apply (`voltra apply`) time from the `kind` option.
+  /// Absent when every widget keeps the default `Voltra_Widget_<id>` kind.
+  public static func widgetKinds(bundle: Bundle = .main) -> [String: String] {
+    normalizeWidgetKinds(bundle.object(forInfoDictionaryKey: VoltraStorageKeys.widgetKinds))
+  }
+
+  /// Value handling for `widgetKinds(bundle:)`, split out so every malformed shape the plist can
+  /// hold is covered without building a bundle per case. Entries that are not non-empty strings
+  /// are dropped, leaving those widgets on the default kind.
+  static func normalizeWidgetKinds(_ rawValue: Any?) -> [String: String] {
+    guard let rawMap = rawValue as? [String: Any] else {
+      return [:]
+    }
+
+    return rawMap.compactMapValues { value in
+      guard let kind = value as? String, !kind.isEmpty else { return nil }
+      return kind
+    }
+  }
 }

package/ios/shared/VoltraConstants.swift

@@ -32,6 +32,18 @@ public enum VoltraStorageKeys {
     "Voltra_DynamicWidget_Props_v1_\(dynamicWidgetId)"
   }
 
+  /// One placement's own props slot (ADR 0007), keyed by `WidgetScope.Instance.storageKey`
+  /// (`<widgetId>#<key>`).
+  public static func dynamicWidgetInstancePropsV1(_ storageKey: String) -> String {
+    "Voltra_DynamicWidget_Props_v1_\(storageKey)"
+  }
+
+  /// The set of instance keys `dynamicWidgetId` has ever committed props into, so a widget-level
+  /// clear (or logout) can drop every instance slot without enumerating placements.
+  public static func dynamicWidgetPropsInstanceIndexV1(_ dynamicWidgetId: String) -> String {
+    "Voltra_DynamicWidget_Props_Instances_v1_\(dynamicWidgetId)"
+  }
+
   // MARK: - Prefixes / kind identifiers
 
   public static let widgetKindPrefix = "Voltra_Widget_"
@@ -43,6 +55,8 @@ public enum VoltraStorageKeys {
   // MARK: - Info.plist keys
 
   public static let widgetIds = "Voltra_WidgetIds"
+  /// `{ widgetId: kind }` for widgets that pin a custom WidgetKit kind (plugin `kind` option)
+  public static let widgetKinds = "Voltra_WidgetKinds"
   public static let enablePushNotifications = "Voltra_EnablePushNotifications"
   public static let widgetServerUrls = "Voltra_WidgetServerUrls"
   public static let widgetServerIntervals = "Voltra_WidgetServerIntervals"
@@ -50,4 +64,5 @@ public enum VoltraStorageKeys {
   public static let appGroupIdentifier = "Voltra_AppGroupIdentifier"
   public static let legacyAppGroupIdentifier = "AppGroupIdentifier"
   public static let keychainGroup = "Voltra_KeychainGroup"
+  public static let voltraVersion = "Voltra_Version"
 }