@use-voltra/ios-client 2.1.1 → 2.3.0

package/ios/shared/dynamic-live-activity/VoltraDynamicLiveActivityObserver.swift

@@ -0,0 +1,97 @@
+import ActivityKit
+import Foundation
+
+/// Observes every concrete generated Dynamic Live Activity type. ActivityKit's
+/// activity streams are type-specific, so the generated catalog invokes this
+/// observer once for each bundled attributes type.
+public actor VoltraDynamicLiveActivityObserver {
+  private let onActivityDiscovered: (@Sendable (String) -> Void)?
+  private let onTokenUpdated: (@Sendable (String, String) -> Void)?
+  private let onStateChanged: (@Sendable (String, String) -> Void)?
+
+  private var definitionTasks: [String: Task<Void, Never>] = [:]
+  private var tokenTasks: [String: Task<Void, Never>] = [:]
+  private var stateTasks: [String: Task<Void, Never>] = [:]
+
+  public init(
+    onActivityDiscovered: (@Sendable (String) -> Void)? = nil,
+    onTokenUpdated: (@Sendable (String, String) -> Void)? = nil,
+    onStateChanged: (@Sendable (String, String) -> Void)? = nil
+  ) {
+    self.onActivityDiscovered = onActivityDiscovered
+    self.onTokenUpdated = onTokenUpdated
+    self.onStateChanged = onStateChanged
+  }
+
+  public func observe<Attributes: VoltraDynamicLiveActivityDefinition>(_: Attributes.Type) {
+    let definitionId = Attributes.definitionId
+    guard definitionTasks[definitionId] == nil else { return }
+
+    definitionTasks[definitionId] = Task { [weak self] in
+      for activity in Activity<Attributes>.activities {
+        await self?.observe(activity, definitionId: definitionId)
+      }
+      for await activity in Activity<Attributes>.activityUpdates {
+        await self?.observe(activity, definitionId: definitionId)
+      }
+      await self?.removeDefinitionTask(for: definitionId)
+    }
+  }
+
+  public func stopObserving() {
+    for task in definitionTasks.values {
+      task.cancel()
+    }
+    for task in tokenTasks.values {
+      task.cancel()
+    }
+    for task in stateTasks.values {
+      task.cancel()
+    }
+    definitionTasks.removeAll()
+    tokenTasks.removeAll()
+    stateTasks.removeAll()
+  }
+
+  private func observe<Attributes: VoltraDynamicLiveActivityDefinition>(
+    _ activity: Activity<Attributes>,
+    definitionId: String
+  ) {
+    let key = "\(definitionId):\(activity.id)"
+    let name = activity.attributes.name
+    onActivityDiscovered?(activity.id)
+
+    if let onTokenUpdated, tokenTasks[key] == nil {
+      tokenTasks[key] = Task { [weak self] in
+        for await token in activity.pushTokenUpdates {
+          onTokenUpdated(name, token.hexString)
+        }
+        await self?.removeTokenTask(for: key)
+      }
+    }
+
+    if let onStateChanged, stateTasks[key] == nil {
+      stateTasks[key] = Task { [weak self] in
+        for await state in activity.activityStateUpdates {
+          onStateChanged(name, String(describing: state))
+        }
+        await self?.removeStateTask(for: key)
+      }
+    }
+  }
+
+  private func removeDefinitionTask(for definitionId: String) {
+    definitionTasks[definitionId]?.cancel()
+    definitionTasks.removeValue(forKey: definitionId)
+  }
+
+  private func removeTokenTask(for key: String) {
+    tokenTasks[key]?.cancel()
+    tokenTasks.removeValue(forKey: key)
+  }
+
+  private func removeStateTask(for key: String) {
+    stateTasks[key]?.cancel()
+    stateTasks.removeValue(forKey: key)
+  }
+}

package/ios/shared/dynamic-live-activity/VoltraDynamicLiveActivityOperations.swift

