@use-voltra/ios-client 2.0.0 → 2.1.0

package/ios/target/VoltraClientWidgetRuntime.swift

@@ -0,0 +1,379 @@
+import Foundation
+import SwiftUI
+import WidgetKit
+
+// Shared runtime for Dynamic Widgets.
+//
+// This file is compiled into the VoltraWidget framework alongside the existing
+// VoltraHomeWidget.swift, so widget extension code generated by the plugin can
+// reference VoltraClientWidget* types without any per-widget glue duplicated.
+//
+// Pipeline:
+//
+//   1. Provider runs on a WidgetKit timeline tick.
+//      - Fetches the JS bundle (dev = Metro HTTP, prod = baked asset stub).
+//      - Evaluates it once in the shared JSContext via VoltraJSRenderer.
+//      - Emits a VoltraClientWidgetEntry with `bundleReady = true` (or errorMessage on failure).
+//
+//   2. ContentView body runs per (family, scheme, renderingMode) combo.
+//      - Reads SwiftUI @Environment values (which are ONLY accessible inside a View body).
+//      - Builds envJSON matching WidgetEnvironment in packages/core/src/widget-environment.ts.
+//      - Calls VoltraJSRenderer.render(widgetId, propsJSON, envJSON) → resolved JSON string.
+//      - Parses the resolved JSON into a VoltraNode and hands a VoltraHomeWidgetEntry to
+//        the existing VoltraHomeWidgetView so Dynamic Widgets reach the same UI
+//        renderer as server-rendered ones.
+//
+// On bundle-load failure the View falls back to the prerendered initial state.
+
+// MARK: - Entry
+
+public struct VoltraClientWidgetEntry: TimelineEntry {
+  public let date: Date
+  public let widgetId: String
+  public let bundleReady: Bool
+  public let errorMessage: String?
+  /// User-configured AppIntent parameters → `env.configuration`. Empty for widgets without an
+  /// AppIntent configuration; populated by the generated AppIntentTimelineProvider from the
+  /// configured intent.
+  public let configuration: [String: String]
+  /// The evaluated widget's JS bundle. Carried on the entry (not just left in the provider's
+  /// JSContext) because WidgetKit archives entries and re-renders the View in a *fresh* extension
+  /// process, where the provider's process-static JSContext is empty. The View re-evaluates from
+  /// this source so `render()` always has the widget's function available in its own process.
+  public let bundleSource: String?
+
+  public init(
+    date: Date,
+    widgetId: String,
+    bundleReady: Bool,
+    errorMessage: String? = nil,
+    configuration: [String: String] = [:],
+    bundleSource: String? = nil
+  ) {
+    self.date = date
+    self.widgetId = widgetId
+    self.bundleReady = bundleReady
+    self.errorMessage = errorMessage
+    self.configuration = configuration
+    self.bundleSource = bundleSource
+  }
+}
+
+// MARK: - Provider
+
+//
+// Refresh model:
+//
+//   - DEBUG builds: Provider fetches `<id>.bundle` from Metro on every
+//        `getTimeline`/`getSnapshot`, evaluates it in the shared JSContext, and emits
+//        `bundleReady = true`. The ContentView then runs the freshly evaluated
+//        `render(props, env)` and feeds the result to `VoltraHomeWidgetView`.
+//
+//   - Release builds: Provider attempts to load a baked-in bundle (release-path loader is
+//        a future addition); on failure the ContentView renders the prerendered initial state.
+//
+//   - Timeline policy is ALWAYS `.never`. The widget refreshes only when something
+//        explicitly calls `WidgetCenter.shared.reloadAllTimelines()` or when WidgetKit
+//        naturally re-invokes the Provider on its own lifecycle events (e.g., host app
+//        foregrounding). iOS rate-limits timeline-policy-driven refresh aggressively
+//        (~5-minute floor even in the simulator), so explicit reloads or natural
+//        lifecycle re-invocations are the only mechanisms that deliver fresh content.
+
+public struct VoltraClientWidgetProvider: TimelineProvider {
+  public let widgetId: String
+  /// Prerendered initial state JSON from `VoltraWidgetInitialStates.getInitialState(for:)`.
+  /// Used as the placeholder, the Loading fallback, and the steady-state view if a bundle
+  /// load fails.
+  public let initialState: Data?
+
+  public init(widgetId: String, initialState: Data? = nil) {
+    self.widgetId = widgetId
+    self.initialState = initialState
+  }
+
+  public func placeholder(in _: Context) -> VoltraClientWidgetEntry {
+    VoltraClientWidgetEntry(date: Date(), widgetId: widgetId, bundleReady: false)
+  }
+
+  public func getSnapshot(in _: Context, completion: @escaping (VoltraClientWidgetEntry) -> Void) {
+    Task { completion(await loadBundleEntry()) }
+  }
+
+  public func getTimeline(in _: Context, completion: @escaping (Timeline<VoltraClientWidgetEntry>) -> Void) {
+    Task {
+      let entry = await loadBundleEntry()
+      completion(Timeline(entries: [entry], policy: .never))
+    }
+  }
+
+  private func loadBundleEntry() async -> VoltraClientWidgetEntry {
+    await VoltraClientWidgetProvider.loadEntry(widgetId: widgetId, configuration: [:])
+  }
+
+  /// Fetch + evaluate the widget bundle and build an entry. Shared by this `TimelineProvider` and
+  /// the plugin-generated `AppIntentTimelineProvider`s (which pass the user-configured params as
+  /// `configuration`).
+  public static func loadEntry(widgetId: String, configuration: [String: String]) async -> VoltraClientWidgetEntry {
+    let date = Date()
+
+    let source: String
+    do {
+      source = try await VoltraClientWidgetBundleSource.load(widgetId: widgetId)
+    } catch {
+      return VoltraClientWidgetEntry(
+        date: date,
+        widgetId: widgetId,
+        bundleReady: false,
+        errorMessage: error.localizedDescription,
+        configuration: configuration
+      )
+    }
+
+    let okEval = VoltraJSRenderer.evaluateBundle(source: source, widgetId: widgetId)
+    if !okEval {
+      return VoltraClientWidgetEntry(
+        date: date,
+        widgetId: widgetId,
+        bundleReady: false,
+        errorMessage: "Bundle eval failed (see logs)",
+        configuration: configuration
+      )
+    }
+    return VoltraClientWidgetEntry(
+      date: date,
+      widgetId: widgetId,
+      bundleReady: true,
+      configuration: configuration,
+      bundleSource: source
+    )
+  }
+}
+
+// MARK: - Bundle source (dev vs prod)
+
+//
+// Dual-path bundle loader. Dev reads from Metro localhost; prod reads from a baked asset
+// in the .app bundle. The build-time bundle writer that produces the baked asset is a
+// future addition; until then prod throws a clear error.
+
+public enum VoltraClientWidgetBundleSource {
+  public enum LoadError: LocalizedError {
+    case metroHTTP(Int)
+    case nonUTF8
+    case bakedBundleNotFound(widgetId: String)
+
+    public var errorDescription: String? {
+      switch self {
+      case let .metroHTTP(code):
+        return "Metro HTTP \(code) — is the dev server running?"
+      case .nonUTF8:
+        return "Bundle response was not UTF-8 text"
+      case let .bakedBundleNotFound(id):
+        return "Production bundle missing for widgetId=\(id) (release path not yet implemented)"
+      }
+    }
+  }
+
+  public static func load(widgetId: String) async throws -> String {
+    #if DEBUG
+      return try await loadFromMetro(widgetId: widgetId)
+    #else
+      return try loadFromBakedAsset(widgetId: widgetId)
+    #endif
+  }
+
+  private static func loadFromMetro(widgetId: String) async throws -> String {
+    // Dev mode = always-refetch. URLSession default cache policy is fine —
+    // Metro's bundle responses are not cacheable, so each request hits the server.
+    //
+    // The base URL is relayed from the app via the app group (the app resolves it with
+    // RCTBundleURLProvider; this extension is React-free). Falls back to localhost:8081 when the
+    // app hasn't written it yet (e.g. first render before the host app has run).
+    let base = VoltraWidgetDefaults.devServerURL() ?? "http://localhost:8081"
+    let urlString = "\(base)/voltra/widgets/\(widgetId).bundle?platform=ios&dev=true"
+    guard let url = URL(string: urlString) else {
+      throw LoadError.metroHTTP(-1)
+    }
+    let (data, response) = try await URLSession.shared.data(from: url)
+    if let httpResponse = response as? HTTPURLResponse, !(200 ... 299).contains(httpResponse.statusCode) {
+      throw LoadError.metroHTTP(httpResponse.statusCode)
+    }
+    guard let text = String(data: data, encoding: .utf8) else {
+      throw LoadError.nonUTF8
+    }
+    return text
+  }
+
+  /// Release-path stub — currently always throws. The plan is to emit the baked bundle
+  /// at `expo prebuild` (config plugin step) into the extension target's resources, then
+  /// read it here with Bundle.main.url(forResource:withExtension:).
+  private static func loadFromBakedAsset(widgetId: String) throws -> String {
+    if let url = Bundle.main.url(forResource: "voltra-widget-\(widgetId)", withExtension: "bundle"),
+       let text = try? String(contentsOf: url, encoding: .utf8)
+    {
+      return text
+    }
+    throw LoadError.bakedBundleNotFound(widgetId: widgetId)
+  }
+}
+
+// MARK: - Env capture + JSON marshaling
+
+//
+// SwiftUI @Environment values are read inside the View body (see ContentView below) and
+// passed here as plain values. This helper emits a JSON string matching the
+// WidgetEnvironment type from packages/core/src/widget-environment.ts. We hand-roll the
+// JSON instead of going through JSONSerialization so the shape is locked to that type and
+// any drift produces a Swift compile error rather than a runtime parse failure.
+
+public enum VoltraClientWidgetEnvBuilder {
+  public static func build(
+    date: Date,
+    widgetFamily: WidgetFamily,
+    colorScheme: ColorScheme?,
+    widgetRenderingMode: WidgetRenderingMode,
+    showsWidgetContainerBackground: Bool,
+    locale: Locale,
+    configuration: [String: String]
+  ) -> String {
+    let timestampMs = Int(date.timeIntervalSince1970 * 1000)
+    let appVersion = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "unknown"
+
+    #if DEBUG
+      let isDev = true
+      let metroUrl: String? = VoltraWidgetDefaults.devServerURL() ?? "http://localhost:8081"
+    #else
+      let isDev = false
+      let metroUrl: String? = nil
+    #endif
+
+    let metroUrlLiteral = metroUrl.map(jsonString) ?? "null"
+    let buildJSON = """
+    {
+      "isDev": \(isDev),
+      "metroUrl": \(metroUrlLiteral),
+      "appVersion": \(jsonString(appVersion)),
+      "voltraVersion": \(jsonString("1.4.1"))
+    }
+    """
+
+    let configurationJSON: String
+    if configuration.isEmpty {
+      configurationJSON = "{}"
+    } else {
+      let entries = configuration
+        .map { "\(jsonString($0.key)): \(jsonString($0.value))" }
+        .joined(separator: ", ")
+      configurationJSON = "{ \(entries) }"
+    }
+
+    return """
+    {
+      "date": \(timestampMs),
+      "widgetFamily": \(jsonString(familyString(widgetFamily))),
+      "colorScheme": \(jsonString(schemeString(colorScheme))),
+      "locale": \(jsonString(locale.identifier)),
+      "widgetRenderingMode": \(jsonString(renderingModeString(widgetRenderingMode))),
+      "showsWidgetContainerBackground": \(showsWidgetContainerBackground),
+      "configuration": \(configurationJSON),
+      "build": \(buildJSON)
+    }
+    """
+  }
+
+  /// All three SwiftUI enums have String(describing:) representations that match their
+  /// case names exactly (e.g. "systemMedium", "fullColor", "dark"). Using String(describing:)
+  /// keeps these helpers forward-compatible when Apple adds new cases in a future SDK.
+  private static func familyString(_ family: WidgetFamily) -> String {
+    String(describing: family)
+  }
+
+  private static func renderingModeString(_ mode: WidgetRenderingMode) -> String {
+    String(describing: mode)
+  }
+
+  private static func schemeString(_ scheme: ColorScheme?) -> String {
+    guard let scheme else { return "light" }
+    return String(describing: scheme)
+  }
+
+  private static func jsonString(_ value: String) -> String {
+    let escaped = value
+      .replacingOccurrences(of: "\\", with: "\\\\")
+      .replacingOccurrences(of: "\"", with: "\\\"")
+      .replacingOccurrences(of: "\n", with: "\\n")
+      .replacingOccurrences(of: "\r", with: "\\r")
+    return "\"\(escaped)\""
+  }
+}
+
+// MARK: - Content view
+
+//
+// Per Q5 grilling: the resolved JSON is parsed into a VoltraNode and rendered via the
+// existing VoltraHomeWidgetView so Dynamic Widgets are visually indistinguishable
+// from server-rendered ones at the UI layer.
+
+public struct VoltraClientWidgetContentView: View {
+  public let entry: VoltraClientWidgetEntry
+  public let initialState: Data?
+
+  @Environment(\.widgetFamily) private var widgetFamily
+  @Environment(\.colorScheme) private var colorScheme
+  @Environment(\.widgetRenderingMode) private var widgetRenderingMode
+  @Environment(\.showsWidgetContainerBackground) private var showsWidgetContainerBackground
+  @Environment(\.locale) private var locale
+
+  public init(entry: VoltraClientWidgetEntry, initialState: Data?) {
+    self.entry = entry
+    self.initialState = initialState
+  }
+
+  public var body: some View {
+    let homeEntry = makeHomeEntry()
+    return VoltraHomeWidgetView(entry: homeEntry)
+  }
+
+  private func makeHomeEntry() -> VoltraHomeWidgetEntry {
+    if entry.bundleReady {
+      // WidgetKit may render this archived entry in a fresh extension process where the provider's
+      // bundle evaluation didn't happen. Re-evaluate from the entry's carried source (no-op if this
+      // process already has it) so render() finds the widget's function.
+      if let source = entry.bundleSource {
+        _ = VoltraJSRenderer.ensureEvaluated(widgetId: entry.widgetId, source: source)
+      }
+      let envJSON = VoltraClientWidgetEnvBuilder.build(
+        date: entry.date,
+        widgetFamily: widgetFamily,
+        colorScheme: colorScheme,
+        widgetRenderingMode: widgetRenderingMode,
+        showsWidgetContainerBackground: showsWidgetContainerBackground,
+        locale: locale,
+        configuration: entry.configuration
+      )
+      if let resolved = VoltraJSRenderer.render(
+        widgetId: entry.widgetId,
+        propsJSON: "{}",
+        envJSON: envJSON
+      ), let node = parseResolvedNode(jsonString: resolved) {
+        return VoltraHomeWidgetEntry(date: entry.date, rootNode: node, widgetId: entry.widgetId)
+      }
+      // render() or VoltraNode.parse failed — fall through to the prerendered initial state
+      // so the widget still shows real UI instead of a blank tile.
+    }
+    let fallbackNode = initialState.flatMap(parseResolvedNode(jsonData:))
+    return VoltraHomeWidgetEntry(date: entry.date, rootNode: fallbackNode, widgetId: entry.widgetId)
+  }
+
+  private func parseResolvedNode(jsonString: String) -> VoltraNode? {
+    guard let json = try? JSONValue.parse(from: jsonString) else { return nil }
+    let node = VoltraNode.parse(from: json)
+    if case .empty = node { return nil }
+    return node
+  }
+
+  private func parseResolvedNode(jsonData: Data) -> VoltraNode? {
+    guard let text = String(data: jsonData, encoding: .utf8) else { return nil }
+    return parseResolvedNode(jsonString: text)
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@use-voltra/ios-client",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Client-only Voltra APIs for iOS",
   "main": "./build/commonjs/index.js",
   "module": "./build/module/index.js",
@@ -28,19 +28,7 @@
     "expo-plugin/app.plugin.js",
     "expo-plugin/build",
     "expo-plugin/src",
-    "ios/Package.swift",
-    "ios/VoltraWidget.podspec",
-    "ios/app",
-    "ios/shared",
-    "ios/target",
-    "ios/ui/Extensions",
-    "ios/ui/Generated/Parameters/*",
-    "ios/ui/Helpers",
-    "ios/ui/Layout",
-    "ios/ui/Protocols",
-    "ios/ui/Style",
-    "ios/ui/Views",
-    "ios/ui/Voltra.swift",
+    "ios",
     "src",
     "*.podspec",
     "README.md"
@@ -51,8 +39,9 @@
     "@expo/plist": "^0.3.5",
     "dedent": "^1.7.1",
     "xcode": "^3.0.1",
-    "@use-voltra/expo-plugin": "^2.0.0",
-    "@use-voltra/ios": "^2.0.0"
+    "@use-voltra/compiler": "^2.1.0",
+    "@use-voltra/ios": "^2.1.0",
+    "@use-voltra/expo-plugin": "^2.1.0"
   },
   "peerDependencies": {
     "expo": "*",

package/src/index.ts

@@ -31,6 +31,7 @@ export {
   reloadLiveActivities,
 } from './preload.js'
 export { assertRunningOnApple } from './utils/assertRunningOnApple.js'
+export { enableWidgetHotReload } from './utils/enableWidgetHotReload.js'
 export { useUpdateOnHMR } from './utils/useUpdateOnHMR.js'
 export * from './utils/helpers.js'
 export type { VoltraElementJson, VoltraNodeJson } from './types.js'

package/src/utils/enableWidgetHotReload.ts

@@ -0,0 +1,39 @@
+import { reloadWidgets } from '../widgets/widget-api.js'
+
+declare global {
+  var __accept: (...args: unknown[]) => void
+}
+
+/**
+ * Trigger `reloadWidgets()` on every Metro Fast Refresh patch (DEV only).
+ *
+ * Hooks the global `__accept` callback Metro fires when a Fast Refresh patch
+ * lands in the host app's JS runtime. When fired, calls
+ * `WidgetCenter.shared.reloadAllTimelines()` so WidgetKit re-invokes each widget
+ * Provider, which re-fetches the freshest bundle from Metro and renders the
+ * updated UI.
+ *
+ * Only effective while the host app's JS thread is alive — iOS suspends the
+ * RN runtime within ~5 seconds of backgrounding, so the "edit while staring at
+ * the home screen, never touch the host app" case is not covered. For that
+ * workflow the dev still relies on WidgetKit's natural lifecycle refresh on
+ * app foreground.
+ *
+ * Call once at app startup. Returns `dispose()` to restore the prior
+ * `__accept` (rarely needed in practice). No-op in release builds.
+ */
+export function enableWidgetHotReload(): () => void {
+  if (!__DEV__) {
+    return () => {}
+  }
+
+  const oldAccept = global['__accept']
+  global['__accept'] = (...args) => {
+    void reloadWidgets()
+    oldAccept?.(...args)
+  }
+
+  return () => {
+    global['__accept'] = oldAccept
+  }
+}