@use-voltra/ios-client 2.0.0 → 2.1.1

package/expo-plugin/src/ios-widget/clientRenderedPrerender.ts

@@ -0,0 +1,103 @@
+import { evaluateWidgetModuleExports, logger, type PrerenderedWidgetStates } from '@use-voltra/expo-plugin'
+
+import type { DetectedIOSWidget } from './clientRendered'
+
+/**
+ * Initial-state prerender for Dynamic Widgets.
+ *
+ * For widgets with `initialStatePath`, the existing `prerenderWidgetState` in
+ * @use-voltra/expo-plugin loads the file and reads `exports.default` (a `WidgetVariants`
+ * object), then runs it through the multi-family `renderWidgetToString` to produce a
+ * per-family JSON payload that the runtime's `selectContentForFamily` will pick from.
+ *
+ * Dynamic Widgets work differently: the module referenced by `entry` default-exports a
+ * function or component, and the runtime calls it per-render with real env values. For the
+ * WidgetKit placeholder (`Provider.placeholder` and the widget gallery preview) ONE
+ * pre-rendered JSON entry is needed to display before any Metro fetch completes. That's
+ * generated here by calling the entry default export at prebuild with empty props + a
+ * minimal env, storing the compact `{t, c, p}` JSON in the existing `voltra_initial_states.json`.
+ *
+ * The placeholder's env values are fixed (`widgetFamily: 'systemMedium'`,
+ * `colorScheme: 'light'`, etc.) and may not match what the user actually sees the moment
+ * they add the widget — but the first real timeline tick replaces this entry within
+ * milliseconds, so the brief mismatch is invisible in practice.
+ */
+
+/** Locale key used for non-localized prerendered states (mirrors prerender.ts behavior). */
+const SINGLE_LOCALE_KEY = '__default'
+
+/**
+ * Default env passed to Dynamic Widgets at prebuild for the placeholder render. Fields
+ * mirror `WidgetEnvironment` from packages/core/src/widget-environment.ts so the widget
+ * function sees the same shape it gets at runtime.
+ */
+function buildPlaceholderEnv(): Record<string, unknown> {
+  return {
+    date: Date.now(),
+    widgetFamily: 'systemMedium',
+    colorScheme: 'light',
+    locale: 'en-US',
+    widgetRenderingMode: 'fullColor',
+    showsWidgetContainerBackground: true,
+    configuration: undefined,
+    build: {
+      isDev: false,
+      metroUrl: null,
+      appVersion: 'unknown',
+      voltraVersion: '1.4.1',
+    },
+  }
+}
+
+/**
+ * Prerender placeholder JSON for every Dynamic Widget. Returns a map shaped
+ * identically to `prerenderWidgetState`'s output so the two can be merged before
+ * generating `VoltraWidgetInitialStates.swift`.
+ */
+export async function prerenderClientRenderedWidgets(
+  widgets: DetectedIOSWidget[],
+  projectRoot: string
+): Promise<PrerenderedWidgetStates> {
+  const results: PrerenderedWidgetStates = new Map()
+
+  const clientWidgets = widgets.filter(
+    (w): w is Extract<DetectedIOSWidget, { clientRendered: true }> => w.clientRendered
+  )
+  if (clientWidgets.length === 0) {
+    return results
+  }
+
+  // Lazy-loaded so server-only projects never pull in @use-voltra/ios. The renderer
+  // is iOS-specific by design — the Android counterpart will use the same shape via
+  // @use-voltra/android in a future phase.
+  const iosModuleId = '@use-voltra/ios'
+  const { renderVoltraVariantToJson } = (await import(iosModuleId)) as {
+    renderVoltraVariantToJson: (element: unknown) => unknown
+  }
+
+  const placeholderEnv = buildPlaceholderEnv()
+
+  for (const widget of clientWidgets) {
+    try {
+      const widgetModule = evaluateWidgetModuleExports(projectRoot, widget.clientSourcePath)
+      const widgetFn = widgetModule?.default ?? widgetModule
+      if (typeof widgetFn !== 'function') {
+        throw new Error(
+          `Expected the entry module at ${widget.clientSourcePath} to default-export a function or component.`
+        )
+      }
+
+      const element = widgetFn({}, placeholderEnv)
+      const json = renderVoltraVariantToJson(element)
+      const jsonString = JSON.stringify(json)
+      results.set(widget.id, new Map([[SINGLE_LOCALE_KEY, jsonString]]))
+    } catch (error) {
+      throw new Error(
+        `Failed to prerender Dynamic Widget "${widget.id}": ${error instanceof Error ? error.message : String(error)}`
+      )
+    }
+  }
+
+  logger.info(`Prerendered ${clientWidgets.length} Dynamic Widget placeholder(s)`)
+  return results
+}

