@use-voltra/ios-client 2.2.0 → 2.3.0

package/expo-plugin/src/ios/infoPlist.ts

@@ -1,12 +1,15 @@
 import { ConfigPlugin, withInfoPlist } from '@expo/config-plugins'
 
+import { widgetKindOverrides } from '../constants'
 import type { IOSWidgetConfig } from '../types'
+import { resolveIOSWidgetServerUpdate } from './serverUpdate'
 
 export interface ConfigureInfoPlistProps {
   groupIdentifier?: string
   widgetIds?: string[]
   widgets?: IOSWidgetConfig[]
   keychainGroup?: string
+  voltraVersion: string
 }
 
 /**
@@ -16,14 +19,16 @@ export interface ConfigureInfoPlistProps {
  * - NSSupportsLiveActivities: Enables Live Activities support
  * - Voltra_AppGroupIdentifier: App group ID for widget communication (if provided)
  * - Voltra_WidgetIds: Array of widget IDs for native module access (if provided)
+ * - Voltra_WidgetKinds: Map of widget IDs to custom WidgetKit kinds (if any widget sets `kind`)
  * - Voltra_WidgetServerUrls: Map of widget IDs to server URLs (if any widgets have serverUpdate)
  * - Voltra_WidgetServerIntervals: Map of widget IDs to update intervals (if any widgets have serverUpdate)
  * - Voltra_KeychainGroup: Keychain access group for shared credentials (if provided)
  */
