voltra 1.4.0 → 2.0.0-rc.3

package/ios/shared/VoltraElement.swift

@@ -1,153 +0,0 @@
-import Foundation
-
-/// A single component element in the Voltra UI tree
-public struct VoltraElement: Hashable {
-  /// Component type name (e.g., "VStack", "Text", "Button")
-  public let type: String
-
-  /// Optional identifier for the element
-  public let id: String?
-
-  /// Child nodes or text content
-  public let children: VoltraNode?
-
-  /// Raw properties (stored as JSONValue for type safety)
-  private let _props: [String: JSONValue]?
-
-  /// Optional stylesheet for resolving style references
-  public let stylesheet: [[String: JSONValue]]?
-
-  /// Optional shared elements for resolving element references
-  public let sharedElements: [JSONValue]?
-
-  // MARK: - Hashable
-
-  public func hash(into hasher: inout Hasher) {
-    hasher.combine(type)
-    hasher.combine(id)
-    hasher.combine(children)
-    hasher.combine(_props)
-  }
-
-  public static func == (lhs: VoltraElement, rhs: VoltraElement) -> Bool {
-    lhs.type == rhs.type &&
-      lhs.id == rhs.id &&
-      lhs.children == rhs.children &&
-      lhs._props == rhs._props
-  }
-
-  // MARK: - Computed Properties
-
-  /// Expanded props with full property names
-  public var props: [String: JSONValue]? {
-    guard let props = _props else { return nil }
-    var expanded: [String: JSONValue] = [:]
-    for (key, value) in props {
-      // Expand short key to full name using unified ShortNames mapping
-      let fullKey = ShortNames.expand(key)
-      expanded[fullKey] = value
-    }
-    return expanded.isEmpty ? nil : expanded
-  }
-
-  /// Style dictionary with expanded keys
-  public var style: [String: JSONValue]? {
-    guard let styleValue = props?["style"] else {
-      return nil
-    }
-
-    let styleDict: [String: JSONValue]
-
-    // Handle stylesheet reference (integer index)
-    if let index = styleValue.intValue,
-       let stylesheet = stylesheet,
-       index >= 0, index < stylesheet.count
-    {
-      styleDict = stylesheet[index]
-    }
-    // Handle inline style (object)
-    else if let objectValue = styleValue.objectValue {
-      styleDict = objectValue
-    } else {
-      return nil
-    }
-
-    var expanded: [String: JSONValue] = [:]
-    for (key, value) in styleDict {
-      // Use unified ShortNames mapping for style properties
-      let expandedKey = ShortNames.expand(key)
-      expanded[expandedKey] = value
-    }
-
-    return expanded
-  }
-
-  // MARK: - Initialization
-
-  /// Initialize from JSONValue (no serialization roundtrip)
-  /// - 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) {
-    guard case let .object(dict) = json else {
-      return nil
-    }
-
-    // Decode component type as Int (numeric ID) and convert to component name
-    guard case let .int(typeID) = dict["t"],
-          let componentTypeID = ComponentTypeID(rawValue: typeID)
-    else {
-      return nil
-    }
-    type = componentTypeID.componentName
-
-    // Extract id
-    id = dict["i"]?.stringValue
-
-    // Extract children
-    if let childrenValue = dict["c"] {
-      children = VoltraNode(from: childrenValue, stylesheet: stylesheet, sharedElements: sharedElements)
-    } else {
-      children = nil
-    }
-
-    // Extract props
-    if let propsValue = dict["p"], case let .object(propsDict) = propsValue {
-      _props = propsDict
-    } else {
-      _props = nil
-    }
-
-    // Store stylesheet reference
-    self.stylesheet = stylesheet
-
-    // Store shared elements reference
-    self.sharedElements = sharedElements
-  }
-
-  /// Get component prop by name - handles both single component and array
-  public func componentProp(_ propName: String) -> VoltraNode {
-    guard let propValue = props?[propName] else { return .empty }
-
-    return VoltraNode(from: propValue, stylesheet: stylesheet, sharedElements: sharedElements)
-  }
-
-  /// Decode parameters from props
-  public func parameters<T: Decodable>(_: T.Type) -> T {
-    guard let props = props else {
-      // Return default instance if decoding fails
-      return try! JSONDecoder().decode(T.self, from: "{}".data(using: .utf8)!)
-    }
-
-    do {
-      // Convert JSONValue dictionary to [String: Any] for JSONSerialization
-      let dict = props.mapValues { $0.toAny() }
-      let jsonData = try JSONSerialization.data(withJSONObject: dict, options: [])
-      return try JSONDecoder().decode(T.self, from: jsonData)
-    } catch {
-      // Return default instance if decoding fails
-      return try! JSONDecoder().decode(T.self, from: "{}".data(using: .utf8)!)
-    }
-  }
-}