@@ -0,0 +1,105 @@
+import ActivityKit
+import Foundation
+
+public struct VoltraDynamicLiveActivityCreateRequest {
+  public let definitionId: String
+  public let name: String
+  public let deepLinkUrl: String?
+  public let props: [String: VoltraDynamicLiveActivityJSONValue]
+  public let staleDate: Date?
+  public let relevanceScore: Double
+  public let pushType: PushType?
+}
+
+public struct VoltraDynamicLiveActivityUpdateRequest {
+  public let props: [String: VoltraDynamicLiveActivityJSONValue]
+  public let staleDate: Date?
+  public let relevanceScore: Double
+}
+
+public struct VoltraDynamicLiveActivityReference: Hashable {
+  public let id: String
+  public let name: String
+  public let definitionId: String
+}
+
+/// Generic ActivityKit operations called by the generated catalog. The catalog
+/// supplies the concrete generated Attributes type without exposing it to the
+/// legacy service or the React Native bridge.
+public enum VoltraDynamicLiveActivityOperations {
+  public static func create<Attributes: VoltraDynamicLiveActivityDefinition>(
+    _: Attributes.Type,
+    request: VoltraDynamicLiveActivityCreateRequest
+  ) async throws -> VoltraDynamicLiveActivityReference {
+    let attributes = Attributes(name: request.name, deepLinkUrl: request.deepLinkUrl)
+    let state = VoltraDynamicLiveActivityContentState(props: request.props)
+    let activity = try Activity.request(
+      attributes: attributes,
+      content: ActivityContent(state: state, staleDate: request.staleDate, relevanceScore: request.relevanceScore),
+      pushType: request.pushType
+    )
+    return VoltraDynamicLiveActivityReference(
+      id: activity.id,
+      name: activity.attributes.name,
+      definitionId: Attributes.definitionId
+    )
+  }
+
+  public static func update<Attributes: VoltraDynamicLiveActivityDefinition>(
+    _: Attributes.Type,
+    byName name: String,
+    request: VoltraDynamicLiveActivityUpdateRequest
+  ) async -> Bool {
+    let activities = Activity<Attributes>.activities.filter { $0.attributes.name == name }
+    for activity in activities {
+      // State is deliberately replaced in full; V1 does not merge props.
+      await activity.update(ActivityContent(
+        state: VoltraDynamicLiveActivityContentState(props: request.props),
+        staleDate: request.staleDate,
+        relevanceScore: request.relevanceScore
+      ))
+    }
+    return !activities.isEmpty
+  }
+
+  public static func end<Attributes: VoltraDynamicLiveActivityDefinition>(
+    _: Attributes.Type,
+    byName name: String,
+    dismissalPolicy: ActivityUIDismissalPolicy
+  ) async -> Bool {
+    let activities = Activity<Attributes>.activities.filter { $0.attributes.name == name }
+    for activity in activities {
+      await activity.end(ActivityContent(state: activity.content.state, staleDate: nil), dismissalPolicy: dismissalPolicy)
+    }
+    return !activities.isEmpty
+  }
+
+  public static func endAll<Attributes: VoltraDynamicLiveActivityDefinition>(
+    _: Attributes.Type,
+    dismissalPolicy: ActivityUIDismissalPolicy
+  ) async {
+    for activity in Activity<Attributes>.activities {
+      await activity.end(ActivityContent(state: activity.content.state, staleDate: nil), dismissalPolicy: dismissalPolicy)
+    }
+  }
+
+  public static func activities<Attributes: VoltraDynamicLiveActivityDefinition>(
+    _: Attributes.Type
+  ) -> [VoltraDynamicLiveActivityReference] {
+    Activity<Attributes>.activities.map {
+      VoltraDynamicLiveActivityReference(id: $0.id, name: $0.attributes.name, definitionId: Attributes.definitionId)
+    }
+  }
+
+  public static func reload<Attributes: VoltraDynamicLiveActivityDefinition>(
+    _: Attributes.Type
+  ) async {
+    for activity in Activity<Attributes>.activities {
+      await activity.update(ActivityContent(
+        state: activity.content.state,
+        staleDate: activity.content.staleDate,
+        relevanceScore: activity.content.relevanceScore
+      ))
+    }
+  }
+}

