@use-voltra/ios-client 2.2.0 → 2.3.0

package/ios/shared/VoltraElement.swift

@@ -11,17 +11,20 @@ public struct VoltraElement: Hashable {
   /// Child nodes or text content
   public let children: VoltraNode?
 
-  /// Raw properties (stored as JSONValue for type safety)
+  /// Raw properties (stored as JSONValue for type safety).
+  ///
+  /// Stylesheet indices and shared element references are substituted for the values they point
+  /// at while parsing, so this holds no handle into a per-payload lookup table.
   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]?
+  /// Style dictionary with expanded keys, resolved once while parsing.
+  private let _style: [String: JSONValue]?
 
   // MARK: - Hashable
 
+  /// `_props` carries fully resolved values, so it alone distinguishes elements that render
+  /// differently. Identity deliberately omits `_style`, which is derived from `_props` and would
+  /// only restate it.
   public func hash(into hasher: inout Hasher) {
     hasher.combine(type)
     hasher.combine(id)
@@ -52,39 +55,15 @@ public struct VoltraElement: Hashable {
 
   /// 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
+    _style
   }
 
   // MARK: - Initialization
 
   /// Initialize from JSONValue (no serialization roundtrip)
+  ///
+  /// The stylesheet and shared elements are consumed here rather than retained: every reference
+  /// into them is replaced by the value it names, leaving a self-contained element.
   /// - Parameters:
   ///   - json: The JSON value to parse
   ///   - stylesheet: Optional shared stylesheet for style deduplication
@@ -112,25 +91,28 @@ public struct VoltraElement: Hashable {
       children = nil
     }
 
-    // Extract props
+    // Extract props, substituting the values behind every stylesheet index and shared element
+    // reference so the element stops depending on lookup tables it does not carry.
+    let resolvedProps: [String: JSONValue]?
     if let propsValue = dict["p"], case let .object(propsDict) = propsValue {
-      _props = propsDict
+      resolvedProps = Self.resolvingReferences(
+        inProps: propsDict,
+        stylesheet: stylesheet,
+        sharedElements: sharedElements
+      )
     } else {
-      _props = nil
+      resolvedProps = nil
     }
 
-    // Store stylesheet reference
-    self.stylesheet = stylesheet
-
-    // Store shared elements reference
-    self.sharedElements = sharedElements
+    _props = resolvedProps
+    _style = Self.expandedStyle(from: resolvedProps)
   }
 
   /// 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)
+    return VoltraNode(from: propValue)
   }
 
   /// Decode parameters from props
@@ -150,4 +132,106 @@ public struct VoltraElement: Hashable {
       return try! JSONDecoder().decode(T.self, from: "{}".data(using: .utf8)!)
     }
   }
