voltra 1.4.0 → 2.0.0-rc.3

package/ios/shared/VoltraLiveActivityPayload.swift

@@ -1,113 +0,0 @@
-import Foundation
-
-/// The parsed root payload for a Live Activity update
-/// Handles the one-time JSON parsing and region extraction
-public struct VoltraLiveActivityPayload: Hashable {
-  /// Parsed UI trees for each region
-  public let regions: [VoltraRegion: [VoltraNode]]
-
-  /// Optional tint color for Dynamic Island keyline
-  public let keylineTint: String?
-
-  /// Optional background tint for Lock Screen
-  public let activityBackgroundTint: String?
-
-  /// Whether this payload represents an unsupported version (renders empty)
-  public let isUnsupportedVersion: Bool
-
-  /// Parse from decompressed JSON string (called once per update)
-  public init(jsonString: String) throws {
-    let root = try JSONValue.parse(from: jsonString)
-
-    // Migrate to current version if needed
-    guard let migrated = try VoltraPayloadMigrator.migrateToCurrentVersion(root) else {
-      // Unsupported version (future version) - render empty
-      regions = [:]
-      keylineTint = nil
-      activityBackgroundTint = nil
-      isUnsupportedVersion = true
-      return
-    }
-
-    // Extract regions directly from the parsed tree
-    regions = try Self.extractRegions(from: migrated)
-    keylineTint = migrated["isl_keyline_tint"]?.stringValue
-    activityBackgroundTint = migrated["ls_background_tint"]?.stringValue
-    isUnsupportedVersion = false
-  }
-
-  /// Extract regions from the parsed JSON tree
-  private static func extractRegions(from root: JSONValue) throws -> [VoltraRegion: [VoltraNode]] {
-    var regions: [VoltraRegion: [VoltraNode]] = [:]
-
-    // Handle array case (same UI for all regions)
-    if case .array = root {
-      let nodes = try parseNodes(from: root, stylesheet: nil, sharedElements: nil)
-      for region in VoltraRegion.allCases {
-        regions[region] = nodes
-      }
-      return regions
-    }
-
-    // Handle object case (region-specific UIs)
-    guard case let .object(rootObject) = root else {
-      throw NSError(domain: "VoltraLiveActivityPayload",
-                    code: -1,
-                    userInfo: [NSLocalizedDescriptionKey: "Invalid root JSON type"])
-    }
-
-    // Extract the shared stylesheet from root (key "s")
-    let stylesheet = extractStylesheet(from: rootObject)
-
-    // Extract the shared elements from root (key "e") for element deduplication
-    let sharedElements = extractSharedElements(from: rootObject)
-
-    // Extract components for each region
-    for region in VoltraRegion.allCases {
-      if let regionValue = rootObject[region.jsonKey] {
-        let nodes = try parseNodes(from: regionValue, stylesheet: stylesheet, sharedElements: sharedElements)
-        regions[region] = nodes
-      }
-    }
-
-    return regions
-  }
-
-  /// Parse an array of JSON values into VoltraNodes
-  private static func parseNodes(from value: JSONValue, stylesheet: [[String: JSONValue]]?, sharedElements: [JSONValue]?) throws -> [VoltraNode] {
-    if case let .array(nodeArray) = value {
-      return try nodeArray.compactMap { nodeJson in
-        guard case .object = nodeJson else { return nil }
-        return try VoltraNode(from: nodeJson, stylesheet: stylesheet, sharedElements: sharedElements)
-      }
-    } else if case .object = value {
-      // Single node wrapped in array
-      return try [VoltraNode(from: value, stylesheet: stylesheet, sharedElements: sharedElements)]
-    } else {
-      return []
-    }
-  }
-
-  /// Extract the shared stylesheet from root
-  private static func extractStylesheet(from root: [String: JSONValue]) -> [[String: JSONValue]]? {
-    guard case let .array(stylesheetArray) = root["s"] else {
-      return nil
-    }
-
-    // Convert JSONValue array to [[String: JSONValue]]
-    return stylesheetArray.compactMap { item in
-      if case let .object(dict) = item {
-        return dict
-      }
-      return nil
-    }
-  }
-
-  /// Extract the shared elements array from root (for element deduplication)
-  private static func extractSharedElements(from root: [String: JSONValue]) -> [JSONValue]? {
-    guard case let .array(elementsArray) = root["e"] else {
-      return nil
-    }
-    return elementsArray
-  }
-}