package/expo-plugin/src/ios-widget/files/index.ts

@@ -6,6 +6,7 @@ import type { IOSWidgetConfig } from '../../types'
 import { generateAssets } from './assets'
 import { generateEntitlements } from './entitlements'
 import { generateInfoPlist } from './infoPlist'
+import { generateIOSDynamicWidgetsManifest } from './manifest'
 import { generateSwiftFiles } from './swift'
 
 export interface GenerateWidgetExtensionFilesProps {
@@ -60,6 +61,12 @@ export const generateWidgetExtensionFiles: ConfigPlugin<GenerateWidgetExtensionF
         widgets,
       })
 
+      // Write the iOS-owned Dynamic Widgets manifest for Metro to consume later.
+      generateIOSDynamicWidgetsManifest({
+        projectRoot,
+        widgets,
+      })
+
       // Generate entitlements file (may be empty if no groupIdentifier or keychainGroup)
       generateEntitlements({
         targetPath,

package/expo-plugin/src/ios-widget/files/manifest.ts

@@ -0,0 +1,47 @@
+import * as fs from 'fs'
+import * as path from 'path'
+
+import { type DynamicWidgetManifest, logger, validateWidgetEntry } from '@use-voltra/expo-plugin'
+
+import type { IOSWidgetConfig } from '../../types'
+
+const MANIFEST_PATH = path.join('.voltra', 'manifest.ios.json')
+
+export interface GenerateIOSDynamicWidgetsManifestOptions {
+  projectRoot: string
+  widgets?: IOSWidgetConfig[]
+}
+
+export function createIOSDynamicWidgetsManifest(
+  projectRoot: string,
+  widgets: IOSWidgetConfig[]
+): DynamicWidgetManifest {
+  const manifestWidgets: DynamicWidgetManifest['widgets'] = []
+
+  for (const widget of widgets) {
+    if (widget.entry === undefined) {
+      continue
+    }
+
+    manifestWidgets.push({
+      id: widget.id,
+      entry: validateWidgetEntry(widget.entry, widget.id, projectRoot),
+    })
+  }
+
+  return {
+    version: 1,
+    platform: 'ios',
+    widgets: manifestWidgets,
+  }
+}
+
+export function generateIOSDynamicWidgetsManifest(options: GenerateIOSDynamicWidgetsManifestOptions): void {
+  const { projectRoot, widgets } = options
+  const manifestPath = path.join(projectRoot, MANIFEST_PATH)
+  const manifest = createIOSDynamicWidgetsManifest(projectRoot, widgets ?? [])
+
+  fs.mkdirSync(path.dirname(manifestPath), { recursive: true })
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+  logger.info(`Generated ${MANIFEST_PATH}`)
+}

package/expo-plugin/src/ios-widget/files/swift.ts

@@ -14,6 +14,8 @@ import {
 import { DEFAULT_WIDGET_FAMILIES, WIDGET_FAMILY_MAP } from '../../constants'
 import type { IOSWidgetConfig } from '../../types'
 import { VOLTRA_WIDGET_STRINGS_BASENAME } from '../../utils/fileDiscovery'
+import { detectClientRenderedWidgets, type DetectedIOSWidget } from '../clientRendered'
+import { prerenderClientRenderedWidgets } from '../clientRenderedPrerender'
 
 export interface GenerateSwiftFilesOptions {
   targetPath: string
@@ -43,8 +45,23 @@ export async function generateSwiftFiles(options: GenerateSwiftFilesOptions): Pr
     renderWidgetToString: RenderWidgetToString
   }
 
-  // Prerender widget initial states if any widgets have initialStatePath configured
-  const prerenderedStates = await prerenderWidgetState(widgets || [], projectRoot, renderWidgetToString)
+  // Tag each widget with its rendering mode (server vs Dynamic Widget) by inspecting the
+  // app.json entry module. See ../clientRendered.ts.
+  const detectedWidgets = detectClientRenderedWidgets(widgets || [], projectRoot)
+  const clientWidgetCount = detectedWidgets.filter((w) => w.clientRendered).length
+  if (clientWidgetCount > 0) {
+    logger.info(`Detected ${clientWidgetCount} Dynamic Widget(s) — generating Provider scaffolding`)
+  }
+
+  // Prerender widget initial states. Widgets with `initialStatePath` go through the existing
+  // multi-family WidgetVariants → JSON path; Dynamic Widgets go through the entry-module path
+  // (call the default export with default props + minimal env, run renderVoltraVariantToJson,
+  // stringify). Both produce entries in the same map shape so
+  // VoltraWidgetInitialStates.swift can read either via the same lookup at runtime.
+  const serverWidgets = detectedWidgets.filter((w) => !w.clientRendered)
+  const serverStates = await prerenderWidgetState(serverWidgets, projectRoot, renderWidgetToString)
+  const clientStates = await prerenderClientRenderedWidgets(detectedWidgets, projectRoot)
+  const prerenderedStates = new Map([...serverStates, ...clientStates])
 
   syncVoltraWidgetGalleryStrings(targetPath, widgets)
 
@@ -59,7 +76,7 @@ export async function generateSwiftFiles(options: GenerateSwiftFilesOptions): Pr
 
   // Generate the widget bundle Swift file
   const widgetBundleContent =
-    widgets && widgets.length > 0 ? generateWidgetBundleSwift(widgets) : generateDefaultWidgetBundleSwift()
+    detectedWidgets.length > 0 ? generateWidgetBundleSwift(detectedWidgets) : generateDefaultWidgetBundleSwift()
 
   const widgetBundlePath = path.join(targetPath, 'VoltraWidgetBundle.swift')
   fs.writeFileSync(widgetBundlePath, widgetBundleContent)
@@ -263,9 +280,23 @@ function iosWidgetGalleryLabelSwiftExpr(
 }
 
 /**
- * Generates Swift code for a single widget struct
+ * Generates Swift code for a single widget struct. Dispatches on rendering mode:
+ *  - server-rendered → `VoltraHomeWidgetProvider` + `VoltraHomeWidgetView` (existing path)
+ *  - Dynamic Widget → `VoltraClientWidgetProvider` + `VoltraClientWidgetContentView`
+ *    (the content view internally renders via VoltraHomeWidgetView so the UI layer is
+ *    identical to the fallback state path — see VoltraClientWidgetRuntime.swift)
  */
-function generateWidgetStruct(widget: IOSWidgetConfig): string {
+function widgetUsesAppIntent(widget: DetectedIOSWidget): boolean {
+  return widget.clientRendered && !!widget.appIntent && widget.appIntent.parameters.length > 0
+}
+
+function generateWidgetStruct(widget: DetectedIOSWidget): string {
+  // Client-rendered widgets with an appIntent config get a native "Edit Widget" sheet via
+  // AppIntentConfiguration; the configured params flow into env.configuration.
+  if (widgetUsesAppIntent(widget)) {
+    return generateClientAppIntentWidgetCode(widget)
+  }
+
   const families = widget.supportedFamilies ?? DEFAULT_WIDGET_FAMILIES
   const familiesSwift = families.map((f) => WIDGET_FAMILY_MAP[f]).join(', ')
 
@@ -275,6 +306,27 @@ function generateWidgetStruct(widget: IOSWidgetConfig): string {
   const displayNameExpr = iosWidgetGalleryLabelSwiftExpr(widget.id, 'displayName', widget.displayName)
   const descriptionExpr = iosWidgetGalleryLabelSwiftExpr(widget.id, 'description', widget.description)
 
+  const providerAndContent = widget.clientRendered
+    ? dedent`
+        provider: VoltraClientWidgetProvider(
+          widgetId: widgetId,
+          initialState: VoltraWidgetInitialStates.getInitialState(for: widgetId)
+        )
+      ) { entry in
+        VoltraClientWidgetContentView(
+          entry: entry,
+          initialState: VoltraWidgetInitialStates.getInitialState(for: widgetId)
+        )
+      }`
+    : dedent`
+        provider: VoltraHomeWidgetProvider(
+          widgetId: widgetId,
+          initialState: VoltraWidgetInitialStates.getInitialState(for: widgetId)
+        )
+      ) { entry in
+        VoltraHomeWidgetView(entry: entry)
+      }`
+
   return dedent`
     public struct ${structName}: Widget {
       private let widgetId = "${widget.id}"
@@ -284,12 +336,100 @@ function generateWidgetStruct(widget: IOSWidgetConfig): string {
       public var body: some WidgetConfiguration {
         StaticConfiguration(
           kind: "Voltra_Widget_${widget.id}",
-          provider: VoltraHomeWidgetProvider(
-            widgetId: widgetId,
+          ${providerAndContent}
+        .configurationDisplayName(${displayNameExpr})
+        .description(${descriptionExpr})
+        .supportedFamilies([${familiesSwift}])
+        .contentMarginsDisabled()
+      }
+    }
+  `
+}
+
+/**
+ * Generates a Dynamic Widget backed by AppIntentConfiguration (iOS 17+): a
+ * WidgetConfigurationIntent (params + code defaults), an AppIntentTimelineProvider that loads the
+ * bundle via the shared client runtime, and an AppIntentConfiguration widget. The configured
+ * params are passed into the render as env.configuration; the native "Edit Widget" sheet edits them.
+ */
+function generateClientAppIntentWidgetCode(widget: DetectedIOSWidget): string {
+  const params = widget.appIntent!.parameters
+  const families = widget.supportedFamilies ?? DEFAULT_WIDGET_FAMILIES
+  const familiesSwift = families.map((f) => WIDGET_FAMILY_MAP[f]).join(', ')
+  const intentName = `VoltraWidget_${widget.id}_Intent`
+  const providerName = `VoltraWidget_${widget.id}_ClientProvider`
+  const intentTitle = escapeForSwiftStringLiteral(`Configure ${widgetLabelEnglish(widget.displayName)}`)
+  const displayNameExpr = iosWidgetGalleryLabelSwiftExpr(widget.id, 'displayName', widget.displayName)
+  const descriptionExpr = iosWidgetGalleryLabelSwiftExpr(widget.id, 'description', widget.description)
+
+  const swiftDefault = (p: { default?: string }) => `"${escapeForSwiftStringLiteral(p.default ?? '')}"`
+  const dictLiteral = (entries: string[]) => (entries.length > 0 ? `[${entries.join(', ')}]` : '[:]')
+
+  const paramDecls = params
+    .map(
+      (p) =>
+        `  @Parameter(title: "${escapeForSwiftStringLiteral(p.title)}", default: ${swiftDefault(p)})\n  var ${
+          p.name
+        }: String`
+    )
+    .join('\n\n')
+  const initParams = params.map((p) => `${p.name}: String`).join(', ')
+  const initBody = params.map((p) => `    self.${p.name} = ${p.name}`).join('\n')
+  const configuredDict = dictLiteral(params.map((p) => `"${p.name}": configuration.${p.name}`))
+  const defaultDict = dictLiteral(params.map((p) => `"${p.name}": ${swiftDefault(p)}`))
+
+  return dedent`
+    // MARK: - Client-rendered AppIntent widget: ${widget.id}
+
+    @available(iOS 17.0, *)
+    struct ${intentName}: WidgetConfigurationIntent {
+      static var title: LocalizedStringResource = "${intentTitle}"
+
+    ${paramDecls}
+
+      init() {}
+      init(${initParams}) {
+    ${initBody}
+      }
+    }
+
+    @available(iOS 17.0, *)
+    private struct ${providerName}: AppIntentTimelineProvider {
+      typealias Intent = ${intentName}
+      typealias Entry = VoltraClientWidgetEntry
+
+      private let widgetId = "${widget.id}"
+
+      func placeholder(in _: Context) -> VoltraClientWidgetEntry {
+        VoltraClientWidgetEntry(date: Date(), widgetId: widgetId, bundleReady: false, configuration: ${defaultDict})
+      }
+
+      func snapshot(for configuration: ${intentName}, in _: Context) async -> VoltraClientWidgetEntry {
+        await VoltraClientWidgetProvider.loadEntry(widgetId: widgetId, configuration: ${configuredDict})
+      }
+
+      func timeline(for configuration: ${intentName}, in _: Context) async -> Timeline<VoltraClientWidgetEntry> {
+        let entry = await VoltraClientWidgetProvider.loadEntry(widgetId: widgetId, configuration: ${configuredDict})
+        return Timeline(entries: [entry], policy: .never)
+      }
+    }
+
+    @available(iOS 17.0, *)
+    public struct VoltraWidget_${widget.id}: Widget {
+      private let widgetId = "${widget.id}"
+
+      public init() {}
+
+      public var body: some WidgetConfiguration {
+        AppIntentConfiguration(
+          kind: "Voltra_Widget_${widget.id}",
+          intent: ${intentName}.self,
+          provider: ${providerName}()
+        ) { entry in
+          VoltraClientWidgetContentView(
+            entry: entry,
             initialState: VoltraWidgetInitialStates.getInitialState(for: widgetId)
           )
-        ) { entry in
-          VoltraHomeWidgetView(entry: entry)
         }
         .configurationDisplayName(${displayNameExpr})
         .description(${descriptionExpr})
@@ -303,15 +443,25 @@ function generateWidgetStruct(widget: IOSWidgetConfig): string {
 /**
  * Generates the VoltraWidgetBundle.swift file content with configured widgets
  */
-function generateWidgetBundleSwift(widgets: IOSWidgetConfig[]): string {
+function generateWidgetBundleSwift(widgets: DetectedIOSWidget[]): string {
   // Generate widget structs
-  const widgetStructs = widgets.map(generateWidgetStruct).join('\n\n')
-
-  // Generate widget bundle body entries
-  const widgetInstances = widgets.map((w) => `VoltraWidget_${w.id}()`).join('\n    ')
+  const widgetStructs = widgets.map((w) => generateWidgetStruct(w)).join('\n\n')
+
+  // AppIntent widgets are iOS 17+, so their bundle entries are gated behind #available.
+  const appIntentWidgets = widgets.filter(widgetUsesAppIntent)
+  const plainWidgets = widgets.filter((w) => !widgetUsesAppIntent(w))
+  const plainInstances = plainWidgets.map((w) => `VoltraWidget_${w.id}()`).join('\n    ')
+  const appIntentInstances =
+    appIntentWidgets.length > 0
+      ? `if #available(iOS 17.0, *) {\n      ${appIntentWidgets
+          .map((w) => `VoltraWidget_${w.id}()`)
+          .join('\n      ')}\n    }`
+      : ''
+  const widgetInstances = [plainInstances, appIntentInstances].filter(Boolean).join('\n    ')
 
   const needsFoundation = widgets.some(widgetUsesGalleryLocalization)
   const foundationImport = needsFoundation ? 'import Foundation\n' : ''
+  const appIntentsImport = appIntentWidgets.length > 0 ? 'import AppIntents\n' : ''
 
   return dedent`
     //
@@ -321,7 +471,7 @@ function generateWidgetBundleSwift(widgets: IOSWidgetConfig[]): string {
     //  This file defines which Voltra widgets are available in your app.
     //
 
-    ${foundationImport}import SwiftUI
+    ${foundationImport}${appIntentsImport}import SwiftUI
     import WidgetKit
     import VoltraWidget
 
@@ -473,4 +623,5 @@ function getSwiftRawStringDelimiter(str: string): string {
 
 export const __test__ = {
   generateInitialStatesSwift,
+  generateWidgetBundleSwift,
 }

package/expo-plugin/src/ios-widget/index.ts

@@ -54,7 +54,7 @@ export const withIOS: ConfigPlugin<WithIOSProps> = (config, props) => {
     ...(fonts && fonts.length > 0 ? [[withFonts, { fonts, targetName }] as [ConfigPlugin<any>, any]] : []),
 
     // 2. Configure Xcode project (creates the target - must run before fonts mod executes)
-    [configureXcodeProject, { targetName, bundleIdentifier, deploymentTarget }],
+    [configureXcodeProject, { targetName, bundleIdentifier, deploymentTarget, widgets }],
 
     // 3. Configure Podfile for widget extension target
     [configurePodfile, { targetName }],

package/expo-plugin/src/ios-widget/widgetPlist.ts

@@ -4,6 +4,7 @@ import { existsSync, readFileSync, writeFileSync } from 'fs'
 import { join as joinPath } from 'path'
 
 import type { IOSWidgetConfig } from '../types'
+import { detectClientRenderedWidgets } from './clientRendered'
 import { logger } from '@use-voltra/expo-plugin'
 
 export interface ConfigureMainAppPlistProps {
@@ -46,6 +47,27 @@ export const configureWidgetExtensionPlist: ConfigPlugin<ConfigureMainAppPlistPr
 
         const content = plist.parse(readFileSync(filePath, 'utf8')) as InfoPlist
 
+        // Dynamic Widgets fetch their JS bundle from Metro at
+        // http://localhost:8081 in DEBUG builds. iOS requires an ATS exception for
+        // plaintext HTTP, scoped to localhost. The keys are only added when a
+        // Dynamic Widget actually exists, so server-only configurations
+        // keep their plist minimal.
+        if (widgets && widgets.length > 0) {
+          const detected = detectClientRenderedWidgets(widgets, config.modRequest.projectRoot)
+          const hasClientWidget = detected.some((w) => w.clientRendered)
+          if (hasClientWidget) {
+            ;(content as any)['NSAppTransportSecurity'] = {
+              NSAllowsLocalNetworking: true,
+              NSExceptionDomains: {
+                localhost: {
+                  NSExceptionAllowsInsecureHTTPLoads: true,
+                  NSIncludesSubdomains: true,
+                },
+              },
+            }
+          }
+        }
+
         // WidgetKit extensions must NOT declare NSExtensionPrincipalClass/MainStoryboard.
         // The @main WidgetBundle in Swift is the entry point.
         const ext = (content as any).NSExtension as Record<string, any> | undefined

package/expo-plugin/src/ios-widget/xcode/buildPhases.ts

@@ -5,6 +5,99 @@ import type { IOSWidgetExtensionFiles } from '../../types'
 
 const pbxFile = require('xcode/lib/pbxFile')
 
+const WIDGET_BUNDLE_PHASE_NAME = 'Bundle Voltra Dynamic Widgets'
+
+// Release-only build phase that bakes each Dynamic Widget's production JS bundle into the
+// extension's resources. Debug builds fetch from Metro (and hot-reload), so this no-ops there. Runs
+// the project's widget bundler with the extension's resources dir as the output, so each
+// voltra-widget-<id>.bundle lands in the .appex (Bundle.main) where the runtime's release loader
+// reads it. SRCROOT is the ios/ dir; the project root is one level up, matching how Expo's main
+// "Bundle React Native code and images" phase resolves things.
+const WIDGET_BUNDLE_SHELL_SCRIPT = `if [[ "$CONFIGURATION" == *Debug* ]]; then
+  echo "Voltra: Debug build — Dynamic Widgets load from Metro, skipping bundling"
+  exit 0
+fi
+
+if [[ -f "$SRCROOT/.xcode.env" ]]; then
+  source "$SRCROOT/.xcode.env"
+fi
+if [[ -f "$SRCROOT/.xcode.env.local" ]]; then
+  source "$SRCROOT/.xcode.env.local"
+fi
+
+export PROJECT_ROOT="\${PROJECT_ROOT:-$SRCROOT/..}"
+NODE_BINARY="\${NODE_BINARY:-node}"
+
+BUNDLER="$("$NODE_BINARY" - "$PROJECT_ROOT" <<'NODE'
+const { createRequire } = require('node:module')
+const path = require('node:path')
+
+const projectRoot = process.argv[2]
+const requireFromProject = createRequire(path.join(projectRoot, 'package.json'))
+
+try {
+  const resolved = requireFromProject.resolve('@use-voltra/metro/bundle-widgets')
+  process.stdout.write(resolved)
+} catch (error) {
+  console.error(
+    'error: Voltra widget bundler could not resolve @use-voltra/metro from ' +
+      projectRoot +
+      '. Install @use-voltra/metro in the app project so release widgets can be baked.'
+  )
+  console.error(error && error.message ? error.message : String(error))
+  process.exit(1)
+}
+NODE
+)"
+if [[ -z "$BUNDLER" ]]; then
+  echo "Voltra: resolver returned an empty string for @use-voltra/metro/bundle-widgets" >&2
+  exit 1
+fi
+
+echo "Voltra: widget bundler resolved to $BUNDLER"
+"$NODE_BINARY" "$BUNDLER" --out-dir "$TARGET_BUILD_DIR/$UNLOCALIZED_RESOURCES_FOLDER_PATH" --platform ios --project-root "$PROJECT_ROOT"
+`
+
+/**
+ * Adds (idempotently) the release-only shell-script phase that bakes Dynamic Widget
+ * bundles into the extension. Safe to call on every prebuild; only added when absent.
+ */
+export function ensureWidgetBundleScriptPhase(xcodeProject: XcodeProject, targetUuid: string): void {
+  const nativeTargets = xcodeProject.pbxNativeTargetSection()
+  const target = nativeTargets[targetUuid]
+  if (!target) {
+    return
+  }
+  if (!target.buildPhases) {
+    target.buildPhases = []
+  }
+
+  const shellPhases = xcodeProject.hash.project.objects.PBXShellScriptBuildPhase || {}
+  const quotedName = `"${WIDGET_BUNDLE_PHASE_NAME}"`
+  const alreadyPresent = target.buildPhases.some((entry: any) => shellPhases[entry.value]?.name === quotedName)
+  if (alreadyPresent) {
+    return
+  }
+
+  xcodeProject.addBuildPhase([], 'PBXShellScriptBuildPhase', WIDGET_BUNDLE_PHASE_NAME, targetUuid, {
+    shellPath: '/bin/sh',
+    shellScript: WIDGET_BUNDLE_SHELL_SCRIPT,
+  })
+
+  // The phase intentionally re-bakes on every release build (it can't statically enumerate every
+  // widget source as an input). Mark it always-out-of-date so Xcode doesn't warn about the missing
+  // input/output dependencies.
+  const shellPhasesAfter = xcodeProject.hash.project.objects.PBXShellScriptBuildPhase || {}
+  for (const key of Object.keys(shellPhasesAfter)) {
+    if (/_comment$/.test(key)) {
+      continue
+    }
+    if (shellPhasesAfter[key]?.name === quotedName) {
+      shellPhasesAfter[key].alwaysOutOfDate = 1
+    }
+  }
+}
+
 export interface AddBuildPhasesOptions {
   targetUuid: string
   groupName: string

package/expo-plugin/src/ios-widget/xcode/index.ts

@@ -1,8 +1,10 @@
 import { ConfigPlugin, withXcodeProject } from '@expo/config-plugins'
 import * as path from 'path'
 
+import type { IOSWidgetConfig } from '../../types'
 import { getIOSWidgetExtensionFiles } from '../../utils/fileDiscovery'
-import { addBuildPhases, ensureBuildPhases } from './buildPhases'
+import { detectClientRenderedWidgets } from '../clientRendered'
+import { addBuildPhases, ensureBuildPhases, ensureWidgetBundleScriptPhase } from './buildPhases'
 import { addXCConfigurationList, ensureXCConfigurationList } from './configurationList'
 import { addPbxGroup, ensurePbxGroup } from './groups'
 import { getMainAppTargetSettings } from './mainAppSettings'
@@ -13,6 +15,7 @@ export interface ConfigureXcodeProjectProps {
   targetName: string
   bundleIdentifier: string
   deploymentTarget: string
+  widgets?: IOSWidgetConfig[]
 }
 
 /**
@@ -28,7 +31,7 @@ export interface ConfigureXcodeProjectProps {
  * This should run after generateWidgetExtensionFiles so the files exist.
  */
 export const configureXcodeProject: ConfigPlugin<ConfigureXcodeProjectProps> = (config, props) => {
-  const { targetName, bundleIdentifier, deploymentTarget } = props
+  const { targetName, bundleIdentifier, deploymentTarget, widgets } = props
 
   return withXcodeProject(config, (config) => {
     if (config.modRequest.introspect) {
@@ -38,6 +41,12 @@ export const configureXcodeProject: ConfigPlugin<ConfigureXcodeProjectProps> = (
     const xcodeProject = config.modResults
     const groupName = 'Embed Foundation Extensions'
 
+    // The release widget-bundling phase is only needed when a widget is a Dynamic Widget (server
+    // widgets carry no JS bundle). Detect once so both the create and update paths agree.
+    const hasClientRenderedWidgets =
+      !!widgets &&
+      detectClientRenderedWidgets(widgets, config.modRequest.projectRoot).some((widget) => widget.clientRendered)
+
     // Check if target already exists
     const nativeTargets = xcodeProject.pbxNativeTargetSection()
     const existingTargetKey = xcodeProject.findTargetKey(targetName)
@@ -93,6 +102,10 @@ export const configureXcodeProject: ConfigPlugin<ConfigureXcodeProjectProps> = (
         mainTargetUuid: xcodeProject.getFirstTarget().uuid,
       })
 
+      if (hasClientRenderedWidgets) {
+        ensureWidgetBundleScriptPhase(xcodeProject, existingTargetKey)
+      }
+
       ensurePbxGroup(xcodeProject, {
         targetName,
         widgetFiles,
@@ -138,6 +151,10 @@ export const configureXcodeProject: ConfigPlugin<ConfigureXcodeProjectProps> = (
       widgetFiles,
     })
 
+    if (hasClientRenderedWidgets) {
+      ensureWidgetBundleScriptPhase(xcodeProject, targetUuid)
+    }
+
     // Add PBX group
     addPbxGroup(xcodeProject, {
       targetName,