+
+  // MARK: - Reference Resolution
+
+  /// Substitutes the stylesheet entry behind a style index, and the shared element behind a
+  /// `$r` reference, throughout a props dictionary.
+  ///
+  /// Element-valued props carry serialized nodes of their own, and those nodes reference the
+  /// same payload-level tables. Leaving them unresolved would make two elements with equal
+  /// props compare equal while rendering differently.
+  /// The renderer registers shared elements only after rendering their contents, so generated
+  /// references point to completed entries and cannot form cycles.
+  private static func resolvingReferences(
+    inProps props: [String: JSONValue],
+    stylesheet: [[String: JSONValue]]?,
+    sharedElements: [JSONValue]?
+  ) -> [String: JSONValue] {
+    guard stylesheet != nil || sharedElements != nil else {
+      return props
+    }
+
+    var resolved = props
+    for (key, value) in props {
+      if ShortNames.expand(key) == "style" {
+        if let index = value.intValue,
+           let stylesheet = stylesheet,
+           index >= 0, index < stylesheet.count
+        {
+          resolved[key] = .object(stylesheet[index])
+        }
+      } else {
+        resolved[key] = resolvingReferences(
+          in: value,
+          stylesheet: stylesheet,
+          sharedElements: sharedElements
+        )
+      }
+    }
+    return resolved
+  }
+
+  /// Resolves references inside a value that may hold serialized nodes.
+  private static func resolvingReferences(
+    in value: JSONValue,
+    stylesheet: [[String: JSONValue]]?,
+    sharedElements: [JSONValue]?
+  ) -> JSONValue {
+    switch value {
+    case let .array(items):
+      return .array(items.map {
+        resolvingReferences(in: $0, stylesheet: stylesheet, sharedElements: sharedElements)
+      })
+
+    case let .object(dict):
+      // Element reference ($r key) - substitute the shared element it names
+      if let refIndex = dict["$r"]?.intValue,
+         let sharedElements = sharedElements,
+         refIndex >= 0, refIndex < sharedElements.count
+      {
+        return resolvingReferences(
+          in: sharedElements[refIndex],
+          stylesheet: stylesheet,
+          sharedElements: sharedElements
+        )
+      }
+
+      var resolved = dict
+      if let propsValue = dict["p"], case let .object(propsDict) = propsValue {
+        resolved["p"] = .object(resolvingReferences(
+          inProps: propsDict,
+          stylesheet: stylesheet,
+          sharedElements: sharedElements
+        ))
+      }
+      if let childrenValue = dict["c"] {
+        resolved["c"] = resolvingReferences(
+          in: childrenValue,
+          stylesheet: stylesheet,
+          sharedElements: sharedElements
+        )
+      }
+      return .object(resolved)
+
+    default:
+      return value
+    }
+  }
+
+  /// Expands the short keys of an already resolved style prop into full property names.
+  private static func expandedStyle(from props: [String: JSONValue]?) -> [String: JSONValue]? {
+    guard let styleValue = props?["s"] ?? props?["style"],
+          let styleDict = styleValue.objectValue
+    else {
+      return nil
+    }
+
+    var expanded: [String: JSONValue] = [:]
+    for (key, value) in styleDict {
+      // Use unified ShortNames mapping for style properties
+      expanded[ShortNames.expand(key)] = value
+    }
+    return expanded
+  }
 }

package/ios/shared/VoltraEventBus.swift

@@ -8,6 +8,9 @@ public class VoltraEventBus {
   public static let shared = VoltraEventBus()
 
   private var observer: NSObjectProtocol?
+  private var renderFailureObserver: UUID?
+  private var handler: ((String, [String: Any]) -> Void)?
+  private var renderFailureListenerCount = 0
   private let lock = NSLock()
 
   private init() {}
@@ -39,20 +42,18 @@ public class VoltraEventBus {
   /// - 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() }
-
     if let observer {
       NotificationCenter.default.removeObserver(observer)
       self.observer = nil
     }
+    if let renderFailureObserver {
+      VoltraDynamicLiveActivityRenderFailureReporter.removeChangeObserver(renderFailureObserver)
+      self.renderFailureObserver = nil
+    }
+    self.handler = handler
 
     // 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,
@@ -66,6 +67,44 @@ public class VoltraEventBus {
       }
       handler(eventName, userInfo)
     }
+    renderFailureObserver = VoltraDynamicLiveActivityRenderFailureReporter.observeChanges { [weak self] in
+      self?.drainDynamicLiveActivityRenderFailures()
+    }
+    lock.unlock()
+
+    for event in persistedEvents {
+      handler(event.name, event.data)
+    }
+    VoltraLogger.event.info("Replayed \(persistedEvents.count) persisted events")
+  }
+
+  /// JS owns the dedicated emitter subscription count. Persisted failures must
+  /// remain queued whenever there is no relevant JavaScript listener.
+  public func setDynamicLiveActivityRenderFailureListenerActive(_ active: Bool) {
+    lock.lock()
+    renderFailureListenerCount = active ? 1 : 0
+    lock.unlock()
+    if active {
+      drainDynamicLiveActivityRenderFailures()
+    }
+  }
+
+  /// Flush only the dedicated Dynamic Live Activity diagnostic queue. This
+  /// cannot read, displace, or clear persistent interaction events.
+  public func drainDynamicLiveActivityRenderFailures() {
+    lock.lock()
+    let handler = handler
+    let isReady = renderFailureListenerCount > 0
+    lock.unlock()
+    guard isReady, let handler else { return }
+
+    let failures = VoltraDynamicLiveActivityRenderFailureReporter.drain()
+    for failure in failures {
+      handler(failure.type, failure.dictionary)
+    }
+    if !failures.isEmpty {
+      VoltraLogger.event.info("Replayed \(failures.count) Dynamic Live Activity render failures")
+    }
   }
 
   /// Unsubscribe from Voltra events
