@use-voltra/ios-client 2.1.1 → 2.3.0

package/ios/shared/VoltraNode.swift

@@ -1,8 +1,7 @@
 import Foundation
-import SwiftUI
 
 /// Represents anything that can be rendered (like ReactNode)
-public indirect enum VoltraNode: Hashable, View {
+public indirect enum VoltraNode: Hashable {
   /// A component element
   case element(VoltraElement)
 
@@ -55,7 +54,9 @@ public indirect enum VoltraNode: Hashable, View {
 
   /// Check if node represents nothing
   public var isEmpty: Bool {
-    if case .empty = self { return true }
+    if case .empty = self {
+      return true
+    }
     return false
   }
 
@@ -72,7 +73,9 @@ public indirect enum VoltraNode: Hashable, View {
       // Extract stylesheet (key "s")
       if case let .array(stylesheetArray) = rootObject["s"] {
         stylesheet = stylesheetArray.compactMap { item in
-          if case let .object(dict) = item { return dict }
+          if case let .object(dict) = item {
+            return dict
+          }
           return nil
         }
       }
@@ -84,111 +87,4 @@ public indirect enum VoltraNode: Hashable, View {
 
     return VoltraNode(from: json, stylesheet: stylesheet, sharedElements: sharedElements)
   }
-
-  // MARK: - View conformance
-
-  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/shared/VoltraRefreshIntent.swift

@@ -19,7 +19,7 @@ public struct VoltraRefreshIntent: AppIntent {
 
   public func perform() async throws -> some IntentResult {
     if let widgetId = widgetId {
-      let kind = "\(VoltraStorageKeys.widgetKindPrefix)\(widgetId)"
+      let kind = VoltraWidgetKind.kind(for: widgetId)
       WidgetCenter.shared.reloadTimelines(ofKind: kind)
     } else {
       WidgetCenter.shared.reloadAllTimelines()

package/ios/shared/VoltraWidgetDefaults.swift

@@ -86,13 +86,17 @@ public enum VoltraWidgetDefaults {
 
   // MARK: - Remove
 
-  /// Removes all persisted data (json, deepLinkUrl, timeline) for a single widget.
+  /// Removes all persisted data (json, deepLinkUrl, timeline, Dynamic Widget props) for a single widget.
   /// This is the single source of truth for which keys exist per widget.
   public static func removeAllData(for widgetId: String) {
     guard let defaults = try? resolvedDefaults() else { return }
     defaults.removeObject(forKey: VoltraStorageKeys.widgetJson(widgetId))
     defaults.removeObject(forKey: VoltraStorageKeys.widgetDeepLinkUrl(widgetId))
     defaults.removeObject(forKey: VoltraStorageKeys.widgetTimeline(widgetId))
+    let dynamicWidgetPropsStore = DynamicWidgetPropsStore(
+      storage: DynamicWidgetPropsUserDefaultsStorage(userDefaults: defaults)
+    )
+    try? dynamicWidgetPropsStore.clearDynamicWidgetProps(for: widgetId)
     defaults.synchronize()
   }
 
@@ -105,11 +109,15 @@ public enum VoltraWidgetDefaults {
   /// Removes all persisted data for every widget listed in the app's Info.plist.
   public static func removeAllWidgets() {
     guard let defaults = try? resolvedDefaults() else { return }
+    let dynamicWidgetPropsStore = DynamicWidgetPropsStore(
+      storage: DynamicWidgetPropsUserDefaultsStorage(userDefaults: defaults)
+    )
     let widgetIds = Bundle.main.object(forInfoDictionaryKey: VoltraStorageKeys.widgetIds) as? [String] ?? []
     for widgetId in widgetIds {
       defaults.removeObject(forKey: VoltraStorageKeys.widgetJson(widgetId))
       defaults.removeObject(forKey: VoltraStorageKeys.widgetDeepLinkUrl(widgetId))
       defaults.removeObject(forKey: VoltraStorageKeys.widgetTimeline(widgetId))
+      try? dynamicWidgetPropsStore.clearDynamicWidgetProps(for: widgetId)
     }
     defaults.synchronize()
   }

package/ios/shared/VoltraWidgetKind.swift

@@ -0,0 +1,41 @@
+import Foundation
+
+/// Maps a widget id to its WidgetKit `kind` and back.
+///
+/// The kind defaults to `Voltra_Widget_<id>`. A widget can pin another kind through the plugin
+/// `kind` option, stored in Info.plist under `Voltra_WidgetKinds` (app and extension), so widgets
+/// placed before a migration to Voltra keep their identity.
+///
+/// This is the only place either half of that mapping is derived; nothing else should reach for
+/// `VoltraStorageKeys.widgetKindPrefix`.
+public enum VoltraWidgetKind {
+  /// Info.plist cannot change for the life of the process, so the map is read once.
+  private static let mainOverrides = VoltraConfig.widgetKinds()
+
+  public static func kind(for widgetId: String) -> String {
+    kind(for: widgetId, overrides: mainOverrides)
+  }
+
+  /// Returns nil when the kind does not belong to a Voltra widget.
+  public static func widgetId(for kind: String) -> String? {
+    widgetId(for: kind, overrides: mainOverrides)
+  }
+
+  /// Pure half of `kind(for:)`, split out so the mapping is covered without building a bundle.
+  static func kind(for widgetId: String, overrides: [String: String]) -> String {
+    overrides[widgetId] ?? "\(VoltraStorageKeys.widgetKindPrefix)\(widgetId)"
+  }
+
+  /// Pure half of `widgetId(for:)`. Overrides win over the prefix so a widget that pins a kind
+  /// shaped like another widget's default still resolves to its own id.
+  static func widgetId(for kind: String, overrides: [String: String]) -> String? {
+    if let match = overrides.first(where: { $0.value == kind }) {
+      return match.key
+    }
+
+    let prefix = VoltraStorageKeys.widgetKindPrefix
+    guard kind.hasPrefix(prefix) else { return nil }
+
+    return String(kind.dropFirst(prefix.count))
+  }
+}

package/ios/shared/VoltraWidgetServerFetcher.swift

@@ -1,8 +1,12 @@
 import Foundation
-import UIKit
 
-/// Handles fetching widget content from a remote Voltra SSR server.
-/// Used by the TimelineProvider to pull server-driven widget updates.
+/// Fetches a Voltra payload from the server for a payload-driven widget.
+///
+/// Since ADR 0002 the request itself is built by `shared/WidgetServer`, the same code the Dynamic
+/// engine uses. With no runtime settings set, that produces the request this fetcher always sent,
+/// plus `locale` and a conditional `If-None-Match`; with settings set, this widget gains the
+/// runtime URL, method, headers, query and body too. What the timeline does with the response is
+/// unchanged.
 public enum VoltraWidgetServerFetcher {
   /// Errors that can occur during server fetch
   public enum FetchError: Error, LocalizedError {
@@ -12,6 +16,8 @@ public enum VoltraWidgetServerFetcher {
     case httpError(statusCode: Int)
     case invalidResponse
     case emptyResponse
+    /// `304`: what is already stored is still current, so there is nothing new to render.
+    case notModified
 
     public var errorDescription: String? {
       switch self {
@@ -27,142 +33,81 @@ public enum VoltraWidgetServerFetcher {
         return "Invalid response from server"
       case .emptyResponse:
         return "Empty response from server"
+      case .notModified:
+        return "Server content is unchanged"
       }
     }
   }
 
-  /// Read the server update URL for a widget from Info.plist / UserDefaults config.
+  /// The URL this widget will fetch from, after runtime overrides. Callers use it to decide
+  /// whether a widget is server-driven at all before starting a timeline.
   public static func serverUrl(for widgetId: String) -> String? {
-    // Check Info.plist first (set at build time by config plugin)
-    if let urls = Bundle.main.object(forInfoDictionaryKey: VoltraStorageKeys.widgetServerUrls) as? [String: String],
-       let url = urls[widgetId]
-    {
-      return url
-    }
-
-    // Fallback to UserDefaults (can be set at runtime)
-    if let group = VoltraConfig.groupIdentifier(),
-       let defaults = UserDefaults(suiteName: group)
-    {
-      return defaults.string(forKey: VoltraStorageKeys.widgetServerUrl(widgetId))
-    }
-
-    return nil
+    VoltraWidgetServer.resolver.resolve(.of(widgetId)).url
   }
 
-  /// Read the update interval (in minutes) for a widget.
+  /// The resolved interval, in minutes. Runtime settings win over app.json.
   public static func updateInterval(for widgetId: String) -> Int {
-    if let intervals = Bundle.main.object(forInfoDictionaryKey: VoltraStorageKeys.widgetServerIntervals) as? [String: Int],
-       let interval = intervals[widgetId]
-    {
-      return interval
-    }
-    return 60 // default: 1 hour
+    VoltraWidgetServer.resolver.resolve(.of(widgetId)).intervalMinutes
   }
 
+  /// Whether the widget draws a refresh button. Build-time only: the button is generated UI
+  /// structure, so unlike the URL and the interval it cannot be changed at runtime.
   public static func isRefreshEnabled(for widgetId: String) -> Bool {
-    if let refreshDict = Bundle.main.object(forInfoDictionaryKey: VoltraStorageKeys.widgetServerRefresh) as? [String: Bool],
-       let enabled = refreshDict[widgetId]
-    {
-      return enabled
-    }
-    return false
-  }
-
-  private static func currentColorScheme() -> String {
-    if #available(iOSApplicationExtension 13.0, *) {
-      switch UITraitCollection.current.userInterfaceStyle {
-      case .dark:
-        return "dark"
-      case .light:
-        return "light"
-      default:
-        return "light"
-      }
-    }
-    return "light"
+    VoltraWidgetServer.isRefreshEnabled(for: widgetId)
   }
 
   /// Fetch widget content from the remote Voltra SSR server.
   ///
-  /// The request includes:
-  /// - `widgetId` query parameter
-  /// - `family` query parameter (e.g., "systemSmall")
-  /// - `platform` query parameter (`ios`)
-  /// - `theme` query parameter (`light` or `dark`)
-  /// - `Authorization: Bearer <token>` header (if credentials stored in Keychain)
-  /// - Any custom headers stored in Keychain
+  /// The request carries `widgetId`, `family`, `platform`, `theme` and `locale` as query
+  /// parameters, `Accept: application/json`, a Voltra user agent, whatever headers the app has set
+  /// — including `Authorization` from the deprecated credential API — and `If-None-Match` when a
+  /// stored ETag belongs to the URL being fetched.
   ///
   /// Returns the raw JSON data from the server, ready to be parsed by VoltraNode.
   public static func fetchWidgetContent(
     widgetId: String,
     family: String
   ) async throws -> Data {
-    guard let baseUrl = serverUrl(for: widgetId) else {
-      throw FetchError.noServerUrl
-    }
-
-    // Build URL with query parameters
-    guard var components = URLComponents(string: baseUrl) else {
-      throw FetchError.invalidUrl(baseUrl)
-    }
-
-    let theme = currentColorScheme()
+    let scope = WidgetScope.of(widgetId)
+    let settings = VoltraWidgetServer.resolver.resolve(scope)
 
-    var queryItems = components.queryItems ?? []
-    queryItems.append(URLQueryItem(name: "widgetId", value: widgetId))
-    queryItems.append(URLQueryItem(name: "family", value: family))
-    queryItems.append(URLQueryItem(name: "platform", value: "ios"))
-    queryItems.append(URLQueryItem(name: "theme", value: theme))
-    components.queryItems = queryItems
-
-    guard let url = components.url else {
-      throw FetchError.invalidUrl(baseUrl)
+    guard let url = settings.url else {
+      throw FetchError.noServerUrl
     }
 
-    var request = URLRequest(url: url)
-    request.httpMethod = "GET"
-    request.timeoutInterval = 15 // Widgets have limited execution time
-
-    // Add auth token from Keychain if available
-    if let token = VoltraKeychainHelper.readToken() {
-      request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
+    // No If-None-Match: a payload widget sends the request it always sent, plus locale. The last
+    // successful response is kept only for this extension process, so a 304 could arrive with
+    // nothing to fall back on and leave the widget on its initial state.
+    guard let request = WidgetServerRequestBuilder.build(
+      scope: scope,
+      settings: settings,
+      context: VoltraWidgetAppearance.requestContext(family: family)
+    ) else {
+      throw FetchError.invalidUrl(url)
     }
 
-    // Add custom headers from Keychain if available
-    if let headers = VoltraKeychainHelper.readHeaders() {
-      for (key, value) in headers {
-        request.setValue(value, forHTTPHeaderField: key)
+    switch await WidgetServerFetcher.fetch(request) {
+    case let .success(body, _, _, _):
+      guard !body.isEmpty else {
+        throw FetchError.emptyResponse
       }
-    }
 
-    // Add Voltra-specific headers
-    let systemVersion = await MainActor.run {
-      UIDevice.current.systemVersion
-    }
-    request.setValue("application/json", forHTTPHeaderField: "Accept")
-    request.setValue("VoltraWidget/1.0 (iOS/\(systemVersion))", forHTTPHeaderField: "User-Agent")
-
-    do {
-      let (data, response) = try await URLSession.shared.data(for: request)
+      return body
 
-      guard let httpResponse = response as? HTTPURLResponse else {
-        throw FetchError.invalidResponse
-      }
+    case .notModified:
+      // Only reachable if the server answers 304 unprompted; nothing was requested conditionally.
+      throw FetchError.notModified
 
-      guard (200 ... 299).contains(httpResponse.statusCode) else {
-        throw FetchError.httpError(statusCode: httpResponse.statusCode)
-      }
+    case let .tooLarge(statusCode):
+      throw FetchError.httpError(statusCode: statusCode)
 
-      guard !data.isEmpty else {
-        throw FetchError.emptyResponse
-      }
+    case let .httpFailure(statusCode, _):
+      throw FetchError.httpError(statusCode: statusCode)
 
-      return data
-    } catch let error as FetchError {
-      throw error
-    } catch {
-      throw FetchError.networkError(error)
+    case let .networkFailure(message):
+      throw FetchError.networkError(NSError(domain: "VoltraWidgetServerFetcher", code: -1, userInfo: [
+        NSLocalizedDescriptionKey: message,
+      ]))
     }
   }
 }

package/ios/shared/WidgetServer/VoltraWidgetAppearance.swift

@@ -0,0 +1,17 @@
+import UIKit
+
+/// The appearance a widget is being drawn in, as the request contract reports it.
+///
+/// Split out from the rest of `WidgetServer` because it is the one piece that needs UIKit, and
+/// keeping it here lets everything else — the resolver, the store, the request builder, the
+/// fetcher — be compiled and tested on its own.
+public enum VoltraWidgetAppearance {
+  public static func currentTheme() -> String {
+    UITraitCollection.current.userInterfaceStyle == .dark ? "dark" : "light"
+  }
+
+  /// The device state a request carries, for callers that are already on a UIKit-capable target.
+  public static func requestContext(family: String? = nil) -> WidgetServerRequestContext {
+    VoltraWidgetServer.requestContext(theme: currentTheme(), family: family)
+  }
+}

package/ios/shared/WidgetServer/VoltraWidgetServer.swift

@@ -0,0 +1,138 @@
+import Foundation
+
+/// Build-time server-update defaults, read from the Info.plist keys the config plugin and the CLI
+/// write.
+///
+/// `Voltra_WidgetServerIntervals` carries an entry for every server-driven widget, so its keys are
+/// the set of widget ids this app may fetch for. `Voltra_WidgetServerUrls` carries only the ones
+/// app.json gave a URL; the rest expect one at runtime from `setWidgetServerUpdate`.
+struct ConfigWidgetServerSettingsLayer: WidgetServerSettingsLayer {
+  let name = "config"
+
+  private let urls: [String: String]
+  private let intervals: [String: Int]
+
+  init(bundle: Bundle = .main) {
+    urls = bundle.object(forInfoDictionaryKey: VoltraStorageKeys.widgetServerUrls) as? [String: String] ?? [:]
+    intervals = bundle.object(forInfoDictionaryKey: VoltraStorageKeys.widgetServerIntervals) as? [String: Int] ?? [:]
+  }
+
+  init(urls: [String: String], intervals: [String: Int]) {
+    self.urls = urls
+    self.intervals = intervals
+  }
+
+  func settings(for scope: WidgetScope) -> WidgetServerUpdateSettings? {
+    guard let interval = intervals[scope.widgetId] else { return nil }
+
+    return WidgetServerUpdateSettings(url: urls[scope.widgetId], intervalMinutes: interval)
+  }
+
+  func isServerDriven(_ scope: WidgetScope) -> Bool {
+    intervals[scope.widgetId] != nil
+  }
+
+  var serverDrivenWidgetIds: Set<String> {
+    Set(intervals.keys)
+  }
+}
+
+/// Assembles the settings stack for the process.
+///
+/// Everything that needs server-update settings goes through here: the payload timeline, the
+/// Dynamic Widget timeline, and the bridge methods. Neither engine reads Info.plist, the Keychain,
+/// or the credential records on its own, which is what keeps the layer order and the merge rule in
+/// one place.
+public enum VoltraWidgetServer {
+  private static let configLayer = ConfigWidgetServerSettingsLayer()
+
+  /// Fixed order, lowest priority first. An instance layer will slot in above `widget`.
+  public static let resolver = WidgetServerSettingsResolver(
+    layers: [
+      configLayer,
+      CredentialsWidgetServerSettingsLayer(),
+      GlobalWidgetServerSettingsLayer(),
+      WidgetWidgetServerSettingsLayer(),
+    ],
+    revisionSource: { WidgetServerSettingsStore.revision() }
+  )
+
+  /// Every widget app.json marked server-driven, whichever engine renders it.
+  public static var serverDrivenWidgetIds: Set<String> {
+    configLayer.serverDrivenWidgetIds
+  }
+
+  public static func isServerDriven(_ widgetId: String) -> Bool {
+    configLayer.isServerDriven(.of(widgetId))
+  }
+
+  /// Whether the widget draws a refresh button. Build-time only: the button is generated UI
+  /// structure, so unlike the URL and the interval it cannot be changed at runtime.
+  public static func isRefreshEnabled(for widgetId: String) -> Bool {
+    guard let refresh = Bundle.main.object(forInfoDictionaryKey: VoltraStorageKeys.widgetServerRefresh) as? [String: Bool] else {
+      return false
+    }
+
+    return refresh[widgetId] ?? false
+  }
+
+  /// Whether plain http to a local dev host is allowed. Release builds have App Transport Security
+  /// blocking cleartext anyway, so accepting such a URL there would only move the failure to fetch
+  /// time.
+  public static var isDebugBuild: Bool {
+    #if DEBUG
+      return true
+    #else
+      return false
+    #endif
+  }
+
+  /// The device state a request carries. The theme is passed in rather than read here so this
+  /// whole module stays free of UIKit and the request contract can be tested without a simulator;
+  /// `VoltraWidgetAppearance` is the UIKit-side helper that supplies it.
+  public static func requestContext(theme: String, family: String? = nil) -> WidgetServerRequestContext {
+    WidgetServerRequestContext(
+      theme: theme,
+      locale: bcp47Locale(),
+      userAgent: userAgent(),
+      family: family
+    )
+  }
+
+  /// The device locale as a BCP-47 tag, so a backend sees `en-US` from both platforms.
+  /// `Locale.identifier` is the ICU form (`en_US`), which is not what the contract promises.
+  static func bcp47Locale(_ locale: Locale = .current) -> String {
+    if #available(iOS 16.0, macOS 13.0, *) {
+      return locale.identifier(.bcp47)
+    }
+
+    return locale.identifier.replacingOccurrences(of: "_", with: "-")
+  }
+
+  static func userAgent() -> String {
+    "VoltraWidget/\(VoltraConfig.voltraVersion()) (iOS/\(systemVersion))"
+  }
+
+  /// `UIDevice.current.systemVersion` is main-actor isolated and a timeline provider is not, so
+  /// the OS version comes from `ProcessInfo`, which is not.
+  private static var systemVersion: String {
+    let version = ProcessInfo.processInfo.operatingSystemVersion
+
+    return "\(version.majorVersion).\(version.minorVersion).\(version.patchVersion)"
+  }
+
+  /// Resolves settings and builds the request for one scope, or returns nil when there is nothing
+  /// to fetch.
+  public static func request(
+    for scope: WidgetScope,
+    context: WidgetServerRequestContext,
+    etag: String? = nil
+  ) -> URLRequest? {
+    WidgetServerRequestBuilder.build(
+      scope: scope,
+      settings: resolver.resolve(scope),
+      context: context,
+      etag: etag
+    )
+  }
+}

package/ios/shared/WidgetServer/WidgetCanonicalConfiguration.swift

@@ -0,0 +1,77 @@
+import Foundation
+
+/// Turns a merged `env.configuration` map into the canonical form ADR 0007 sends on the wire and
+/// hashes into an instance key.
+///
+/// Canonical serialization: keys sorted by Unicode scalar (code point), no whitespace, values as
+/// JSON strings. Decoded, it is byte for byte what the widget sees as `env.configuration`, so
+/// server and widget agree by construction. Both platforms produce this same string for the same
+/// map, which is what lets the hash below be a stable, cross-platform instance identity.
+public enum WidgetCanonicalConfiguration {
+  /// The canonical JSON string for `configuration`, or nil when the map is empty — a widget with
+  /// no configuration parameters has exactly one instance, the widget scope, and sends neither
+  /// `instance` nor `configuration`.
+  public static func canonicalize(_ configuration: [String: String]) -> String? {
+    guard !configuration.isEmpty else { return nil }
+
+    let sortedKeys = configuration.keys.sorted { lhs, rhs in
+      lhs.unicodeScalars.lexicographicallyPrecedes(rhs.unicodeScalars) { $0.value < $1.value }
+    }
+
+    var pieces: [String] = []
+    pieces.reserveCapacity(sortedKeys.count)
+    for key in sortedKeys {
+      let value = configuration[key] ?? ""
+      pieces.append("\(encodeJSONString(key)):\(encodeJSONString(value))")
+    }
+
+    return "{" + pieces.joined(separator: ",") + "}"
+  }
+
+  /// The instance key for `configuration`: FNV-1a, 32-bit, over the UTF-8 bytes of the canonical
+  /// serialization, rendered as 8 lowercase hex digits. Nil when the map is empty, matching
+  /// `canonicalize`.
+  ///
+  /// FNV-1a was picked for being small, dependency-free, and trivial to reproduce identically in
+  /// Kotlin — this is not a cryptographic hash, and nothing about instance identity depends on
+  /// collision resistance beyond "different configurations usually get different keys".
+  public static func key(_ configuration: [String: String]) -> String? {
+    guard let canonical = canonicalize(configuration) else { return nil }
+    return fnv1a32Hex(canonical)
+  }
+
+  /// Minimal, dependency-free JSON string encoder — just enough for configuration keys/values,
+  /// which are plain strings, not arbitrary JSON. Escapes the characters `JSONSerialization` would.
+  private static func encodeJSONString(_ value: String) -> String {
+    var result = "\""
+    for scalar in value.unicodeScalars {
+      switch scalar {
+      case "\"": result += "\\\""
+      case "\\": result += "\\\\"
+      case "\n": result += "\\n"
+      case "\r": result += "\\r"
+      case "\t": result += "\\t"
+      default:
+        if scalar.value < 0x20 {
+          result += String(format: "\\u%04x", scalar.value)
+        } else {
+          result.unicodeScalars.append(scalar)
+        }
+      }
+    }
+    result += "\""
+    return result
+  }
+
+  private static let fnvOffsetBasis: UInt32 = 0x811C_9DC5
+  private static let fnvPrime: UInt32 = 0x0100_0193
+
+  private static func fnv1a32Hex(_ value: String) -> String {
+    var hash = fnvOffsetBasis
+    for byte in Array(value.utf8) {
+      hash ^= UInt32(byte)
+      hash = hash &* fnvPrime
+    }
+    return String(format: "%08x", hash)
+  }
+}