package/ios/shared/dynamic-live-activity/VoltraDynamicLiveActivityPayloadValidator.swift

@@ -0,0 +1,55 @@
+import Foundation
+
+/// Checks the portion of a Dynamic Live Activity payload ActivityKit stores.
+/// This is intentionally uncompressed: ActivityKit's 4 KB limit applies to its
+/// encoded attributes and content state, not Voltra's legacy rendered payload.
+public enum VoltraDynamicLiveActivityPayloadValidator {
+  private struct Attributes: Encodable {
+    let name: String
+    let deepLinkUrl: String?
+  }
+
+  public static func decodeProps(_ jsonString: String) throws -> [String: VoltraDynamicLiveActivityJSONValue] {
+    let data = Data(jsonString.utf8)
+    return try JSONDecoder().decode([String: VoltraDynamicLiveActivityJSONValue].self, from: data)
+  }
+
+  public static func validate(
+    name: String,
+    deepLinkUrl: String?,
+    props: [String: VoltraDynamicLiveActivityJSONValue]
+  ) throws {
+    let attributesSize = try encodedSize(Attributes(name: name, deepLinkUrl: deepLinkUrl))
+    let contentStateSize = try encodedSize(VoltraDynamicLiveActivityContentState(props: props))
+    try validateSize(attributesSize + contentStateSize)
+  }
+
+  public static func validateContentState(_ props: [String: VoltraDynamicLiveActivityJSONValue]) throws {
+    try validateSize(encodedSize(VoltraDynamicLiveActivityContentState(props: props)))
+  }
+
+  public static func encodedContentStateSize(
+    _ props: [String: VoltraDynamicLiveActivityJSONValue]
+  ) throws -> Int {
+    try encodedSize(VoltraDynamicLiveActivityContentState(props: props))
+  }
+
+  public static func encodedStartSize(
+    name: String,
+    deepLinkUrl: String?,
+    props: [String: VoltraDynamicLiveActivityJSONValue]
+  ) throws -> Int {
+    try encodedSize(Attributes(name: name, deepLinkUrl: deepLinkUrl)) +
+      encodedSize(VoltraDynamicLiveActivityContentState(props: props))
+  }
+
+  private static func encodedSize(_ value: some Encodable) throws -> Int {
+    try JSONEncoder().encode(value).count
+  }
+
+  private static func validateSize(_ size: Int) throws {
+    guard size <= VoltraConstants.maxPayloadSizeBytes else {
+      throw VoltraDynamicLiveActivityError.payloadTooLarge(size: size)
+    }
+  }
+}

package/ios/shared/dynamic-live-activity/VoltraDynamicLiveActivityRegistry.swift

