voltra 2.2.0 → 2.3.1

package/src/config/types.ts

@@ -1,4 +1,5 @@
 import type { CLI_DEFAULTS } from './defaults'
+import type { PerConfiguration } from './perConfiguration'
 
 export type VoltraPlatform = 'android' | 'ios'
 
@@ -15,8 +16,11 @@ export type WidgetLabel = string | WidgetLocalizedValue
 export type WidgetInitialStatePath = string | WidgetLocalizedValue
 
 export interface AndroidWidgetServerUpdateConfig {
-  /** Server endpoint that returns widget state updates. */
-  url: string
+  /**
+   * Server endpoint that returns widget state updates. Optional — omit it to mark the widget
+   * server-driven and supply the URL at runtime with `setWidgetServerUpdate`.
+   */
+  url?: string
   /** Refresh interval, in minutes, for fetching server updates. */
   intervalMinutes?: number
   /** Whether fetched updates should trigger an immediate widget refresh. */
@@ -44,14 +48,32 @@ export interface AndroidWidgetConfig {
   displayName: WidgetLabel
   /** User-facing widget description shown by the launcher. */
   description: WidgetLabel
-  /** Minimum widget width in dp. */
+  /** Minimum widget width in dp. Only affects Android 11 and older. */
   minWidth?: number
-  /** Minimum widget height in dp. */
+  /** Minimum widget height in dp. Only affects Android 11 and older. */
   minHeight?: number
-  /** Minimum widget width in launcher grid cells. */
+  /**
+   * Minimum widget width in launcher grid cells.
+   *
+   * @deprecated Use `minWidth` instead. The value is approximated in dp for Android 11 and
+   * older.
+   */
   minCellWidth?: number
-  /** Minimum widget height in launcher grid cells. */
+  /**
+   * Minimum widget height in launcher grid cells.
+   *
+   * @deprecated Use `minHeight` instead. The value is approximated in dp for Android 11 and
+   * older.
+   */
   minCellHeight?: number
+  /** Minimum width, in dp, the widget can be resized down to. */
+  minResizeWidth?: number
+  /** Minimum height, in dp, the widget can be resized down to. */
+  minResizeHeight?: number
+  /** Maximum width, in dp, the widget can be resized up to. Honoured on Android 12 and newer. */
+  maxResizeWidth?: number
+  /** Maximum height, in dp, the widget can be resized up to. Honoured on Android 12 and newer. */
+  maxResizeHeight?: number
   /** Default widget width in launcher grid cells. */
   targetCellWidth: number
   /** Default widget height in launcher grid cells. */
@@ -84,8 +106,11 @@ export type IOSWidgetFamily =
   | 'accessoryInline'
 
 export interface IOSWidgetServerUpdateConfig {
-  /** Server endpoint that returns widget state updates. */
-  url: string
+  /**
+   * Server endpoint that returns widget state updates. Optional — omit it to mark the widget
+   * server-driven and supply the URL at runtime with `setWidgetServerUpdate`.
+   */
+  url?: string
   /** Refresh interval, in minutes, for fetching server updates. */
   intervalMinutes?: number
   /** Whether fetched updates should trigger an immediate widget refresh. */
@@ -109,6 +134,12 @@ export interface IOSWidgetAppIntentConfig {
 export interface IOSWidgetConfig {
   /** Stable widget identifier used in generated files and registrations. */
   id: string
+  /**
+   * WidgetKit `kind` of the generated widget. Defaults to `Voltra_Widget_<id>`.
+   * Pin it to the kind of a pre-Voltra widget so already placed instances survive the migration
+   * (WidgetKit identifies a placed widget by extension bundle id + kind).
+   */
+  kind?: string
   /** User-facing widget name shown in iOS widget configuration UI. */
   displayName: WidgetLabel
   /** User-facing widget description shown in iOS widget configuration UI. */
@@ -145,8 +176,11 @@ export interface IOSProjectOverrides {
   mainTargetName?: string
   /** Explicit path to the app target Info.plist file. */
   infoPlistPath?: string
-  /** Explicit path to the main app entitlements file. */
-  entitlementsPath?: string
+  /**
+   * Explicit path to the main app entitlements file, or one path per Xcode build configuration
+   * name when each environment has its own.
+   */
+  entitlementsPath?: PerConfiguration<string>
   /** Explicit path to the Podfile. */
   podfilePath?: string
 }
@@ -175,8 +209,11 @@ export interface VoltraAndroidConfig {
 export interface VoltraIOSConfig {
   /** Whether to enable push-notification-related iOS setup for widgets and Live Activities. */
   enablePushNotifications?: boolean
-  /** App Group identifier used to share data between the app and widget extension. */
-  groupIdentifier?: string
+  /**
+   * App Group identifier used to share data between the app and widget extension, or one per Xcode
+   * build configuration name when each environment has its own.
+   */
+  groupIdentifier?: PerConfiguration<string>
   /** iOS widgets to generate and register. */
   widgets?: IOSWidgetConfig[]
   /** Minimum iOS deployment target for generated widget targets. */
@@ -187,8 +224,11 @@ export interface VoltraIOSConfig {
   fonts?: string[]
   /** Directory containing user-provided images for iOS widgets. */
   userImagesPath?: string
-  /** Keychain access group shared by the app and extension. */
-  keychainGroup?: string
+  /**
+   * Keychain access group shared by the app and extension, or one per Xcode build configuration
+   * name when each environment has its own.
+   */
+  keychainGroup?: PerConfiguration<string>
   /** Native iOS project discovery overrides. */
   project?: IOSProjectOverrides
 }
@@ -211,28 +251,27 @@ export interface LoadedVoltraConfig {
   configDir: string
 }
 
-export interface NormalizedAndroidWidgetServerUpdateConfig {
-  /** Server endpoint that returns widget state updates. */
-  url: string
+/**
+ * Build-time server-update defaults after normalization. The device treats these as the lowest
+ * settings layer; `setWidgetServerUpdate` overrides `url` and `intervalMinutes` at runtime.
+ */
+export interface NormalizedWidgetServerUpdateConfig {
+  /** Server endpoint, when app.json set one. Absent means "URL supplied at runtime". */
+  url?: string
   /** Refresh interval, in minutes, for fetching server updates. */
   intervalMinutes: number
-  /** Whether fetched updates should trigger an immediate widget refresh. */
+  /** Whether the widget draws a refresh button. Build-time only: it is generated UI structure. */
   refresh: boolean
 }
 
+export type NormalizedAndroidWidgetServerUpdateConfig = NormalizedWidgetServerUpdateConfig
+
 export interface NormalizedAndroidWidgetConfig extends Omit<AndroidWidgetConfig, 'serverUpdate'> {
   /** Server-driven update settings after defaults have been applied. */
   serverUpdate?: NormalizedAndroidWidgetServerUpdateConfig
 }
 
-export interface NormalizedIOSWidgetServerUpdateConfig {
-  /** Server endpoint that returns widget state updates. */
-  url: string
-  /** Refresh interval, in minutes, for fetching server updates. */
-  intervalMinutes: number
-  /** Whether fetched updates should trigger an immediate widget refresh. */
-  refresh: boolean
-}
+export type NormalizedIOSWidgetServerUpdateConfig = NormalizedWidgetServerUpdateConfig
 
 export interface NormalizedIOSWidgetConfig extends Omit<IOSWidgetConfig, 'serverUpdate' | 'supportedFamilies'> {
   /** Supported iOS widget families after defaults have been applied. */
@@ -261,8 +300,8 @@ export interface NormalizedIOSProjectConfig {
   mainTargetName?: string
   /** Absolute path to the Info.plist file, if overridden. */
   infoPlistPath?: string
-  /** Absolute path to the entitlements file, if overridden. */
-  entitlementsPath?: string
+  /** Absolute path to the entitlements file, or one per build configuration name, if overridden. */
+  entitlementsPath?: PerConfiguration<string>
   /** Absolute path to the Podfile, if overridden. */
   podfilePath?: string
 }
@@ -284,7 +323,7 @@ export interface NormalizedVoltraIOSConfig {
   /** Whether iOS push-notification-related setup should be applied. */
   enablePushNotifications: boolean
   /** App Group identifier used to share data between the app and extension. */
-  groupIdentifier?: string
+  groupIdentifier?: PerConfiguration<string>
   /** iOS widgets after validation and normalization. */
   widgets: NormalizedIOSWidgetConfig[]
   /** Effective iOS deployment target for generated widget targets. */
@@ -296,11 +335,37 @@ export interface NormalizedVoltraIOSConfig {
   /** Absolute path to the iOS user images directory. */
   userImagesPath: string
   /** Keychain access group shared by the app and extension. */
-  keychainGroup?: string
+  keychainGroup?: PerConfiguration<string>
   /** Normalized iOS native project discovery overrides. */
   project: NormalizedIOSProjectConfig
 }
 
+/**
+ * iOS project overrides after per-build-configuration values have been resolved against the Xcode
+ * project.
+ */
+export type ResolvedIOSProjectConfig = Omit<NormalizedIOSProjectConfig, 'entitlementsPath'> & {
+  /** Absolute path to the entitlements file of the default build configuration, if overridden. */
+  entitlementsPath?: string
+}
+
+/**
+ * iOS config as the platform mutators consume it: every per-build-configuration value has been
+ * collapsed to a single string, either the configured value or a reference to a build setting
+ * Voltra writes per build configuration.
+ */
+export type ResolvedVoltraIOSConfig = Omit<
+  NormalizedVoltraIOSConfig,
+  'groupIdentifier' | 'keychainGroup' | 'project'
+> & {
+  /** App Group identifier used to share data between the app and extension. */
+  groupIdentifier?: string
+  /** Keychain access group shared by the app and extension. */
+  keychainGroup?: string
+  /** Resolved iOS native project discovery overrides. */
+  project: ResolvedIOSProjectConfig
+}
+
 export interface NormalizedVoltraConfig {
   /** Absolute path to the loaded config file, when the config came from a file. */
   configPath?: string
@@ -312,6 +377,8 @@ export interface NormalizedVoltraConfig {
   android?: NormalizedVoltraAndroidConfig
   /** Normalized iOS-specific Voltra configuration. */
   ios?: NormalizedVoltraIOSConfig
+  /** Non-fatal config problems, surfaced in the `voltra apply` summary. */
+  warnings?: string[]
 }
 
 export type CliDefaults = typeof CLI_DEFAULTS

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

@@ -0,0 +1,27 @@
+import assert from 'node:assert/strict'
+import { describe, test } from 'node:test'
+
+import { iosWidgetKind, iosWidgetKindOverrides } from './widgetKind.ts'
+
+describe('iosWidgetKind', () => {
+  test('defaults to the prefixed widget id', () => {
+    assert.equal(iosWidgetKind({ id: 'weather' }), 'Voltra_Widget_weather')
+  })
+
+  test('uses the pinned kind when the widget has one', () => {
+    assert.equal(iosWidgetKind({ id: 'streak', kind: 'StreakWidget' }), 'StreakWidget')
+  })
+})
+
+describe('iosWidgetKindOverrides', () => {
+  test('is undefined when no widget pins a kind, so the Info.plist key stays absent', () => {
+    assert.equal(iosWidgetKindOverrides([{ id: 'weather' }, { id: 'streak' }]), undefined)
+    assert.equal(iosWidgetKindOverrides([]), undefined)
+  })
+
+  test('maps only the widgets that pin a kind', () => {
+    const overrides = iosWidgetKindOverrides([{ id: 'weather' }, { id: 'streak', kind: 'StreakWidget' }])
+
+    assert.deepEqual(overrides, { streak: 'StreakWidget' })
+  })
+})

package/src/config/widgetKind.ts

@@ -0,0 +1,27 @@
+import type { IOSWidgetConfig } from './types'
+
+/** Default prefix of a widget's WidgetKit `kind`: `Voltra_Widget_<id>`. Mirrors `VoltraStorageKeys.widgetKindPrefix`. */
+export const IOS_WIDGET_KIND_PREFIX = 'Voltra_Widget_'
+
+/** WidgetKit `kind` of a widget: the `kind` option when set, else `Voltra_Widget_<id>`. */
+export function iosWidgetKind(widget: Pick<IOSWidgetConfig, 'id' | 'kind'>): string {
+  return widget.kind ?? `${IOS_WIDGET_KIND_PREFIX}${widget.id}`
+}
+
+/**
+ * `{ id: kind }` for the widgets that pin a custom `kind`, or undefined when none does.
+ * Written to both Info.plists (`Voltra_WidgetKinds`) so native code maps ids to kinds and back.
+ */
+export function iosWidgetKindOverrides(
+  widgets: Pick<IOSWidgetConfig, 'id' | 'kind'>[]
+): Record<string, string> | undefined {
+  const overrides: Record<string, string> = {}
+
+  for (const widget of widgets) {
+    if (widget.kind !== undefined) {
+      overrides[widget.id] = widget.kind
+    }
+  }
+
+  return Object.keys(overrides).length > 0 ? overrides : undefined
+}

package/src/dependencies/platformPackages.ts

@@ -36,6 +36,17 @@ export function requirePlatformPackage<TPackage>(projectRoot: string, platform:
   return createProjectRequire(projectRoot)(getPlatformPackageName(platform)) as TPackage
 }
 
+export function getPlatformClientPackageVersion(projectRoot: string, platform: VoltraPlatform): string {
+  const packageName = getPlatformClientPackageName(platform)
+  const manifest = createProjectRequire(projectRoot)(`${packageName}/package.json`) as { version?: unknown }
+
+  if (typeof manifest.version !== 'string' || manifest.version.length === 0) {
+    throw new Error(`Package ${packageName} does not declare a valid version.`)
+  }
+
+  return manifest.version
+}
+
 export function getMissingPlatformPackageMessage(
   platform: VoltraPlatform,
   packageNames = getRequiredPlatformPackageNames(platform)

package/src/discovery/ios.ts

@@ -4,6 +4,7 @@ import path from 'node:path'
 import type { Stats } from 'node:fs'
 
 import { VoltraCliError } from '../reporting/summary'
+import { getValuesByBuildConfiguration, isPerConfigurationMap } from '../config/perConfiguration'
 
 import type { NormalizedIOSProjectConfig } from '../config/types'
 
@@ -19,8 +20,18 @@ export interface IOSProjectDiscovery {
   podfilePath: string
   mainTargetName: string
   mainTargetCandidates: string[]
+  /** Build configuration names of the app target, default build configuration first. */
+  buildConfigurationNames: string[]
+  /** Info.plist of the default build configuration. Always the first entry of `infoPlistPaths`. */
   infoPlistPath: string
+  /** Every distinct Info.plist the app target references, default build configuration first. */
+  infoPlistPaths: string[]
+  /** Entitlements file of the default build configuration, when the project references one. */
   entitlementsPath?: string
+  /** Every distinct entitlements file the app target references, default build configuration first. */
+  entitlementsPaths: string[]
+  /** Entitlements file per build configuration, when the config file names one per configuration. */
+  entitlementsPathByConfiguration?: Map<string, string>
 }
 
 interface ParsedPbxNativeTarget {
@@ -72,8 +83,13 @@ export async function discoverIOSProject(
   const mainTargetCandidates = getMainTargetCandidates(parsedProject.targets)
   const mainTarget = resolveMainTarget(mainTargetCandidates, config.mainTargetName, pbxprojPath)
   const mainTargetBuildConfigurations = getTargetBuildConfigurations(parsedProject, mainTarget, pbxprojPath)
-  const infoPlistPath = await resolveInfoPlistPath(iosRoot, config, mainTarget, mainTargetBuildConfigurations)
-  const entitlementsPath = await resolveEntitlementsPath(iosRoot, config, mainTarget, mainTargetBuildConfigurations)
+  const infoPlistPaths = await resolveInfoPlistPaths(iosRoot, config, mainTarget, mainTargetBuildConfigurations)
+  const { entitlementsPaths, entitlementsPathByConfiguration } = await resolveEntitlements(
+    iosRoot,
+    config,
+    mainTarget,
+    mainTargetBuildConfigurations
+  )
 
   return {
     iosRoot,
@@ -82,8 +98,12 @@ export async function discoverIOSProject(
     podfilePath,
     mainTargetName: mainTarget.name,
     mainTargetCandidates: mainTargetCandidates.map((target) => target.name).sort(),
-    infoPlistPath,
-    entitlementsPath,
+    buildConfigurationNames: mainTargetBuildConfigurations.map((configuration) => configuration.name),
+    infoPlistPath: infoPlistPaths[0],
+    infoPlistPaths,
+    entitlementsPath: entitlementsPaths[0],
+    entitlementsPaths,
+    entitlementsPathByConfiguration,
   }
 }
 
@@ -343,75 +363,102 @@ function getTargetBuildConfigurations(
     : buildConfigurations
 }
 
-async function resolveInfoPlistPath(
+async function resolveInfoPlistPaths(
   iosRoot: string,
   config: NormalizedIOSProjectConfig,
   target: ParsedPbxNativeTarget,
   buildConfigurations: ParsedXCBuildConfiguration[]
-): Promise<string> {
-  const infoPlistPath =
-    config.infoPlistPath ??
-    resolveConsistentBuildSettingPath(
-      iosRoot,
-      target,
-      buildConfigurations,
-      'INFOPLIST_FILE',
-      (configuration) => configuration.buildSettings.infoPlistFile
-    )
+): Promise<string[]> {
+  const discoveredPaths = config.infoPlistPath
+    ? new Map<string, string[]>()
+    : resolveBuildSettingPaths(
+        iosRoot,
+        target,
+        buildConfigurations,
+        (configuration) => configuration.buildSettings.infoPlistFile
+      )
+  const infoPlistPaths = config.infoPlistPath ? [config.infoPlistPath] : [...discoveredPaths.keys()]
 
-  if (!infoPlistPath) {
+  if (infoPlistPaths.length === 0) {
     throw new IOSProjectDiscoveryError(
       `Could not determine Info.plist for target '${target.name}'. Set ios.project.infoPlistPath explicitly.`
     )
   }
 
-  await ensureFile(
-    infoPlistPath,
-    config.infoPlistPath
-      ? `Configured Info.plist does not exist: ${infoPlistPath}`
-      : `Discovered Info.plist does not exist: ${infoPlistPath}`
-  )
+  for (const infoPlistPath of infoPlistPaths) {
+    await ensureFile(
+      infoPlistPath,
+      config.infoPlistPath
+        ? `Configured Info.plist does not exist: ${infoPlistPath}`
+        : `Discovered Info.plist does not exist: ${infoPlistPath}${describeReferencingBuildConfigurations(
+            discoveredPaths,
+            infoPlistPath
+          )}. Set ios.project.infoPlistPath to override discovery.`
+    )
+  }
+
+  return infoPlistPaths
+}
 
-  return infoPlistPath
+interface ResolvedEntitlements {
+  entitlementsPaths: string[]
+  entitlementsPathByConfiguration?: Map<string, string>
 }
 
-async function resolveEntitlementsPath(
+async function resolveEntitlements(
   iosRoot: string,
   config: NormalizedIOSProjectConfig,
   target: ParsedPbxNativeTarget,
   buildConfigurations: ParsedXCBuildConfiguration[]
-): Promise<string | undefined> {
-  const entitlementsPath =
-    config.entitlementsPath ??
-    resolveConsistentBuildSettingPath(
-      iosRoot,
-      target,
-      buildConfigurations,
-      'CODE_SIGN_ENTITLEMENTS',
-      (configuration) => configuration.buildSettings.codeSignEntitlements
+): Promise<ResolvedEntitlements> {
+  const entitlementsPathByConfiguration = isPerConfigurationMap(config.entitlementsPath)
+    ? getValuesByBuildConfiguration(
+        config.entitlementsPath,
+        buildConfigurations.map((configuration) => configuration.name),
+        'ios.project.entitlementsPath',
+        (message) => new IOSProjectDiscoveryError(message)
+      )
+    : undefined
+  const discoveredPaths = config.entitlementsPath
+    ? new Map<string, string[]>()
+    : resolveBuildSettingPaths(
+        iosRoot,
+        target,
+        buildConfigurations,
+        (configuration) => configuration.buildSettings.codeSignEntitlements
+      )
+  const entitlementsPaths = entitlementsPathByConfiguration
+    ? [...new Set(entitlementsPathByConfiguration.values())]
+    : typeof config.entitlementsPath === 'string'
+    ? [config.entitlementsPath]
+    : [...discoveredPaths.keys()]
+
+  for (const entitlementsPath of entitlementsPaths) {
+    await ensureFile(
+      entitlementsPath,
+      config.entitlementsPath
+        ? `Configured entitlements file does not exist: ${entitlementsPath}`
+        : `Discovered entitlements file does not exist: ${entitlementsPath}${describeReferencingBuildConfigurations(
+            discoveredPaths,
+            entitlementsPath
+          )}. Set ios.project.entitlementsPath to override discovery.`
     )
-
-  if (!entitlementsPath) {
-    return undefined
   }
 
-  await ensureFile(
-    entitlementsPath,
-    config.entitlementsPath
-      ? `Configured entitlements file does not exist: ${entitlementsPath}`
-      : `Discovered entitlements file does not exist: ${entitlementsPath}`
-  )
-
-  return entitlementsPath
+  return { entitlementsPaths, entitlementsPathByConfiguration }
 }
 
-function resolveConsistentBuildSettingPath(
+/**
+ * Collects the distinct paths a build setting resolves to across the target's build configurations.
+ * Apps that ship several environments point each configuration at its own file, so divergence is
+ * expected rather than an error.
+ */
+function resolveBuildSettingPaths(
   iosRoot: string,
   target: ParsedPbxNativeTarget,
   buildConfigurations: ParsedXCBuildConfiguration[],
-  settingName: string,
   getSettingValue: (configuration: ParsedXCBuildConfiguration) => string | undefined
-): string | undefined {
+): Map<string, string[]> {
   const resolvedPaths = new Map<string, string[]>()
 
   for (const configuration of buildConfigurations) {
@@ -423,25 +470,22 @@ function resolveConsistentBuildSettingPath(
 
     const resolvedPath = resolveXcodePathValue(settingValue, iosRoot, target, configuration)
     const configurationNames = resolvedPaths.get(resolvedPath) ?? []
+
     configurationNames.push(configuration.name)
     resolvedPaths.set(resolvedPath, configurationNames)
   }
 
-  if (resolvedPaths.size === 0) {
-    return undefined
-  }
+  return resolvedPaths
+}
 
-  if (resolvedPaths.size > 1) {
-    throw new IOSProjectDiscoveryError(
-      `Target '${target.name}' resolves ${settingName} to multiple paths: ${[...resolvedPaths.entries()]
-        .map(([resolvedPath, configurationNames]) => `${resolvedPath} (${configurationNames.join(', ')})`)
-        .join('; ')}. Set ios.project.${
-        settingName === 'INFOPLIST_FILE' ? 'infoPlistPath' : 'entitlementsPath'
-      } explicitly.`
-    )
-  }
+/** Names the build configurations that reference a path, so a missing file can be traced back. */
+function describeReferencingBuildConfigurations(
+  pathsByBuildConfiguration: Map<string, string[]>,
+  filePath: string
+): string {
+  const configurationNames = pathsByBuildConfiguration.get(filePath)
 
-  return [...resolvedPaths.keys()][0]
+  return configurationNames?.length ? ` (referenced by ${configurationNames.join(', ')})` : ''
 }
 
 function resolveXcodePathValue(

package/src/discovery/metro.node.test.ts

@@ -0,0 +1,91 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { describe, test } from 'node:test'
+
+import { findMissingMetroPackageWarning } from './metro.ts'
+
+import type { NormalizedVoltraConfig } from '../config/types.ts'
+
+/**
+ * A project root with its own `package.json`, so `createRequire` has an anchor, and optionally a
+ * `node_modules/@use-voltra/metro` that resolves the `bundle-widgets` subpath the same way the real
+ * package does.
+ */
+async function createProject({ withMetroInstalled }: { withMetroInstalled: boolean }): Promise<string> {
+  const projectRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'voltra-metro-'))
+  await fs.writeFile(path.join(projectRoot, 'package.json'), JSON.stringify({ name: 'app', version: '1.0.0' }))
+
+  if (withMetroInstalled) {
+    const packageRoot = path.join(projectRoot, 'node_modules', '@use-voltra', 'metro')
+    await fs.mkdir(path.join(packageRoot, 'build', 'cjs', 'bin'), { recursive: true })
+    await fs.writeFile(path.join(packageRoot, 'build', 'cjs', 'bin', 'bundle-widgets.js'), 'module.exports = {}\n')
+    await fs.writeFile(
+      path.join(packageRoot, 'package.json'),
+      JSON.stringify({
+        name: '@use-voltra/metro',
+        version: '2.3.0',
+        exports: { './bundle-widgets': './build/cjs/bin/bundle-widgets.js' },
+      })
+    )
+  }
+
+  return projectRoot
+}
+
+function configWith(projectRoot: string, entry: string | undefined): NormalizedVoltraConfig {
+  return {
+    projectRoot,
+    android: {
+      project: {},
+      widgets: [
+        {
+          id: 'portfolio',
+          displayName: 'Portfolio',
+          description: 'Your holdings',
+          targetCellWidth: 2,
+          targetCellHeight: 2,
+          entry,
+        },
+      ],
+      fonts: [],
+    },
+    warnings: [],
+  } as unknown as NormalizedVoltraConfig
+}
+
+describe('metro package detection', () => {
+  test('warns when a Dynamic Widget is declared and the package is not installed', async () => {
+    const projectRoot = await createProject({ withMetroInstalled: false })
+
+    const warning = findMissingMetroPackageWarning(configWith(projectRoot, './widgets/portfolio.tsx'))
+
+    assert.match(warning ?? '', /@use-voltra\/metro/)
+    assert.match(warning ?? '', /prerendered initial state/)
+  })
+
+  test('stays quiet when the package resolves', async () => {
+    const projectRoot = await createProject({ withMetroInstalled: true })
+
+    assert.equal(findMissingMetroPackageWarning(configWith(projectRoot, './widgets/portfolio.tsx')), undefined)
+  })
+
+  test('stays quiet when no widget has an entry, however Metro is set up', async () => {
+    const projectRoot = await createProject({ withMetroInstalled: false })
+
+    assert.equal(findMissingMetroPackageWarning(configWith(projectRoot, undefined)), undefined)
+  })
+
+  test('does not warn at a project whose Metro config never names withVoltra', async () => {
+    // A config delegating to a shared preset, or hand-composed from createVoltraMiddleware, is
+    // correctly wired and must stay quiet — the package resolving is the whole signal.
+    const projectRoot = await createProject({ withMetroInstalled: true })
+    await fs.writeFile(
+      path.join(projectRoot, 'metro.config.js'),
+      "module.exports = require('@myorg/metro-config')(__dirname)\n"
+    )
+
+    assert.equal(findMissingMetroPackageWarning(configWith(projectRoot, './widgets/portfolio.tsx')), undefined)
+  })
+})