package/ios/shared/VoltraLogger.swift

@@ -1,30 +0,0 @@
-import os
-
-/// Centralized loggers for the Voltra module.
-///
-/// Each category maps to a distinct domain of concern so logs can be filtered
-/// independently in Console.app or via `log stream --predicate 'subsystem == "com.voltra"'`.
-enum VoltraLogger {
-  private static let subsystem = "com.voltra"
-
-  /// Expo module boundary (JS → native calls, error remapping)
-  static let module = Logger(subsystem: subsystem, category: "module")
-
-  /// Widget data, timelines, server credentials, WidgetCenter reloads
-  static let widget = Logger(subsystem: subsystem, category: "widget")
-
-  /// Live Activity lifecycle (create, update, end, reload)
-  static let activity = Logger(subsystem: subsystem, category: "liveActivity")
-
-  /// Image preloading and the shared image store
-  static let image = Logger(subsystem: subsystem, category: "image")
-
-  /// VoltraEventBus and VoltraPersistentEventQueue
-  static let event = Logger(subsystem: subsystem, category: "event")
-
-  /// Keychain reads and writes
-  static let keychain = Logger(subsystem: subsystem, category: "keychain")
-
-  /// UserDefaults / shared storage (VoltraWidgetDefaults)
-  static let storage = Logger(subsystem: subsystem, category: "storage")
-}

package/ios/shared/VoltraNode.swift

@@ -1,196 +0,0 @@
-import Foundation
-import SwiftUI
-
-/// Represents anything that can be rendered (like ReactNode)
-public indirect enum VoltraNode: Hashable, View {
-  /// A component element
-  case element(VoltraElement)
-
-  /// Multiple nodes (fragment/array)
-  case array([VoltraNode])
-
-  /// Plain text content
-  case text(String)
-
-  /// Nothing to render
-  case empty
-
-  // MARK: - Initialization
-
-  /// Initialize from JSONValue (handles all types)
-  /// - Parameters:
-  ///   - json: The JSON value to parse
-  ///   - stylesheet: Optional shared stylesheet for style deduplication
-  ///   - sharedElements: Optional shared elements array for element deduplication
-  public init(from json: JSONValue, stylesheet: [[String: JSONValue]]? = nil, sharedElements: [JSONValue]? = nil) {
-    switch json {
-    case let .string(text):
-      self = .text(text)
-    case let .int(num):
-      self = .text(String(num))
-    case let .double(num):
-      self = .text(String(num))
-    case let .bool(val):
-      self = .text(String(val))
-    case .null:
-      self = .empty
-    case let .array(items):
-      let nodes = items.map { VoltraNode(from: $0, stylesheet: stylesheet, sharedElements: sharedElements) }.filter { !$0.isEmpty }
-      self = nodes.isEmpty ? .empty : .array(nodes)
-    case let .object(dict):
-      // Check for element reference ($r key) and resolve from shared elements
-      if let refIndex = dict["$r"]?.intValue,
-         let sharedElements = sharedElements,
-         refIndex >= 0, refIndex < sharedElements.count
-      {
-        // Resolve reference by parsing the shared element
-        self = VoltraNode(from: sharedElements[refIndex], stylesheet: stylesheet, sharedElements: sharedElements)
-      } else if let element = VoltraElement(from: json, stylesheet: stylesheet, sharedElements: sharedElements) {
-        self = .element(element)
-      } else {
-        self = .empty
-      }
-    }
-  }
-
-  /// Check if node represents nothing
-  public var isEmpty: Bool {
-    if case .empty = self { return true }
-    return false
-  }
-
-  /// Parse a VoltraNode from JSON, extracting stylesheet and sharedElements if present
-  /// This is a convenience factory that handles the common pattern of extracting
-  /// stylesheet ("s") and sharedElements ("e") from the root JSON object.
-  /// - Parameter json: The JSON value to parse
-  /// - Returns: A parsed VoltraNode
-  public static func parse(from json: JSONValue) -> VoltraNode {
-    var stylesheet: [[String: JSONValue]]? = nil
-    var sharedElements: [JSONValue]? = nil
-
-    if case let .object(rootObject) = json {
-      // Extract stylesheet (key "s")
-      if case let .array(stylesheetArray) = rootObject["s"] {
-        stylesheet = stylesheetArray.compactMap { item in
-          if case let .object(dict) = item { return dict }
-          return nil
-        }
-      }
-      // Extract shared elements (key "e")
-      if case let .array(elementsArray) = rootObject["e"] {
-        sharedElements = elementsArray
-      }
-    }
-
-    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)
-      } else {
-        EmptyView()
-      }
-
-    default:
-      EmptyView()
-    }
-  }
-}