@@ -0,0 +1,143 @@
+import ActivityKit
+import Foundation
+
+/// Type-erased operations for one generated ActivityKit attributes type.
+///
+/// Generated source registers descriptors at runtime. Pod-owned code only
+/// depends on this registry and never names a type compiled into the host app.
+private struct VoltraDynamicLiveActivityDescriptor {
+  let definitionId: String
+  let create: (VoltraDynamicLiveActivityCreateRequest) async throws -> VoltraDynamicLiveActivityReference
+  let update: (String, VoltraDynamicLiveActivityUpdateRequest) async -> Bool
+  let end: (String, ActivityUIDismissalPolicy) async -> Bool
+  let endAll: (ActivityUIDismissalPolicy) async -> Void
+  let activities: () -> [VoltraDynamicLiveActivityReference]
+  let observe: (VoltraDynamicLiveActivityObserver) async -> Void
+  let reload: () async -> Void
+
+  init<Attributes: VoltraDynamicLiveActivityDefinition>(_ attributes: Attributes.Type) {
+    definitionId = Attributes.definitionId
+    create = { try await VoltraDynamicLiveActivityOperations.create(attributes, request: $0) }
+    update = { await VoltraDynamicLiveActivityOperations.update(attributes, byName: $0, request: $1) }
+    end = { await VoltraDynamicLiveActivityOperations.end(attributes, byName: $0, dismissalPolicy: $1) }
+    endAll = { await VoltraDynamicLiveActivityOperations.endAll(attributes, dismissalPolicy: $0) }
+    activities = { VoltraDynamicLiveActivityOperations.activities(attributes) }
+    observe = { await $0.observe(attributes) }
+    reload = { await VoltraDynamicLiveActivityOperations.reload(attributes) }
+  }
+}
+
+/// Runtime-owned catalog populated by the generated host source.
+///
+/// `VoltraGeneratedDynamicLiveActivityRegistration` has a fixed Objective-C
+/// runtime name in both the app and extension products. This lets the pod ask
+/// the host target to register its generated types without creating a reverse
+/// compile-time dependency from the pod to the host.
+public final class VoltraDynamicLiveActivityRegistry {
+  public static let shared = VoltraDynamicLiveActivityRegistry()
+
+  private let lock = NSLock()
+  private var descriptors: [String: VoltraDynamicLiveActivityDescriptor] = [:]
+  private var attemptedGeneratedRegistration = false
+
+  private init() {}
+
+  public func register<Attributes: VoltraDynamicLiveActivityDefinition>(_ attributes: Attributes.Type) {
+    lock.lock()
+    descriptors[Attributes.definitionId] = VoltraDynamicLiveActivityDescriptor(attributes)
+    lock.unlock()
+  }
+
+  public func contains(_ definitionId: String) -> Bool {
+    ensureGeneratedRegistration()
+    lock.lock()
+    defer { lock.unlock() }
+    return descriptors[definitionId] != nil
+  }
+
+  public func definitionIds() -> [String] {
+    ensureGeneratedRegistration()
+    lock.lock()
+    defer { lock.unlock() }
+    return descriptors.keys.sorted()
+  }
+
+  public func create(_ request: VoltraDynamicLiveActivityCreateRequest) async throws -> VoltraDynamicLiveActivityReference? {
+    guard let descriptor = descriptor(for: request.definitionId) else { return nil }
+    return try await descriptor.create(request)
+  }
+
+  public func update(byName name: String, request: VoltraDynamicLiveActivityUpdateRequest) async -> Bool {
+    for descriptor in descriptorSnapshot() {
+      if await descriptor.update(name, request) {
+        return true
+      }
+    }
+    return false
+  }
+
+  public func end(byName name: String, dismissalPolicy: ActivityUIDismissalPolicy) async -> Bool {
+    var ended = false
+    for descriptor in descriptorSnapshot() {
+      if await descriptor.end(name, dismissalPolicy) {
+        ended = true
+      }
+    }
+    return ended
+  }
+
+  public func endAll(dismissalPolicy: ActivityUIDismissalPolicy) async {
+    for descriptor in descriptorSnapshot() {
+      await descriptor.endAll(dismissalPolicy)
+    }
+  }
+
+  public func activities() -> [VoltraDynamicLiveActivityReference] {
+    descriptorSnapshot().flatMap { $0.activities() }
+  }
+
+  public func startObserving(with observer: VoltraDynamicLiveActivityObserver) async {
+    for descriptor in descriptorSnapshot() {
+      await descriptor.observe(observer)
+    }
+  }
+
+  public func reload(definitionIds: Set<String>?) async {
+    for descriptor in descriptorSnapshot() where definitionIds?.contains(descriptor.definitionId) != false {
+      await descriptor.reload()
+    }
+  }
+
+  private func descriptor(for definitionId: String) -> VoltraDynamicLiveActivityDescriptor? {
+    ensureGeneratedRegistration()
+    lock.lock()
+    defer { lock.unlock() }
+    return descriptors[definitionId]
+  }
+
+  private func descriptorSnapshot() -> [VoltraDynamicLiveActivityDescriptor] {
+    ensureGeneratedRegistration()
+    lock.lock()
+    defer { lock.unlock() }
+    return descriptors.values.sorted { $0.definitionId < $1.definitionId }
+  }
+
+  private func ensureGeneratedRegistration() {
+    lock.lock()
+    guard !attemptedGeneratedRegistration else {
+      lock.unlock()
+      return
+    }
+    attemptedGeneratedRegistration = true
+    lock.unlock()
+
+    let className = "VoltraGeneratedDynamicLiveActivityRegistration"
+    let selector = NSSelectorFromString("registerDefinitions")
+    guard let registration = NSClassFromString(className) as? NSObject.Type,
+          registration.responds(to: selector)
+    else {
+      return
+    }
+    registration.perform(selector)
+  }
+}

