voltra 2.2.0 → 2.3.1

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,90 @@ function normalizeIOSAppIntent(
   return { parameters }
 }
 
-function normalizeServerUpdate(
-  serverUpdate: { url: string; intervalMinutes?: number; refresh?: boolean },
+/**
+ * `appIntent` only reaches the generated project through the `clientRendered` branches, so on a
+ * widget with no `entry` every parameter is dropped: no configuration defaults are emitted, the
+ * receiver stays payload-driven, and `getWidgetConfiguration` rejects it at runtime. Generate time
+ * is the only place that can still say so.
+ */
+function warnOnAppIntentWithoutEntry(
+  appIntent: { parameters: unknown[] } | undefined,
+  hasEntry: boolean,
   context: string,
-  defaultIntervalMinutes: number,
-  defaultRefresh: boolean,
+  warnings: string[]
+): void {
+  if (hasEntry || !appIntent || appIntent.parameters.length === 0) {
+    return
+  }
+
+  warnings.push(
+    `${context}.appIntent is ignored because the widget has no 'entry'. Configuration parameters ` +
+      `only apply to Dynamic Widgets. Add an 'entry' to make this one, or drop 'appIntent'.`
+  )
+}
+
+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)
+  }
+
+  const interval = resolveServerUpdateInterval({
+    intervalMinutes: serverUpdate.intervalMinutes,
+    context,
+    hasEntry,
+    defaultIntervalMinutes,
+    minimumIntervalMinutes,
+  })
+
+  if (interval.kind === 'invalid') {
+    throw new VoltraConfigNormalizationError(interval.error)
   }
 
-  if (serverUpdate.refresh !== undefined && typeof serverUpdate.refresh !== 'boolean') {
-    throw new VoltraConfigNormalizationError(`${context}.refresh must be a boolean`)
+  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 +438,15 @@ 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`)
+
+  const androidAppIntent = normalizeAndroidAppIntent(widget.appIntent, `android.widgets[${widget.id}].appIntent`)
+  warnOnAppIntentWithoutEntry(androidAppIntent, widget.entry !== undefined, `android.widgets[${widget.id}]`, warnings)
 
   return {
     ...widget,
@@ -350,24 +460,33 @@ function normalizeAndroidWidget(projectRoot: string, widget: AndroidWidgetConfig
     ),
     previewImage: resolveOptionalPathFromProjectRoot(projectRoot, widget.previewImage),
     previewLayout: resolveOptionalPathFromProjectRoot(projectRoot, widget.previewLayout),
-    appIntent: normalizeAndroidAppIntent(widget.appIntent, `android.widgets[${widget.id}].appIntent`),
+    appIntent: androidAppIntent,
     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`)
@@ -382,6 +501,9 @@ function normalizeIOSWidget(projectRoot: string, widget: IOSWidgetConfig): Norma
     }
   }
 
+  const iosAppIntent = normalizeIOSAppIntent(widget.appIntent, `ios.widgets[${widget.id}].appIntent`)
+  warnOnAppIntentWithoutEntry(iosAppIntent, widget.entry !== undefined, `ios.widgets[${widget.id}]`, warnings)
+
   return {
     ...widget,
     displayName: normalizeLabel(widget.displayName, `ios.widgets[${widget.id}].displayName`),
@@ -393,15 +515,16 @@ function normalizeIOSWidget(projectRoot: string, widget: IOSWidgetConfig): Norma
       widget.initialStatePath,
       `ios.widgets[${widget.id}].initialStatePath`
     ),