package/ios/shared/VoltraPayloadMigrator.swift

@@ -1,63 +0,0 @@
-import Foundation
-
-/// Error types for payload migration
-public enum VoltraPayloadError: Error {
-  case missingVersion
-  case invalidPayloadStructure
-}
-
-/// Protocol for migrating payloads from one version to the next
-public protocol VoltraPayloadMigration {
-  /// The source version this migration upgrades FROM
-  static var fromVersion: Int { get }
-
-  /// The target version this migration upgrades TO
-  static var toVersion: Int { get }
-
-  /// Migrate the raw JSON from the source version to the target version
-  static func migrate(_ json: JSONValue) throws -> JSONValue
-}
-
-/// Manages payload version migrations
-public enum VoltraPayloadMigrator {
-  /// Current (latest) payload version
-  public static let currentVersion = 1
-
-  /// Registered migrations, keyed by source version
-  /// When adding a new version:
-  /// 1. Increment currentVersion
-  /// 2. Add migration: [oldVersion: VOldToVNewMigration.self]
-  private static let migrations: [Int: any VoltraPayloadMigration.Type] = [:
-    // Empty for v1, add as needed:
-    // 1: V1ToV2Migration.self,
-  ]
-
-  /// Migrate a payload to the current version
-  /// - Parameter json: The raw parsed JSON payload
-  /// - Returns: Migrated JSON, or nil if version is unsupported (future version)
-  public static func migrateToCurrentVersion(_ json: JSONValue) throws -> JSONValue? {
-    guard let version = json["v"]?.intValue else {
-      throw VoltraPayloadError.missingVersion
-    }
-
-    // Future version we don't understand - silently ignore
-    if version > currentVersion {
-      return nil
-    }
-
-    var currentJson = json
-    var currentVer = version
-
-    // Apply migrations sequentially until we reach the current version
-    while currentVer < currentVersion {
-      guard let migration = migrations[currentVer] else {
-        // Gap in migration chain - shouldn't happen if migrations are maintained properly
-        return nil
-      }
-      currentJson = try migration.migrate(currentJson)
-      currentVer = migration.toVersion
-    }
-
-    return currentJson
-  }
-}

package/ios/shared/VoltraPersistentEventQueue.swift

