voltra 2.2.0 → 2.3.1

package/src/discovery/metro.ts

@@ -0,0 +1,54 @@
+import { createRequire } from 'node:module'
+import path from 'node:path'
+
+import type { NormalizedVoltraConfig } from '../config/types'
+
+/**
+ * A Dynamic Widget renders on device from a per-widget JS bundle that `@use-voltra/metro` produces:
+ * the dev server serves it at `/voltra/widgets/<id>.bundle`, and the release bundler reads the same
+ * registry. Without the package there is no bundle, and the widget silently draws its prerendered
+ * `initialStatePath` forever while its server updates keep fetching — a failure that otherwise shows
+ * up only as one `Log.w` line in logcat.
+ *
+ * Resolution from the project root is the same signal the generated Xcode build phase and Gradle
+ * task already use (`platforms/ios/xcodeTarget.ts`, `platforms/android/gradle.ts`), so a project
+ * that passes here is a project whose release bundling can run.
+ *
+ * This deliberately does not try to decide whether the app's Metro config is *wired up* — whether
+ * `withVoltra` wraps it. That cannot be read off the config source without warning at correct
+ * projects: a config that delegates to a shared preset (`module.exports =
+ * require('@myorg/metro-config')(__dirname)`) applies the wrapper somewhere this cannot see, and a
+ * config hand-composed from `createVoltraMiddleware` and `createWidgetRegistry` never names
+ * `withVoltra` at all. A warning that fires on a working setup costs more than the one it catches.
+ */
+export function findMissingMetroPackageWarning(config: NormalizedVoltraConfig): string | undefined {
+  if (!hasDynamicWidget(config)) {
+    return undefined
+  }
+
+  if (canResolveVoltraMetro(config.projectRoot)) {
+    return undefined
+  }
+
+  return (
+    `This project declares a widget with an 'entry', but '@use-voltra/metro' cannot be resolved from ` +
+    `${config.projectRoot}. Dynamic Widgets render from a bundle only that package produces, so they ` +
+    `will keep showing their prerendered initial state. Install '@use-voltra/metro' and wrap the app's ` +
+    `Metro config: module.exports = withVoltra(config).`
+  )
+}
+
+function hasDynamicWidget(config: NormalizedVoltraConfig): boolean {
+  const widgets = [...(config.android?.widgets ?? []), ...(config.ios?.widgets ?? [])]
+
+  return widgets.some((widget) => widget.entry !== undefined)
+}
+
+function canResolveVoltraMetro(projectRoot: string): boolean {
+  try {
+    createRequire(path.join(projectRoot, 'package.json')).resolve('@use-voltra/metro/bundle-widgets')
+    return true
+  } catch {
+    return false
+  }
+}

package/src/index.ts

@@ -117,6 +117,11 @@ export type { GenerateIOSFilesOptions, GenerateIOSFilesResult } from './platform
 export { resolveIOSWidgetTargetName } from './platforms/ios/targetName'
 export { IOSWidgetTargetMutationError, ensureIOSWidgetTarget } from './platforms/ios/xcodeTarget'
 export { applyIOSPlatform, createIOSPreflightRunner } from './platforms/ios/apply'
+export {
+  IOSBuildConfigurationValueError,
+  VOLTRA_BUILD_SETTING_PREFIX,
+  resolveIOSBuildConfigurationValues,
+} from './platforms/ios/buildConfigurationValues'
 export { IOSEntitlementsMutationError, ensureEntitlements } from './platforms/ios/entitlements'
 export type { EnsureEntitlementsOptions, EnsureEntitlementsResult } from './platforms/ios/entitlements'
 export { IOSInfoPlistMutationError, ensureInfoPlist } from './platforms/ios/plist'