package/ios/shared/VoltraEvent.swift

@@ -1,72 +0,0 @@
-import Foundation
-
-// MARK: - Event Types
-
-/// All Voltra event types with their associated data
-public enum VoltraEventType {
-  /// Persistent events (widget → app, survives app death)
-  case interaction(source: String, identifier: String, payload: String?)
-
-  // Transient events (main app only, in-memory)
-  case stateChange(activityName: String, state: String)
-  case tokenReceived(activityName: String, pushToken: String)
-  case pushToStartTokenReceived(token: String)
-
-  /// Whether this event should be persisted to UserDefaults (survives app death)
-  var isPersistent: Bool {
-    switch self {
-    case .interaction:
-      return true
-    default:
-      return false
-    }
-  }
-
-  /// The event name used for JS bridge
-  var name: String {
-    switch self {
-    case .interaction:
-      return "interaction"
-    case .stateChange:
-      return "stateChange"
-    case .tokenReceived:
-      return "activityTokenReceived"
-    case .pushToStartTokenReceived:
-      return "activityPushToStartTokenReceived"
-    }
-  }
-
-  /// Convert to dictionary for JS bridge
-  var asDictionary: [String: Any] {
-    var dict: [String: Any] = ["type": name]
-
-    switch self {
-    case let .interaction(source, identifier, payload):
-      dict["source"] = source
-      dict["timestamp"] = Date().timeIntervalSince1970
-      dict["identifier"] = identifier
-      dict["payload"] = payload ?? ""
-
-    case let .stateChange(activityName, state):
-      dict["timestamp"] = Date().timeIntervalSince1970
-      dict["activityName"] = activityName
-      dict["activityState"] = state
-
-    case let .tokenReceived(activityName, pushToken):
-      dict["timestamp"] = Date().timeIntervalSince1970
-      dict["activityName"] = activityName
-      dict["pushToken"] = pushToken
-
-    case let .pushToStartTokenReceived(token):
-      dict["pushToStartToken"] = token
-    }
-
-    return dict
-  }
-}
-
-// MARK: - Notification Name
-
-extension Notification.Name {
-  static let voltraEvent = Notification.Name("voltraEvent")
-}

package/ios/shared/VoltraEventBus.swift

@@ -1,80 +0,0 @@
-import Foundation
-import os
-
-/// A centralized event bus that manages Voltra events
-/// - Persistent events (interactions): routed through UserDefaults for cross-process delivery
-/// - Transient events (state changes, tokens): routed through NotificationCenter for in-process delivery
-public class VoltraEventBus {
-  public static let shared = VoltraEventBus()
-
-  private var observer: NSObjectProtocol?
-  private let lock = NSLock()
-
-  private init() {}
-
-  /// Send an event. Routing is automatic based on event type:
-  /// - Persistent events → UserDefaults (survives app death, cross-process) + NotificationCenter (hot delivery)
-  /// - Transient events → NotificationCenter only (in-memory, same process)
-  public func send(_ event: VoltraEventType) {
-    // Compute dictionary once to ensure consistent timestamp across all delivery paths
-    let eventData = event.asDictionary
-
-    if event.isPersistent {
-      // Persistent: write to UserDefaults first (for widget → app communication, survives app death)
-      VoltraPersistentEventQueue.write(eventData)
-    }
-
-    // Always post to NotificationCenter for immediate delivery when app is running
-    NotificationCenter.default.post(
-      name: .voltraEvent,
-      object: nil,
-      userInfo: eventData
-    )
-  }
-
-  /// Subscribe to Voltra events. This will:
-  /// 1. Replay any persisted events from UserDefaults (cold start)
-  /// 2. Set up a NotificationCenter observer for all events (hot delivery)
-  ///
-  /// - Parameter handler: A closure that receives the event name and event data dictionary
-  public func subscribe(handler: @escaping (String, [String: Any]) -> Void) {
-    lock.lock()
-    defer { lock.unlock() }
-
-    // 1. Replay persisted events from UserDefaults (interactions from widget)
-    let persistedEvents = VoltraPersistentEventQueue.popAll()
-    for event in persistedEvents {
-      handler(event.name, event.data)
-    }
-    VoltraLogger.event.info("Replayed \(persistedEvents.count) persisted events")
-
-    // 2. Listen for all events via NotificationCenter (hot delivery)
-    observer = NotificationCenter.default.addObserver(
-      forName: .voltraEvent,
-      object: nil,
-      queue: .main
-    ) { notification in
-      guard let userInfo = notification.userInfo as? [String: Any],
-            let eventName = userInfo["type"] as? String
-      else {
-        return
-      }
-      handler(eventName, userInfo)
-    }
-  }
-
-  /// Unsubscribe from Voltra events
-  public func unsubscribe() {
-    lock.lock()
-    defer { lock.unlock() }
-
-    if let observer = observer {
-      NotificationCenter.default.removeObserver(observer)
-      self.observer = nil
-    }
-  }
-
-  deinit {
-    unsubscribe()
-  }
-}