@@ -1,67 +0,0 @@
-import Foundation
-import os
-
-/// Persistent event queue for events that must survive app death (e.g., interactions from widget)
-/// Uses UserDefaults with App Group for cross-process communication
-public enum VoltraPersistentEventQueue {
-  private static let queueKey = "Voltra_EventsQueue"
-
-  /// Write an event to the persistent queue (UserDefaults)
-  static func write(_ payload: [String: Any]) {
-    guard let group = VoltraConfig.groupIdentifier(),
-          let defaults = UserDefaults(suiteName: group),
-          JSONSerialization.isValidJSONObject(payload),
-          let data = try? JSONSerialization.data(withJSONObject: payload, options: [])
-    else {
-      VoltraLogger.event.error("Failed to write event — no group identifier or invalid payload")
-      return
-    }
-
-    let jsonString = String(data: data, encoding: .utf8) ?? "{}"
-
-    var queue = defaults.array(forKey: queueKey) as? [String] ?? []
-    queue.append(jsonString)
-    defaults.set(queue, forKey: queueKey)
-    defaults.synchronize()
-
-    let eventName = payload["type"] as? String ?? "unknown"
-    VoltraLogger.event.debug("Wrote event: \(eventName)")
-  }
-
-  /// Read all events from the persistent queue and clear it
-  /// Returns an array of (eventName, eventData) tuples
-  static func popAll() -> [(name: String, data: [String: Any])] {
-    guard let group = VoltraConfig.groupIdentifier() else {
-      VoltraLogger.event.error("popAll: No group identifier found")
-      return []
-    }
-    guard let defaults = UserDefaults(suiteName: group) else {
-      VoltraLogger.event.error("popAll: Could not access UserDefaults for group '\(group)'")
-      return []
-    }
-
-    let queue = defaults.array(forKey: queueKey) as? [String] ?? []
-    let eventCount = queue.count
-    VoltraLogger.event.debug("popAll: Found \(eventCount) events in queue")
-
-    // Clear the queue first
-    defaults.set([String](), forKey: queueKey)
-    defaults.synchronize()
-
-    // Skip processing if queue is excessively large (stale data)
-    if eventCount > 1000 {
-      VoltraLogger.event.warning("popAll: Skipping \(eventCount) stale events")
-      return []
-    }
-
-    // Parse JSON strings into event tuples
-    return queue.compactMap { jsonString -> (name: String, data: [String: Any])? in
-      guard let data = jsonString.data(using: .utf8),
-            let dict = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
-            let eventName = dict["type"] as? String
-      else { return nil }
-
-      return (name: eventName, data: dict)
-    }
-  }
-}

package/ios/shared/VoltraRefreshIntent.swift

@@ -1,29 +0,0 @@
-import AppIntents
-import WidgetKit
-
-/// An AppIntent that triggers an immediate widget timeline reload.
-/// Used by the native refresh button overlay on server-driven widgets.
-@available(iOS 17.0, *)
-public struct VoltraRefreshIntent: AppIntent {
-  public static var title: LocalizedStringResource = "Refresh Widget"
-  public static var isDiscoverable: Bool = false
-
-  @Parameter(title: "Widget ID")
-  public var widgetId: String?
-
-  public init() {}
-
-  public init(widgetId: String) {
-    self.widgetId = widgetId
-  }
-
-  public func perform() async throws -> some IntentResult {
-    if let widgetId = widgetId {
-      let kind = "\(VoltraStorageKeys.widgetKindPrefix)\(widgetId)"
-      WidgetCenter.shared.reloadTimelines(ofKind: kind)
-    } else {
-      WidgetCenter.shared.reloadAllTimelines()
-    }
-    return .result()
-  }
-}

package/ios/shared/VoltraRegion.swift

@@ -1,37 +0,0 @@
-import Foundation
-
-public enum VoltraRegion: String, Codable, Hashable, CaseIterable {
-  case lockScreen
-  case islandExpandedCenter
-  case islandExpandedLeading
-  case islandExpandedTrailing
-  case islandExpandedBottom
-  case islandCompactLeading
-  case islandCompactTrailing
-  case islandMinimal
-  case supplementalActivityFamiliesSmall
-
-  /// The JSON key for this region in the payload
-  public var jsonKey: String {
-    switch self {
-    case .lockScreen:
-      return "ls"
-    case .islandExpandedCenter:
-      return "isl_exp_c"
-    case .islandExpandedLeading:
-      return "isl_exp_l"
-    case .islandExpandedTrailing:
-      return "isl_exp_t"
-    case .islandExpandedBottom:
-      return "isl_exp_b"
-    case .islandCompactLeading:
-      return "isl_cmp_l"
-    case .islandCompactTrailing:
-      return "isl_cmp_t"
-    case .islandMinimal:
-      return "isl_min"
-    case .supplementalActivityFamiliesSmall:
-      return "saf_sm"
-    }
-  }
-}

package/ios/shared/VoltraWidgetDefaults.swift