package/ios/shared/dynamic-live-activity/VoltraDynamicLiveActivityRenderFailureQueue.swift

@@ -0,0 +1,158 @@
+import Foundation
+
+#if canImport(Darwin)
+  import Darwin
+#else
+  import Glibc
+#endif
+
+/// The intentionally minimal diagnostic record sent from the widget extension
+/// to the app after a Dynamic Live Activity definition cannot be rendered.
+/// Do not add props, tokens, stages, or arbitrary error details here.
+public struct VoltraDynamicLiveActivityRenderFailure: Codable, Equatable {
+  public static let eventType = "dynamicLiveActivityRenderFailed"
+
+  public let type: String
+  public let source: String
+  public let timestamp: TimeInterval
+  public let activityName: String
+  public let definitionId: String
+  public let message: String
+
+  public init(activityName: String, definitionId: String, message: String, timestamp: Date = Date()) {
+    type = Self.eventType
+    source = activityName
+    self.timestamp = timestamp.timeIntervalSince1970
+    self.activityName = activityName
+    self.definitionId = definitionId
+    self.message = Self.sanitize(message)
+  }
+
+  public var dictionary: [String: Any] {
+    [
+      "type": type,
+      "source": source,
+      "timestamp": timestamp,
+      "activityName": activityName,
+      "definitionId": definitionId,
+      "message": message,
+    ]
+  }
+
+  /// Error descriptions can contain line breaks and unbounded implementation
+  /// details. Keep the diagnostic useful while making the persisted contract
+  /// predictable and safe to expose to JavaScript.
+  public static func sanitize(_ message: String) -> String {
+    let collapsed = message
+      .components(separatedBy: .whitespacesAndNewlines)
+      .filter { !$0.isEmpty }
+      .joined(separator: " ")
+    let fallback = "Dynamic Live Activity rendering failed."
+    return String((collapsed.isEmpty ? fallback : collapsed).prefix(500))
+  }
+}
+
+public protocol VoltraDynamicLiveActivityRenderFailureStorage {
+  func append(_ failure: VoltraDynamicLiveActivityRenderFailure, capacity: Int) throws
+  func drain() throws -> [VoltraDynamicLiveActivityRenderFailure]
+}
+
+/// Cross-process-safe file storage for the dedicated failure queue.
+///
+/// The app and widget extension take an advisory lock on the same App Group
+/// lock file before every read/modify/write transaction. Atomic replacement of
+/// the JSON data file prevents partial writes. Corrupt data is quarantined and
+/// treated as an empty queue so one damaged record cannot permanently disable
+/// diagnostics.
+public final class VoltraDynamicLiveActivityRenderFailureFileStorage: VoltraDynamicLiveActivityRenderFailureStorage {
+  private let directoryURL: URL
+  private let fileManager: FileManager
+  private let queueFileName = "dynamic-live-activity-render-failures-v1.json"
+  private let lockFileName = "dynamic-live-activity-render-failures-v1.lock"
+
+  public init(directoryURL: URL, fileManager: FileManager = .default) {
+    self.directoryURL = directoryURL
+    self.fileManager = fileManager
+  }
+
+  public func append(_ failure: VoltraDynamicLiveActivityRenderFailure, capacity: Int) throws {
+    try withExclusiveAccess { queueURL in
+      var failures = loadRecoveringCorruption(from: queueURL)
+      failures.append(failure)
+      if failures.count > capacity {
+        failures.removeFirst(failures.count - capacity)
+      }
+      try write(failures, to: queueURL)
+    }
+  }
+
+  public func drain() throws -> [VoltraDynamicLiveActivityRenderFailure] {
+    try withExclusiveAccess { queueURL in
+      let failures = loadRecoveringCorruption(from: queueURL)
+      try write([], to: queueURL)
+      return failures
+    }
+  }
+
+  private func withExclusiveAccess<Result>(
+    _ operation: (URL) throws -> Result
+  ) throws -> Result {
+    try fileManager.createDirectory(at: directoryURL, withIntermediateDirectories: true)
+    let lockURL = directoryURL.appendingPathComponent(lockFileName, isDirectory: false)
+    let descriptor = open(lockURL.path, O_CREAT | O_RDWR, S_IRUSR | S_IWUSR)
+    guard descriptor >= 0 else { throw POSIXError(.EIO) }
+    defer { close(descriptor) }
+    guard flock(descriptor, LOCK_EX) == 0 else { throw POSIXError(.EIO) }
+    defer { flock(descriptor, LOCK_UN) }
+    return try operation(directoryURL.appendingPathComponent(queueFileName, isDirectory: false))
+  }
+
+  private func loadRecoveringCorruption(from url: URL) -> [VoltraDynamicLiveActivityRenderFailure] {
+    guard fileManager.fileExists(atPath: url.path) else { return [] }
+    do {
+      return try JSONDecoder().decode(
+        [VoltraDynamicLiveActivityRenderFailure].self,
+        from: Data(contentsOf: url)
+      )
+    } catch {
+      let quarantineURL = directoryURL.appendingPathComponent(
+        "\(queueFileName).corrupt-\(UUID().uuidString)",
+        isDirectory: false
+      )
+      try? fileManager.moveItem(at: url, to: quarantineURL)
+      return []
+    }
+  }
+
+  private func write(_ failures: [VoltraDynamicLiveActivityRenderFailure], to url: URL) throws {
+    try JSONEncoder().encode(failures).write(to: url, options: .atomic)
+  }
+}
+
+/// A dedicated, bounded queue whose storage owns the append/drain transaction.
+public final class VoltraDynamicLiveActivityRenderFailureQueue {
+  public static let capacity = 100
+
+  private let storage: VoltraDynamicLiveActivityRenderFailureStorage
+  public init(storage: VoltraDynamicLiveActivityRenderFailureStorage) {
+    self.storage = storage
+  }
+
+  @discardableResult
+  public func record(_ failure: VoltraDynamicLiveActivityRenderFailure) -> Bool {
+    do {
+      try storage.append(failure, capacity: Self.capacity)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  public func drain() -> [VoltraDynamicLiveActivityRenderFailure] {
+    do {
+      return try storage.drain()
+    } catch {
+      return []
+    }
+  }
+}

package/ios/shared/dynamic-live-activity/VoltraDynamicLiveActivityRenderFailureReporter.swift

@@ -0,0 +1,120 @@
+import CoreFoundation
+import Foundation
+
+/// Cross-process notification relay for the App Group backed failure queue.
+/// Darwin notifications carry no payload, so consumers always drain storage.
+private final class VoltraDynamicLiveActivityRenderFailureNotifier {
+  static let shared = VoltraDynamicLiveActivityRenderFailureNotifier()
+
+  private let lock = NSLock()
+  private var handlers: [UUID: () -> Void] = [:]
+  private let name = "com.voltra.dynamicLiveActivityRenderFailures" as CFString
+
+  private init() {
+    CFNotificationCenterAddObserver(
+      CFNotificationCenterGetDarwinNotifyCenter(),
+      Unmanaged.passUnretained(self).toOpaque(),
+      Self.didReceive,
+      name,
+      nil,
+      .deliverImmediately
+    )
+  }
+
+  deinit {
+    CFNotificationCenterRemoveObserver(
+      CFNotificationCenterGetDarwinNotifyCenter(),
+      Unmanaged.passUnretained(self).toOpaque(),
+      CFNotificationName(name),
+      nil
+    )
+  }
+
+  func add(_ handler: @escaping () -> Void) -> UUID {
+    let token = UUID()
+    lock.lock()
+    handlers[token] = handler
+    lock.unlock()
+    return token
+  }
+
+  func remove(_ token: UUID) {
+    lock.lock()
+    handlers.removeValue(forKey: token)
+    lock.unlock()
+  }
+
+  func post() {
+    notifyHandlers()
+    CFNotificationCenterPostNotification(
+      CFNotificationCenterGetDarwinNotifyCenter(),
+      CFNotificationName(name),
+      nil,
+      nil,
+      true
+    )
+  }
+
+  private static let didReceive: CFNotificationCallback = { _, observer, _, _, _ in
+    guard let observer else { return }
+    Unmanaged<VoltraDynamicLiveActivityRenderFailureNotifier>
+      .fromOpaque(observer)
+      .takeUnretainedValue()
+      .notifyHandlers()
+  }
+
+  private func notifyHandlers() {
+    lock.lock()
+    let currentHandlers = Array(handlers.values)
+    lock.unlock()
+    currentHandlers.forEach { $0() }
+  }
+}
+
+/// Owns the production App Group queue and OS logging path. The extension only
+/// records failures; the app's event bus drains them when JavaScript can listen.
+public enum VoltraDynamicLiveActivityRenderFailureReporter {
+  private static var queue: VoltraDynamicLiveActivityRenderFailureQueue? {
+    guard
+      let group = VoltraConfig.groupIdentifier(),
+      let directoryURL = FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: group)
+    else {
+      return nil
+    }
+    return VoltraDynamicLiveActivityRenderFailureQueue(
+      storage: VoltraDynamicLiveActivityRenderFailureFileStorage(directoryURL: directoryURL)
+    )
+  }
+
+  @discardableResult
+  public static func record(activityName: String, definitionId: String, message: String) -> Bool {
+    let failure = VoltraDynamicLiveActivityRenderFailure(
+      activityName: activityName,
+      definitionId: definitionId,
+      message: message
+    )
+    let persisted = queue?.record(failure) ?? false
+    VoltraLogger.activity.error(
+      "[DynamicLiveActivity] activity=\(failure.activityName, privacy: .public) definitionId=\(failure.definitionId, privacy: .public) \(failure.message, privacy: .public)"
+    )
+    if persisted {
+      VoltraDynamicLiveActivityRenderFailureNotifier.shared.post()
+    } else {
+      VoltraLogger.event.error("Failed to persist Dynamic Live Activity render failure")
+    }
+    return persisted
+  }
+
+  public static func drain() -> [VoltraDynamicLiveActivityRenderFailure] {
+    queue?.drain() ?? []
+  }
+
+  /// The returned token must be removed when the JS bridge listener goes away.
+  public static func observeChanges(_ handler: @escaping () -> Void) -> UUID {
+    VoltraDynamicLiveActivityRenderFailureNotifier.shared.add(handler)
+  }
+
+  public static func removeChangeObserver(_ token: UUID) {
+    VoltraDynamicLiveActivityRenderFailureNotifier.shared.remove(token)
+  }
+}