@use-voltra/expo-plugin 2.1.1 → 2.3.0

package/build/types/utils/prerender.d.ts

@@ -1,3 +1,4 @@
+import { type WidgetModuleLoader, type WidgetModulePlatform } from '@use-voltra/compiler';
 import type { WidgetInitialStatePath } from '../types';
 /**
  * Type for the widget renderer function
@@ -12,20 +13,32 @@ export interface PrerenderableWidget {
 }
 /** widgetId -> locale key -> prerendered JSON string (single-file widgets use `__default`) */
 export type PrerenderedWidgetStates = Map<string, Map<string, string>>;
+export interface WidgetModuleEvaluationOptions {
+    projectRoot: string;
+    /** Platform being prebuilt. Determines `Platform.OS` inside widget code. */
+    platform: WidgetModulePlatform;
+    /** Reuse a loader across several widgets so warnings are reported once per prebuild. */
+    loader?: WidgetModuleLoader;
+}
+/**
+ * Create the loader used to evaluate widget source during prebuild.
+ *
+ * Evaluation rules live in `@use-voltra/compiler` so that prebuild, `voltra apply`, and
+ * the Metro widget bundler agree on what widget code may import.
+ */
+export declare function createPrerenderWidgetModuleLoader(projectRoot: string, platform: WidgetModulePlatform): WidgetModuleLoader;
 /**
- * Evaluate a widget module using Babel transpilation and Node.js VM.
- * This allows executing widget code that uses JSX and React components.
- * Local module dependencies are also transpiled with the same Babel settings.
+ * Evaluate a widget module and return its exports object.
  *
  * Exported so platform-specific prerender flows can reuse the same module loader rather
- * than duplicating the Babel + VM scaffolding. The returned value is the module's exports
- * object — callers decide whether to read `.default`, a named export, etc.
+ * than duplicating the Babel + VM scaffolding. Callers decide whether to read `.default`,
+ * a named export, etc.
  */
-export declare function evaluateWidgetModuleExports(projectRoot: string, filePath: string, warnedRedirects?: Set<string>): any;
+export declare function evaluateWidgetModuleExports(filePath: string, options: WidgetModuleEvaluationOptions): any;
 /**
  * Evaluate a widget file as a server-style WidgetVariants module and return its object export.
  */
-export declare function evaluateWidgetModule(projectRoot: string, filePath: string, warnedRedirects?: Set<string>): any;
+export declare function evaluateWidgetModule(filePath: string, options: WidgetModuleEvaluationOptions): any;
 /**
  * Prerender widget initial states for build-time inclusion.
  *
@@ -36,7 +49,8 @@ export declare function evaluateWidgetModule(projectRoot: string, filePath: stri
  * @param widgets - Array of widget configurations
  * @param projectRoot - Root directory of the Expo project
  * @param renderer - The renderer function to use (voltra/server or voltra/android/server)
+ * @param platform - Platform being prebuilt
  * @returns Map of widgetId -> (locale key -> prerendered JSON string)
  */
-export declare function prerenderWidgetState(widgets: PrerenderableWidget[], projectRoot: string, renderer: WidgetRenderer): Promise<PrerenderedWidgetStates>;
+export declare function prerenderWidgetState(widgets: PrerenderableWidget[], projectRoot: string, renderer: WidgetRenderer, platform: WidgetModulePlatform): Promise<PrerenderedWidgetStates>;
 //# sourceMappingURL=prerender.d.ts.map

package/build/types/utils/prerender.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prerender.d.ts","sourceRoot":"","sources":["../../../src/utils/prerender.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,sBAAsB,EAAe,MAAM,UAAU,CAAA;AAInE;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,GAAG,KAAK,MAAM,CAAA;AAEtD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,gBAAgB,CAAC,EAAE,sBAAsB,CAAA;CAC1C;AAED,8FAA8F;AAC9F,MAAM,MAAM,uBAAuB,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;AA2EtE;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,eAAe,cAAoB,GAClC,GAAG,CAsEL;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,eAAe,cAAoB,GAAG,GAAG,CASpH;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,mBAAmB,EAAE,EAC9B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,cAAc,GACvB,OAAO,CAAC,uBAAuB,CAAC,CAgClC"}
+{"version":3,"file":"prerender.d.ts","sourceRoot":"","sources":["../../../src/utils/prerender.ts"],"names":[],"mappings":"AAEA,OAAO,EAA4B,KAAK,kBAAkB,EAAE,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAEnH,OAAO,KAAK,EAAE,sBAAsB,EAAe,MAAM,UAAU,CAAA;AAInE;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,GAAG,KAAK,MAAM,CAAA;AAEtD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,gBAAgB,CAAC,EAAE,sBAAsB,CAAA;CAC1C;AAED,8FAA8F;AAC9F,MAAM,MAAM,uBAAuB,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;AAEtE,MAAM,WAAW,6BAA6B;IAC5C,WAAW,EAAE,MAAM,CAAA;IACnB,4EAA4E;IAC5E,QAAQ,EAAE,oBAAoB,CAAA;IAC9B,wFAAwF;IACxF,MAAM,CAAC,EAAE,kBAAkB,CAAA;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,iCAAiC,CAC/C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,oBAAoB,GAC7B,kBAAkB,CAMpB;AAMD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,6BAA6B,GAAG,GAAG,CAEzG;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,6BAA6B,GAAG,GAAG,CAQlG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,mBAAmB,EAAE,EAC9B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,uBAAuB,CAAC,CAgClC"}

