@use-voltra/ios-client 2.2.0 → 2.3.0

package/ios/app/VoltraModuleImpl.swift

@@ -89,6 +89,14 @@ public class VoltraModuleImpl {
     VoltraHeadlessState.shared.clear()
   }
 
+  func drainDynamicLiveActivityRenderFailures() {
+    VoltraEventBus.shared.drainDynamicLiveActivityRenderFailures()
+  }
+
+  func setDynamicLiveActivityRenderFailureListenerActive(_ active: Bool) {
+    VoltraEventBus.shared.setDynamicLiveActivityRenderFailureListenerActive(active)
+  }
+
   var pushNotificationsEnabled: Bool {
     // Support both keys for compatibility with older plugin and new Voltra naming
     let main = Bundle.main
@@ -182,6 +190,48 @@ public class VoltraModuleImpl {
     }
   }
 
+  func startDynamicLiveActivity(definitionId: String, propsJson: String, options: StartVoltraOptions?) async throws -> String {
+    guard #available(iOS 16.4, *) else { throw VoltraErrors.unsupportedOS }
+    let name = options?.activityName?.trimmingCharacters(in: .whitespacesAndNewlines)
+    let activityName = name?.isEmpty == false ? name! : UUID().uuidString
+    do {
+      let props = try VoltraDynamicLiveActivityPayloadValidator.decodeProps(propsJson)
+      let staleDate = options?.staleDate.map { Date(timeIntervalSince1970: $0.doubleValue / 1000.0) }
+      let pushType = try resolvePushType(channelId: options?.channelId)
+      let request = VoltraDynamicLiveActivityCreateRequest(
+        definitionId: definitionId,
+        name: activityName,
+        deepLinkUrl: options?.deepLinkUrl,
+        props: props,
+        staleDate: staleDate,
+        relevanceScore: options?.relevanceScore?.doubleValue ?? 0.0,
+        pushType: pushType
+      )
+      return try await liveActivityService.createDynamicActivity(request)
+    } catch {
+      VoltraLogger.module.error("startDynamicLiveActivity failed: \(error)")
+      throw mapError(error)
+    }
+  }
+
+  func updateDynamicLiveActivity(activityId: String, propsJson: String, options: UpdateVoltraOptions?) async throws {
+    guard #available(iOS 16.4, *) else { throw VoltraErrors.unsupportedOS }
+    do {
+      let props = try VoltraDynamicLiveActivityPayloadValidator.decodeProps(propsJson)
+      let staleDate = options?.staleDate.map { Date(timeIntervalSince1970: $0.doubleValue / 1000.0) }
+      try await liveActivityService.updateDynamicActivity(
+        byName: activityId,
+        request: VoltraDynamicLiveActivityUpdateRequest(
+          props: props,
+          staleDate: staleDate,
+          relevanceScore: options?.relevanceScore?.doubleValue ?? 0.0
+        )
+      )
+    } catch {
+      throw mapError(error)
+    }
+  }
+
   func endLiveActivity(activityId: String, options: EndVoltraOptions?) async throws {
     guard #available(iOS 16.4, *) else { throw VoltraErrors.unsupportedOS }
 
@@ -202,12 +252,17 @@ public class VoltraModuleImpl {
 
   func getLatestVoltraActivityId() -> String? {
     guard #available(iOS 16.4, *) else { return nil }
-    return liveActivityService.getLatestActivity()?.id
+    return liveActivityService.latestActivityId()
   }
 
   func listVoltraActivityIds() -> [String] {
     guard #available(iOS 16.4, *) else { return [] }
-    return liveActivityService.getAllActivities().map(\.id)
+    return liveActivityService.getAllActivityReferences().map(\.id)
+  }
+
+  func getDynamicLiveActivityDefinitionIds() -> [String] {
+    guard #available(iOS 16.4, *) else { return [] }
+    return liveActivityService.dynamicLiveActivityDefinitionIds()
   }
 
   func isLiveActivityActive(name: String) -> Bool {
@@ -245,6 +300,13 @@ public class VoltraModuleImpl {
     }
   }
 
+  func reloadDynamicLiveActivities(definitionIds: [String]?) async {
+    #if DEBUG
+      syncDevServerURL()
+    #endif
+    await liveActivityService.reloadDynamicActivities(definitionIds: definitionIds)
+  }
+
   // MARK: - Image Preloading
 
   func preloadImages(images: [PreloadImageOptions]) async throws -> PreloadImagesResult {
@@ -264,6 +326,13 @@ public class VoltraModuleImpl {
     let dynamicWidgetUpdater = DynamicWidgetUpdater(
       dynamicWidgetPropsPersistence: DynamicWidgetPropsStore(),
       dynamicWidgetTimelineReload: { dynamicWidgetId in
+        // On a server-driven widget the reload below runs getTimeline, which would otherwise
+        // fetch and overwrite what was just written. ADR 0002 says the *next scheduled* fetch
+        // overwrites app-written props, not the reload the write itself caused.
+        if VoltraWidgetServer.isServerDriven(dynamicWidgetId) {
+          DynamicWidgetServerPropsStore().noteAppWrite(for: .of(dynamicWidgetId))
+        }
+
         VoltraWidgetService.reloadTimeline(for: dynamicWidgetId)
       }
     )
@@ -307,11 +376,17 @@ public class VoltraModuleImpl {
 
   func clearWidget(widgetId: String) async {
     VoltraWidgetService.removeAllData(for: widgetId)
+    VoltraWidgetService.clearWidgetServerState(for: widgetId)
     VoltraWidgetService.reloadTimeline(for: widgetId)
   }
 
   func clearAllWidgets() async {
     VoltraWidgetService.removeAllWidgets()
+
+    for widgetId in VoltraWidgetServer.serverDrivenWidgetIds {
+      VoltraWidgetService.clearWidgetServerState(for: widgetId)
+    }
+
     VoltraWidgetService.reloadAllTimelines()
   }
 
@@ -319,6 +394,19 @@ public class VoltraModuleImpl {
     try await VoltraWidgetService.getActiveWidgets()
   }
 
+  /// - Returns: an error message when the settings were rejected, or nil when they were applied.
+  func setWidgetServerUpdate(settingsJson: String, widgetId: String?) -> String? {
+    VoltraWidgetService.setWidgetServerUpdate(settingsJson: settingsJson, widgetId: widgetId)
+  }
+
+  func clearWidgetServerUpdate(widgetId: String?) -> String? {
+    VoltraWidgetService.clearWidgetServerUpdate(widgetId: widgetId)
+  }
+
+  func getWidgetServerUpdate(widgetId: String?) -> String? {
+    VoltraWidgetService.getWidgetServerUpdate(widgetId: widgetId)
+  }
+
   func setWidgetServerCredentials(token: String, headers: [String: String]?) {
     VoltraWidgetService.setWidgetServerCredentials(token: token, headers: headers)
   }
@@ -342,6 +430,16 @@ public class VoltraModuleImpl {
         return VoltraErrors.liveActivitiesNotEnabled
       case .notFound:
         return VoltraErrors.notFound
+      case .rendererMismatch:
+        return VoltraErrors.rendererMismatch
+      }
+    }
+    if let dynamicError = error as? VoltraDynamicLiveActivityError {
+      switch dynamicError {
+      case .rendererMismatch:
+        return VoltraErrors.rendererMismatch
+      case .unknownDefinition, .payloadTooLarge, .resourceUnavailable:
+        return VoltraErrors.unexpectedError(error)
       }
     }
     return VoltraErrors.unexpectedError(error)

package/ios/app/VoltraViewComponentView.mm

@@ -1,9 +1,9 @@
 #import "VoltraViewComponentView.h"
 
-#if __has_include("Voltra/Voltra-Swift.h")
-#import "Voltra/Voltra-Swift.h"
+#if __has_include("Voltra/VoltraRuntime-Swift.h")
+#import "Voltra/VoltraRuntime-Swift.h"
 #else
-#import "Voltra-Swift.h"
+#import "VoltraRuntime-Swift.h"
 #endif
 
 #import <react/renderer/components/VoltraSpec/ComponentDescriptors.h>

package/ios/app/VoltraWidgetService.swift

@@ -40,7 +40,7 @@ enum VoltraWidgetService {
   // MARK: - Reload
 
   static func reloadTimeline(for widgetId: String) {
-    WidgetCenter.shared.reloadTimelines(ofKind: "\(VoltraStorageKeys.widgetKindPrefix)\(widgetId)")
+    WidgetCenter.shared.reloadTimelines(ofKind: VoltraWidgetKind.kind(for: widgetId))
     VoltraLogger.widget.info("Reloaded timeline for '\(widgetId)'")
   }
 
@@ -49,10 +49,145 @@ enum VoltraWidgetService {
     VoltraLogger.widget.info("Reloaded all timelines")
   }
 
-  // MARK: - Server credentials
+  // MARK: - Server update settings
+
+  /// Applies runtime server-update settings and reloads the widgets they affect.
+  ///
+  /// Storing is only half of what an app expects from `setWidgetServerUpdate`: a new URL should be
+  /// fetched from now on, and `enabled: false` should take effect without waiting out the current
+  /// interval. A reload makes the affected timelines re-resolve their settings straight away.
+  ///
+  /// - Parameter widgetId: the widget to scope the settings to, or nil for every server-driven one.
+  /// - Returns: an error message, or nil when the settings were applied.
+  static func setWidgetServerUpdate(settingsJson: String, widgetId: String?) -> String? {
+    let settings: WidgetServerUpdateSettings
+
+    switch WidgetServerUpdateSettingsJson.parse(settingsJson) {
+    case let .invalid(reason):
+      return reason
+    case let .parsed(parsed):
+      settings = parsed
+    }
+
+    if let widgetId, let error = rejectIfNotServerDriven(widgetId) {
+      return error
+    }
+
+    if let error = WidgetServerSettingsValidator.validate(settings, isDebugBuild: VoltraWidgetServer.isDebugBuild) {
+      return error
+    }
+
+    WidgetServerSettingsStore.set(settings, scope: widgetId.map { .of($0) })
+    reloadServerDrivenWidgets(widgetId: widgetId)
+
+    return nil
+  }
+
+  /// Drops the runtime settings for one widget, or the global ones, so the widget falls back to
+  /// what app.json configured. Clearing the global settings is the logout gesture.
+  static func clearWidgetServerUpdate(widgetId: String?) -> String? {
+    if let widgetId, let error = rejectIfNotServerDriven(widgetId) {
+      return error
+    }
+
+    WidgetServerSettingsStore.clear(scope: widgetId.map { .of($0) })
+
+    // Clearing the global settings is logout: what the previous account's server sent has to go
+    // with it, or the widget keeps showing their data. A widget-scoped clear only drops that
+    // widget's overrides, so its props are left alone.
+    if widgetId == nil {
+      clearFetchedState()
+    }
+
+    reloadServerDrivenWidgets(widgetId: widgetId)
+
+    return nil
+  }
+
+  /// Drops what the server last sent for every server-driven widget, so a Dynamic Widget falls
+  /// back to `{}` with `env.serverUpdate.status` of `never` — the state it is in before its first
+  /// fetch.
+  private static func clearFetchedState() {
+    let statuses = DynamicWidgetServerPropsStore()
+    let propsStore = DynamicWidgetPropsStore()
+
+    for widgetId in VoltraWidgetServer.serverDrivenWidgetIds {
+      let scope = WidgetScope.of(widgetId)
+
+      try? propsStore.clearDynamicWidgetProps(for: widgetId)
+      statuses.clear(scope)
+      WidgetServerEtagStore.clear(scope)
+    }
+  }
+
+  /// The engine is chosen at generate time, so a runtime URL cannot turn a locally-driven widget
+  /// into a server-driven one. Saying so at call time is much easier to act on than a widget that
+  /// quietly never fetches.
+  private static func rejectIfNotServerDriven(_ widgetId: String) -> String? {
+    guard !VoltraWidgetServer.isServerDriven(widgetId) else { return nil }
+
+    return "Widget '\(widgetId)' is not server-driven. Add a serverUpdate entry for it in app.json "
+      + "and rebuild; a runtime url does not change how a widget is rendered."
+  }
+
+  private static func reloadServerDrivenWidgets(widgetId: String?) {
+    guard let widgetId else {
+      for id in VoltraWidgetServer.serverDrivenWidgetIds {
+        reloadTimeline(for: id)
+      }
+      return
+    }
+
+    reloadTimeline(for: widgetId)
+  }
+
+  /// Reads settings back rather than reasoning about what was set: with a `widgetId`, the fully
+  /// resolved settings that widget would fetch with right now (nil if it is not server-driven);
+  /// with none, the raw global layer only, no defaults applied.
+  static func getWidgetServerUpdate(widgetId: String?) -> String? {
+    if let widgetId {
+      let scope = WidgetScope.of(widgetId)
+
+      guard VoltraWidgetServer.resolver.isServerDriven(scope) else { return nil }
+
+      let resolved = VoltraWidgetServer.resolver.resolve(scope)
+      let settings = WidgetServerUpdateSettings(
+        url: resolved.url,
+        intervalMinutes: resolved.intervalMinutes,
+        enabled: resolved.enabled,
+        method: resolved.method,
+        query: resolved.query,
+        headers: resolved.headers,
+        body: resolved.body
+      )
+
+      return WidgetServerUpdateSettingsJson.stringify(settings)
+    }
+
+    guard let global = VoltraWidgetServer.resolver.globalSettings() else { return nil }
+
+    return WidgetServerUpdateSettingsJson.stringify(global)
+  }
+
+  /// Drops one widget's runtime settings and its fetch history, for `clearWidget`.
+  static func clearWidgetServerState(for widgetId: String) {
+    guard VoltraWidgetServer.isServerDriven(widgetId) else { return }
+
+    let scope = WidgetScope.of(widgetId)
+
+    WidgetServerSettingsStore.clear(scope: scope)
+    WidgetServerEtagStore.clear(scope)
+    DynamicWidgetServerPropsStore().clear(scope)
+  }
+
+  // MARK: - Server credentials (deprecated)
 
   /// Saves widget server credentials to the Keychain and reloads all widget timelines
   /// so extensions can use them on the next fetch.
+  ///
+  /// Deprecated in favour of `setWidgetServerUpdate` with an `Authorization` header. Kept as a
+  /// wrapper over the same Keychain accounts, so an app that has not migrated keeps working and
+  /// nothing has to be moved on device.
   static func setWidgetServerCredentials(token: String, headers: [String: String]?) {
     VoltraKeychainHelper.saveToken(token)
     if let headers = headers {
@@ -60,13 +195,20 @@ enum VoltraWidgetService {
     } else {
       VoltraKeychainHelper.deleteHeaders()
     }
+    // The credentials layer does not go through the settings store, but a new token is exactly the
+    // thing a widget stuck on a 401 is waiting for, so an in-flight fetch built with the old one
+    // must not commit.
+    WidgetServerSettingsStore.bumpRevision()
     VoltraLogger.widget.info("Server credentials saved")
     reloadAllTimelines()
   }
 
   /// Clears widget server credentials from the Keychain and reloads all widget timelines.
+  ///
+  /// Deprecated alongside `setWidgetServerCredentials`.
   static func clearWidgetServerCredentials() {
     VoltraKeychainHelper.clearAll()
+    WidgetServerSettingsStore.bumpRevision()
     VoltraLogger.widget.info("Server credentials cleared")
     reloadAllTimelines()
   }
@@ -80,10 +222,7 @@ enum VoltraWidgetService {
         switch result {
         case let .success(widgetInfos):
           let mapped = widgetInfos.map { widget -> [String: String] in
-            let prefix = VoltraStorageKeys.widgetKindPrefix
-            let name = widget.kind.hasPrefix(prefix)
-              ? String(widget.kind.dropFirst(prefix.count))
-              : widget.kind
+            let name = VoltraWidgetKind.widgetId(for: widget.kind) ?? widget.kind
 
             return [
               "name": name,
@@ -100,17 +239,13 @@ enum VoltraWidgetService {
   }
 
   /// Returns the set of widget IDs currently installed on the device.
-  /// Only IDs whose kind carries the Voltra prefix are included.
+  /// Only Voltra widgets (default `Voltra_Widget_` kind or a pinned `kind`) are included.
   static func getInstalledWidgetIds() async throws -> Set<String> {
     try await withCheckedThrowingContinuation { continuation in
       WidgetCenter.shared.getCurrentConfigurations { result in
         switch result {
         case let .success(configs):
-          let ids = Set(configs.compactMap { config -> String? in
-            let prefix = VoltraStorageKeys.widgetKindPrefix
-            guard config.kind.hasPrefix(prefix) else { return nil }
-            return String(config.kind.dropFirst(prefix.count))
-          })
+          let ids = Set(configs.compactMap { VoltraWidgetKind.widgetId(for: $0.kind) })
           continuation.resume(returning: ids)
         case let .failure(error):
           continuation.resume(throwing: error)

package/ios/app/dynamic-live-activity/VoltraDynamicLiveActivityService.swift

@@ -0,0 +1,97 @@
+import ActivityKit
+import Foundation
+
+/// App-process orchestration for the dynamic renderer. The legacy service keeps
+/// only thin cross-engine coordination points and delegates feature-specific
+/// catalog, bundle, payload, and reload behavior here.
+final class VoltraDynamicLiveActivityService {
+  private let chronology: VoltraLiveActivityChronology
+
+  init(chronology: VoltraLiveActivityChronology = .shared) {
+    self.chronology = chronology
+  }
+
+  func isActive(name: String) -> Bool {
+    activityReferences().contains { $0.name == name }
+  }
+
+  func activityReferences() -> [VoltraDynamicLiveActivityReference] {
+    VoltraDynamicLiveActivityRegistry.shared.activities()
+  }
+
+  func definitionIds() -> [String] {
+    VoltraDynamicLiveActivityRegistry.shared.definitionIds()
+  }
+
+  func create(_ request: VoltraDynamicLiveActivityCreateRequest) async throws -> String {
+    guard VoltraDynamicLiveActivityRegistry.shared.contains(request.definitionId) else {
+      throw VoltraDynamicLiveActivityError.unknownDefinition(request.definitionId)
+    }
+    do {
+      let source = try await VoltraDynamicLiveActivityBundleSource.loadForApp(definitionId: request.definitionId)
+      guard VoltraJSRenderer.evaluateLiveActivityBundle(source: source, definitionId: request.definitionId) else {
+        throw VoltraDynamicLiveActivityError.resourceUnavailable(
+          NSError(
+            domain: "VoltraDynamicLiveActivity",
+            code: -1,
+            userInfo: [NSLocalizedDescriptionKey: "Dynamic Live Activity bundle could not be evaluated."]
+          )
+        )
+      }
+    } catch let error as VoltraDynamicLiveActivityError {
+      throw error
+    } catch {
+      throw VoltraDynamicLiveActivityError.resourceUnavailable(error)
+    }
+    try VoltraDynamicLiveActivityPayloadValidator.validate(
+      name: request.name,
+      deepLinkUrl: request.deepLinkUrl,
+      props: request.props
+    )
+    guard let activity = try await VoltraDynamicLiveActivityRegistry.shared.create(request) else {
+      throw VoltraDynamicLiveActivityError.unknownDefinition(request.definitionId)
+    }
+    chronology.record(activity.id)
+    return request.name
+  }
+
+  func update(byName name: String, request: VoltraDynamicLiveActivityUpdateRequest) async throws -> Bool {
+    try VoltraDynamicLiveActivityPayloadValidator.validateContentState(request.props)
+    return await VoltraDynamicLiveActivityRegistry.shared.update(byName: name, request: request)
+  }
+
+  func end(byName name: String, dismissalPolicy: ActivityUIDismissalPolicy) async -> Bool {
+    await VoltraDynamicLiveActivityRegistry.shared.end(byName: name, dismissalPolicy: dismissalPolicy)
+  }
+
+  func endAll(dismissalPolicy: ActivityUIDismissalPolicy) async {
+    await VoltraDynamicLiveActivityRegistry.shared.endAll(dismissalPolicy: dismissalPolicy)
+  }
+
+  func reload(definitionIds: [String]?) async {
+    #if DEBUG
+      let requested = definitionIds.map(Set.init)
+      let ids = requested ?? Set(self.definitionIds())
+      var refreshed = Set<String>()
+      for definitionId in ids.sorted() {
+        guard VoltraDynamicLiveActivityRegistry.shared.contains(definitionId) else { continue }
+        do {
+          let source = try await VoltraDynamicLiveActivityBundleSource.loadForApp(definitionId: definitionId)
+          guard VoltraJSRenderer.evaluateLiveActivityBundle(source: source, definitionId: definitionId) else {
+            throw VoltraDynamicLiveActivityError.resourceUnavailable(
+              NSError(
+                domain: "VoltraDynamicLiveActivity",
+                code: -2,
+                userInfo: [NSLocalizedDescriptionKey: "Dynamic Live Activity bundle could not be evaluated."]
+              )
+            )
+          }
+          refreshed.insert(definitionId)
+        } catch {
+          VoltraLogger.activity.error("Failed to refresh Dynamic Live Activity definition '\(definitionId)': \(error)")
+        }
+      }
+      await VoltraDynamicLiveActivityRegistry.shared.reload(definitionIds: refreshed)
+    #endif
+  }
+}

package/ios/app/dynamic-live-activity/VoltraLiveActivityChronology.swift

@@ -0,0 +1,68 @@
+import Foundation
+
+/// Persists creation-time observations made by this app process. ActivityKit
+/// does not expose a cross-attributes-type creation timestamp, so an instance
+/// first encountered after a process restart must never be assigned an order
+/// merely because a catalog happened to enumerate it first.
+final class VoltraLiveActivityChronology: @unchecked Sendable {
+  static let shared = VoltraLiveActivityChronology()
+
+  private static let storageKey = "Voltra_LiveActivityChronology"
+
+  private let lock = NSLock()
+  private let defaults: UserDefaults
+  private var timestamps: [String: TimeInterval]
+
+  init(defaults: UserDefaults = .standard) {
+    self.defaults = defaults
+    if let stored = defaults.dictionary(forKey: Self.storageKey) as? [String: TimeInterval] {
+      timestamps = stored
+    } else {
+      // Migrate the previous observation-order ledger without reordering it.
+      let legacy = defaults.stringArray(forKey: Self.storageKey) ?? []
+      timestamps = Dictionary(uniqueKeysWithValues: legacy.enumerated().map { index, id in (id, Double(index)) })
+    }
+  }
+
+  func record(_ activityId: String) {
+    lock.lock()
+    defer { lock.unlock() }
+    guard timestamps[activityId] == nil else { return }
+    timestamps[activityId] = Date().timeIntervalSince1970
+    persist()
+  }
+
+  func order(
+    _ references: [VoltraDynamicLiveActivityReference]
+  ) -> [VoltraDynamicLiveActivityReference] {
+    lock.lock()
+    defer { lock.unlock() }
+
+    let activeIds = Set(references.map(\.id))
+    let nextTimestamps = timestamps.filter { activeIds.contains($0.key) }
+    if nextTimestamps != timestamps {
+      timestamps = nextTimestamps
+      persist()
+    }
+    return references.sorted { lhs, rhs in
+      switch (timestamps[lhs.id], timestamps[rhs.id]) {
+      case let (left?, right?): return left < right
+      case (_?, nil): return true
+      case (nil, _?): return false
+      case (nil, nil): return lhs.id < rhs.id
+      }
+    }
+  }
+
+  func latest(_ references: [VoltraDynamicLiveActivityReference]) -> VoltraDynamicLiveActivityReference? {
+    lock.lock()
+    defer { lock.unlock() }
+    return references.compactMap { reference in
+      timestamps[reference.id].map { (reference, $0) }
+    }.max { $0.1 < $1.1 }?.0
+  }
+
+  private func persist() {
+    defaults.set(timestamps, forKey: Self.storageKey)
+  }
+}

package/ios/shared/DynamicWidgetPropsStore.swift

@@ -20,28 +20,95 @@ struct DynamicWidgetPropsStore {
     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: Self.storageKey(for: dynamicWidgetID))
+    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 {
-    guard
-      case let .success(resolvedStorage) = storage,
-      let storageEntryJSON = try? resolvedStorage.string(forKey: Self.storageKey(for: dynamicWidgetID))
-    else {
-      return DynamicWidgetPropsCodec.emptyDynamicWidgetPropsJSON
+    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 {