package/ios/shared/VoltraImageStore.swift

@@ -1,119 +0,0 @@
-import Foundation
-import UIKit
-
-/// Utility for reading/writing preloaded images to App Group shared storage
-public enum VoltraImageStore {
-  private static let imageDirectoryName = "voltra_images"
-
-  /// Get the shared container URL for storing images
-  public static func imageDirectory() -> URL? {
-    guard let groupId = VoltraConfig.groupIdentifier(),
-          let containerURL = FileManager.default.containerURL(forSecurityApplicationGroupIdentifier: groupId)
-    else { return nil }
-
-    return containerURL.appendingPathComponent(imageDirectoryName, isDirectory: true)
-  }
-
-  /// Ensure the image directory exists
-  private static func ensureDirectoryExists() throws {
-    guard let directory = imageDirectory() else {
-      throw VoltraImageStoreError.appGroupNotConfigured
-    }
-
-    if !FileManager.default.fileExists(atPath: directory.path) {
-      try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
-    }
-  }
-
-  /// Save image data to App Group storage
-  /// - Parameters:
-  ///   - data: The image data to save
-  ///   - key: The key/name to use for the image (will be used as assetName)
-  public static func saveImage(_ data: Data, key: String) throws {
-    try ensureDirectoryExists()
-
-    guard let directory = imageDirectory() else {
-      throw VoltraImageStoreError.appGroupNotConfigured
-    }
-
-    let sanitizedKey = sanitizeKey(key)
-    let fileURL = directory.appendingPathComponent(sanitizedKey)
-
-    // Write atomically to ensure the file is fully written before it becomes visible
-    try data.write(to: fileURL, options: .atomic)
-  }
-
-  /// Load a preloaded image from App Group storage
-  /// - Parameter key: The key/name of the image
-  /// - Returns: The UIImage if found, nil otherwise
-  public static func loadImage(key: String) -> UIImage? {
-    guard let directory = imageDirectory() else { return nil }
-
-    let sanitizedKey = sanitizeKey(key)
-    let fileURL = directory.appendingPathComponent(sanitizedKey)
-
-    guard FileManager.default.fileExists(atPath: fileURL.path),
-          let data = try? Data(contentsOf: fileURL),
-          let image = UIImage(data: data)
-    else { return nil }
-
-    return image
-  }
-
-  /// Check if a preloaded image exists
-  /// - Parameter key: The key/name of the image
-  /// - Returns: true if the image exists in App Group storage
-  public static func imageExists(key: String) -> Bool {
-    guard let directory = imageDirectory() else { return false }
-
-    let sanitizedKey = sanitizeKey(key)
-    let fileURL = directory.appendingPathComponent(sanitizedKey)
-
-    return FileManager.default.fileExists(atPath: fileURL.path)
-  }
-
-  /// Remove a preloaded image from App Group storage
-  /// - Parameter key: The key/name of the image to remove
-  public static func removeImage(key: String) {
-    guard let directory = imageDirectory() else { return }
-
-    let sanitizedKey = sanitizeKey(key)
-    let fileURL = directory.appendingPathComponent(sanitizedKey)
-
-    try? FileManager.default.removeItem(at: fileURL)
-  }
-
-  /// Remove multiple preloaded images
-  /// - Parameter keys: The keys/names of the images to remove
-  public static func removeImages(keys: [String]) {
-    for key in keys {
-      removeImage(key: key)
-    }
-  }
-
-  /// Clear all preloaded images from App Group storage
-  public static func clearAll() {
-    guard let directory = imageDirectory() else { return }
-
-    try? FileManager.default.removeItem(at: directory)
-  }
-
-  /// Sanitize the key to be a valid filename
-  private static func sanitizeKey(_ key: String) -> String {
-    // Replace any characters that might cause issues in filenames
-    let invalidChars = CharacterSet(charactersIn: "/\\:*?\"<>|")
-    return key.components(separatedBy: invalidChars).joined(separator: "_")
-  }
-}
-
-/// Errors that can occur during image store operations
-public enum VoltraImageStoreError: Error, LocalizedError {
-  case appGroupNotConfigured
-
-  public var errorDescription: String? {
-    switch self {
-    case .appGroupNotConfigured:
-      return "App Group not configured. Set 'groupIdentifier' in the Voltra config plugin."
-    }
-  }
-}