package/build/types/widgetServerUpdate.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Expo-plugin side of the `serverUpdate` config rules. The rules themselves live in
+ * `./serverUpdate`, which the `voltra` CLI mirrors; this module only turns them into the plugin's
+ * thrown errors and console warnings.
+ */
+/** `serverUpdate` as it appears in app.json, before defaults are applied. */
+export interface WidgetServerUpdateConfig {
+    url?: string;
+    intervalMinutes?: number;
+    refresh?: boolean;
+}
+/** `serverUpdate` after defaults, as the generators consume it. */
+export interface ResolvedWidgetServerUpdateConfig {
+    /** Absent when app.json set no URL — the app supplies one at runtime. */
+    url?: string;
+    intervalMinutes: number;
+    refresh: boolean;
+}
+export interface WidgetServerUpdateRules {
+    /** True when the widget has an `entry` and so renders bundled JS from fetched props. */
+    hasEntry: boolean;
+    /** Interval used when the widget sets none. Ignored for widgets with `entry`. */
+    defaultIntervalMinutes: number;
+    /** Platform floor for payload widgets. Ignored for widgets with `entry`. */
+    minimumIntervalMinutes: number;
+}
+export declare function validateWidgetServerUpdate(serverUpdate: unknown, widgetId: string, rules: WidgetServerUpdateRules): void;
+/**
+ * Applies defaults to a validated `serverUpdate`. Generators call this instead of reading
+ * `intervalMinutes` directly, so the value written into a plist or a generated asset is the one
+ * the widget will actually be scheduled on.
+ */
+export declare function resolveWidgetServerUpdate(serverUpdate: WidgetServerUpdateConfig, rules: WidgetServerUpdateRules): ResolvedWidgetServerUpdateConfig;
+//# sourceMappingURL=widgetServerUpdate.d.ts.map

package/build/types/widgetServerUpdate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widgetServerUpdate.d.ts","sourceRoot":"","sources":["../../src/widgetServerUpdate.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH,6EAA6E;AAC7E,MAAM,WAAW,wBAAwB;IACvC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,mEAAmE;AACnE,MAAM,WAAW,gCAAgC;IAC/C,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,eAAe,EAAE,MAAM,CAAA;IACvB,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC,wFAAwF;IACxF,QAAQ,EAAE,OAAO,CAAA;IACjB,iFAAiF;IACjF,sBAAsB,EAAE,MAAM,CAAA;IAC9B,4EAA4E;IAC5E,sBAAsB,EAAE,MAAM,CAAA;CAC/B;AAED,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,OAAO,EACrB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,uBAAuB,GAC7B,IAAI,CA4CN;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,wBAAwB,EACtC,KAAK,EAAE,uBAAuB,GAC7B,gCAAgC,CAiBlC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@use-voltra/expo-plugin",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "description": "Shared utilities for Voltra Expo config plugins",
   "main": "build/cjs/index.js",
   "module": "build/esm/index.js",
@@ -20,7 +20,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@babel/core": "^7.27.4"
+    "@use-voltra/compiler": "^2.3.0",
+    "@use-voltra/core": "^2.3.0"
   },
   "keywords": [
     "voltra",
@@ -44,7 +45,6 @@
     "react-native": "*"
   },
   "devDependencies": {
-    "@types/babel__core": "^7.20.5",
     "@types/jest": "^29.5.14",
     "@types/node": "^20.19.25",
     "jest": "^29.7.0",

package/src/constants.ts

@@ -1,5 +1,2 @@
-/** Extensions to try when resolving module paths for pre-rendering */
-export const MODULE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '']
-
 /** Maximum image size in bytes for widget / Live Activity assets (4KB limit) */
 export const MAX_IMAGE_SIZE_BYTES = 4096