-    appIntent: normalizeIOSAppIntent(widget.appIntent, `ios.widgets[${widget.id}].appIntent`),
+    appIntent: iosAppIntent,
     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 +541,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 +577,7 @@ function assertValidIOSTargetName(targetName: string, context: string): void {
 }
 
 function normalizeAndroidConfig(
+  warnings: string[],
   projectRoot: string,
   config: LoadedVoltraConfig['config']['android']
 ): NormalizedVoltraAndroidConfig | undefined {
@@ -459,7 +602,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 +626,7 @@ function normalizeAndroidConfig(
 }
 
 function normalizeIOSConfig(
+  warnings: string[],
   projectRoot: string,
   config: LoadedVoltraConfig['config']['ios']
 ): NormalizedVoltraIOSConfig | undefined {
@@ -492,12 +636,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 +649,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 +661,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 +682,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 +697,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
+}

package/src/config/serverUpdate.ts

@@ -0,0 +1,160 @@
+/**
+ * Config rules for `serverUpdate`, shared by the Expo plugins and the `voltra` CLI.
+ *
+ * `serverUpdate` marks a widget as server-driven for both render engines. On a widget with
+ * `entry` the device fetches a JSON object and hands it to the bundled JS as props; without
+ * `entry` the server returns a full Voltra payload. Widgets without `entry` keep exactly the
+ * rules they had before ADR 0002, so no existing config breaks.
+ *
+ * `url` is optional. `serverUpdate: {}` means "server-driven, URL supplied at runtime" through
+ * `setWidgetServerUpdate`, which covers per-tenant backends whose URL is only known after login.
+ *
+ * These helpers report problems instead of throwing so each caller can raise its own error type.
+ *
+ * The `@use-voltra/expo-plugin` package holds the other copy of this module, shared by the
+ * Expo config plugins; keep the two in sync.
+ */
+
+/**
+ * Interval floor and default for a widget with `entry`. WorkManager cannot run periodic work
+ * more often than every 15 minutes, and WidgetKit stretches timelines requested closer together
+ * than five minutes, so a smaller number would only mislead.
+ */
+export const DYNAMIC_WIDGET_SERVER_UPDATE_INTERVAL_MINUTES = 15
+
+/** Hosts allowed over plain `http`, for talking to a dev server from a simulator or emulator. */
+const LOCAL_HTTP_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '10.0.2.2', '10.0.3.2'])
+
+/** Outcome of resolving `serverUpdate.intervalMinutes` against a platform's floor. */
+export type ServerUpdateIntervalResolution =
+  | { kind: 'ok'; intervalMinutes: number }
+  | { kind: 'clamped'; intervalMinutes: number; warning: string }
+  | { kind: 'invalid'; error: string }
+
+export interface ResolveServerUpdateIntervalOptions {
+  /** Raw `intervalMinutes` from app.json, if the widget set one. */
+  intervalMinutes: unknown
+  /** Config path used in messages, e.g. `android.widgets[portfolio].serverUpdate`. */
+  context: string
+  /** True when the widget has an `entry` and therefore renders on device. */
+  hasEntry: boolean
+  /** Interval used when the widget does not set one. Ignored for widgets with `entry`. */
+  defaultIntervalMinutes: number
+  /** Platform floor for payload widgets. Ignored for widgets with `entry`. */
+  minimumIntervalMinutes: number
+}
+
+/**
+ * Resolves the interval a widget should be scheduled on.
+ *
+ * A widget with `entry` is clamped up to {@link DYNAMIC_WIDGET_SERVER_UPDATE_INTERVAL_MINUTES}
+ * with a warning, because a shorter interval is not something either platform can honour. A
+ * payload widget keeps the platform's existing rule and is rejected below the floor.
+ */
+export function resolveServerUpdateInterval(
+  options: ResolveServerUpdateIntervalOptions
+): ServerUpdateIntervalResolution {
+  const { intervalMinutes, context, hasEntry, defaultIntervalMinutes, minimumIntervalMinutes } = options
+  const fallback = hasEntry ? DYNAMIC_WIDGET_SERVER_UPDATE_INTERVAL_MINUTES : defaultIntervalMinutes
+
+  if (intervalMinutes === undefined) {
+    return { kind: 'ok', intervalMinutes: fallback }
+  }
+
+  if (typeof intervalMinutes !== 'number' || !Number.isFinite(intervalMinutes)) {
+    return { kind: 'invalid', error: `${context}.intervalMinutes must be a number` }
+  }
+
+  if (!Number.isInteger(intervalMinutes)) {
+    return { kind: 'invalid', error: `${context}.intervalMinutes must be an integer` }
+  }
+
+  if (hasEntry) {
+    if (intervalMinutes < DYNAMIC_WIDGET_SERVER_UPDATE_INTERVAL_MINUTES) {
+      return {
+        kind: 'clamped',
+        intervalMinutes: DYNAMIC_WIDGET_SERVER_UPDATE_INTERVAL_MINUTES,
+        warning:
+          `${context}.intervalMinutes is ${intervalMinutes}, below the ` +
+          `${DYNAMIC_WIDGET_SERVER_UPDATE_INTERVAL_MINUTES} minute floor for widgets with an entry. ` +
+          `Using ${DYNAMIC_WIDGET_SERVER_UPDATE_INTERVAL_MINUTES}.`,
+      }
+    }
+
+    return { kind: 'ok', intervalMinutes }
+  }
+
+  if (intervalMinutes < minimumIntervalMinutes) {
+    return { kind: 'invalid', error: `${context}.intervalMinutes must be at least ${minimumIntervalMinutes}` }
+  }
+
+  return { kind: 'ok', intervalMinutes }
+}
+
+/** Outcome of checking `serverUpdate.url`. */
+export type ServerUpdateUrlResolution =
+  | { kind: 'ok' }
+  | { kind: 'insecure'; warning: string }
+  | { kind: 'invalid'; error: string }
+
+/**
+ * Checks `serverUpdate.url`. An absent URL is fine — the app supplies it at runtime through
+ * `setWidgetServerUpdate`.
+ *
+ * A URL that is not an absolute `http`/`https` URL is rejected: no platform HTTP stack here
+ * accepts one, so such a config could only ever have failed to fetch. Plain `http` to a
+ * non-local host is reported as insecure rather than rejected — App Transport Security and
+ * Android's cleartext policy already block it in a release build, and rejecting it outright
+ * would break configs that point at a LAN dev server.
+ */
+export function resolveServerUpdateUrl(url: unknown, context: string): ServerUpdateUrlResolution {
+  if (url === undefined) {
+    return { kind: 'ok' }
+  }
+
+  if (typeof url !== 'string' || !url.trim()) {
+    return { kind: 'invalid', error: `${context}.url must be a non-empty string` }
+  }
+
+  let parsed: URL
+
+  try {
+    parsed = new URL(url)
+  } catch {
+    return { kind: 'invalid', error: `${context}.url must be an absolute http(s) URL, received '${url}'` }
+  }
+
+  if (parsed.protocol === 'https:') {
+    return { kind: 'ok' }
+  }
+
+  if (parsed.protocol !== 'http:') {
+    return { kind: 'invalid', error: `${context}.url must be an absolute http(s) URL, received '${url}'` }
+  }
+
+  if (isLocalHttpHost(parsed.hostname)) {
+    return { kind: 'ok' }
+  }
+
+  return {
+    kind: 'insecure',
+    warning:
+      `${context}.url uses plain http ('${url}'). Release builds block cleartext traffic, so the ` +
+      'widget will not fetch outside a development build. Use https, or a local dev host ' +
+      `(${[...LOCAL_HTTP_HOSTS].join(', ')}).`,
+  }
+}
+
+/** True for the hosts Voltra allows over plain `http` — dev servers reachable from a simulator. */
+export function isLocalHttpHost(hostname: string): boolean {
+  return LOCAL_HTTP_HOSTS.has(hostname.replace(/^\[|\]$/g, ''))
+}
+
+/** Validates `serverUpdate.refresh`. Returns an error message, or `undefined` when it is fine. */
+export function validateServerUpdateRefresh(refresh: unknown, context: string): string | undefined {
+  if (refresh !== undefined && typeof refresh !== 'boolean') {
+    return `${context}.refresh must be a boolean`
+  }
+
+  return undefined
+}