@@ -1,114 +0,0 @@
-import Foundation
-import os
-
-/// Errors that can occur during widget persistence operations.
-public enum WidgetError: Error, LocalizedError {
-  case appGroupNotConfigured
-  case userDefaultsUnavailable
-
-  public var errorDescription: String? {
-    switch self {
-    case .appGroupNotConfigured:
-      return "App Group not configured. Set 'groupIdentifier' in the Voltra config plugin to use widgets."
-    case .userDefaultsUnavailable:
-      return "Unable to access UserDefaults for the app group."
-    }
-  }
-}
-
-/// Low-level UserDefaults CRUD for widget keys.
-/// Shared between the app target (write/clear) and the widget extension target (read).
-///
-/// Write methods throw `WidgetError` to surface configuration problems to the caller.
-/// Read and remove methods are non-throwing: they return nil / no-op when the app group
-/// is not configured, since the widget extension has no way to propagate errors.
-public enum VoltraWidgetDefaults {
-  // MARK: - Read
-
-  public static func widgetJson(for widgetId: String) -> String? {
-    try? resolvedDefaults().string(forKey: VoltraStorageKeys.widgetJson(widgetId))
-  }
-
-  public static func deepLinkUrl(for widgetId: String) -> String? {
-    try? resolvedDefaults().string(forKey: VoltraStorageKeys.widgetDeepLinkUrl(widgetId))
-  }
-
-  public static func timelineString(for widgetId: String) -> String? {
-    try? resolvedDefaults().string(forKey: VoltraStorageKeys.widgetTimeline(widgetId))
-  }
-
-  // MARK: - Write
-
-  public static func setWidgetJson(_ json: String, for widgetId: String, deepLinkUrl: String?) throws {
-    let defaults = try resolvedDefaults()
-
-    let dataSize = json.utf8.count
-    if dataSize > VoltraConstants.widgetJsonWarningSizeBytes {
-      VoltraLogger.storage.warning("Large widget payload for '\(widgetId)': \(dataSize) bytes (threshold: \(VoltraConstants.widgetJsonWarningSizeBytes) bytes)")
-    }
-
-    defaults.set(json, forKey: VoltraStorageKeys.widgetJson(widgetId))
-
-    if let url = deepLinkUrl, !url.isEmpty {
-      defaults.set(url, forKey: VoltraStorageKeys.widgetDeepLinkUrl(widgetId))
-    } else {
-      defaults.removeObject(forKey: VoltraStorageKeys.widgetDeepLinkUrl(widgetId))
-    }
-
-    defaults.synchronize()
-  }
-
-  public static func setTimeline(_ timeline: String, for widgetId: String) throws {
-    let defaults = try resolvedDefaults()
-
-    let dataSize = timeline.utf8.count
-    if dataSize > VoltraConstants.timelineWarningSizeBytes {
-      VoltraLogger.storage.warning("Large timeline for '\(widgetId)': \(dataSize) bytes (threshold: \(VoltraConstants.timelineWarningSizeBytes) bytes)")
-    }
-
-    defaults.set(timeline, forKey: VoltraStorageKeys.widgetTimeline(widgetId))
-    defaults.synchronize()
-  }
-
-  // MARK: - Remove
-
-  /// Removes all persisted data (json, deepLinkUrl, timeline) 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))
-    defaults.synchronize()
-  }
-
-  public static func removeTimeline(for widgetId: String) {
-    guard let defaults = try? resolvedDefaults() else { return }
-    defaults.removeObject(forKey: VoltraStorageKeys.widgetTimeline(widgetId))
-    defaults.synchronize()
-  }
-
-  /// 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 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))
-    }
-    defaults.synchronize()
-  }
-
-  // MARK: - Private
-
-  private static func resolvedDefaults() throws -> UserDefaults {
-    guard let groupId = VoltraConfig.groupIdentifier() else {
-      throw WidgetError.appGroupNotConfigured
-    }
-    guard let defaults = UserDefaults(suiteName: groupId) else {
-      throw WidgetError.userDefaultsUnavailable
-    }
-    return defaults
-  }
-}