package/src/dynamic-live-activity.node.test.ts

@@ -0,0 +1,18 @@
+import { getDynamicLiveActivityAttributesType as getIOSAttributesType } from '../../ios/src/live-activity/dynamic'
+import { getDynamicLiveActivityAttributesType as getCanonicalAttributesType } from '../../core/src/dynamic-live-activity'
+
+import { getDynamicLiveActivityAttributesType as getExpoPluginAttributesType } from './dynamic-live-activity'
+
+describe('Dynamic Live Activity attributes type naming', () => {
+  it.each([
+    ['', 'VoltraLiveActivityAttributes'],
+    ['order_finished', 'VoltraOrderFinishedLiveActivityAttributes'],
+    ['order__finished', 'VoltraOrderFinishedLiveActivityAttributes'],
+    ['_driver_arrived_', 'VoltraDriverArrivedLiveActivityAttributes'],
+    ['alreadyCamel', 'VoltraAlreadyCamelLiveActivityAttributes'],
+  ])('keeps core, Expo generation, and the iOS public helper aligned for %p', (definitionId, expected) => {
+    expect(getCanonicalAttributesType(definitionId)).toBe(expected)
+    expect(getExpoPluginAttributesType(definitionId)).toBe(expected)
+    expect(getIOSAttributesType(definitionId)).toBe(expected)
+  })
+})

package/src/dynamic-live-activity.ts

@@ -0,0 +1 @@
+export { getDynamicLiveActivityAttributesType } from '@use-voltra/core/dynamic-live-activity'

package/src/index.ts

