@use-voltra/ios-client 2.0.0 → 2.1.0

package/expo-plugin/src/types.ts

@@ -1,6 +1,6 @@
 import type { ConfigPlugin } from '@expo/config-plugins'
 
-import type { WidgetInitialStatePath, WidgetLabel } from '@use-voltra/expo-plugin'
+import type { DynamicWidgetEntryConfig, WidgetInitialStatePath, WidgetLabel } from '@use-voltra/expo-plugin'
 
 /**
  * Supported iOS Home Screen widget size families.
@@ -14,10 +14,33 @@ export type IOSWidgetFamily =
   | 'accessoryRectangular'
   | 'accessoryInline'
 
+/**
+ * A single user-configurable parameter exposed via AppIntent (the native "Edit Widget" sheet).
+ */
+export interface AppIntentParameter {
+  /** Swift property name + the key under `env.configuration`. */
+  name: string
+  /** Label shown in the widget configuration sheet. */
+  title: string
+  /** Default value used before the user configures the widget (the "from code" default). */
+  default?: string
+}
+
+/**
+ * AppIntent configuration for a user-configurable widget (iOS 17+).
+ */
+export interface IOSWidgetAppIntentConfig {
+  /** Parameters the user can edit via "Edit Widget"; surfaced as `env.configuration`. */
+  parameters: AppIntentParameter[]
+}
+
 /**
  * Configuration for a single iOS home screen widget.
+ *
+ * `entry` is required only for Dynamic Widgets. Widgets without `entry` remain server-rendered /
+ * server-updated legacy widgets and are excluded from the Dynamic Widgets manifest.
  */
