voltra 2.2.0 → 2.3.1

package/src/platforms/ios/buildConfigurationValues.ts

@@ -0,0 +1,105 @@
+import { getValuesByBuildConfiguration, isPerConfigurationMap } from '../../config/perConfiguration'
+import { VoltraCliError } from '../../reporting/summary'
+
+import type { PerConfiguration } from '../../config/perConfiguration'
+import type { NormalizedVoltraIOSConfig, ResolvedVoltraIOSConfig } from '../../config/types'
+import type { IOSProjectDiscovery } from '../../discovery/ios'
+
+/**
+ * Prefix of the user-defined build settings Voltra writes. Settings under it are Voltra's to add
+ * and remove, so a value that stops being per build configuration leaves nothing behind.
+ */
+export const VOLTRA_BUILD_SETTING_PREFIX = 'VOLTRA_'
+
+const APP_GROUP_IDENTIFIER_SETTING = `${VOLTRA_BUILD_SETTING_PREFIX}APP_GROUP_IDENTIFIER`
+const KEYCHAIN_GROUP_SETTING = `${VOLTRA_BUILD_SETTING_PREFIX}KEYCHAIN_GROUP`
+
+/**
+ * The settings Voltra writes and is therefore allowed to remove. Anything else a project happens to
+ * name `VOLTRA_*` belongs to the user and is left alone.
+ */
+export const VOLTRA_OWNED_BUILD_SETTINGS: readonly string[] = [APP_GROUP_IDENTIFIER_SETTING, KEYCHAIN_GROUP_SETTING]
+
+export interface IOSBuildConfigurationValues {
+  /** iOS config with every per-build-configuration value collapsed to a single string. */
+  ios: ResolvedVoltraIOSConfig
+  /** User-defined build settings to write, keyed by build configuration name. */
+  buildSettings: Map<string, Record<string, string>>
+}
+
+export class IOSBuildConfigurationValueError extends VoltraCliError {
+  constructor(message: string) {
+    super(message, 'VOLTRA_IOS_BUILD_CONFIGURATION_VALUE_FAILED')
+    this.name = 'IOSBuildConfigurationValueError'
+  }
+}
+
+/**
+ * Collapses per-build-configuration values into the single strings the platform mutators consume.
+ *
+ * A plain string resolves to itself and writes no build settings. A value given per build
+ * configuration becomes a user-defined build setting holding one value per configuration, and
+ * resolves to a reference to that setting, which Xcode expands per build into the entitlements and
+ * Info.plist files. The app and the generated widget extension both read the value that way, so
+ * nothing downstream has to know which environment is being built.
+ */
+export function resolveIOSBuildConfigurationValues(
+  ios: NormalizedVoltraIOSConfig,
+  discovery: IOSProjectDiscovery
+): IOSBuildConfigurationValues {
+  const buildSettings = new Map<string, Record<string, string>>()
+
+  const resolve = (
+    settingName: string,
+    value: PerConfiguration<string> | undefined,
+    context: string
+  ): string | undefined => {
+    if (!isPerConfigurationMap(value)) {
+      return value
+    }
+
+    const valuesByBuildConfiguration = getValuesByBuildConfiguration(
+      value,
+      discovery.buildConfigurationNames,
+      context,
+      (message) => new IOSBuildConfigurationValueError(message)
+    )
+
+    for (const [buildConfigurationName, configurationValue] of valuesByBuildConfiguration) {
+      const configurationSettings = buildSettings.get(buildConfigurationName) ?? {}
+      configurationSettings[settingName] = configurationValue
+      buildSettings.set(buildConfigurationName, configurationSettings)
+    }
+
+    return `$(${settingName})`
+  }
+
+  return {
+    ios: {
+      ...ios,
+      groupIdentifier: resolve(APP_GROUP_IDENTIFIER_SETTING, ios.groupIdentifier, 'ios.groupIdentifier'),
+      keychainGroup: resolve(KEYCHAIN_GROUP_SETTING, ios.keychainGroup, 'ios.keychainGroup'),
+      project: {
+        ...ios.project,
+        entitlementsPath: resolveEntitlementsPath(ios.project.entitlementsPath, discovery),
+      },
+    },
+    buildSettings,
+  }
+}
+
+/**
+ * The entitlements file of the default build configuration. Unlike a value written into a file, a
+ * per-configuration entitlements path is a build setting of its own, so it is applied to the Xcode
+ * project directly rather than through a reference.
+ */
+function resolveEntitlementsPath(
+  entitlementsPath: PerConfiguration<string> | undefined,
+  discovery: IOSProjectDiscovery
+): string | undefined {
+  if (!isPerConfigurationMap(entitlementsPath)) {
+    return entitlementsPath
+  }
+
+  return discovery.entitlementsPathByConfiguration?.get(discovery.buildConfigurationNames[0])
+}