@@ -1,6 +1,10 @@
-export { MAX_IMAGE_SIZE_BYTES, MODULE_EXTENSIONS } from './constants'
+export { MAX_IMAGE_SIZE_BYTES } from './constants'
+export { getDynamicLiveActivityAttributesType } from './dynamic-live-activity'
 export type {
   DynamicWidgetEntryConfig,
+  DynamicLiveActivityEntryConfig,
+  DynamicLiveActivityManifest,
+  DynamicLiveActivityManifestDefinition,
   DynamicWidgetManifest,
   DynamicWidgetManifestWidget,
   DynamicWidgetPlatform,
@@ -8,6 +12,20 @@ export type {
   WidgetLabel,
   WidgetLocalizedCopy,
 } from './types'
+export type { ServerUpdateIntervalResolution, ServerUpdateUrlResolution } from './serverUpdate'
+export {
+  DYNAMIC_WIDGET_SERVER_UPDATE_INTERVAL_MINUTES,
+  isLocalHttpHost,
+  resolveServerUpdateInterval,
+  resolveServerUpdateUrl,
+  validateServerUpdateRefresh,
+} from './serverUpdate'
+export type {
+  ResolvedWidgetServerUpdateConfig,
+  WidgetServerUpdateConfig,
+  WidgetServerUpdateRules,
+} from './widgetServerUpdate'
+export { resolveWidgetServerUpdate, validateWidgetServerUpdate } from './widgetServerUpdate'
 export {
   assertValidLocaleKey,
   normalizeWidgetEntryPath,
@@ -20,6 +38,18 @@ export { addApplicationGroupsEntitlement } from './utils/entitlements'
 export { resolveFontPaths } from './utils/fonts'
 export { normalizeLocaleTag, pickLocalizedValue } from './utils/localePick'
 export { logger } from './utils/logger'
-export type { PrerenderableWidget, PrerenderedWidgetStates, WidgetRenderer } from './utils/prerender'
-export { evaluateWidgetModule, evaluateWidgetModuleExports, prerenderWidgetState } from './utils/prerender'
+export { resolveInstalledPackageVersion } from './utils/packageVersion'
+export type {
+  PrerenderableWidget,
+  PrerenderedWidgetStates,
+  WidgetModuleEvaluationOptions,
+  WidgetRenderer,
+} from './utils/prerender'
+export {
+  createPrerenderWidgetModuleLoader,
+  evaluateWidgetModule,
+  evaluateWidgetModuleExports,
+  prerenderWidgetState,
+} from './utils/prerender'
+export type { WidgetModuleLoader, WidgetModulePlatform } from '@use-voltra/compiler'
 export { isWidgetLocalizedMap, widgetLabelEnglish } from './utils/widgetLabel'

package/src/serverUpdate.node.test.ts

@@ -0,0 +1,126 @@
+import {
+  DYNAMIC_WIDGET_SERVER_UPDATE_INTERVAL_MINUTES,
+  resolveServerUpdateInterval,
+  resolveServerUpdateUrl,
+  validateServerUpdateRefresh,
+} from './serverUpdate'
+
+const PAYLOAD_WIDGET = {
+  context: 'android.widgets[portfolio].serverUpdate',
+  hasEntry: false,
+  defaultIntervalMinutes: 60,
+  minimumIntervalMinutes: 15,
+}
+
+const DYNAMIC_WIDGET = { ...PAYLOAD_WIDGET, hasEntry: true }
+
+describe('resolveServerUpdateInterval', () => {
+  it('falls back to the platform default for a payload widget that sets no interval', () => {
+    expect(resolveServerUpdateInterval({ ...PAYLOAD_WIDGET, intervalMinutes: undefined })).toEqual({
+      kind: 'ok',
+      intervalMinutes: 60,
+    })
+  })
+
+  it('falls back to 15 for a widget with an entry, ignoring the platform default', () => {
+    expect(resolveServerUpdateInterval({ ...DYNAMIC_WIDGET, intervalMinutes: undefined })).toEqual({
+      kind: 'ok',
+      intervalMinutes: DYNAMIC_WIDGET_SERVER_UPDATE_INTERVAL_MINUTES,
+    })
+  })
+
+  it('keeps the payload widget rule and rejects an interval below the platform floor', () => {
+    const resolution = resolveServerUpdateInterval({ ...PAYLOAD_WIDGET, intervalMinutes: 5 })
+
+    expect(resolution.kind).toBe('invalid')
+    expect(resolution).toHaveProperty('error', expect.stringContaining('at least 15'))
+  })
+
+  it('accepts an interval below 15 on iOS payload widgets, where the floor is 1', () => {
+    expect(
+      resolveServerUpdateInterval({
+        ...PAYLOAD_WIDGET,
+        context: 'ios.widgets[portfolio].serverUpdate',
+        defaultIntervalMinutes: 15,
+        minimumIntervalMinutes: 1,
+        intervalMinutes: 5,
+      })
+    ).toEqual({ kind: 'ok', intervalMinutes: 5 })
+  })
+
+  it('clamps a widget with an entry up to 15 and warns instead of failing the build', () => {
+    const resolution = resolveServerUpdateInterval({
+      ...DYNAMIC_WIDGET,
+      minimumIntervalMinutes: 1,
+      intervalMinutes: 5,
+    })
+
+    expect(resolution).toEqual({
+      kind: 'clamped',
+      intervalMinutes: 15,
+      warning: expect.stringContaining('below the 15 minute floor'),
+    })
+  })
+
+  it('accepts an interval at or above 15 for a widget with an entry', () => {
+    expect(resolveServerUpdateInterval({ ...DYNAMIC_WIDGET, intervalMinutes: 30 })).toEqual({
+      kind: 'ok',
+      intervalMinutes: 30,
+    })
+  })
+
+  it('rejects a non-integer or non-finite interval on either engine', () => {
+    expect(resolveServerUpdateInterval({ ...DYNAMIC_WIDGET, intervalMinutes: 15.5 }).kind).toBe('invalid')
+    expect(resolveServerUpdateInterval({ ...PAYLOAD_WIDGET, intervalMinutes: Number.NaN }).kind).toBe('invalid')
+    expect(resolveServerUpdateInterval({ ...PAYLOAD_WIDGET, intervalMinutes: '30' }).kind).toBe('invalid')
+  })
+})
+
+describe('resolveServerUpdateUrl', () => {
+  const context = 'ios.widgets[portfolio].serverUpdate'
+
+  it('accepts an absent url, so the app can supply one at runtime', () => {
+    expect(resolveServerUpdateUrl(undefined, context)).toEqual({ kind: 'ok' })
+  })
+
+  it('accepts https', () => {
+    expect(resolveServerUpdateUrl('https://api.example.com/widgets/portfolio', context)).toEqual({ kind: 'ok' })
+  })
+
+  it('accepts plain http for the dev hosts a simulator and an emulator reach', () => {
+    expect(resolveServerUpdateUrl('http://localhost:3333', context)).toEqual({ kind: 'ok' })
+    expect(resolveServerUpdateUrl('http://10.0.2.2:3333/widgets', context)).toEqual({ kind: 'ok' })
+    expect(resolveServerUpdateUrl('http://127.0.0.1:3333', context)).toEqual({ kind: 'ok' })
+  })
+
+  it('warns rather than failing on plain http to another host, which release builds block', () => {
+    const resolution = resolveServerUpdateUrl('http://192.168.1.5:3333', context)
+
+    expect(resolution.kind).toBe('insecure')
+    expect(resolution).toHaveProperty('warning', expect.stringContaining('cleartext'))
+  })
+
+  it('rejects a url with no scheme, which no platform HTTP stack accepts', () => {
+    expect(resolveServerUpdateUrl('api.example.com/widgets', context).kind).toBe('invalid')
+  })
+
+  it('rejects a non-http scheme', () => {
+    expect(resolveServerUpdateUrl('ftp://api.example.com', context).kind).toBe('invalid')
+  })
+
+  it('rejects an empty url', () => {
+    expect(resolveServerUpdateUrl('   ', context).kind).toBe('invalid')
+    expect(resolveServerUpdateUrl(42, context).kind).toBe('invalid')
+  })
+})
+
+describe('validateServerUpdateRefresh', () => {
+  it('accepts a boolean or nothing', () => {
+    expect(validateServerUpdateRefresh(undefined, 'ctx')).toBeUndefined()
+    expect(validateServerUpdateRefresh(true, 'ctx')).toBeUndefined()
+  })
+
+  it('rejects a non-boolean', () => {
+    expect(validateServerUpdateRefresh('yes', 'ctx')).toContain('must be a boolean')
+  })
+})

package/src/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 `voltra` CLI validates `serverUpdate` from its own copy of this module; 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
+}

package/src/types.ts

@@ -26,6 +26,31 @@ export interface DynamicWidgetManifest {
   widgets: DynamicWidgetManifestWidget[]
 }
 
+/**
+ * Generated by the iOS config plugin for Metro's Dynamic Live Activity pipeline.
+ * This intentionally does not share the Dynamic Widget manifest: an ID may exist in
+ * both collections and each collection has a separate runtime and bundle namespace.
+ */
+export interface DynamicLiveActivityManifestDefinition {
+  id: string
+  entry: string
+}
+
+export interface DynamicLiveActivityManifest {
+  version: 1
+  platform: 'ios'
+  liveActivities: DynamicLiveActivityManifestDefinition[]
+}
+
+/**
+ * Shared app.json entry contract for Dynamic Live Activities.
+ * @experimental
+ */
+export interface DynamicLiveActivityEntryConfig {
+  id: string
+  entry: string
+}
+
 /**
  * Per-locale strings for widget picker/gallery labels (`displayName`, `description`).
  * Keys should be BCP-47-style locale tags (e.g. `en`, `pl`, `pt-BR`). Plain `string` is still allowed for a single-language setup.

package/src/utils/packageVersion.node.test.ts

@@ -0,0 +1,24 @@
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+
+import { resolveInstalledPackageVersion } from './packageVersion'
+
+describe('resolveInstalledPackageVersion', () => {
+  it('reads the version from the package installed in the project', () => {
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'voltra-package-version-'))
+    const packageDir = path.join(projectRoot, 'node_modules', '@use-voltra', 'ios-client')
+    fs.mkdirSync(packageDir, { recursive: true })
+    fs.writeFileSync(path.join(projectRoot, 'package.json'), '{}\n')
+    fs.writeFileSync(
+      path.join(packageDir, 'package.json'),
+      `${JSON.stringify({ name: '@use-voltra/ios-client', version: '9.8.7' })}\n`
+    )
+
+    try {
+      expect(resolveInstalledPackageVersion(projectRoot, '@use-voltra/ios-client')).toBe('9.8.7')
+    } finally {
+      fs.rmSync(projectRoot, { recursive: true, force: true })
+    }
+  })
+})

package/src/utils/packageVersion.ts

@@ -0,0 +1,19 @@
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import { createRequire } from 'node:module'
+
+interface PackageManifest {
+  version?: unknown
+}
+
+export function resolveInstalledPackageVersion(projectRoot: string, packageName: string): string {
+  const projectRequire = createRequire(path.join(projectRoot, 'package.json'))
+  const packageJsonPath = projectRequire.resolve(`${packageName}/package.json`)
+  const manifest = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')) as PackageManifest
+
+  if (typeof manifest.version !== 'string' || manifest.version.length === 0) {
+    throw new Error(`Package ${packageName} does not declare a valid version in ${packageJsonPath}.`)
+  }
+
+  return manifest.version
+}

package/src/utils/prerender.node.test.ts

@@ -54,7 +54,8 @@ describe('prerenderWidgetState', () => {
       const states = await prerenderWidgetState(
         [{ id: 'demo', initialStatePath: './widgets/state.ts' }],
         tempRoot,
-        (variants) => JSON.stringify(variants)
+        (variants) => JSON.stringify(variants),
+        targetLabel
       )
 
       expect(states.get('demo')?.get('__default')).toBe(JSON.stringify({ label: targetLabel }))