@@ -187,6 +192,8 @@ export type {
   NormalizedVoltraAndroidConfig,
   NormalizedVoltraConfig,
   NormalizedVoltraIOSConfig,
+  ResolvedIOSProjectConfig,
+  ResolvedVoltraIOSConfig,
   VoltraAndroidConfig,
   VoltraConfig,
   VoltraIOSConfig,
@@ -195,6 +202,7 @@ export type {
   WidgetLabel,
   WidgetLocalizedValue,
 } from './config/types'
+export type { PerConfiguration } from './config/perConfiguration'
 export type {
   ApplySummary,
   PreflightFailureReport,

package/src/platforms/android/generated.ts

@@ -4,11 +4,14 @@ import path from 'node:path'
 import { createRequire } from 'node:module'
 import { vdConvert } from 'vd-tool'
 
-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 { androidWidgetSizingAttributes, androidWidgetSizingWarnings } from './widgetSizing'
+
+import type { WidgetModuleLoader } from '@use-voltra/compiler'
 
 import type { AndroidProjectDiscovery } from '../../discovery/android'
 import type {
@@ -27,6 +30,7 @@ const LOCALIZED_INITIAL_STATE_KEY = '__voltraLocales'
 const DEFAULT_WIDGET_LOCALE_QUALIFIER = 'en'
 const ANDROID_DYNAMIC_WIDGET_MANIFEST_PATH = path.join('.voltra', 'manifest.android.json')
 const ANDROID_WIDGET_CONFIG_DEFAULTS_PATH = path.join('assets', 'voltra', 'widget_config_defaults.json')
+const ANDROID_WIDGET_SERVER_DEFAULTS_PATH = path.join('assets', 'voltra', 'widget_server_defaults.json')
 
 export interface GenerateAndroidFilesOptions {
   projectRoot: string
@@ -76,11 +80,18 @@ type DetectedAndroidWidget =
 
 export async function generateAndroidFiles(options: GenerateAndroidFilesOptions): Promise<GenerateAndroidFilesResult> {
   const { projectRoot, android, discovery } = options
+  const voltraVersion = getPlatformClientPackageVersion(projectRoot, 'android')
   const resourceRoot = path.join(discovery.appModuleRoot, 'src', 'main')
-  const detectedWidgets = detectClientRenderedWidgets(projectRoot, android.widgets)
   const changes: ReportedChange[] = []
   const warnings: string[] = []
   const generatedFiles = new Set<string>()
+  const widgetModuleLoader = createGeneratedWidgetModuleLoader(
+    projectRoot,
+    'android',
+    createAndroidGeneratedFilesError,
+    (message) => warnings.push(message)
+  )
+  const detectedWidgets = detectClientRenderedWidgets(projectRoot, widgetModuleLoader, android.widgets)
 
   mergeSingleResult(
     await writeGeneratedTextFile(
@@ -104,7 +115,13 @@ export async function generateAndroidFiles(options: GenerateAndroidFilesOptions)
   const fontFiles = await copyAndroidFonts(projectRoot, resourceRoot, android.fonts)
   mergeResult(fontFiles, changes, warnings, generatedFiles)
 
-  const initialStateFiles = await generateAndroidInitialStates(projectRoot, resourceRoot, detectedWidgets)
+  const initialStateFiles = await generateAndroidInitialStates(
+    projectRoot,
+    widgetModuleLoader,
+    resourceRoot,
+    detectedWidgets,
+    voltraVersion
+  )
   mergeResult(initialStateFiles, changes, warnings, generatedFiles)
 
   const configDefaultsResult = await generateAndroidConfigDefaults(projectRoot, resourceRoot, detectedWidgets)
@@ -112,6 +129,11 @@ export async function generateAndroidFiles(options: GenerateAndroidFilesOptions)
     mergeSingleResult(configDefaultsResult, changes, generatedFiles)
   }
 
+  const serverDefaultsResult = await generateAndroidServerDefaults(projectRoot, resourceRoot, detectedWidgets)
+  if (serverDefaultsResult) {
+    mergeSingleResult(serverDefaultsResult, changes, generatedFiles)
+  }
+
   return {
     changes,
     files: [...generatedFiles].sort(),
@@ -216,6 +238,7 @@ async function generateAndroidXmlFiles(
     const widgetInfoResult = await writeGeneratedTextFile(projectRoot, widgetInfoPath, widgetInfoContent)
     pushChange(changes, widgetInfoResult.change)
     generatedFiles.add(widgetInfoResult.relativePath)
+    warnings.push(...androidWidgetSizingWarnings(widget, widget.id))
   }
 
   return {
@@ -408,19 +431,21 @@ async function copyAndroidFonts(
 
 async function generateAndroidInitialStates(
   projectRoot: string,
+  loader: WidgetModuleLoader,
   resourceRoot: string,
-  widgets: DetectedAndroidWidget[]
+  widgets: DetectedAndroidWidget[],
+  voltraVersion: string
 ): Promise<GenerateAndroidFilesResult> {
   const serverWidgets = widgets.filter(
     (widget): widget is Extract<DetectedAndroidWidget, { clientRendered: false }> => !widget.clientRendered
   )
   const prerenderableServerWidgets = serverWidgets.filter((widget) => widget.initialStatePath)
   const serverStates = await prerenderWidgetStates(
-    projectRoot,
+    loader,
     prerenderableServerWidgets,
     loadAndroidWidgetRenderer(projectRoot)
   )
-  const clientStates = await prerenderClientRenderedAndroidWidgets(projectRoot, widgets)
+  const clientStates = await prerenderClientRenderedAndroidWidgets(projectRoot, loader, widgets, voltraVersion)
   const prerenderedStates = new Map([...serverStates, ...clientStates])
 
   if (prerenderedStates.size === 0) {
@@ -443,7 +468,7 @@ async function generateAndroidInitialStates(
 }
 
 async function prerenderWidgetStates(
-  projectRoot: string,
+  loader: WidgetModuleLoader,
   widgets: NormalizedAndroidWidgetConfig[],
   renderer: AndroidWidgetRenderer
 ): Promise<PrerenderedWidgetStates> {
@@ -468,7 +493,7 @@ async function prerenderWidgetStates(
         throw new AndroidGeneratedFilesError(`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))
     }
 
@@ -478,11 +503,8 @@ async function prerenderWidgetStates(
   return prerenderedStates
 }
 
-function evaluateLegacyWidgetModule(projectRoot: string, filePath: string): AndroidWidgetVariants {
-  const exports = evaluateWidgetModuleExports(projectRoot, filePath, createAndroidGeneratedFilesError) as {
-    default?: unknown
-  }
-  const widgetVariants = exports.default ?? exports
+function evaluateLegacyWidgetModule(loader: WidgetModuleLoader, filePath: string): AndroidWidgetVariants {
+  const widgetVariants = loader.loadDefaultExport(filePath)
 
   if (!widgetVariants || typeof widgetVariants !== 'object') {
     throw new AndroidGeneratedFilesError(`Widget file must export widget variants: ${filePath}`)
@@ -530,12 +552,17 @@ function createDynamicWidgetsManifest(widgets: DetectedAndroidWidget[]): Dynamic
 
 function detectClientRenderedWidgets(
   projectRoot: string,
+  loader: WidgetModuleLoader,
   widgets: NormalizedAndroidWidgetConfig[]
 ): DetectedAndroidWidget[] {
-  return widgets.map((widget) => detectSingleWidget(projectRoot, widget))
+  return widgets.map((widget) => detectSingleWidget(projectRoot, loader, widget))
 }
 
-function detectSingleWidget(projectRoot: string, widget: NormalizedAndroidWidgetConfig): DetectedAndroidWidget {
+function detectSingleWidget(
+  projectRoot: string,
+  loader: WidgetModuleLoader,
+  widget: NormalizedAndroidWidgetConfig
+): DetectedAndroidWidget {
   if (!widget.entry) {
     return {
       ...widget,
@@ -549,7 +576,7 @@ function detectSingleWidget(projectRoot: string, widget: NormalizedAndroidWidget
     throw createAndroidGeneratedFilesError(`[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') {
@@ -568,7 +595,9 @@ function detectSingleWidget(projectRoot: string, widget: NormalizedAndroidWidget
 
 async function prerenderClientRenderedAndroidWidgets(
   projectRoot: string,
-  widgets: DetectedAndroidWidget[]
+  loader: WidgetModuleLoader,
+  widgets: DetectedAndroidWidget[],
+  voltraVersion: string
 ): Promise<PrerenderedWidgetStates> {
   const clientWidgets = widgets.filter(
     (widget): widget is Extract<DetectedAndroidWidget, { clientRendered: true }> => widget.clientRendered
@@ -585,13 +614,13 @@ async function prerenderClientRenderedAndroidWidgets(
     colorScheme: 'light',
     locale: 'en-US',
     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))]]))
@@ -612,13 +641,13 @@ async function prerenderClientRenderedAndroidWidgets(
 }
 
 function safelyEvaluateDynamicWidget(
-  projectRoot: string,
+  loader: WidgetModuleLoader,
   widgetId: string,
   widgetEntry: string,
   clientSourcePath: string
 ): unknown {
   try {
-    return evaluateWidgetModuleExports(projectRoot, clientSourcePath, createAndroidGeneratedFilesError)
+    return loader.load(clientSourcePath)
   } catch (error) {
     if (error instanceof AndroidGeneratedFilesError) {
       throw error
@@ -670,6 +699,59 @@ async function generateAndroidConfigDefaults(
   )
 }
 
+/**
+ * Emits the build-time `serverUpdate` defaults the runtime settings resolver reads as its lowest
+ * layer.
+ *
+ * These used to be Kotlin literals inside each generated receiver. They live in an asset now
+ * because the app can override the URL and the interval with `setWidgetServerUpdate`, and a
+ * receiver compiled at build time cannot be asked what the interval is today.
+ *
+ * A widget id present in this file is server-driven. `url` is omitted when app.json declared
+ * `serverUpdate` without one, which means the app supplies it at runtime.
+ */
+async function generateAndroidServerDefaults(
+  projectRoot: string,
+  resourceRoot: string,
+  widgets: DetectedAndroidWidget[]
+): Promise<GeneratedFileResult | undefined> {
+  const defaults = createWidgetServerDefaults(widgets)
+
+  if (Object.keys(defaults).length === 0) {
+    return undefined
+  }
+
+  return writeGeneratedTextFile(
+    projectRoot,
+    path.join(resourceRoot, ANDROID_WIDGET_SERVER_DEFAULTS_PATH),
+    `${JSON.stringify(defaults, null, 2)}\n`
+  )
+}
+
+interface WidgetServerDefaults {
+  url?: string
+  intervalMinutes: number
+  refresh: boolean
+}
+
+function createWidgetServerDefaults(widgets: DetectedAndroidWidget[]): Record<string, WidgetServerDefaults> {
+  const defaults: Record<string, WidgetServerDefaults> = {}
+
+  for (const widget of widgets) {
+    if (!widget.serverUpdate) {
+      continue
+    }
+
+    defaults[widget.id] = {
+      ...(widget.serverUpdate.url !== undefined ? { url: widget.serverUpdate.url } : {}),
+      intervalMinutes: widget.serverUpdate.intervalMinutes,
+      refresh: widget.serverUpdate.refresh,
+    }
+  }
+
+  return defaults
+}
+
 function createWidgetConfigDefaults(widgets: DetectedAndroidWidget[]): WidgetConfigDefaults {
   const defaults: WidgetConfigDefaults = {}
 
@@ -916,15 +998,41 @@ async function getLargeImageWarning(imagePath: string, fileName: string): Promis
   return `Image '${fileName}' is ${stat.size} bytes. Large Android widget images may not display correctly.`
 }
 
+/**
+ * `entry` picks the render engine and `serverUpdate` picks where the data comes from, so the two
+ * keys together select one of four base classes. Runtime code never asks "is this server-driven?" —
+ * the answer is baked in here, once, at generate time.
+ */
 function generateWidgetReceiverContent(widget: DetectedAndroidWidget, packageName: string): string {
   const className = `VoltraWidget_${widget.id}Receiver`
   const labelForComment = widgetLabelEnglish(widget.displayName)
 
+  // A widget with an entry and a serverUpdate renders bundled JS from props fetched in the
+  // background. The scheduling lives in the base class, so the generated receiver stays a name and
+  // an id — the URL and the interval come from widget_server_defaults.json at runtime, where
+  // setWidgetServerUpdate can override them.
+  if (widget.clientRendered && widget.serverUpdate) {
+    return [
+      `package ${packageName}.widget`,
+      '',
+      'import voltra.dynamicwidget.serverupdate.VoltraServerDrivenClientWidgetReceiver',
+      '',
+      '/**',
+      ` * Auto-generated server-driven Dynamic Widget receiver for ${labelForComment}`,
+      ` * Widget ID: ${widget.id}`,
+      ' */',
+      `class ${className} : VoltraServerDrivenClientWidgetReceiver() {`,
+      `    override val widgetId: String = "${widget.id}"`,
+      '}',
+      '',
+    ].join('\n')
+  }
+
   if (widget.clientRendered) {
     return [
       `package ${packageName}.widget`,
       '',
-      'import voltra.widget.VoltraClientWidgetReceiver',
+      'import voltra.dynamicwidget.VoltraClientWidgetReceiver',
       '',
       '/**',
       ` * Auto-generated Dynamic Widget receiver for ${labelForComment}`,
@@ -938,35 +1046,30 @@ function generateWidgetReceiverContent(widget: DetectedAndroidWidget, packageNam
   }
 
   if (widget.serverUpdate) {
-    const refreshEnabled = widget.serverUpdate.refresh === true
-
     return [
       `package ${packageName}.widget`,
       '',
       'import android.appwidget.AppWidgetManager',
       'import android.content.Context',
-      'import voltra.widget.VoltraWidgetReceiver',
-      'import voltra.widget.VoltraWidgetUpdateScheduler',
+      'import kotlinx.coroutines.runBlocking',
+      'import voltra.widget.payload.VoltraPayloadWidgetReceiver',
+      'import voltra.widget.payload.VoltraWidgetUpdateScheduler',
       '',
       '/**',
       ` * Auto-generated widget receiver for ${labelForComment}`,
       ` * Widget ID: ${widget.id}`,
-      ` * Server Update: ${widget.serverUpdate.url} (every ${widget.serverUpdate.intervalMinutes} minutes)`,
-      ` * Refresh Button: ${String(refreshEnabled)}`,
       ' */',
-      `class ${className} : VoltraWidgetReceiver() {`,
+      `class ${className} : VoltraPayloadWidgetReceiver() {`,
       `    override val widgetId: String = "${widget.id}"`,
       '',
       '    override fun onUpdate(context: Context, appWidgetManager: AppWidgetManager, appWidgetIds: IntArray) {',
       '        super.onUpdate(context, appWidgetManager, appWidgetIds)',
       '',
-      '        VoltraWidgetUpdateScheduler.schedulePeriodicUpdate(',
-      '            context = context,',
-      `            widgetId = "${widget.id}",`,
-      `            serverUrl = "${widget.serverUpdate.url}",`,
-      `            intervalMinutes = ${widget.serverUpdate.intervalMinutes}L,`,
-      `            refreshEnabled = ${String(refreshEnabled)}`,
-      '        )',
+      '        // Blocking rather than launching: onReceive must not return before the work is',
+      '        // enqueued, or a widget added while the app is not running loses its schedule.',
+      '        runBlocking {',
+      `            VoltraWidgetUpdateScheduler.schedulePeriodicUpdate(context.applicationContext, "${widget.id}")`,
+      '        }',
       '    }',
       '',
       '    override fun onDeleted(context: Context, appWidgetIds: IntArray) {',
@@ -992,13 +1095,13 @@ function generateWidgetReceiverContent(widget: DetectedAndroidWidget, packageNam
   return [
     `package ${packageName}.widget`,
     '',
-    'import voltra.widget.VoltraWidgetReceiver',
+    'import voltra.widget.payload.VoltraPayloadWidgetReceiver',
     '',
     '/**',
     ` * Auto-generated widget receiver for ${labelForComment}`,
     ` * Widget ID: ${widget.id}`,
     ' */',
-    `class ${className} : VoltraWidgetReceiver() {`,
+    `class ${className} : VoltraPayloadWidgetReceiver() {`,
     `    override val widgetId: String = "${widget.id}"`,
     '}',
     '',
@@ -1010,18 +1113,12 @@ function generateWidgetInfoXml(
   previewImageResourceName?: string,
   previewLayoutResourceName?: string
 ): string {
-  const minWidth = widget.minWidth ?? (widget.minCellWidth !== undefined ? widget.minCellWidth * 70 - 30 : undefined)
-  const minHeight =
-    widget.minHeight ?? (widget.minCellHeight !== undefined ? widget.minCellHeight * 70 - 30 : undefined)
   const resizeMode = widget.resizeMode ?? 'horizontal|vertical'
   const widgetCategory = widget.widgetCategory ?? 'home_screen'
   const lines = [
     '<?xml version="1.0" encoding="utf-8"?>',
-    `<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"${
-      minWidth !== undefined ? ` android:minWidth="${minWidth}dp"` : ''
-    }${minHeight !== undefined ? ` android:minHeight="${minHeight}dp"` : ''}`,
-    `    android:targetCellWidth="${widget.targetCellWidth}"`,
-    `    android:targetCellHeight="${widget.targetCellHeight}"`,
+    '<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"',
+    ...androidWidgetSizingAttributes(widget).map((attribute) => `    ${attribute}`),
     '    android:updatePeriodMillis="0"',
     '    android:initialLayout="@layout/voltra_widget_placeholder"',
     `    android:resizeMode="${resizeMode}"`,

package/src/platforms/android/widgetSizing.ts

@@ -0,0 +1,112 @@
+/**
+ * Android widget sizing.
+ *
+ * Android 12+ (API 31+) places widgets by `targetCellWidth`/`targetCellHeight`, expressed in
+ * launcher grid cells. Android 11 and older ignore those attributes entirely and place widgets by
+ * `minWidth`/`minHeight`, expressed in dp, so a widget has to declare both sets to be placed
+ * correctly everywhere. Voltra widgets build against the host app's `minSdkVersion` — React
+ * Native's template sets 24 — so the pre-Android-12 path is not a legacy edge case.
+ * https://developer.android.com/develop/ui/compose/glance/create-app-widget
+ *
+ * Cell size varies by device, launcher and orientation, so converting cells to dp can only ever be
+ * an approximation. These are the figures Google publishes for a 5x4 handset grid, following the
+ * accompanying guidance to size widths from the portrait table and heights from the landscape
+ * table, because those are the smaller cells on each axis.
+ * https://developer.android.com/develop/ui/views/appwidgets/layouts
+ *
+ * The `voltra` CLI and the `@use-voltra/android-client` Expo plugin generate the same
+ * `appwidget-provider` XML from their own copy of this module; keep the two in sync.
+ */
+
+/** Widget fields that determine the generated `appwidget-provider` sizing attributes. */
+export interface AndroidWidgetSizingInput {
+  targetCellWidth: number
+  targetCellHeight: number
+  minWidth?: number
+  minHeight?: number
+  minCellWidth?: number
+  minCellHeight?: number
+  minResizeWidth?: number
+  minResizeHeight?: number
+  maxResizeWidth?: number
+  maxResizeHeight?: number
+}
+
+/** Resize bounds, in dp, emitted only when set. `maxResize*` is honoured from Android 12 on. */
+const RESIZE_BOUNDS = ['minResizeWidth', 'minResizeHeight', 'maxResizeWidth', 'maxResizeHeight'] as const
+
+function cellsToWidthDp(cells: number): number {
+  return cells * 73 - 16
+}
+
+function cellsToHeightDp(cells: number): number {
+  return cells * 66 - 15
+}
+
+function resolveMinimumSize(widget: AndroidWidgetSizingInput): { minWidth: number; minHeight: number } {
+  return {
+    minWidth: widget.minWidth ?? cellsToWidthDp(widget.minCellWidth ?? widget.targetCellWidth),
+    minHeight: widget.minHeight ?? cellsToHeightDp(widget.minCellHeight ?? widget.targetCellHeight),
+  }
+}
+
+/**
+ * Sizing attributes for a single widget, ordered as in Android's own reference example.
+ *
+ * `minWidth` and `minHeight` are always emitted, so a widget is placed at its intended size on
+ * Android 11 and older: an explicit dp value wins, then the deprecated cell count, then the
+ * target cell count.
+ */
+export function androidWidgetSizingAttributes(widget: AndroidWidgetSizingInput): string[] {
+  const { minWidth, minHeight } = resolveMinimumSize(widget)
+
+  const attributes = [
+    `android:minWidth="${minWidth}dp"`,
+    `android:minHeight="${minHeight}dp"`,
+    `android:targetCellWidth="${widget.targetCellWidth}"`,
+    `android:targetCellHeight="${widget.targetCellHeight}"`,
+  ]
+
+  for (const bound of RESIZE_BOUNDS) {
+    const value = widget[bound]
+    if (value !== undefined) {
+      attributes.push(`android:${bound}="${value}dp"`)
+    }
+  }
+
+  return attributes
+}
+
+/**
+ * Resize bounds Android will silently ignore, described for the developer who set them.
+ *
+ * `minResizeWidth` has no effect when it is greater than `minWidth`, and `maxResizeWidth` has no
+ * effect when it is smaller; likewise for the height pair. This reports rather than throws,
+ * because `minWidth` is usually the approximation derived from the widget's cell count.
+ * https://developer.android.com/reference/android/appwidget/AppWidgetProviderInfo
+ */
+export function androidWidgetSizingWarnings(widget: AndroidWidgetSizingInput, widgetId: string): string[] {
+  const { minWidth, minHeight } = resolveMinimumSize(widget)
+  const warnings: string[] = []
+
+  const report = (bound: string, value: number, relation: string, minimum: string, minimumValue: number): void => {
+    warnings.push(
+      `Widget '${widgetId}': ${bound} (${value}dp) is ${relation} ${minimum} (${minimumValue}dp), so Android ignores it.`
+    )
+  }
+
+  if (widget.minResizeWidth !== undefined && widget.minResizeWidth > minWidth) {
+    report('minResizeWidth', widget.minResizeWidth, 'greater than', 'minWidth', minWidth)
+  }
+  if (widget.minResizeHeight !== undefined && widget.minResizeHeight > minHeight) {
+    report('minResizeHeight', widget.minResizeHeight, 'greater than', 'minHeight', minHeight)
+  }
+  if (widget.maxResizeWidth !== undefined && widget.maxResizeWidth < minWidth) {
+    report('maxResizeWidth', widget.maxResizeWidth, 'smaller than', 'minWidth', minWidth)
+  }
+  if (widget.maxResizeHeight !== undefined && widget.maxResizeHeight < minHeight) {
+    report('maxResizeHeight', widget.maxResizeHeight, 'smaller than', 'minHeight', minHeight)
+  }
+
+  return warnings
+}

package/src/platforms/ios/apply.ts

@@ -2,6 +2,7 @@ import { discoverIOSProject } from '../../discovery/ios'
 import { getMissingPlatformPackageMessage, getMissingPlatformPackages } from '../../dependencies/platformPackages'
 import { VoltraCliError } from '../../reporting/summary'
 
+import { resolveIOSBuildConfigurationValues } from './buildConfigurationValues'
 import { ensureEntitlements } from './entitlements'
 import { generateIOSFiles } from './generated'
 import { ensureInfoPlist } from './plist'
@@ -52,32 +53,36 @@ export async function applyIOSPlatform(context: PlatformApplyContext): Promise<P
   }
 
   const discovery = getIOSDiscovery(context.preflight)
+  // Values given per build configuration are collapsed once, so every mutator below sees a plain
+  // string and the project carries the per-configuration values.
+  const { ios, buildSettings } = resolveIOSBuildConfigurationValues(iosConfig, discovery)
   const generatedResult = await generateIOSFiles({
     projectRoot: context.config.projectRoot,
-    ios: iosConfig,
+    ios,
     discovery,
   })
   const entitlementsResult = await ensureEntitlements({
     projectRoot: context.config.projectRoot,
-    ios: iosConfig,
+    ios,
     discovery,
   })
   const infoPlistResult = await ensureInfoPlist({
     projectRoot: context.config.projectRoot,
-    ios: iosConfig,
+    ios,
     discovery,
   })
   const podfileResult = await ensurePodfileBlock({
     projectRoot: context.config.projectRoot,
-    ios: iosConfig,
+    ios,
     discovery,
   })
   const xcodeTargetResult = await ensureIOSWidgetTarget({
     projectRoot: context.config.projectRoot,
-    ios: iosConfig,
+    ios,
     discovery,
     generatedFiles: generatedResult.files,
     previousGeneratedFiles: context.previousState?.files,
+    buildSettings,
   })
 
   if (generatedResult.targetName !== xcodeTargetResult.targetName) {
@@ -93,11 +98,10 @@ export async function applyIOSPlatform(context: PlatformApplyContext): Promise<P
   }
 
   const changes = [
-    infoPlistResult.change,
-    entitlementsResult.change,
-    podfileResult.change,
-    xcodeTargetResult.change,
-  ].filter(isDefined)
+    ...infoPlistResult.changes,
+    ...entitlementsResult.changes,
+    ...[podfileResult.change, xcodeTargetResult.change].filter(isDefined),
+  ]
 
   return {
     platform: 'ios',
@@ -130,7 +134,13 @@ function isIOSProjectDiscovery(value: unknown): value is IOSProjectDiscovery {
       candidate.podfilePath,
       candidate.mainTargetName,
       candidate.infoPlistPath,
-    ].every((entry) => typeof entry === 'string' && entry.length > 0) && Array.isArray(candidate.mainTargetCandidates)
+    ].every((entry) => typeof entry === 'string' && entry.length > 0) &&
+    [
+      candidate.mainTargetCandidates,
+      candidate.buildConfigurationNames,
+      candidate.infoPlistPaths,
+      candidate.entitlementsPaths,
+    ].every((entry) => Array.isArray(entry))
   )
 }