@@ -77,6 +116,12 @@ public class VoltraEventBus {
       NotificationCenter.default.removeObserver(observer)
       self.observer = nil
     }
+    if let renderFailureObserver {
+      VoltraDynamicLiveActivityRenderFailureReporter.removeChangeObserver(renderFailureObserver)
+      self.renderFailureObserver = nil
+    }
+    handler = nil
+    renderFailureListenerCount = 0
   }
 
   deinit {

package/ios/shared/VoltraJSRenderer.swift

@@ -15,6 +15,7 @@ import JavaScriptCore
 /// indefinitely.
 public enum VoltraJSRenderer {
   private static var _context: JSContext?
+  private static var liveActivitySources: [String: String] = [:]
   private static let lock = NSLock()
   private static let TAG = "VoltraJSRenderer"
 
@@ -30,6 +31,28 @@ public enum VoltraJSRenderer {
   /// Idempotent: re-evaluating the same widget overwrites the captured exports — used
   /// by dev-mode hot-reload (always-refetch policy).
   public static func evaluateBundle(source: String, widgetId: String) -> Bool {
+    evaluateBundle(source: source, id: widgetId, registryName: "__voltraWidgets", kind: "widget")
+  }
+
+  /// Evaluate a Dynamic Live Activity bundle in the shared JSContext. Its exports
+  /// are captured separately from Dynamic Widgets so both collections may use the
+  /// same definition ID without overwriting one another.
+  public static func evaluateLiveActivityBundle(source: String, definitionId: String) -> Bool {
+    let evaluated = evaluateBundle(
+      source: source,
+      id: definitionId,
+      registryName: "__voltraDynamicLiveActivities",
+      kind: "live activity"
+    )
+    if evaluated {
+      lock.lock()
+      liveActivitySources[definitionId] = source
+      lock.unlock()
+    }
+    return evaluated
+  }
+
+  private static func evaluateBundle(source: String, id: String, registryName: String, kind: String) -> Bool {
     lock.lock()
     defer { lock.unlock() }
 
@@ -38,7 +61,7 @@ public enum VoltraJSRenderer {
       return false
     }
 
-    let escapedId = jsStringLiteral(widgetId)
+    let escapedId = jsStringLiteral(id)
     // Metro emits the bundle's entry invocation as `__r(<entryModuleId>);` near the
     // end of the file (before the sourcemap/sourceURL comments). The entry id is NOT
     // always 0 — when Metro serves multiple widget bundles from the same process, it
@@ -50,34 +73,34 @@ public enum VoltraJSRenderer {
     let wrapped = """
     \(source)
     ;(function () {
-      if (!globalThis.__voltraWidgets) { globalThis.__voltraWidgets = {}; }
-      globalThis.__voltraWidgets[\(escapedId)] = __r(\(entryModuleId));
+      if (!globalThis.\(registryName)) { globalThis.\(registryName) = {}; }
+      globalThis.\(registryName)[\(escapedId)] = __r(\(entryModuleId));
     })();
     """
 
     ctx.exception = nil
     ctx.evaluateScript(wrapped)
     if let message = exceptionMessage(ctx) {
-      VoltraLogger.widget.error("[\(TAG)] Bundle eval failed for widgetId=\(widgetId): \(message)")
+      VoltraLogger.widget.error("[\(TAG)] Bundle eval failed for \(kind) id=\(id): \(message)")
       return false
     }
 
     // Verify the bootstrap captured the exports correctly
     guard
-      let registry = ctx.objectForKeyedSubscript("__voltraWidgets"),
+      let registry = ctx.objectForKeyedSubscript(registryName),
       !registry.isUndefined,
-      let widget = registry.objectForKeyedSubscript(widgetId),
-      !widget.isUndefined,
-      let renderFn = widget.objectForKeyedSubscript("render"),
+      let entry = registry.objectForKeyedSubscript(id),
+      !entry.isUndefined,
+      let renderFn = entry.objectForKeyedSubscript("render"),
       renderFn.isObject,
       renderFn.objectForKeyedSubscript("call") != nil
     else {
-      VoltraLogger.widget.error("[\(TAG)] Bundle evaluated but did not expose render() for widgetId=\(widgetId)")
+      VoltraLogger.widget.error("[\(TAG)] Bundle evaluated but did not expose render() for \(kind) id=\(id)")
       return false
     }
     _ = renderFn
 
-    VoltraLogger.widget.info("[\(TAG)] Bundle evaluated for widgetId=\(widgetId) (\(source.count) chars)")
+    VoltraLogger.widget.info("[\(TAG)] Bundle evaluated for \(kind) id=\(id) (\(source.count) chars)")
     return true
   }
 
@@ -90,11 +113,31 @@ public enum VoltraJSRenderer {
   /// evaluation never ran. The View calls this before `render()` so rendering never depends on
   /// which process evaluated the bundle.
   public static func ensureEvaluated(widgetId: String, source: String) -> Bool {
+    ensureEvaluated(source: source, id: widgetId, registryName: "__voltraWidgets", kind: "widget")
+  }
+
+  public static func ensureLiveActivityEvaluated(definitionId: String, source: String) -> Bool {
+    lock.lock()
+    let currentSource = liveActivitySources[definitionId]
+    let hasRender =
+      _context?
+        .objectForKeyedSubscript("__voltraDynamicLiveActivities")?
+        .objectForKeyedSubscript(definitionId)?
+        .objectForKeyedSubscript("render")?
+        .isObject ?? false
+    lock.unlock()
+    if hasRender, currentSource == source {
+      return true
+    }
+    return evaluateLiveActivityBundle(source: source, definitionId: definitionId)
+  }
+
+  private static func ensureEvaluated(source: String, id: String, registryName: String, kind: String) -> Bool {
     lock.lock()
     let alreadyEvaluated =
       _context?
-        .objectForKeyedSubscript("__voltraWidgets")?
-        .objectForKeyedSubscript(widgetId)?
+        .objectForKeyedSubscript(registryName)?
+        .objectForKeyedSubscript(id)?
         .objectForKeyedSubscript("render")?
         .isObject ?? false
     lock.unlock()
@@ -102,7 +145,7 @@ public enum VoltraJSRenderer {
     if alreadyEvaluated {
       return true
     }
-    return evaluateBundle(source: source, widgetId: widgetId)
+    return evaluateBundle(source: source, id: id, registryName: registryName, kind: kind)
   }
 
   /// Invoke the previously-evaluated widget's `render(propsJSON, envJSON)` function and
@@ -114,39 +157,64 @@ public enum VoltraJSRenderer {
     widgetId: String,
     propsJSON: String,
     envJSON: String
+  ) -> String? {
+    render(id: widgetId, propsJSON: propsJSON, envJSON: envJSON, registryName: "__voltraWidgets", kind: "widget")
+  }
+
+  /// Render a Dynamic Live Activity from its separately registered definition.
+  public static func renderLiveActivity(
+    definitionId: String,
+    propsJSON: String,
+    envJSON: String
+  ) -> String? {
+    render(
+      id: definitionId,
+      propsJSON: propsJSON,
+      envJSON: envJSON,
+      registryName: "__voltraDynamicLiveActivities",
+      kind: "live activity"
+    )
+  }
+
+  private static func render(
+    id: String,
+    propsJSON: String,
+    envJSON: String,
+    registryName: String,
+    kind: String
   ) -> String? {
     lock.lock()
     defer { lock.unlock() }
 
     guard let ctx = _context else {
-      VoltraLogger.widget.error("[\(TAG)] render(\(widgetId)): no JSContext (call evaluateBundle first)")
+      VoltraLogger.widget.error("[\(TAG)] render \(kind) id=\(id): no JSContext (call evaluateBundle first)")
       return nil
     }
 
     guard
-      let registry = ctx.objectForKeyedSubscript("__voltraWidgets"),
+      let registry = ctx.objectForKeyedSubscript(registryName),
       !registry.isUndefined,
-      let widget = registry.objectForKeyedSubscript(widgetId),
-      !widget.isUndefined,
-      let renderFn = widget.objectForKeyedSubscript("render"),
+      let entry = registry.objectForKeyedSubscript(id),
+      !entry.isUndefined,
+      let renderFn = entry.objectForKeyedSubscript("render"),
       renderFn.isObject
     else {
-      VoltraLogger.widget.error("[\(TAG)] render(\(widgetId)): no captured render() — bundle not evaluated?")
+      VoltraLogger.widget.error("[\(TAG)] render \(kind) id=\(id): no captured render() — bundle not evaluated?")
       return nil
     }
 
     ctx.exception = nil
     guard let result = renderFn.call(withArguments: [propsJSON, envJSON]) else {
-      VoltraLogger.widget.error("[\(TAG)] render(\(widgetId)): call returned nil")
+      VoltraLogger.widget.error("[\(TAG)] render \(kind) id=\(id): call returned nil")
       return nil
     }
     if let message = exceptionMessage(ctx) {
-      VoltraLogger.widget.error("[\(TAG)] render(\(widgetId)) threw: \(message)")
+      VoltraLogger.widget.error("[\(TAG)] render \(kind) id=\(id) threw: \(message)")
       return nil
     }
 
     guard result.isString else {
-      VoltraLogger.widget.error("[\(TAG)] render(\(widgetId)) did not return a string")
+      VoltraLogger.widget.error("[\(TAG)] render \(kind) id=\(id) did not return a string")
       return nil
     }
     return result.toString()

package/ios/shared/VoltraNode.swift

@@ -1,8 +1,7 @@
 import Foundation
-import SwiftUI
 
 /// Represents anything that can be rendered (like ReactNode)
-public indirect enum VoltraNode: Hashable, View {
+public indirect enum VoltraNode: Hashable {
   /// A component element
   case element(VoltraElement)
 
@@ -88,111 +87,4 @@ public indirect enum VoltraNode: Hashable, View {
 
     return VoltraNode(from: json, stylesheet: stylesheet, sharedElements: sharedElements)
   }
-
-  // MARK: - View conformance
-
-  public var body: some View {
-    switch self {
-    case let .element(element):
-      VoltraElementView(element: element)
-    case let .array(nodes):
-      // Use stable identifiers: prefer element.id, fall back to index
-      let items: [(id: String, node: VoltraNode)] = nodes.enumerated().map { offset, node in
-        let id: String
-        if case let .element(element) = node, let elementId = element.id {
-          id = elementId
-        } else {
-          id = "idx_\(offset)"
-        }
-        return (id: id, node: node)
-      }
-      ForEach(items, id: \.id) { item in
-        item.node
-      }
-    case let .text(text):
-      Text(text)
-    case .empty:
-      EmptyView()
-    }
-  }
-}
-
-/// View that renders a VoltraElement based on its type
-struct VoltraElementView: View {
-  let element: VoltraElement
-
-  var body: some View {
-    switch element.type {
-    case "Button":
-      VoltraButton(element)
-
-    case "Link":
-      VoltraLink(element)
-
-    case "VStack":
-      VoltraVStack(element)
-
-    case "HStack":
-      VoltraHStack(element)
-
-    case "View":
-      VoltraFlexView(element)
-
-    case "ZStack":
-      VoltraZStack(element)
-
-    case "Text":
-      VoltraText(element)
-
-    case "Image":
-      VoltraImage(element)
-
-    case "Symbol":
-      VoltraSymbol(element)
-
-    case "Divider":
-      VoltraDivider(element)
-
-    case "Spacer":
-      VoltraSpacer(element)
-
-    case "Label":
-      VoltraLabel(element)
-
-    case "Toggle":
-      VoltraToggle(element)
-
-    case "Gauge":
-      VoltraGauge(element)
-
-    case "LinearProgressView":
-      VoltraLinearProgressView(element)
-
-    case "CircularProgressView":
-      VoltraCircularProgressView(element)
-
-    case "Timer":
-      VoltraTimer(element)
-
-    case "GroupBox":
-      VoltraGroupBox(element)
-
-    case "LinearGradient":
-      VoltraLinearGradient(element)
-
-    case "GlassContainer":
-      VoltraGlassContainer(element)
-
-    case "Mask":
-      VoltraMask(element)
-
-    case "Chart":
-      if #available(iOS 16.0, macOS 13.0, *) {
-        VoltraChart(element)
-      }
-
-    default:
-      EmptyView()
-    }
-  }
 }

package/ios/shared/VoltraRefreshIntent.swift

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

package/ios/shared/VoltraWidgetKind.swift

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