-export interface IOSWidgetConfig {
+export interface IOSWidgetConfig extends DynamicWidgetEntryConfig {
   /**
    * Unique identifier for the widget (used as the widget kind and in JS API)
    */
@@ -28,6 +51,13 @@ export interface IOSWidgetConfig {
   supportedFamilies?: IOSWidgetFamily[]
   initialStatePath?: WidgetInitialStatePath
   serverUpdate?: IOSWidgetServerUpdateConfig
+  /**
+   * AppIntent configuration (iOS 17+). When set on a Dynamic Widget, the plugin generates
+   * an `AppIntentConfiguration` so users configure parameters via the native "Edit Widget" sheet;
+   * defaults come from `parameters[].default`, and the configured values are passed into the
+   * widget's `env.configuration` on each render.
+   */
+  appIntent?: IOSWidgetAppIntentConfig
 }
 
 /**

package/expo-plugin/src/validation.ts

@@ -1,4 +1,9 @@
-import { validateHomeScreenWidgetId, validateInitialStatePath, validateWidgetLabel } from '@use-voltra/expo-plugin'
+import {
+  validateHomeScreenWidgetId,
+  validateInitialStatePath,
+  validateWidgetEntry,
+  validateWidgetLabel,
+} from '@use-voltra/expo-plugin'
 
 import type { IOSConfigPluginProps, IOSWidgetConfig, IOSWidgetFamily } from './types'
 
@@ -12,11 +17,15 @@ const VALID_FAMILIES: Set<IOSWidgetFamily> = new Set([
   'accessoryInline',
 ])
 
-export function validateIOSWidgetConfig(widget: IOSWidgetConfig): void {
+export function validateIOSWidgetConfig(widget: IOSWidgetConfig, projectRoot?: string): void {
   validateHomeScreenWidgetId(widget.id)
   validateWidgetLabel(widget.displayName, widget.id, 'displayName')
   validateWidgetLabel(widget.description, widget.id, 'description')
-  validateInitialStatePath(widget.initialStatePath, widget.id)
+  validateInitialStatePath(widget.initialStatePath, widget.id, projectRoot)
+
+  if (widget.entry !== undefined) {
+    validateWidgetEntry(widget.entry, widget.id, projectRoot)
+  }
 
   if (widget.supportedFamilies) {
     if (!Array.isArray(widget.supportedFamilies)) {
@@ -34,7 +43,7 @@ export function validateIOSWidgetConfig(widget: IOSWidgetConfig): void {
   }
 }
 
-export function validateIOSConfigPluginProps(props: IOSConfigPluginProps): void {
+export function validateIOSConfigPluginProps(props: IOSConfigPluginProps, projectRoot?: string): void {
   if (props.groupIdentifier !== undefined) {
     if (typeof props.groupIdentifier !== 'string') {
       throw new Error('groupIdentifier must be a string')
@@ -52,7 +61,7 @@ export function validateIOSConfigPluginProps(props: IOSConfigPluginProps): void
 
     const seenIds = new Set<string>()
     for (const widget of props.widgets) {
-      validateIOSWidgetConfig(widget)
+      validateIOSWidgetConfig(widget, projectRoot)
 
       if (seenIds.has(widget.id)) {
         throw new Error(`Duplicate widget ID: '${widget.id}'`)

package/ios/app/VoltraModuleImpl.swift

@@ -2,6 +2,7 @@ import ActivityKit
 import Compression
 import Foundation
 import os
+import React
 import UIKit
 
 @objc(VoltraHeadlessState)
@@ -59,7 +60,26 @@ public class VoltraModuleImpl {
   public init() {
     // Clean up data for widgets that are no longer installed
     VoltraWidgetService.cleanupOrphanedData()
-  }
+    #if DEBUG
+      syncDevServerURL()
+    #endif
+  }
+
+  #if DEBUG
+    /// Resolve the Metro dev-server base URL via React Native's own provider and relay it to the
+    /// widget extension through the app group. The extension is React-free (can't call
+    /// RCTBundleURLProvider itself), so the app resolves it and the extension reads it — fixing the
+    /// case where Metro isn't on localhost:8081 (custom port, LAN dev server, physical device).
+    private func syncDevServerURL() {
+      guard
+        let url = RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index"),
+        let scheme = url.scheme,
+        let host = url.host
+      else { return }
+      let port = url.port.map { ":\($0)" } ?? ""
+      VoltraWidgetDefaults.setDevServerURL("\(scheme)://\(host)\(port)")
+    }
+  #endif
 
   func isHeadless() -> Bool {
     VoltraHeadlessState.shared.isHeadless()
@@ -255,6 +275,11 @@ public class VoltraModuleImpl {
   }
 
   func reloadWidgets(widgetIds: [String]?) async {
+    #if DEBUG
+      // Refresh the relayed dev-server URL before reloading (hot-reload path) so the extension
+      // fetches from the current Metro host.
+      syncDevServerURL()
+    #endif
     if let ids = widgetIds, !ids.isEmpty {
       for widgetId in ids {
         VoltraWidgetService.reloadTimeline(for: widgetId)

package/ios/shared/VoltraConstants.swift

@@ -32,6 +32,10 @@ public enum VoltraStorageKeys {
 
   public static let widgetKindPrefix = "Voltra_Widget_"
 
+  /// Metro dev-server base URL, relayed app → widget extension (DEBUG only). The extension is
+  /// React-free, so it can't resolve the URL itself; the app writes it via RCTBundleURLProvider.
+  public static let devServerURL = "Voltra_DevServerURL"
+
   // MARK: - Info.plist keys
 
   public static let widgetIds = "Voltra_WidgetIds"

package/ios/shared/VoltraJSRenderer.swift

@@ -0,0 +1,201 @@
+import Foundation
+import JavaScriptCore
+
+/// JavaScriptCore-backed runtime for Voltra **Dynamic Widgets**.
+///
+/// Each widget ships its own Metro bundle that defines `module.exports.render(props, env)`
+/// (see `example/metro/widgetRegistry.js`). When evaluated, the bundle ends with `__r(0)`
+/// which executes its entry module; the source is wrapped with a small bootstrap that
+/// captures those exports into `globalThis.__voltraWidgets[<widgetId>]` so `render` can be
+/// called from native at any later moment.
+///
+/// One shared `JSContext` per process. Each subsequent bundle evaluation overwrites Metro's
+/// `__r`/`__d` globals (they're closure-scoped per bundle's IIFE), but the captured
+/// `globalThis.__voltraWidgets[<widgetId>]` reference retains each widget's render function
+/// indefinitely.
+public enum VoltraJSRenderer {
+  private static var _context: JSContext?
+  private static let lock = NSLock()
+  private static let TAG = "VoltraJSRenderer"
+
+  // MARK: - Public API
+
+  /// Evaluate a Voltra widget bundle in the shared JSContext, capturing the bundle's
+  /// `render(props, env)` export under `globalThis.__voltraWidgets[<widgetId>]`.
+  ///
+  /// The bundle source is the raw output of Metro's
+  /// `/voltra/widgets/<widgetId>.bundle` endpoint. We append a small bootstrap line
+  /// that runs after the bundle's `__r(0)` to capture the entry module's exports.
+  ///
+  /// 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 {
+    lock.lock()
+    defer { lock.unlock() }
+
+    guard let ctx = context() else {
+      VoltraLogger.widget.error("[\(TAG)] No JSContext available")
+      return false
+    }
+
+    let escapedId = jsStringLiteral(widgetId)
+    // 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
+    // shares its module-id registry across bundles so the second/third widget's entry
+    // gets a higher id (e.g. `__r(74);`). We extract whatever id Metro produced and
+    // re-invoke it; Metro's `__r` caches module exports, so the second invocation
+    // returns the same exports the bundle already evaluated.
+    let entryModuleId = extractEntryModuleId(from: source) ?? 0
+    let wrapped = """
+    \(source)
+    ;(function () {
+      if (!globalThis.__voltraWidgets) { globalThis.__voltraWidgets = {}; }
+      globalThis.__voltraWidgets[\(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)")
+      return false
+    }
+
+    // Verify the bootstrap captured the exports correctly
+    guard
+      let registry = ctx.objectForKeyedSubscript("__voltraWidgets"),
+      !registry.isUndefined,
+      let widget = registry.objectForKeyedSubscript(widgetId),
+      !widget.isUndefined,
+      let renderFn = widget.objectForKeyedSubscript("render"),
+      renderFn.isObject,
+      renderFn.objectForKeyedSubscript("call") != nil
+    else {
+      VoltraLogger.widget.error("[\(TAG)] Bundle evaluated but did not expose render() for widgetId=\(widgetId)")
+      return false
+    }
+    _ = renderFn
+
+    VoltraLogger.widget.info("[\(TAG)] Bundle evaluated for widgetId=\(widgetId) (\(source.count) chars)")
+    return true
+  }
+
+  /// Ensure the widget's bundle is evaluated in *this process's* JSContext, returning true if its
+  /// `render()` is available afterward.
+  ///
+  /// Cheap no-op when the widget is already captured in this process (the warm case: the provider
+  /// just evaluated it). Evaluates from `source` when the context is fresh — which is what happens
+  /// when WidgetKit re-renders an archived entry in a new extension process, where the provider's
+  /// 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 {
+    lock.lock()
+    let alreadyEvaluated =
+      _context?
+        .objectForKeyedSubscript("__voltraWidgets")?
+        .objectForKeyedSubscript(widgetId)?
+        .objectForKeyedSubscript("render")?
+        .isObject ?? false
+    lock.unlock()
+
+    if alreadyEvaluated {
+      return true
+    }
+    return evaluateBundle(source: source, widgetId: widgetId)
+  }
+
+  /// Invoke the previously-evaluated widget's `render(propsJSON, envJSON)` function and
+  /// return its resolved JSON string output.
+  ///
+  /// Returns `nil` if the widget hasn't been evaluated, the function throws, or the
+  /// result is not a string.
+  public static func render(
+    widgetId: String,
+    propsJSON: String,
+    envJSON: String
+  ) -> String? {
+    lock.lock()
+    defer { lock.unlock() }
+
+    guard let ctx = _context else {
+      VoltraLogger.widget.error("[\(TAG)] render(\(widgetId)): no JSContext (call evaluateBundle first)")
+      return nil
+    }
+
+    guard
+      let registry = ctx.objectForKeyedSubscript("__voltraWidgets"),
+      !registry.isUndefined,
+      let widget = registry.objectForKeyedSubscript(widgetId),
+      !widget.isUndefined,
+      let renderFn = widget.objectForKeyedSubscript("render"),
+      renderFn.isObject
+    else {
+      VoltraLogger.widget.error("[\(TAG)] render(\(widgetId)): 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")
+      return nil
+    }
+    if let message = exceptionMessage(ctx) {
+      VoltraLogger.widget.error("[\(TAG)] render(\(widgetId)) threw: \(message)")
+      return nil
+    }
+
+    guard result.isString else {
+      VoltraLogger.widget.error("[\(TAG)] render(\(widgetId)) did not return a string")
+      return nil
+    }
+    return result.toString()
+  }
+
+  // MARK: - Lifecycle
+
+  private static func context() -> JSContext? {
+    if let existing = _context { return existing }
+    guard let ctx = JSContext() else {
+      VoltraLogger.widget.error("[\(TAG)] Failed to create JSContext")
+      return nil
+    }
+    ctx.exceptionHandler = { _, exception in
+      VoltraLogger.widget.error("[\(TAG)] JS exception: \(exception?.toString() ?? "unknown")")
+    }
+    _context = ctx
+    return ctx
+  }
+
+  // MARK: - Helpers
+
+  private static func exceptionMessage(_ ctx: JSContext) -> String? {
+    guard let exc = ctx.exception, !exc.isUndefined, !exc.isNull else { return nil }
+    ctx.exception = nil
+    return exc.toString()
+  }
+
+  private static func jsStringLiteral(_ value: String) -> String {
+    let escaped = value
+      .replacingOccurrences(of: "\\", with: "\\\\")
+      .replacingOccurrences(of: "\"", with: "\\\"")
+      .replacingOccurrences(of: "\n", with: "\\n")
+      .replacingOccurrences(of: "\r", with: "\\r")
+    return "\"\(escaped)\""
+  }
+
+  /// Find the entry module id Metro emitted in the bundle's trailing `__r(<id>);`.
+  /// Scans the LAST occurrence of `__r(<digits>);` in the source — every `__d(...)`
+  /// module declaration also contains internal `__r(...)` calls, so taking the last
+  /// match (the entrypoint invocation Metro appends at bundle's end) is what we want.
+  private static func extractEntryModuleId(from source: String) -> Int? {
+    guard let regex = try? NSRegularExpression(pattern: #"__r\((\d+)\);"#) else { return nil }
+    let nsRange = NSRange(source.startIndex ..< source.endIndex, in: source)
+    let matches = regex.matches(in: source, range: nsRange)
+    guard let last = matches.last,
+          let range = Range(last.range(at: 1), in: source),
+          let id = Int(source[range])
+    else { return nil }
+    return id
+  }
+}

package/ios/shared/VoltraWidgetDefaults.swift

@@ -37,6 +37,12 @@ public enum VoltraWidgetDefaults {
     try? resolvedDefaults().string(forKey: VoltraStorageKeys.widgetTimeline(widgetId))
   }
 
+  /// Metro dev-server base URL relayed from the app (DEBUG). Read by the client-widget runtime;
+  /// nil falls back to localhost.
+  public static func devServerURL() -> String? {
+    try? resolvedDefaults().string(forKey: VoltraStorageKeys.devServerURL)
+  }
+
   // MARK: - Write
 
   public static func setWidgetJson(_ json: String, for widgetId: String, deepLinkUrl: String?) throws {
@@ -70,6 +76,14 @@ public enum VoltraWidgetDefaults {
     defaults.synchronize()
   }
 
+  /// Relay the Metro dev-server base URL to the widget extension (DEBUG). Best-effort: a missing
+  /// app group just leaves the extension on its localhost fallback.
+  public static func setDevServerURL(_ url: String) {
+    guard let defaults = try? resolvedDefaults() else { return }
+    defaults.set(url, forKey: VoltraStorageKeys.devServerURL)
+    defaults.synchronize()
+  }
+
   // MARK: - Remove
 
   /// Removes all persisted data (json, deepLinkUrl, timeline) for a single widget.