voltra 2.2.0 → 2.3.0

package/build/types/platforms/ios/plist.d.ts

@@ -1,15 +1,15 @@
 import { VoltraCliError } from '../../reporting/summary';
 import type { IOSProjectDiscovery } from '../../discovery/ios';
-import type { NormalizedVoltraIOSConfig } from '../../config/types';
+import type { ResolvedVoltraIOSConfig } from '../../config/types';
 import type { ReportedChange } from '../../reporting/summary';
 type PlistErrorFactory = (message: string) => Error;
 export interface EnsureInfoPlistOptions {
     projectRoot: string;
-    ios: NormalizedVoltraIOSConfig;
+    ios: ResolvedVoltraIOSConfig;
     discovery: IOSProjectDiscovery;
 }
 export interface EnsureInfoPlistResult {
-    change?: ReportedChange;
+    changes: ReportedChange[];
 }
 export declare class IOSInfoPlistMutationError extends VoltraCliError {
     constructor(message: string);

package/build/types/platforms/ios/plist.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plist.d.ts","sourceRoot":"","sources":["../../../../src/platforms/ios/plist.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAExD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAA;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAa7D,KAAK,iBAAiB,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,KAAK,CAAA;AAEnD,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAA;IACnB,GAAG,EAAE,yBAAyB,CAAA;IAC9B,SAAS,EAAE,mBAAmB,CAAA;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,cAAc,CAAA;CACxB;AAED,qBAAa,yBAA0B,SAAQ,cAAc;gBAC/C,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAmCrG;AAED,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,iBAAiB,GAC7B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAuBlC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,iBAAiB,GAAG,MAAM,CAiBpF"}
+{"version":3,"file":"plist.d.ts","sourceRoot":"","sources":["../../../../src/platforms/ios/plist.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAExD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAA;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAa7D,KAAK,iBAAiB,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,KAAK,CAAA;AAEnD,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,MAAM,CAAA;IACnB,GAAG,EAAE,uBAAuB,CAAA;IAC5B,SAAS,EAAE,mBAAmB,CAAA;CAC/B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,cAAc,EAAE,CAAA;CAC1B;AAED,qBAAa,yBAA0B,SAAQ,cAAc;gBAC/C,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAsB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAcrG;AAmDD,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,iBAAiB,GAC7B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAuBlC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,iBAAiB,GAAG,MAAM,CAiBpF"}

package/build/types/platforms/ios/podfile.d.ts

@@ -1,10 +1,10 @@
 import { VoltraCliError } from '../../reporting/summary';
 import type { IOSProjectDiscovery } from '../../discovery/ios';
-import type { NormalizedVoltraIOSConfig } from '../../config/types';
+import type { ResolvedVoltraIOSConfig } from '../../config/types';
 import type { ReportedChange } from '../../reporting/summary';
 export interface EnsurePodfileBlockOptions {
     projectRoot: string;
-    ios: NormalizedVoltraIOSConfig;
+    ios: ResolvedVoltraIOSConfig;
     discovery: IOSProjectDiscovery;
 }
 export interface EnsurePodfileBlockResult {

package/build/types/platforms/ios/podfile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"podfile.d.ts","sourceRoot":"","sources":["../../../../src/platforms/ios/podfile.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAIxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAA;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAO7D,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,MAAM,CAAA;IACnB,GAAG,EAAE,yBAAyB,CAAA;IAC9B,SAAS,EAAE,mBAAmB,CAAA;CAC/B;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,qBAAa,uBAAwB,SAAQ,cAAc;gBAC7C,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAsB9G"}
+{"version":3,"file":"podfile.d.ts","sourceRoot":"","sources":["../../../../src/platforms/ios/podfile.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAIxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAA;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAO7D,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,MAAM,CAAA;IACnB,GAAG,EAAE,uBAAuB,CAAA;IAC5B,SAAS,EAAE,mBAAmB,CAAA;CAC/B;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,qBAAa,uBAAwB,SAAQ,cAAc;gBAC7C,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAsB9G"}

package/build/types/platforms/ios/targetName.d.ts

@@ -1,4 +1,4 @@
 import type { IOSProjectDiscovery } from '../../discovery/ios';
-import type { NormalizedVoltraIOSConfig } from '../../config/types';
-export declare function resolveIOSWidgetTargetName(ios: NormalizedVoltraIOSConfig, discovery: IOSProjectDiscovery): string;
+import type { ResolvedVoltraIOSConfig } from '../../config/types';
+export declare function resolveIOSWidgetTargetName(ios: ResolvedVoltraIOSConfig, discovery: IOSProjectDiscovery): string;
 //# sourceMappingURL=targetName.d.ts.map

package/build/types/platforms/ios/targetName.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"targetName.d.ts","sourceRoot":"","sources":["../../../../src/platforms/ios/targetName.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAA;AAEnE,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,yBAAyB,EAAE,SAAS,EAAE,mBAAmB,GAAG,MAAM,CAOjH"}
+{"version":3,"file":"targetName.d.ts","sourceRoot":"","sources":["../../../../src/platforms/ios/targetName.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAA;AAEjE,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,uBAAuB,EAAE,SAAS,EAAE,mBAAmB,GAAG,MAAM,CAO/G"}

package/build/types/platforms/ios/xcodeTarget.d.ts

@@ -1,13 +1,15 @@
 import { VoltraCliError } from '../../reporting/summary';
 import type { IOSProjectDiscovery } from '../../discovery/ios';
-import type { NormalizedVoltraIOSConfig } from '../../config/types';
+import type { ResolvedVoltraIOSConfig } from '../../config/types';
 import type { ReportedChange } from '../../reporting/summary';
 export interface EnsureIOSWidgetTargetOptions {
     projectRoot: string;
-    ios: NormalizedVoltraIOSConfig;
+    ios: ResolvedVoltraIOSConfig;
     discovery: IOSProjectDiscovery;
     generatedFiles: string[];
     previousGeneratedFiles?: string[];
+    /** User-defined build settings to write at project level, keyed by build configuration name. */
+    buildSettings?: Map<string, Record<string, string>>;
 }
 export interface EnsureIOSWidgetTargetResult {
     change?: ReportedChange;

package/build/types/platforms/ios/xcodeTarget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"xcodeTarget.d.ts","sourceRoot":"","sources":["../../../../src/platforms/ios/xcodeTarget.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAOxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAA;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AA2D7D,MAAM,WAAW,4BAA4B;IAC3C,WAAW,EAAE,MAAM,CAAA;IACnB,GAAG,EAAE,yBAAyB,CAAA;IAC9B,SAAS,EAAE,mBAAmB,CAAA;IAC9B,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAA;CAClC;AAED,MAAM,WAAW,2BAA2B;IAC1C,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,qBAAa,4BAA6B,SAAQ,cAAc;gBAClD,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,2BAA2B,CAAC,CAkDtC"}
+{"version":3,"file":"xcodeTarget.d.ts","sourceRoot":"","sources":["../../../../src/platforms/ios/xcodeTarget.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAQxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAA;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAgE7D,MAAM,WAAW,4BAA4B;IAC3C,WAAW,EAAE,MAAM,CAAA;IACnB,GAAG,EAAE,uBAAuB,CAAA;IAC5B,SAAS,EAAE,mBAAmB,CAAA;IAC9B,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAA;IACjC,gGAAgG;IAChG,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CACpD;AAED,MAAM,WAAW,2BAA2B;IAC1C,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,qBAAa,4BAA6B,SAAQ,cAAc;gBAClD,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,2BAA2B,CAAC,CAwDtC"}

package/build/types/platforms/shared/widgetModule.d.ts

@@ -1,9 +1,18 @@
+import { type WidgetModuleLoader } from '@use-voltra/compiler';
+import type { VoltraPlatform } from '../../config/types';
 export interface WidgetModuleBuildInfo {
     isDev: false;
     metroUrl: null;
     appVersion: 'unknown';
-    voltraVersion: '1.4.1';
+    voltraVersion: string;
 }
-export declare const DYNAMIC_WIDGET_BUILD_INFO: WidgetModuleBuildInfo;
-export declare function evaluateWidgetModuleExports(projectRoot: string, filePath: string, createError: (message: string) => Error): unknown;
+export declare function createDynamicWidgetBuildInfo(voltraVersion: string): WidgetModuleBuildInfo;
+/**
+ * Loader used by the apply pipeline to evaluate widget source at build time.
+ *
+ * The evaluation rules — which imports are allowed and what they resolve to — live in
+ * `@use-voltra/compiler` so that `voltra apply`, the Expo config plugins, and the Metro
+ * widget bundler all apply the same contract.
+ */
+export declare function createGeneratedWidgetModuleLoader(projectRoot: string, platform: VoltraPlatform, createError: (message: string) => Error, onWarning?: (message: string) => void): WidgetModuleLoader;
 //# sourceMappingURL=widgetModule.d.ts.map

package/build/types/platforms/shared/widgetModule.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"widgetModule.d.ts","sourceRoot":"","sources":["../../../../src/platforms/shared/widgetModule.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,KAAK,CAAA;IACZ,QAAQ,EAAE,IAAI,CAAA;IACd,UAAU,EAAE,SAAS,CAAA;IACrB,aAAa,EAAE,OAAO,CAAA;CACvB;AAED,eAAO,MAAM,yBAAyB,EAAE,qBAKvC,CAAA;AAED,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,KAAK,GACtC,OAAO,CA2CT"}
+{"version":3,"file":"widgetModule.d.ts","sourceRoot":"","sources":["../../../../src/platforms/shared/widgetModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAExF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAExD,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,KAAK,CAAA;IACZ,QAAQ,EAAE,IAAI,CAAA;IACd,UAAU,EAAE,SAAS,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,wBAAgB,4BAA4B,CAAC,aAAa,EAAE,MAAM,GAAG,qBAAqB,CAOzF;AAED;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAC/C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,cAAc,EACxB,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,KAAK,EACvC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GACpC,kBAAkB,CAEpB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voltra",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "CLI for applying Voltra to native React Native projects",
   "main": "build/cjs/index.js",
   "module": "build/esm/index.js",
@@ -40,22 +40,22 @@
   "license": "MIT",
   "homepage": "https://use-voltra.dev",
   "dependencies": {
-    "@babel/core": "^7.27.4",
     "@bacons/xcode": "^1.0.0-alpha.33",
     "@clack/prompts": "^1.0.0-alpha.5",
     "commander": "^12.1.0",
     "cosmiconfig": "^9.0.0",
     "vd-tool": "^4.0.2",
-    "xml2js": "^0.6.2"
+    "xml2js": "^0.6.2",
+    "@use-voltra/compiler": "^2.3.0"
   },
   "devDependencies": {
-    "@types/babel__core": "^7.20.5"
+    "tsx": "^4.19.0"
   },
   "scripts": {
     "build": "node ../../scripts/build-package.mjs packages/cli",
     "clean": "rm -rf build",
     "lint": "oxlint src",
     "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
-    "test": "node --test"
+    "test": "node --import tsx --test"
   }
 }

package/src/apply/index.ts

@@ -108,7 +108,10 @@ export async function runApplyPipeline(options: ApplyOptions, dependencies: Appl
   const deletedChanges = await removeStaleGeneratedFiles(normalizedConfig.projectRoot, stateDiff.staleFiles)
   await saveVoltraState(normalizedConfig.projectRoot, { files: stateDiff.nextFiles })
 
-  const summaryWarnings = platformResults.flatMap((result) => result.warnings ?? []).filter(isDefined)
+  const summaryWarnings = [
+    ...(normalizedConfig.warnings ?? []),
+    ...platformResults.flatMap((result) => result.warnings ?? []),
+  ].filter(isDefined)
   const summaryChanges = [...platformResults.flatMap((result) => result.changes), ...deletedChanges]
 
   await resolvedDependencies.writeSummary({ changes: summaryChanges, warnings: summaryWarnings })

package/src/config/normalize.node.test.ts

@@ -0,0 +1,61 @@
+import assert from 'node:assert/strict'
+import { describe, test } from 'node:test'
+
+import { normalizeVoltraConfig, VoltraConfigNormalizationError } from './normalize.ts'
+
+import type { IOSWidgetConfig } from './types.ts'
+
+function normalizeWidgets(widgets: IOSWidgetConfig[]) {
+  return normalizeVoltraConfig({
+    config: { ios: { widgets } },
+    configDir: process.cwd(),
+  })
+}
+
+const streak: IOSWidgetConfig = { id: 'streak', displayName: 'Streak', description: 'Your daily streak' }
+const weather: IOSWidgetConfig = { id: 'weather', displayName: 'Weather', description: 'Shows weather' }
+
+describe('ios widget kind', () => {
+  test('accepts a custom kind', () => {
+    const config = normalizeWidgets([{ ...streak, kind: 'StreakWidget' }])
+
+    assert.equal(config.ios?.widgets[0]?.kind, 'StreakWidget')
+  })
+
+  test('leaves the kind unset when the config does not pin one', () => {
+    const config = normalizeWidgets([streak])
+
+    assert.equal(config.ios?.widgets[0]?.kind, undefined)
+  })
+
+  test('rejects an empty kind', () => {
+    assert.throws(
+      () => normalizeWidgets([{ ...streak, kind: '' }]),
+      (error: unknown) =>
+        error instanceof VoltraConfigNormalizationError && /ios\.widgets\[streak\]\.kind/.test(error.message)
+    )
+  })
+
+  test('rejects two widgets sharing a kind', () => {
+    assert.throws(
+      () =>
+        normalizeWidgets([
+          { ...streak, kind: 'Widgets' },
+          { ...weather, kind: 'Widgets' },
+        ]),
+      (error: unknown) =>
+        error instanceof VoltraConfigNormalizationError && /Duplicate ios widget kind 'Widgets'/.test(error.message)
+    )
+  })
+
+  test('rejects a custom kind that collides with another widget default kind', () => {
+    // `weather` would answer to `Voltra_Widget_weather` too, so both would fight over the same
+    // placed instances.
+    assert.throws(
+      () => normalizeWidgets([{ ...streak, kind: 'Voltra_Widget_weather' }, weather]),
+      (error: unknown) =>
+        error instanceof VoltraConfigNormalizationError &&
+        /Duplicate ios widget kind 'Voltra_Widget_weather'/.test(error.message)
+    )
+  })
+})

package/src/config/normalize.ts

@@ -2,6 +2,11 @@ import path from 'node:path'
 
 import { resolveFromRoot } from '../fs/path'
 import { CLI_DEFAULTS } from './defaults'
+import { isPerConfigurationMap } from './perConfiguration'
+import { resolveServerUpdateInterval, resolveServerUpdateUrl, validateServerUpdateRefresh } from './serverUpdate'
+import { iosWidgetKind } from './widgetKind'
+
+import type { PerConfiguration } from './perConfiguration'
 
 import type {
   AndroidWidgetAppIntentConfig,
@@ -10,6 +15,7 @@ import type {
   IOSWidgetConfig,
   LoadedVoltraConfig,
   NormalizedAndroidWidgetConfig,
+  NormalizedWidgetServerUpdateConfig,
   NormalizedVoltraAndroidConfig,
   NormalizedVoltraConfig,
   NormalizedVoltraIOSConfig,
@@ -53,6 +59,33 @@ function assertOptionalString(value: unknown, context: string): asserts value is
   }
 }
 
+function assertOptionalPerConfigurationString(
+  value: unknown,
+  context: string
+): asserts value is PerConfiguration<string> | undefined {
+  if (value === undefined || typeof value === 'string') {
+    return
+  }
+
+  if (!isPerConfigurationMap(value as PerConfiguration<unknown>)) {
+    throw new VoltraConfigNormalizationError(
+      `${context} must be a string, or an object of strings keyed by build configuration name`
+    )
+  }
+
+  const entries = Object.entries(value as Record<string, unknown>)
+
+  if (entries.length === 0) {
+    throw new VoltraConfigNormalizationError(`${context} must not be an empty object`)
+  }
+
+  for (const [buildConfigurationName, configurationValue] of entries) {
+    if (typeof configurationValue !== 'string' || !configurationValue.trim()) {
+      throw new VoltraConfigNormalizationError(`${context}.${buildConfigurationName} must be a non-empty string`)
+    }
+  }
+}
+
 function assertOptionalBoolean(value: unknown, context: string): asserts value is boolean | undefined {
   if (value !== undefined && typeof value !== 'boolean') {
     throw new VoltraConfigNormalizationError(`${context} must be a boolean`)
@@ -105,6 +138,26 @@ function resolveOptionalPathFromProjectRoot(projectRoot: string, filePath: strin
   return resolvePathFromProjectRoot(projectRoot, filePath)
 }
 
+function resolveOptionalPerConfigurationPath(
+  projectRoot: string,
+  filePath: PerConfiguration<string> | undefined
+): PerConfiguration<string> | undefined {
+  if (!filePath) {
+    return undefined
+  }
+
+  if (!isPerConfigurationMap(filePath)) {
+    return resolvePathFromProjectRoot(projectRoot, filePath)
+  }
+
+  return Object.fromEntries(
+    Object.entries(filePath).map(([buildConfigurationName, configurationPath]) => [
+      buildConfigurationName,
+      resolvePathFromProjectRoot(projectRoot, configurationPath),
+    ])
+  )
+}
+
 function isAbsoluteWidgetPath(value: string): boolean {
   return path.isAbsolute(value) || path.win32.isAbsolute(value) || /^[a-zA-Z]:[\\/]/.test(value)
 }
@@ -294,42 +347,68 @@ function normalizeIOSAppIntent(
   return { parameters }
 }
 
-function normalizeServerUpdate(
-  serverUpdate: { url: string; intervalMinutes?: number; refresh?: boolean },
-  context: string,
-  defaultIntervalMinutes: number,
-  defaultRefresh: boolean,
+interface NormalizeServerUpdateOptions {
+  context: string
+  /** True when the widget has an `entry`, so the response is props rather than a payload. */
+  hasEntry: boolean
+  defaultIntervalMinutes: number
+  defaultRefresh: boolean
   minimumIntervalMinutes: number
-): { url: string; intervalMinutes: number; refresh: boolean } {
+  warnings: string[]
+}
+
+function normalizeServerUpdate(
+  serverUpdate: { url?: string; intervalMinutes?: number; refresh?: boolean },
+  options: NormalizeServerUpdateOptions
+): NormalizedWidgetServerUpdateConfig {
+  const { context, hasEntry, defaultIntervalMinutes, defaultRefresh, minimumIntervalMinutes, warnings } = options
+
   assertObject(serverUpdate, context)
-  assertNonEmptyString(serverUpdate.url, `${context}.url`)
 
-  if (serverUpdate.intervalMinutes !== undefined) {
-    if (typeof serverUpdate.intervalMinutes !== 'number' || !Number.isFinite(serverUpdate.intervalMinutes)) {
-      throw new VoltraConfigNormalizationError(`${context}.intervalMinutes must be a number`)
-    }
+  const url = resolveServerUpdateUrl(serverUpdate.url, context)
 
-    if (!Number.isInteger(serverUpdate.intervalMinutes)) {
-      throw new VoltraConfigNormalizationError(`${context}.intervalMinutes must be an integer`)
-    }
+  if (url.kind === 'invalid') {
+    throw new VoltraConfigNormalizationError(url.error)
+  }
 
-    if (serverUpdate.intervalMinutes < minimumIntervalMinutes) {
-      throw new VoltraConfigNormalizationError(`${context}.intervalMinutes must be at least ${minimumIntervalMinutes}`)
-    }
+  if (url.kind === 'insecure') {
+    warnings.push(url.warning)
   }
 
-  if (serverUpdate.refresh !== undefined && typeof serverUpdate.refresh !== 'boolean') {
-    throw new VoltraConfigNormalizationError(`${context}.refresh must be a boolean`)
+  const interval = resolveServerUpdateInterval({
+    intervalMinutes: serverUpdate.intervalMinutes,
+    context,
+    hasEntry,
+    defaultIntervalMinutes,
+    minimumIntervalMinutes,
+  })
+
+  if (interval.kind === 'invalid') {
+    throw new VoltraConfigNormalizationError(interval.error)
+  }
+
+  if (interval.kind === 'clamped') {
+    warnings.push(interval.warning)
+  }
+
+  const refreshError = validateServerUpdateRefresh(serverUpdate.refresh, context)
+
+  if (refreshError) {
+    throw new VoltraConfigNormalizationError(refreshError)
   }
 
   return {
     url: serverUpdate.url,
-    intervalMinutes: serverUpdate.intervalMinutes ?? defaultIntervalMinutes,
+    intervalMinutes: interval.intervalMinutes,
     refresh: serverUpdate.refresh ?? defaultRefresh,
   }
 }
 
-function normalizeAndroidWidget(projectRoot: string, widget: AndroidWidgetConfig): NormalizedAndroidWidgetConfig {
+function normalizeAndroidWidget(
+  projectRoot: string,
+  widget: AndroidWidgetConfig,
+  warnings: string[]
+): NormalizedAndroidWidgetConfig {
   assertObject(widget, 'android.widgets[]')
   assertNonEmptyString(widget.id, 'android.widgets[].id')
   assertValidWidgetId(widget.id, 'android.widgets[].id')
@@ -337,6 +416,12 @@ function normalizeAndroidWidget(projectRoot: string, widget: AndroidWidgetConfig
   assertPositiveInteger(widget.targetCellHeight, `android.widgets[${widget.id}].targetCellHeight`)
   assertOptionalPositiveInteger(widget.minCellWidth, `android.widgets[${widget.id}].minCellWidth`)
   assertOptionalPositiveInteger(widget.minCellHeight, `android.widgets[${widget.id}].minCellHeight`)
+  assertOptionalPositiveInteger(widget.minWidth, `android.widgets[${widget.id}].minWidth`)
+  assertOptionalPositiveInteger(widget.minHeight, `android.widgets[${widget.id}].minHeight`)
+  assertOptionalPositiveInteger(widget.minResizeWidth, `android.widgets[${widget.id}].minResizeWidth`)
+  assertOptionalPositiveInteger(widget.minResizeHeight, `android.widgets[${widget.id}].minResizeHeight`)
+  assertOptionalPositiveInteger(widget.maxResizeWidth, `android.widgets[${widget.id}].maxResizeWidth`)
+  assertOptionalPositiveInteger(widget.maxResizeHeight, `android.widgets[${widget.id}].maxResizeHeight`)
 
   return {
     ...widget,
@@ -352,22 +437,31 @@ function normalizeAndroidWidget(projectRoot: string, widget: AndroidWidgetConfig
     previewLayout: resolveOptionalPathFromProjectRoot(projectRoot, widget.previewLayout),
     appIntent: normalizeAndroidAppIntent(widget.appIntent, `android.widgets[${widget.id}].appIntent`),
     serverUpdate: widget.serverUpdate
-      ? normalizeServerUpdate(
-          widget.serverUpdate,
-          `android.widgets[${widget.id}].serverUpdate`,
-          CLI_DEFAULTS.android.serverUpdateIntervalMinutes,
-          CLI_DEFAULTS.android.serverUpdateRefresh,
-          15
-        )
+      ? normalizeServerUpdate(widget.serverUpdate, {
+          context: `android.widgets[${widget.id}].serverUpdate`,
+          hasEntry: widget.entry !== undefined,
+          defaultIntervalMinutes: CLI_DEFAULTS.android.serverUpdateIntervalMinutes,
+          defaultRefresh: CLI_DEFAULTS.android.serverUpdateRefresh,
+          minimumIntervalMinutes: 15,
+          warnings,
+        })
       : undefined,
   }
 }
 
-function normalizeIOSWidget(projectRoot: string, widget: IOSWidgetConfig): NormalizedIOSWidgetConfig {
+function normalizeIOSWidget(
+  projectRoot: string,
+  widget: IOSWidgetConfig,
+  warnings: string[]
+): NormalizedIOSWidgetConfig {
   assertObject(widget, 'ios.widgets[]')
   assertNonEmptyString(widget.id, 'ios.widgets[].id')
   assertValidWidgetId(widget.id, 'ios.widgets[].id')
 
+  if (widget.kind !== undefined) {
+    assertNonEmptyString(widget.kind, `ios.widgets[${widget.id}].kind`)
+  }
+
   if (widget.supportedFamilies !== undefined) {
     if (!Array.isArray(widget.supportedFamilies)) {
       throw new VoltraConfigNormalizationError(`ios.widgets[${widget.id}].supportedFamilies must be an array`)
@@ -395,13 +489,14 @@ function normalizeIOSWidget(projectRoot: string, widget: IOSWidgetConfig): Norma
     ),
     appIntent: normalizeIOSAppIntent(widget.appIntent, `ios.widgets[${widget.id}].appIntent`),
     serverUpdate: widget.serverUpdate
-      ? normalizeServerUpdate(
-          widget.serverUpdate,
-          `ios.widgets[${widget.id}].serverUpdate`,
-          CLI_DEFAULTS.ios.serverUpdateIntervalMinutes,
-          CLI_DEFAULTS.ios.serverUpdateRefresh,
-          1
-        )
+      ? normalizeServerUpdate(widget.serverUpdate, {
+          context: `ios.widgets[${widget.id}].serverUpdate`,
+          hasEntry: widget.entry !== undefined,
+          defaultIntervalMinutes: CLI_DEFAULTS.ios.serverUpdateIntervalMinutes,
+          defaultRefresh: CLI_DEFAULTS.ios.serverUpdateRefresh,
+          minimumIntervalMinutes: 1,
+          warnings,
+        })
       : undefined,
   }
 }
@@ -418,6 +513,25 @@ function assertUniqueWidgetIds(widgetIds: string[], context: string): void {
   }
 }
 
+/**
+ * WidgetKit identifies a placed widget by extension bundle id + kind, so two widgets sharing a kind
+ * would fight over the same Home Screen instances. Compared after defaulting, which also catches a
+ * custom kind that collides with another widget's `Voltra_Widget_<id>`.
+ */
+function assertUniqueIOSWidgetKinds(widgets: Pick<IOSWidgetConfig, 'id' | 'kind'>[]): void {
+  const seen = new Set<string>()
+
+  for (const widget of widgets) {
+    const kind = iosWidgetKind(widget)
+
+    if (seen.has(kind)) {
+      throw new VoltraConfigNormalizationError(`Duplicate ios widget kind '${kind}'`)
+    }
+
+    seen.add(kind)
+  }
+}
+
 function assertValidWidgetId(widgetId: string, context: string): void {
   if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(widgetId)) {
     throw new VoltraConfigNormalizationError(
@@ -435,6 +549,7 @@ function assertValidIOSTargetName(targetName: string, context: string): void {
 }
 
 function normalizeAndroidConfig(
+  warnings: string[],
   projectRoot: string,
   config: LoadedVoltraConfig['config']['android']
 ): NormalizedVoltraAndroidConfig | undefined {
@@ -459,7 +574,7 @@ function normalizeAndroidConfig(
     throw new VoltraConfigNormalizationError('android.widgets must be an array')
   }
 
-  const widgets = (config.widgets ?? []).map((widget) => normalizeAndroidWidget(projectRoot, widget))
+  const widgets = (config.widgets ?? []).map((widget) => normalizeAndroidWidget(projectRoot, widget, warnings))
   assertUniqueWidgetIds(
     widgets.map((widget) => widget.id),
     'android'
@@ -483,6 +598,7 @@ function normalizeAndroidConfig(
 }
 
 function normalizeIOSConfig(
+  warnings: string[],
   projectRoot: string,
   config: LoadedVoltraConfig['config']['ios']
 ): NormalizedVoltraIOSConfig | undefined {
@@ -492,12 +608,12 @@ function normalizeIOSConfig(
 
   assertObject(config, 'ios')
   assertOptionalBoolean(config.enablePushNotifications, 'ios.enablePushNotifications')
-  assertOptionalString(config.groupIdentifier, 'ios.groupIdentifier')
+  assertOptionalPerConfigurationString(config.groupIdentifier, 'ios.groupIdentifier')
   assertOptionalString(config.deploymentTarget, 'ios.deploymentTarget')
   assertOptionalString(config.targetName, 'ios.targetName')
   assertOptionalStringArray(config.fonts, 'ios.fonts')
   assertOptionalString(config.userImagesPath, 'ios.userImagesPath')
-  assertOptionalString(config.keychainGroup, 'ios.keychainGroup')
+  assertOptionalPerConfigurationString(config.keychainGroup, 'ios.keychainGroup')
 
   if (config.project !== undefined) {
     assertObject(config.project, 'ios.project')
@@ -505,7 +621,7 @@ function normalizeIOSConfig(
     assertOptionalString(config.project.xcodeprojPath, 'ios.project.xcodeprojPath')
     assertOptionalString(config.project.mainTargetName, 'ios.project.mainTargetName')
     assertOptionalString(config.project.infoPlistPath, 'ios.project.infoPlistPath')
-    assertOptionalString(config.project.entitlementsPath, 'ios.project.entitlementsPath')
+    assertOptionalPerConfigurationString(config.project.entitlementsPath, 'ios.project.entitlementsPath')
     assertOptionalString(config.project.podfilePath, 'ios.project.podfilePath')
   }
 
@@ -517,11 +633,12 @@ function normalizeIOSConfig(
     assertValidIOSTargetName(config.targetName, 'ios.targetName')
   }
 
-  const widgets = (config.widgets ?? []).map((widget) => normalizeIOSWidget(projectRoot, widget))
+  const widgets = (config.widgets ?? []).map((widget) => normalizeIOSWidget(projectRoot, widget, warnings))
   assertUniqueWidgetIds(
     widgets.map((widget) => widget.id),
     'ios'
   )
+  assertUniqueIOSWidgetKinds(widgets)
 
   return {
     enablePushNotifications: config.enablePushNotifications ?? CLI_DEFAULTS.ios.enablePushNotifications,
@@ -537,7 +654,7 @@ function normalizeIOSConfig(
       xcodeprojPath: resolveOptionalPathFromProjectRoot(projectRoot, config.project?.xcodeprojPath),
       mainTargetName: config.project?.mainTargetName,
       infoPlistPath: resolveOptionalPathFromProjectRoot(projectRoot, config.project?.infoPlistPath),
-      entitlementsPath: resolveOptionalPathFromProjectRoot(projectRoot, config.project?.entitlementsPath),
+      entitlementsPath: resolveOptionalPerConfigurationPath(projectRoot, config.project?.entitlementsPath),
       podfilePath: resolveOptionalPathFromProjectRoot(projectRoot, config.project?.podfilePath),
     },
   }
@@ -552,11 +669,38 @@ export function normalizeVoltraConfig(loadedConfig: LoadedVoltraConfig): Normali
     loadedConfig.config.projectRoot ?? loadedConfig.configDir
   )
 
+  const warnings: string[] = []
+  const android = normalizeAndroidConfig(warnings, projectRoot, loadedConfig.config.android)
+  const ios = normalizeIOSConfig(warnings, projectRoot, loadedConfig.config.ios)
+
+  assertServerDrivenDynamicWidgetsAreSupported(ios)
+
   return {
     configPath: loadedConfig.configPath,
     configDir: loadedConfig.configDir,
     projectRoot,
-    android: normalizeAndroidConfig(projectRoot, loadedConfig.config.android),
-    ios: normalizeIOSConfig(projectRoot, loadedConfig.config.ios),
+    android,
+    ios,
+    warnings,
+  }
+}
+
+/**
+ * A Dynamic Widget commits fetched props to the App Group so the widget extension can read them,
+ * so a server-driven one without a `groupIdentifier` would fetch and have nowhere to put the
+ * result.
+ */
+function assertServerDrivenDynamicWidgetsAreSupported(ios: NormalizedVoltraIOSConfig | undefined): void {
+  if (ios === undefined || ios.groupIdentifier !== undefined) {
+    return
+  }
+
+  for (const widget of ios.widgets) {
+    if (widget.entry !== undefined && widget.serverUpdate !== undefined) {
+      throw new VoltraConfigNormalizationError(
+        `ios.widgets[${widget.id}] has both entry and serverUpdate, which requires ios.groupIdentifier ` +
+          'so fetched props can be shared with the widget extension.'
+      )
+    }
   }
 }

package/src/config/perConfiguration.ts

@@ -0,0 +1,49 @@
+/**
+ * A value that is either shared by every Xcode build configuration, or given once per build
+ * configuration name for apps that ship several environments from the same project.
+ *
+ * ```ts
+ * groupIdentifier: 'group.com.example.app'
+ * groupIdentifier: { Debug: 'group.com.example.app.dev', Release: 'group.com.example.app' }
+ * ```
+ */
+export type PerConfiguration<TValue> = TValue | Record<string, TValue>
+
+export function isPerConfigurationMap<TValue>(
+  value: PerConfiguration<TValue> | undefined
+): value is Record<string, TValue> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Pairs a per-build-configuration value with the project's real build configurations, in the
+ * project's own order. Keys that name no build configuration, and build configurations the value
+ * does not cover, are reported before anything is written to the project.
+ */
+export function getValuesByBuildConfiguration<TValue>(
+  value: Record<string, TValue>,
+  buildConfigurationNames: string[],
+  context: string,
+  createError: (message: string) => Error
+): Map<string, TValue> {
+  const knownNames = `This project has: ${buildConfigurationNames.join(', ')}.`
+  const unknownNames = Object.keys(value).filter((name) => !buildConfigurationNames.includes(name))
+
+  if (unknownNames.length > 0) {
+    throw createError(`${context} names unknown build configurations: ${unknownNames.join(', ')}. ${knownNames}`)
+  }
+
+  const valuesByBuildConfiguration = new Map<string, TValue>()
+
+  for (const buildConfigurationName of buildConfigurationNames) {
+    const configurationValue = value[buildConfigurationName]
+
+    if (configurationValue === undefined) {
+      throw createError(`${context} has no value for build configuration '${buildConfigurationName}'. ${knownNames}`)
+    }
+
+    valuesByBuildConfiguration.set(buildConfigurationName, configurationValue)
+  }
+
+  return valuesByBuildConfiguration
+}