-export const configureInfoPlist: ConfigPlugin<ConfigureInfoPlistProps> = (config, props = {}) => {
+export const configureInfoPlist: ConfigPlugin<ConfigureInfoPlistProps> = (config, props) => {
   return withInfoPlist(config, (mod) => {
     mod.modResults.NSSupportsLiveActivities = true
     mod.modResults.NSSupportsLiveActivitiesFrequentUpdates = false
+    mod.modResults.Voltra_Version = props.voltraVersion
 
     // Only add group identifier if provided
     if (props.groupIdentifier) {
@@ -35,21 +40,44 @@ export const configureInfoPlist: ConfigPlugin<ConfigureInfoPlistProps> = (config
       mod.modResults.Voltra_WidgetIds = props.widgetIds
     }
 
+    // Store custom widget kinds so native code can map ids to kinds and back. A prebuild over an
+    // existing ios/ directory keeps whatever the plist already holds, so a `kind` that was removed
+    // from the config has to be deleted here or the widget would keep a kind nobody configured.
+    const widgetKinds = widgetKindOverrides(props.widgets)
+    if (widgetKinds) {
+      mod.modResults.Voltra_WidgetKinds = widgetKinds
+    } else {
+      delete mod.modResults.Voltra_WidgetKinds
+    }
+
     // Configure server update URLs and intervals for widgets
     if (props.widgets && props.widgets.length > 0) {
       const serverUrls: Record<string, string> = {}
       const serverIntervals: Record<string, number> = {}
 
       for (const widget of props.widgets) {
-        if (widget.serverUpdate) {
-          serverUrls[widget.id] = widget.serverUpdate.url
-          serverIntervals[widget.id] = widget.serverUpdate.intervalMinutes ?? 15
+        const serverUpdate = resolveIOSWidgetServerUpdate(widget)
+
+        if (!serverUpdate) {
+          continue
+        }
+
+        // Every server-driven widget gets an interval, so this dictionary's keys are the set of
+        // server-driven widget ids the runtime settings store validates against. A URL is written
+        // only when app.json set one; otherwise the app supplies it with setWidgetServerUpdate.
+        serverIntervals[widget.id] = serverUpdate.intervalMinutes
+
+        if (serverUpdate.url !== undefined) {
+          serverUrls[widget.id] = serverUpdate.url
         }
       }
 
+      if (Object.keys(serverIntervals).length > 0) {
+        mod.modResults.Voltra_WidgetServerIntervals = serverIntervals
+      }
+
       if (Object.keys(serverUrls).length > 0) {
         mod.modResults.Voltra_WidgetServerUrls = serverUrls
-        mod.modResults.Voltra_WidgetServerIntervals = serverIntervals
       }
     }
 

package/expo-plugin/src/ios/serverUpdate.ts

@@ -0,0 +1,29 @@
+import { resolveWidgetServerUpdate } from '@use-voltra/expo-plugin'
+
+import type { ResolvedWidgetServerUpdateConfig, WidgetServerUpdateRules } from '@use-voltra/expo-plugin'
+
+import type { IOSWidgetConfig } from '../types'
+
+/**
+ * iOS payload widgets have always defaulted to 15 minutes and accepted anything down to 1, since
+ * WidgetKit stretches a timeline it cannot honour rather than refusing it. A widget with an
+ * `entry` follows ADR 0002 instead: default 15, floor 15 on both platforms.
+ */
+export function iosServerUpdateRules(widget: Pick<IOSWidgetConfig, 'entry'>): WidgetServerUpdateRules {
+  return {
+    hasEntry: widget.entry !== undefined,
+    defaultIntervalMinutes: 15,
+    minimumIntervalMinutes: 1,
+  }
+}
+
+/** `serverUpdate` with defaults applied, as the plist and Swift generators consume it. */
+export function resolveIOSWidgetServerUpdate(
+  widget: Pick<IOSWidgetConfig, 'entry' | 'serverUpdate'>
+): ResolvedWidgetServerUpdateConfig | undefined {
+  if (widget.serverUpdate === undefined) {
+    return undefined
+  }
+
+  return resolveWidgetServerUpdate(widget.serverUpdate, iosServerUpdateRules(widget))
+}

package/expo-plugin/src/ios-widget/clientRendered.ts

@@ -1,7 +1,7 @@
 import * as fs from 'fs'
 import * as path from 'path'
 
-import { evaluateWidgetModuleExports } from '@use-voltra/expo-plugin'
+import { createPrerenderWidgetModuleLoader, type WidgetModuleLoader } from '@use-voltra/expo-plugin'
 
 import type { IOSWidgetConfig } from '../types'
 
@@ -30,7 +30,8 @@ let hasWarnedExperimental = false
 
 /** Inspect every widget once and tag entry-backed widgets as Dynamic Widgets. */
 export function detectClientRenderedWidgets(widgets: IOSWidgetConfig[], projectRoot: string): DetectedIOSWidget[] {
-  const detected = widgets.map((widget) => detectSingleWidget(widget, projectRoot))
+  const loader = createPrerenderWidgetModuleLoader(projectRoot, 'ios')
+  const detected = widgets.map((widget) => detectSingleWidget(widget, projectRoot, loader))
 
   if (!hasWarnedExperimental) {
     const clientWidgetIds = detected.filter((widget) => widget.clientRendered).map((widget) => widget.id)
@@ -47,7 +48,11 @@ export function detectClientRenderedWidgets(widgets: IOSWidgetConfig[], projectR
   return detected
 }
 
-function detectSingleWidget(widget: IOSWidgetConfig, projectRoot: string): DetectedIOSWidget {
+function detectSingleWidget(
+  widget: IOSWidgetConfig,
+  projectRoot: string,
+  loader: WidgetModuleLoader
+): DetectedIOSWidget {
   if (widget.entry === undefined) {
     return {
       ...widget,
@@ -65,8 +70,7 @@ function detectSingleWidget(widget: IOSWidgetConfig, projectRoot: string): Detec
     )
   }
 
-  const widgetModule = evaluateWidgetModuleExports(projectRoot, sourcePath)
-  const widgetFn = widgetModule?.default ?? widgetModule
+  const widgetFn = loader.loadDefaultExport(sourcePath)
   if (typeof widgetFn !== 'function') {
     throw new Error(
       `[voltra] Dynamic Widget "${widget.id}" at ${path.relative(

package/expo-plugin/src/ios-widget/clientRenderedPrerender.ts

@@ -1,4 +1,9 @@
-import { evaluateWidgetModuleExports, logger, type PrerenderedWidgetStates } from '@use-voltra/expo-plugin'
+import {
+  createPrerenderWidgetModuleLoader,
+  logger,
+  resolveInstalledPackageVersion,
+  type PrerenderedWidgetStates,
+} from '@use-voltra/expo-plugin'
 
 import type { DetectedIOSWidget } from './clientRendered'
 
@@ -31,7 +36,7 @@ const SINGLE_LOCALE_KEY = '__default'
  * mirror `WidgetEnvironment` from packages/core/src/widget-environment.ts so the widget
  * function sees the same shape it gets at runtime.
  */
-function buildPlaceholderEnv(): Record<string, unknown> {
+function buildPlaceholderEnv(voltraVersion: string): Record<string, unknown> {
   return {
     date: Date.now(),
     widgetFamily: 'systemMedium',
@@ -44,7 +49,7 @@ function buildPlaceholderEnv(): Record<string, unknown> {
       isDev: false,
       metroUrl: null,
       appVersion: 'unknown',
-      voltraVersion: '1.4.1',
+      voltraVersion,
     },
   }
 }
@@ -75,12 +80,12 @@ export async function prerenderClientRenderedWidgets(
     renderVoltraVariantToJson: (element: unknown) => unknown
   }
 
-  const placeholderEnv = buildPlaceholderEnv()
+  const placeholderEnv = buildPlaceholderEnv(resolveInstalledPackageVersion(projectRoot, '@use-voltra/ios-client'))
+  const loader = createPrerenderWidgetModuleLoader(projectRoot, 'ios')
 
   for (const widget of clientWidgets) {
     try {
-      const widgetModule = evaluateWidgetModuleExports(projectRoot, widget.clientSourcePath)
-      const widgetFn = widgetModule?.default ?? widgetModule
+      const widgetFn = loader.loadDefaultExport(widget.clientSourcePath)
       if (typeof widgetFn !== 'function') {
         throw new Error(
           `Expected the entry module at ${widget.clientSourcePath} to default-export a function or component.`

package/expo-plugin/src/ios-widget/dynamic-live-activity/swift.ts

@@ -0,0 +1,138 @@
+import dedent from 'dedent'
+
+import { getDynamicLiveActivityAttributesType } from '@use-voltra/expo-plugin'
+
+import type { IOSDynamicLiveActivityConfig } from '../../types'
+import { escapeForSwiftStringLiteral } from '../files/swift-utils'
+
+export function generateDynamicLiveActivityWidgetInstances(liveActivities: IOSDynamicLiveActivityConfig[]): string {
+  return sortedDefinitions(liveActivities)
+    .map((liveActivity) => `VoltraDynamicLiveActivity_${getDynamicLiveActivityAttributesType(liveActivity.id)}()`)
+    .join('\n    ')
+}
+
+/** Generates the Dynamic Live Activity types shared by the app and extension targets. */
+export function generateDynamicLiveActivityTypesSwift(liveActivities: IOSDynamicLiveActivityConfig[]): string {
+  const definitions = sortedDefinitions(liveActivities)
+  const typeDefinitions = definitions.map(generateDynamicLiveActivitySwift).map(normalizeIndent).join('\n\n')
+
+  const header = dedent`
+    //
+    //  VoltraDynamicLiveActivityTypes.swift
+    //
+    //  Auto-generated by Voltra config plugin. Do not edit.
+    //
+
+    import ActivityKit
+    import Foundation
+
+    import VoltraRuntime
+
+    @objc(VoltraGeneratedDynamicLiveActivityRegistration)
+    public final class VoltraGeneratedDynamicLiveActivityRegistration: NSObject {
+      @objc public static func registerDefinitions() {
+${definitions
+  .map(
+    (liveActivity) =>
+      `        VoltraDynamicLiveActivityRegistry.shared.register(${getDynamicLiveActivityAttributesType(
+        liveActivity.id
+      )}.self)`
+  )
+  .join('\n')}
+      }
+    }
+
+  `
+  return [header.trim(), typeDefinitions.trim()].filter(Boolean).join('\n\n')
+}
+
+/** Generates extension-only ActivityConfiguration declarations for Dynamic Live Activities. */
+export function generateDynamicLiveActivitiesSwift(liveActivities: IOSDynamicLiveActivityConfig[]): string {
+  const configurations = sortedDefinitions(liveActivities)
+    .map((liveActivity) => {
+      const attributesType = getDynamicLiveActivityAttributesType(liveActivity.id)
+      const definitionId = escapeForSwiftStringLiteral(liveActivity.id)
+      return dedent`
+        public struct VoltraDynamicLiveActivity_${attributesType}: Widget {
+          public init() {}
+
+          public var body: some WidgetConfiguration {
+            if #available(iOS 18.0, *) {
+              return adaptiveConfig()
+            } else {
+              return defaultConfig()
+            }
+          }
+
+          @available(iOS 18.0, *)
+          private func adaptiveConfig() -> some WidgetConfiguration {
+            ActivityConfiguration(for: ${attributesType}.self) { context in
+              VoltraDynamicLiveActivityRenderer.lockScreen(definitionId: "${definitionId}", context: context)
+            } dynamicIsland: { context in
+              VoltraDynamicLiveActivityRenderer.dynamicIsland(definitionId: "${definitionId}", context: context)
+            }
+            .supplementalActivityFamilies([.small, .medium])
+          }
+
+          private func defaultConfig() -> some WidgetConfiguration {
+            ActivityConfiguration(for: ${attributesType}.self) { context in
+              VoltraDynamicLiveActivityRenderer.lockScreen(definitionId: "${definitionId}", context: context)
+            } dynamicIsland: { context in
+              VoltraDynamicLiveActivityRenderer.dynamicIsland(definitionId: "${definitionId}", context: context)
+            }
+          }
+        }
+      `
+    })
+    .map(normalizeIndent)
+    .join('\n\n')
+
+  const header = dedent`
+    //
+    //  VoltraDynamicLiveActivities.swift
+    //
+    //  Auto-generated by Voltra config plugin. Do not edit.
+    //
+
+    import ActivityKit
+    import SwiftUI
+    import WidgetKit
+    import VoltraRuntime
+
+  `
+  return [header.trim(), configurations.trim()].filter(Boolean).join('\n\n')
+}
+
+function generateDynamicLiveActivitySwift(liveActivity: IOSDynamicLiveActivityConfig): string {
+  const attributesType = getDynamicLiveActivityAttributesType(liveActivity.id)
+  const definitionId = escapeForSwiftStringLiteral(liveActivity.id)
+
+  return dedent`
+    public struct ${attributesType}: ActivityAttributes {
+      public typealias ContentState = VoltraDynamicLiveActivityContentState
+
+      public let name: String
+      public let deepLinkUrl: String?
+
+      public init(name: String, deepLinkUrl: String?) {
+        self.name = name
+        self.deepLinkUrl = deepLinkUrl
+      }
+    }
+
+    extension ${attributesType}: VoltraDynamicLiveActivityDefinition {
+      public static let definitionId = "${definitionId}"
+    }
+
+  `
+}
+
+function sortedDefinitions(liveActivities: IOSDynamicLiveActivityConfig[]): IOSDynamicLiveActivityConfig[] {
+  return [...liveActivities].sort((left, right) => left.id.localeCompare(right.id))
+}
+
+function normalizeIndent(source: string): string {
+  const lines = source.trim().split('\n')
+  const indent = Math.min(...lines.filter(Boolean).map((line) => line.match(/^\s*/)?.[0].length ?? 0))
+  return lines.map((line) => line.slice(indent)).join('\n')
+}

package/expo-plugin/src/ios-widget/files/index.ts

@@ -2,20 +2,22 @@ import { ConfigPlugin, withDangerousMod } from '@expo/config-plugins'
 import * as fs from 'fs'
 import * as path from 'path'
 
-import type { IOSWidgetConfig } from '../../types'
+import type { IOSDynamicLiveActivityConfig, IOSWidgetConfig } from '../../types'
 import { generateAssets } from './assets'
 import { generateEntitlements } from './entitlements'
 import { generateInfoPlist } from './infoPlist'
-import { generateIOSDynamicWidgetsManifest } from './manifest'
+import { generateIOSDynamicLiveActivitiesManifest, generateIOSDynamicWidgetsManifest } from './manifest'
 import { generateSwiftFiles } from './swift'
 
 export interface GenerateWidgetExtensionFilesProps {
   targetName: string
   widgets?: IOSWidgetConfig[]
+  liveActivities?: IOSDynamicLiveActivityConfig[]
   groupIdentifier?: string
   keychainGroup?: string
   version: string
   buildNumber: string
+  voltraVersion: string
 }
 
 /**
@@ -31,7 +33,8 @@ export interface GenerateWidgetExtensionFilesProps {
  * This should run before configureXcodeProject so the files exist when Xcode project is configured.
  */
 export const generateWidgetExtensionFiles: ConfigPlugin<GenerateWidgetExtensionFilesProps> = (config, props) => {
-  const { targetName, widgets, groupIdentifier, keychainGroup, version, buildNumber } = props
+  const { targetName, widgets, liveActivities, groupIdentifier, keychainGroup, version, buildNumber, voltraVersion } =
+    props
 
   return withDangerousMod(config, [
     'ios',
@@ -49,7 +52,7 @@ export const generateWidgetExtensionFiles: ConfigPlugin<GenerateWidgetExtensionF
       }
 
       // Generate Info.plist
-      generateInfoPlist(targetPath, targetName, version, buildNumber)
+      generateInfoPlist(targetPath, targetName, version, buildNumber, voltraVersion)
 
       // Generate Assets.xcassets and copy user images
       generateAssets({ targetPath })
@@ -59,6 +62,7 @@ export const generateWidgetExtensionFiles: ConfigPlugin<GenerateWidgetExtensionF
         targetPath,
         projectRoot,
         widgets,
+        liveActivities,
       })
 
       // Write the iOS-owned Dynamic Widgets manifest for Metro to consume later.
@@ -67,6 +71,13 @@ export const generateWidgetExtensionFiles: ConfigPlugin<GenerateWidgetExtensionF
         widgets,
       })
 
+      // Dynamic Live Activities have their own Metro manifest so their IDs may overlap with
+      // Dynamic Widgets and stale declarations never leak into a later prebuild.
+      generateIOSDynamicLiveActivitiesManifest({
+        projectRoot,
+        liveActivities,
+      })
+
       // Generate entitlements file (may be empty if no groupIdentifier or keychainGroup)
       generateEntitlements({
         targetPath,

package/expo-plugin/src/ios-widget/files/infoPlist.ts

@@ -9,7 +9,12 @@ import { logger } from '@use-voltra/expo-plugin'
  * This includes version information and the required WidgetKit extension point.
  * Version keys are written directly to the plist following the Expo pattern.
  */
-function generateInfoPlistContent(targetName: string, version: string, buildNumber: string): string {
+function generateInfoPlistContent(
+  targetName: string,
+  version: string,
+  buildNumber: string,
+  voltraVersion: string
+): string {
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -32,6 +37,8 @@ function generateInfoPlistContent(targetName: string, version: string, buildNumb
 	<string>${version}</string>
 	<key>CFBundleVersion</key>
 	<string>${buildNumber}</string>
+	<key>Voltra_Version</key>
+	<string>${voltraVersion}</string>
 	<key>NSExtension</key>
 	<dict>
 		<key>NSExtensionPointIdentifier</key>
@@ -49,9 +56,16 @@ function generateInfoPlistContent(targetName: string, version: string, buildNumb
  * @param targetName - The widget extension target name (used for CFBundleDisplayName)
  * @param version - The app version (CFBundleShortVersionString)
  * @param buildNumber - The build number (CFBundleVersion)
+ * @param voltraVersion - The installed @use-voltra/ios-client package version
  */
-export function generateInfoPlist(targetPath: string, targetName: string, version: string, buildNumber: string): void {
+export function generateInfoPlist(
+  targetPath: string,
+  targetName: string,
+  version: string,
+  buildNumber: string,
+  voltraVersion: string
+): void {
   const infoPlistPath = path.join(targetPath, 'Info.plist')
-  fs.writeFileSync(infoPlistPath, generateInfoPlistContent(targetName, version, buildNumber))
+  fs.writeFileSync(infoPlistPath, generateInfoPlistContent(targetName, version, buildNumber, voltraVersion))
   logger.info('Generated Info.plist')
 }

package/expo-plugin/src/ios-widget/files/manifest.ts

@@ -1,17 +1,28 @@
 import * as fs from 'fs'
 import * as path from 'path'
 
-import { type DynamicWidgetManifest, logger, validateWidgetEntry } from '@use-voltra/expo-plugin'
+import {
+  type DynamicLiveActivityManifest,
+  type DynamicWidgetManifest,
+  logger,
+  validateWidgetEntry,
+} from '@use-voltra/expo-plugin'
 
-import type { IOSWidgetConfig } from '../../types'
+import type { IOSDynamicLiveActivityConfig, IOSWidgetConfig } from '../../types'
 
 const MANIFEST_PATH = path.join('.voltra', 'manifest.ios.json')
+const LIVE_ACTIVITIES_MANIFEST_PATH = path.join('.voltra', 'manifest.ios.live-activities.json')
 
 export interface GenerateIOSDynamicWidgetsManifestOptions {
   projectRoot: string
   widgets?: IOSWidgetConfig[]
 }
 
+export interface GenerateIOSDynamicLiveActivitiesManifestOptions {
+  projectRoot: string
+  liveActivities?: IOSDynamicLiveActivityConfig[]
+}
+
 export function createIOSDynamicWidgetsManifest(
   projectRoot: string,
   widgets: IOSWidgetConfig[]
@@ -36,6 +47,22 @@ export function createIOSDynamicWidgetsManifest(
   }
 }
 
+export function createIOSDynamicLiveActivitiesManifest(
+  projectRoot: string,
+  liveActivities: IOSDynamicLiveActivityConfig[]
+): DynamicLiveActivityManifest {
+  return {
+    version: 1,
+    platform: 'ios',
+    liveActivities: [...liveActivities]
+      .sort((left, right) => left.id.localeCompare(right.id))
+      .map((liveActivity) => ({
+        id: liveActivity.id,
+        entry: validateWidgetEntry(liveActivity.entry, liveActivity.id, projectRoot),
+      })),
+  }
+}
+
 export function generateIOSDynamicWidgetsManifest(options: GenerateIOSDynamicWidgetsManifestOptions): void {
   const { projectRoot, widgets } = options
   const manifestPath = path.join(projectRoot, MANIFEST_PATH)
@@ -45,3 +72,16 @@ export function generateIOSDynamicWidgetsManifest(options: GenerateIOSDynamicWid
   fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
   logger.info(`Generated ${MANIFEST_PATH}`)
 }
+
+/** Writes the dedicated Dynamic Live Activity manifest on every prebuild, including when empty. */
+export function generateIOSDynamicLiveActivitiesManifest(
+  options: GenerateIOSDynamicLiveActivitiesManifestOptions
+): void {
+  const { projectRoot, liveActivities } = options
+  const manifestPath = path.join(projectRoot, LIVE_ACTIVITIES_MANIFEST_PATH)
+  const manifest = createIOSDynamicLiveActivitiesManifest(projectRoot, liveActivities ?? [])
+
+  fs.mkdirSync(path.dirname(manifestPath), { recursive: true })
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+  logger.info(`Generated ${LIVE_ACTIVITIES_MANIFEST_PATH}`)
+}

package/expo-plugin/src/ios-widget/files/swift-utils.ts

@@ -0,0 +1,3 @@
+export function escapeForSwiftStringLiteral(value: string): string {
+  return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\r/g, '\\r')
+}