package/src/platforms/ios/entitlements.ts

@@ -6,7 +6,7 @@ import { buildPlistXml, parsePlistFile } from './plist'
 import { resolveMainAppEntitlementsPath } from './mainAppEntitlements'
 
 import type { IOSProjectDiscovery } from '../../discovery/ios'
-import type { NormalizedVoltraIOSConfig } from '../../config/types'
+import type { ResolvedVoltraIOSConfig } from '../../config/types'
 import type { ReportedChange } from '../../reporting/summary'
 
 interface PreviousVoltraEntitlementValues {
@@ -17,12 +17,12 @@ interface PreviousVoltraEntitlementValues {
 
 export interface EnsureEntitlementsOptions {
   projectRoot: string
-  ios: NormalizedVoltraIOSConfig
+  ios: ResolvedVoltraIOSConfig
   discovery: IOSProjectDiscovery
 }
 
 export interface EnsureEntitlementsResult {
-  change?: ReportedChange
+  changes: ReportedChange[]
 }
 
 export class IOSEntitlementsMutationError extends VoltraCliError {
@@ -34,44 +34,68 @@ export class IOSEntitlementsMutationError extends VoltraCliError {
 
 export async function ensureEntitlements(options: EnsureEntitlementsOptions): Promise<EnsureEntitlementsResult> {
   const { projectRoot, ios, discovery } = options
-  const entitlementsPath = resolveMainAppEntitlementsPath(discovery)
+  const entitlementsPaths = resolveEntitlementsPathsToMutate(ios, discovery)
 
-  if (!discovery.entitlementsPath) {
-    if (!needsEntitlementsMutation(ios)) {
-      return {}
-    }
+  if (entitlementsPaths.length === 0) {
+    return { changes: [] }
   }
 
-  const entitlements: Record<string, unknown> = (await pathExists(entitlementsPath))
-    ? await parsePlistFile(entitlementsPath, 'main app entitlements', createEntitlementsError)
-    : {}
   const previousVoltraValues = await readPreviousVoltraEntitlementValues(discovery.infoPlistPath)
+  const changes: ReportedChange[] = []
+
+  for (const entitlementsPath of entitlementsPaths) {
+    const entitlements: Record<string, unknown> = (await pathExists(entitlementsPath))
+      ? await parsePlistFile(entitlementsPath, 'main app entitlements', createEntitlementsError)
+      : {}
+
+    ensureStringArrayValue(
+      entitlements,
+      'com.apple.security.application-groups',
+      ios.groupIdentifier,
+      previousVoltraValues.appGroupIdentifier
+    )
+    ensureStringArrayValue(
+      entitlements,
+      'keychain-access-groups',
+      ios.keychainGroup,
+      previousVoltraValues.keychainGroup
+    )
+
+    if (ios.enablePushNotifications && entitlements['aps-environment'] === undefined) {
+      entitlements['aps-environment'] = 'development'
+    } else if (
+      !ios.enablePushNotifications &&
+      previousVoltraValues.pushNotificationsEnabled &&
+      entitlements['aps-environment'] === 'development'
+    ) {
+      delete entitlements['aps-environment']
+    }
 
-  ensureStringArrayValue(
-    entitlements,
-    'com.apple.security.application-groups',
-    ios.groupIdentifier,
-    previousVoltraValues.appGroupIdentifier
-  )
-  ensureStringArrayValue(entitlements, 'keychain-access-groups', ios.keychainGroup, previousVoltraValues.keychainGroup)
-
-  if (ios.enablePushNotifications && entitlements['aps-environment'] === undefined) {
-    entitlements['aps-environment'] = 'development'
-  } else if (
-    !ios.enablePushNotifications &&
-    previousVoltraValues.pushNotificationsEnabled &&
-    entitlements['aps-environment'] === 'development'
-  ) {
-    delete entitlements['aps-environment']
+    const nextContent = buildPlistXml(entitlements, createEntitlementsError)
+    const change = await writeEntitlementsIfChanged(projectRoot, entitlementsPath, nextContent)
+
+    if (change) {
+      changes.push(change)
+    }
   }
 
-  const nextContent = buildPlistXml(entitlements, createEntitlementsError)
-  const change = await writeEntitlementsIfChanged(projectRoot, entitlementsPath, nextContent)
+  return { changes }
+}
+
+/**
+ * Every entitlements file the app target references, so each build configuration of a
+ * multi-environment app keeps its own file. Falls back to the standard path when the project
+ * references none and Voltra has values to write.
+ */
+function resolveEntitlementsPathsToMutate(ios: ResolvedVoltraIOSConfig, discovery: IOSProjectDiscovery): string[] {
+  if (discovery.entitlementsPaths.length > 0) {
+    return discovery.entitlementsPaths
+  }
 
-  return { change }
+  return needsEntitlementsMutation(ios) ? [resolveMainAppEntitlementsPath(discovery)] : []
 }
 
-export function needsEntitlementsMutation(ios: NormalizedVoltraIOSConfig): boolean {
+export function needsEntitlementsMutation(ios: ResolvedVoltraIOSConfig): boolean {
   return ios.enablePushNotifications || ios.groupIdentifier !== undefined || ios.keychainGroup !== undefined
 }
 

package/src/platforms/ios/generated.node.test.ts

@@ -0,0 +1,61 @@
+import assert from 'node:assert/strict'
+import { describe, test } from 'node:test'
+
+import { __test__ } from './generated.ts'
+
+import type { DetectedIOSWidget } from './generated.ts'
+
+describe('generateWidgetBundleSwift', () => {
+  test('imports the compiled VoltraRuntime module, not the VoltraWidget pod name', () => {
+    const swift = __test__.generateWidgetBundleSwift([])
+
+    assert.ok(swift.includes('import VoltraRuntime'))
+    assert.ok(!swift.includes('import VoltraWidget'))
+  })
+
+  test('imports VoltraRuntime when widgets are configured too', () => {
+    const widget: DetectedIOSWidget = {
+      id: 'weather',
+      displayName: 'Weather',
+      description: 'Shows weather',
+      supportedFamilies: ['systemSmall'],
+      clientRendered: false,
+    }
+
+    const swift = __test__.generateWidgetBundleSwift([widget])
+
+    assert.ok(swift.includes('import VoltraRuntime'))
+    assert.ok(!swift.includes('import VoltraWidget'))
+  })
+
+  test('defaults the WidgetKit kind to the prefixed widget id', () => {
+    const widget: DetectedIOSWidget = {
+      id: 'weather',
+      displayName: 'Weather',
+      description: 'Shows weather',
+      supportedFamilies: ['systemSmall'],
+      clientRendered: false,
+    }
+
+    const swift = __test__.generateWidgetBundleSwift([widget])
+
+    assert.ok(swift.includes('kind: "Voltra_Widget_weather"'))
+  })
+
+  test('uses the `kind` option as the WidgetKit kind when set', () => {
+    // A widget migrated from a hand-written extension keeps the kind its placed instances use.
+    const widget: DetectedIOSWidget = {
+      id: 'streak',
+      kind: 'StreakWidget',
+      displayName: 'Streak',
+      description: 'Your daily streak',
+      supportedFamilies: ['systemSmall'],
+      clientRendered: false,
+    }
+
+    const swift = __test__.generateWidgetBundleSwift([widget])
+
+    assert.ok(swift.includes('kind: "StreakWidget"'))
+    assert.ok(!swift.includes('Voltra_Widget_streak'))
+  })
+})

package/src/platforms/ios/generated.ts

@@ -3,20 +3,23 @@ import fsPromises from 'node:fs/promises'
 import path from 'node:path'
 import { createRequire } from 'node:module'
 
-import { requirePlatformPackage } from '../../dependencies/platformPackages'
+import { getPlatformClientPackageVersion, requirePlatformPackage } from '../../dependencies/platformPackages'
 import { ensureDirectory, pathExists, readTextFile, writeTextFile } from '../../fs/readWrite'
 import { normalizeRelativePath, toRelativePath } from '../../fs/path'
 import { VoltraCliError } from '../../reporting/summary'
-import { DYNAMIC_WIDGET_BUILD_INFO, evaluateWidgetModuleExports } from '../shared/widgetModule'
+import { createDynamicWidgetBuildInfo, createGeneratedWidgetModuleLoader } from '../shared/widgetModule'
+import { iosWidgetKindOverrides, iosWidgetKind } from '../../config/widgetKind'
 import { buildPlistXml, parsePlistFile } from './plist'
 import { resolveIOSWidgetTargetName } from './targetName'
 
+import type { WidgetModuleLoader } from '@use-voltra/compiler'
+
 import type { IOSProjectDiscovery } from '../../discovery/ios'
 import type {
   IOSWidgetAppIntentParameter,
   IOSWidgetFamily,
   NormalizedIOSWidgetConfig,
-  NormalizedVoltraIOSConfig,
+  ResolvedVoltraIOSConfig,
   WidgetLabel,
 } from '../../config/types'
 import type { ReportedChange } from '../../reporting/summary'
@@ -99,7 +102,7 @@ const GENERATED_INITIAL_STATE_LOCALE_HELPER = `private enum VoltraGeneratedIniti
 
 export interface GenerateIOSFilesOptions {
   projectRoot: string
-  ios: NormalizedVoltraIOSConfig
+  ios: ResolvedVoltraIOSConfig
   discovery: IOSProjectDiscovery
 }
 
@@ -135,7 +138,7 @@ type DynamicWidgetManifest = {
   widgets: Array<{ id: string; entry: string }>
 }
 
-type DetectedIOSWidget =
+export type DetectedIOSWidget =
   | (NormalizedIOSWidgetConfig & { clientRendered: false })
   | (NormalizedIOSWidgetConfig & { entry: string; clientRendered: true; clientSourcePath: string })
 
@@ -152,13 +155,20 @@ function createGeneratedFilesError(message: string): IOSGeneratedFilesError {
 
 export async function generateIOSFiles(options: GenerateIOSFilesOptions): Promise<GenerateIOSFilesResult> {
   const { projectRoot, ios, discovery } = options
+  const voltraVersion = getPlatformClientPackageVersion(projectRoot, 'ios')
   const targetName = resolveIOSWidgetTargetName(ios, discovery)
   const targetPath = path.join(discovery.iosRoot, targetName)
-  const detectedWidgets = detectClientRenderedWidgets(projectRoot, ios.widgets)
   const mainAppMetadata = await readMainAppMetadata(discovery.infoPlistPath)
   const changes: ReportedChange[] = []
-  const warnings: string[] = []
+  const warnings: string[] = [...(await getDivergentMainAppMetadataWarnings(discovery, mainAppMetadata))]
   const generatedFiles = new Set<string>()
+  const widgetModuleLoader = createGeneratedWidgetModuleLoader(
+    projectRoot,
+    'ios',
+    createGeneratedFilesError,
+    (message) => warnings.push(message)
+  )
+  const detectedWidgets = detectClientRenderedWidgets(projectRoot, widgetModuleLoader, ios.widgets)
 
   mergeSingleResult(
     await writeGeneratedTextFile(
@@ -176,7 +186,8 @@ export async function generateIOSFiles(options: GenerateIOSFilesOptions): Promis
     targetName,
     ios,
     mainAppMetadata,
-    detectedWidgets
+    detectedWidgets,
+    voltraVersion
   )
   mergeSingleResult(infoPlistResult, changes, generatedFiles)
 
@@ -189,7 +200,12 @@ export async function generateIOSFiles(options: GenerateIOSFilesOptions): Promis
   const fontsResult = await copyIOSFonts(projectRoot, targetPath, ios.fonts)
   mergeResult(fontsResult, changes, warnings, generatedFiles)
 
-  const initialStatesResult = await generateInitialStatesSwift(projectRoot, detectedWidgets)
+  const initialStatesResult = await generateInitialStatesSwift(
+    projectRoot,
+    widgetModuleLoader,
+    detectedWidgets,
+    voltraVersion
+  )
   mergeSingleResult(
     await writeGeneratedTextFile(
       projectRoot,
@@ -223,15 +239,22 @@ async function generateInfoPlistFile(
   projectRoot: string,
   targetPath: string,
   targetName: string,
-  ios: NormalizedVoltraIOSConfig,
+  ios: ResolvedVoltraIOSConfig,
   mainAppMetadata: MainAppMetadata,
-  widgets: DetectedIOSWidget[]
+  widgets: DetectedIOSWidget[],
+  voltraVersion: string
 ): Promise<GeneratedFileResult> {
   const plistPath = path.join(targetPath, 'Info.plist')
   const fontNames = ios.fonts.map((fontPath) => path.basename(fontPath)).sort()
   const serverWidgets = widgets.filter((widget) => widget.serverUpdate)
   const hasClientRenderedWidget = widgets.some((widget) => widget.clientRendered)
-  const serverUrls = Object.fromEntries(serverWidgets.map((widget) => [widget.id, widget.serverUpdate?.url]))
+  // Keys of the intervals dictionary are the set of server-driven widget ids; a URL appears only
+  // when app.json set one, because it may instead arrive at runtime via setWidgetServerUpdate.
+  const serverUrls = Object.fromEntries(
+    serverWidgets
+      .filter((widget) => widget.serverUpdate?.url !== undefined)
+      .map((widget) => [widget.id, widget.serverUpdate?.url])
+  )
   const serverIntervals = Object.fromEntries(
     serverWidgets.map((widget) => [widget.id, widget.serverUpdate?.intervalMinutes])
   )
@@ -257,6 +280,10 @@ async function generateInfoPlistFile(
       UIAppFonts: fontNames.length > 0 ? fontNames : undefined,
       Voltra_AppGroupIdentifier: ios.groupIdentifier,
       Voltra_KeychainGroup: ios.keychainGroup,
+      Voltra_Version: voltraVersion,
+      // The extension resolves its own kinds too, and Bundle.main there is the extension bundle,
+      // so the map has to be written here as well as into the app's Info.plist.
+      Voltra_WidgetKinds: iosWidgetKindOverrides(widgets),
       Voltra_WidgetServerIntervals: Object.keys(serverIntervals).length > 0 ? serverIntervals : undefined,
       Voltra_WidgetServerRefresh: Object.keys(serverRefresh).length > 0 ? serverRefresh : undefined,
       NSAppTransportSecurity: createWidgetAppTransportSecurity(hasClientRenderedWidget, serverWidgets.length > 0),
@@ -296,7 +323,7 @@ async function generateEntitlementsFile(
   projectRoot: string,
   targetPath: string,
   targetName: string,
-  ios: NormalizedVoltraIOSConfig
+  ios: ResolvedVoltraIOSConfig
 ): Promise<GeneratedFileResult> {
   const entitlementsPath = path.join(targetPath, `${targetName}.entitlements`)
   const entitlements = buildPlistXml(
@@ -418,6 +445,41 @@ async function generateLocalizedWidgetStrings(
   }
 }
 
+/**
+ * The widget extension has a single Info.plist, so its version has to come from one of the app's.
+ * An app whose build configurations disagree on the version would ship an extension that matches
+ * only some of them, which App Store validation rejects, so say so rather than picking silently.
+ */
+async function getDivergentMainAppMetadataWarnings(
+  discovery: IOSProjectDiscovery,
+  mainAppMetadata: MainAppMetadata
+): Promise<string[]> {
+  const warnings: string[] = []
+
+  for (const infoPlistPath of discovery.infoPlistPaths.slice(1)) {
+    const metadata = await readMainAppMetadata(infoPlistPath)
+
+    if (
+      metadata.shortVersionString === mainAppMetadata.shortVersionString &&
+      metadata.buildNumber === mainAppMetadata.buildNumber
+    ) {
+      continue
+    }
+
+    warnings.push(
+      `${toRelativePath(discovery.iosRoot, infoPlistPath)} sets version ${metadata.shortVersionString} (${
+        metadata.buildNumber
+      }) while ${toRelativePath(discovery.iosRoot, discovery.infoPlistPath)} sets ${
+        mainAppMetadata.shortVersionString
+      } (${
+        mainAppMetadata.buildNumber
+      }). The widget extension is generated with the version of the default build configuration. Set ios.project.infoPlistPath to choose a different one.`
+    )
+  }
+
+  return warnings
+}
+
 async function readMainAppMetadata(infoPlistPath: string): Promise<MainAppMetadata> {
   const dict = await parsePlistFile(
     infoPlistPath,
@@ -435,17 +497,22 @@ async function readMainAppMetadata(infoPlistPath: string): Promise<MainAppMetada
   }
 }
 
-async function generateInitialStatesSwift(projectRoot: string, widgets: DetectedIOSWidget[]): Promise<string> {
+async function generateInitialStatesSwift(
+  projectRoot: string,
+  loader: WidgetModuleLoader,
+  widgets: DetectedIOSWidget[],
+  voltraVersion: string
+): Promise<string> {
   const serverWidgets = widgets.filter(
     (widget): widget is Extract<DetectedIOSWidget, { clientRendered: false }> => !widget.clientRendered
   )
   const prerenderableServerWidgets = serverWidgets.filter((widget) => widget.initialStatePath)
   const serverStates = await prerenderWidgetStates(
-    projectRoot,
+    loader,
     prerenderableServerWidgets,
     loadIOSWidgetRenderer(projectRoot)
   )
-  const clientStates = await prerenderClientRenderedWidgets(projectRoot, widgets)
+  const clientStates = await prerenderClientRenderedWidgets(projectRoot, loader, widgets, voltraVersion)
   const prerenderedStates = new Map([...serverStates, ...clientStates])
 
   if (prerenderedStates.size === 0) {
@@ -519,7 +586,7 @@ function generateWidgetBundleSwift(widgets: DetectedIOSWidget[]): string {
     appIntentWidgets.length > 0 ? 'import AppIntents' : undefined,
     'import SwiftUI',
     'import WidgetKit',
-    'import VoltraWidget',
+    'import VoltraRuntime',
   ]
     .filter((value): value is string => value !== undefined)
     .join('\n')
@@ -585,9 +652,14 @@ function generateWidgetStruct(widget: DetectedIOSWidget): string {
   const familiesSwift = widget.supportedFamilies.map((family) => IOS_WIDGET_FAMILY_MAP[family]).join(', ')
   const displayNameExpr = createSwiftLabelExpression(widget.id, 'displayName', widget.displayName)
   const descriptionExpr = createSwiftLabelExpression(widget.id, 'description', widget.description)
+  // `entry` picks the render engine and `serverUpdate` picks where the data comes from, so the two
+  // keys together select one of four providers. Runtime code never asks "is this server-driven?" —
+  // the answer is baked in here, once, at generate time.
   const providerAndContent = widget.clientRendered
     ? [
-        '      provider: VoltraClientWidgetProvider(',
+        `      provider: ${
+          widget.serverUpdate ? 'VoltraDynamicWidgetServerUpdateProvider' : 'VoltraClientWidgetProvider'
+        }(`,
         '        widgetId: widgetId,',
         '        initialState: VoltraWidgetInitialStates.getInitialState(for: widgetId)',
         '      )',
@@ -614,7 +686,7 @@ function generateWidgetStruct(widget: DetectedIOSWidget): string {
     '',
     '  public var body: some WidgetConfiguration {',
     '    StaticConfiguration(',
-    `      kind: ${JSON.stringify(`Voltra_Widget_${widget.id}`)},`,
+    `      kind: ${JSON.stringify(iosWidgetKind(widget))},`,
     providerAndContent,
     '    }',
     `    .configurationDisplayName(${displayNameExpr})`,
@@ -664,6 +736,22 @@ function generateClientAppIntentWidgetCode(
   const defaultDictionary = createSwiftDictionaryLiteral(
     widget.appIntent.parameters.map((parameter) => `${JSON.stringify(parameter.name)}: ${swiftDefaultValue(parameter)}`)
   )
+  // A server-driven Dynamic Widget fetches on every timeline request and schedules the next one
+  // from its resolved interval; a plain one has nothing to ask again for, so its policy is .never.
+  const timelineBody = widget.serverUpdate
+    ? [
+        '    return await VoltraDynamicWidgetServerUpdateProvider.timeline(',
+        '      widgetId: widgetId,',
+        '      family: context.family,',
+        `      configuration: ${configuredDictionary}`,
+        '    )',
+        '  }',
+      ]
+    : [
+        `    let entry = await VoltraClientWidgetProvider.loadEntry(widgetId: widgetId, configuration: ${configuredDictionary})`,
+        '    return Timeline(entries: [entry], policy: .never)',
+        '  }',
+      ]
 
   return [
     `@available(iOS 17.0, *)`,
@@ -693,10 +781,8 @@ function generateClientAppIntentWidgetCode(
     `    await VoltraClientWidgetProvider.loadEntry(widgetId: widgetId, configuration: ${configuredDictionary})`,
     '  }',
     '',
-    `  func timeline(for configuration: ${intentName}, in _: Context) async -> Timeline<VoltraClientWidgetEntry> {`,
-    `    let entry = await VoltraClientWidgetProvider.loadEntry(widgetId: widgetId, configuration: ${configuredDictionary})`,
-    '    return Timeline(entries: [entry], policy: .never)',
-    '  }',
+    `  func timeline(for configuration: ${intentName}, in context: Context) async -> Timeline<VoltraClientWidgetEntry> {`,
+    ...timelineBody,
     '}',
     '',
     `@available(iOS 17.0, *)`,
@@ -707,7 +793,7 @@ function generateClientAppIntentWidgetCode(
     '',
     '  public var body: some WidgetConfiguration {',
     '    AppIntentConfiguration(',
-    `      kind: ${JSON.stringify(`Voltra_Widget_${widget.id}`)},`,
+    `      kind: ${JSON.stringify(iosWidgetKind(widget))},`,
     `      intent: ${intentName}.self,`,
     `      provider: ${providerName}()`,
     '    ) { entry in',
@@ -751,7 +837,7 @@ function createSwiftDictionaryLiteral(entries: string[]): string {
 }
 
 async function prerenderWidgetStates(
-  projectRoot: string,
+  loader: WidgetModuleLoader,
   widgets: NormalizedIOSWidgetConfig[],
   renderer: IOSWidgetRenderer
 ): Promise<PrerenderedWidgetStates> {
@@ -773,7 +859,7 @@ async function prerenderWidgetStates(
         throw new IOSGeneratedFilesError(`Initial state file not found for widget '${widget.id}' at ${modulePath}`)
       }
 
-      const widgetVariants = evaluateLegacyWidgetModule(projectRoot, modulePath)
+      const widgetVariants = evaluateLegacyWidgetModule(loader, modulePath)
       localeStates.set(localeKey, renderer(widgetVariants))
     }
 
@@ -783,9 +869,8 @@ async function prerenderWidgetStates(
   return prerenderedStates
 }
 
-function evaluateLegacyWidgetModule(projectRoot: string, filePath: string): WidgetVariants {
-  const exports = evaluateWidgetModuleExports(projectRoot, filePath, createGeneratedFilesError) as { default?: unknown }
-  const widgetVariants = exports.default ?? exports
+function evaluateLegacyWidgetModule(loader: WidgetModuleLoader, filePath: string): WidgetVariants {
+  const widgetVariants = loader.loadDefaultExport(filePath)
 
   if (!widgetVariants || typeof widgetVariants !== 'object') {
     throw new IOSGeneratedFilesError(`Widget file must export widget variants: ${filePath}`)
@@ -827,11 +912,19 @@ function createDynamicWidgetsManifest(widgets: DetectedIOSWidget[]): DynamicWidg
   }
 }
 
-function detectClientRenderedWidgets(projectRoot: string, widgets: NormalizedIOSWidgetConfig[]): DetectedIOSWidget[] {
-  return widgets.map((widget) => detectSingleWidget(projectRoot, widget))
+function detectClientRenderedWidgets(
+  projectRoot: string,
+  loader: WidgetModuleLoader,
+  widgets: NormalizedIOSWidgetConfig[]
+): DetectedIOSWidget[] {
+  return widgets.map((widget) => detectSingleWidget(projectRoot, loader, widget))
 }
 
-function detectSingleWidget(projectRoot: string, widget: NormalizedIOSWidgetConfig): DetectedIOSWidget {
+function detectSingleWidget(
+  projectRoot: string,
+  loader: WidgetModuleLoader,
+  widget: NormalizedIOSWidgetConfig
+): DetectedIOSWidget {
   if (!widget.entry) {
     return {
       ...widget,
@@ -845,7 +938,7 @@ function detectSingleWidget(projectRoot: string, widget: NormalizedIOSWidgetConf
     throw createGeneratedFilesError(`[voltra] Dynamic Widget "${widget.id}" entry not found at ${widget.entry}`)
   }
 
-  const widgetModule = safelyEvaluateDynamicWidget(projectRoot, widget.id, widget.entry, clientSourcePath)
+  const widgetModule = safelyEvaluateDynamicWidget(loader, widget.id, widget.entry, clientSourcePath)
   const widgetFn = readDynamicWidgetExport(widget.id, widget.entry, widgetModule)
 
   if (typeof widgetFn !== 'function') {
@@ -864,7 +957,9 @@ function detectSingleWidget(projectRoot: string, widget: NormalizedIOSWidgetConf
 
 async function prerenderClientRenderedWidgets(
   projectRoot: string,
-  widgets: DetectedIOSWidget[]
+  loader: WidgetModuleLoader,
+  widgets: DetectedIOSWidget[],
+  voltraVersion: string
 ): Promise<PrerenderedWidgetStates> {
   const clientWidgets = widgets.filter(
     (widget): widget is Extract<DetectedIOSWidget, { clientRendered: true }> => widget.clientRendered
@@ -883,13 +978,13 @@ async function prerenderClientRenderedWidgets(
     widgetRenderingMode: 'fullColor',
     showsWidgetContainerBackground: true,
     configuration: undefined,
-    build: DYNAMIC_WIDGET_BUILD_INFO,
+    build: createDynamicWidgetBuildInfo(voltraVersion),
   }
   const prerenderedStates: PrerenderedWidgetStates = new Map()
 
   for (const widget of clientWidgets) {
     try {
-      const widgetModule = safelyEvaluateDynamicWidget(projectRoot, widget.id, widget.entry, widget.clientSourcePath)
+      const widgetModule = safelyEvaluateDynamicWidget(loader, widget.id, widget.entry, widget.clientSourcePath)
       const widgetFn = readDynamicWidgetExport(widget.id, widget.entry, widgetModule)
       const element = widgetFn({}, placeholderEnv)
       prerenderedStates.set(widget.id, new Map([[DEFAULT_INITIAL_STATE_LOCALE, JSON.stringify(renderer(element))]]))
@@ -910,13 +1005,13 @@ async function prerenderClientRenderedWidgets(
 }
 
 function safelyEvaluateDynamicWidget(
-  projectRoot: string,
+  loader: WidgetModuleLoader,
   widgetId: string,
   widgetEntry: string,
   clientSourcePath: string
 ): unknown {
   try {
-    return evaluateWidgetModuleExports(projectRoot, clientSourcePath, createGeneratedFilesError)
+    return loader.load(clientSourcePath)
   } catch (error) {
     if (error instanceof IOSGeneratedFilesError) {
       throw error
@@ -1231,3 +1326,7 @@ function mergeSingleResult(result: GeneratedFileResult, changes: ReportedChange[
 
   generatedFiles.add(normalizeRelativePath(result.relativePath))
 }
+
+export const __test__ = {
+  generateWidgetBundleSwift,
+}