package/ios/shared/VoltraInteractionIntent.swift

@@ -1,39 +0,0 @@
-import ActivityKit
-import AppIntents
-
-public struct VoltraInteractionIntent: LiveActivityIntent {
-  public static var title: LocalizedStringResource = "Interact"
-  public static var isDiscoverable: Bool = false
-
-  /// The ID of the activity
-  @Parameter(title: "Activity ID")
-  var activityId: String
-
-  /// The ID of the component in your JSON (e.g., "button_1", "pause_btn")
-  @Parameter(title: "Component ID")
-  var componentId: String
-
-  // Optional: Only if you need to pass extra data (like "true/false" or "toggle")
-  @Parameter(title: "Payload")
-  var payload: String?
-
-  public init() {}
-
-  public init(activityId: String, componentId: String, payload: String? = nil) {
-    self.activityId = activityId
-    self.componentId = componentId
-    self.payload = payload
-  }
-
-  public func perform() async throws -> some IntentResult {
-    VoltraEventBus.shared.send(
-      .interaction(
-        source: activityId,
-        identifier: componentId,
-        payload: payload
-      )
-    )
-
-    return .result()
-  }
-}

package/ios/shared/VoltraKeychainHelper.swift

@@ -1,178 +0,0 @@
-import Foundation
-import os
-import Security
-
-/// Shared Keychain helper for securely storing and reading widget server credentials.
-/// Used by both the main app (to write credentials) and the widget extension (to read them).
-public enum VoltraKeychainHelper {
-  /// Keychain service identifier for Voltra widget credentials
-  private static let service = "voltra-widget-server-credentials"
-
-  /// Key for the auth token
-  private static let tokenKey = "auth_token"
-
-  /// Key for additional headers (stored as JSON)
-  private static let headersKey = "custom_headers"
-
-  /// Get the Keychain Access Group from Info.plist (set by the config plugin)
-  private static func keychainGroup() -> String? {
-    VoltraConfig.keychainGroup()
-  }
-
-  // MARK: - Token Storage
-
-  /// Save an auth token to the shared Keychain.
-  /// Called from the main app after user login.
-  @discardableResult
-  public static func saveToken(_ token: String) -> Bool {
-    guard let data = token.data(using: .utf8) else { return false }
-
-    // Delete existing token first
-    deleteToken()
-
-    var query: [String: Any] = [
-      kSecClass as String: kSecClassGenericPassword,
-      kSecAttrService as String: service,
-      kSecAttrAccount as String: tokenKey,
-      kSecValueData as String: data,
-      kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlock,
-    ]
-
-    // Add access group if configured (for sharing between app and extension)
-    if let group = keychainGroup() {
-      query[kSecAttrAccessGroup as String] = group
-    }
-
-    let status = SecItemAdd(query as CFDictionary, nil)
-    if status != errSecSuccess {
-      VoltraLogger.keychain.error("Failed to save token: \(status)")
-    }
-    return status == errSecSuccess
-  }
-
-  /// Read the auth token from the shared Keychain.
-  /// Called from the widget extension's TimelineProvider.
-  public static func readToken() -> String? {
-    var query: [String: Any] = [
-      kSecClass as String: kSecClassGenericPassword,
-      kSecAttrService as String: service,
-      kSecAttrAccount as String: tokenKey,
-      kSecReturnData as String: true,
-      kSecMatchLimit as String: kSecMatchLimitOne,
-    ]
-
-    if let group = keychainGroup() {
-      query[kSecAttrAccessGroup as String] = group
-    }
-
-    var item: CFTypeRef?
-    let status = SecItemCopyMatching(query as CFDictionary, &item)
-
-    guard status == errSecSuccess, let data = item as? Data else {
-      if status != errSecItemNotFound {
-        VoltraLogger.keychain.error("Failed to read token: \(status)")
-      }
-      return nil
-    }
-
-    return String(data: data, encoding: .utf8)
-  }
-
-  /// Delete the auth token from the shared Keychain.
-  @discardableResult
-  public static func deleteToken() -> Bool {
-    var query: [String: Any] = [
-      kSecClass as String: kSecClassGenericPassword,
-      kSecAttrService as String: service,
-      kSecAttrAccount as String: tokenKey,
-    ]
-
-    if let group = keychainGroup() {
-      query[kSecAttrAccessGroup as String] = group
-    }
-
-    let status = SecItemDelete(query as CFDictionary)
-    return status == errSecSuccess || status == errSecItemNotFound
-  }
-
-  // MARK: - Custom Headers Storage
-
-  /// Save additional custom headers to the shared Keychain.
-  @discardableResult
-  public static func saveHeaders(_ headers: [String: String]) -> Bool {
-    guard let data = try? JSONSerialization.data(withJSONObject: headers) else { return false }
-
-    // Delete existing headers first
-    deleteHeaders()
-
-    var query: [String: Any] = [
-      kSecClass as String: kSecClassGenericPassword,
-      kSecAttrService as String: service,
-      kSecAttrAccount as String: headersKey,
-      kSecValueData as String: data,
-      kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlock,
-    ]
-
-    if let group = keychainGroup() {
-      query[kSecAttrAccessGroup as String] = group
-    }
-
-    let status = SecItemAdd(query as CFDictionary, nil)
-    if status != errSecSuccess {
-      VoltraLogger.keychain.error("Failed to save headers: \(status)")
-    }
-    return status == errSecSuccess
-  }
-
-  /// Read custom headers from the shared Keychain.
-  public static func readHeaders() -> [String: String]? {
-    var query: [String: Any] = [
-      kSecClass as String: kSecClassGenericPassword,
-      kSecAttrService as String: service,
-      kSecAttrAccount as String: headersKey,
-      kSecReturnData as String: true,
-      kSecMatchLimit as String: kSecMatchLimitOne,
-    ]
-
-    if let group = keychainGroup() {
-      query[kSecAttrAccessGroup as String] = group
-    }
-
-    var item: CFTypeRef?
-    let status = SecItemCopyMatching(query as CFDictionary, &item)
-
-    guard status == errSecSuccess,
-          let data = item as? Data,
-          let headers = try? JSONSerialization.jsonObject(with: data) as? [String: String]
-    else {
-      return nil
-    }
-
-    return headers
-  }
-
-  /// Delete custom headers from the shared Keychain.
-  @discardableResult
-  public static func deleteHeaders() -> Bool {
-    var query: [String: Any] = [
-      kSecClass as String: kSecClassGenericPassword,
-      kSecAttrService as String: service,
-      kSecAttrAccount as String: headersKey,
-    ]
-
-    if let group = keychainGroup() {
-      query[kSecAttrAccessGroup as String] = group
-    }
-
-    let status = SecItemDelete(query as CFDictionary)
-    return status == errSecSuccess || status == errSecItemNotFound
-  }
-
-  // MARK: - Convenience
-
-  /// Clear all Voltra widget server credentials from the Keychain.
-  public static func clearAll() {
-    deleteToken()
-    deleteHeaders()
-  }
-}