diff --git a/.changeset/client-rendered-widgets-android-experimental.md b/.changeset/client-rendered-widgets-android-experimental.md
new file mode 100644
index 00000000..8486dc9d
--- /dev/null
+++ b/.changeset/client-rendered-widgets-android-experimental.md
@@ -0,0 +1,20 @@
+---
+'@use-voltra/android-client': minor
+---
+
+**Experimental: client-rendered widgets (Android).** A widget component marked with the
+`'use voltra'` directive now renders on-device in a standalone Hermes runtime, called as
+`(props, env) => JSX` on every render, so it reacts to live environment values (widget size, color
+scheme, locale, and configuration). Material You dynamic colors are consumed via
+`AndroidDynamicColors` tokens that the native renderer resolves to the system color scheme (and that
+follow light/dark automatically). In development the bundle is served by Metro and editing the JSX
+hot-reloads the pinned widget; in release builds the bundle is baked into the app's assets at build
+time.
+
+Configuration parameters declared in `app.json` (`appIntent.parameters`, with code-defined
+defaults) surface as `env.configuration`; runtime values set via `setWidgetConfiguration` override
+the defaults (Android has no system widget-configuration UI, so this is an in-app stand-in).
+
+This feature is **experimental** — usable in production at your own risk; the API and generated
+build output may change. Release rendering has been verified on the Android emulator (the baked
+bundle renders on-device with Metro stopped); confirming on a physical device is still recommended.
diff --git a/.changeset/client-rendered-widgets-experimental.md b/.changeset/client-rendered-widgets-experimental.md
new file mode 100644
index 00000000..f64459cf
--- /dev/null
+++ b/.changeset/client-rendered-widgets-experimental.md
@@ -0,0 +1,14 @@
+---
+'@use-voltra/ios-client': minor
+---
+
+**Experimental: client-rendered widgets (iOS).** A widget component marked with the `'use voltra'`
+directive now renders on-device from its own JS bundle, called as `(props, env) => JSX` on every
+render, so it reacts to live environment values (widget family, color scheme, locale, and
+user-editable `configuration` via a native AppIntent "Edit Widget" sheet). In development the
+bundle is served by Metro and editing the JSX hot-reloads the home-screen widget; in release builds
+the bundle is baked into the widget extension at build time.
+
+This feature is **experimental** — usable in production at your own risk; the API and generated
+build output may change. Verify release rendering on a real device (the iOS Simulator is unreliable
+for widget rendering).
diff --git a/.changeset/twelve-widgets-walk.md b/.changeset/twelve-widgets-walk.md
new file mode 100644
index 00000000..ca2c896a
--- /dev/null
+++ b/.changeset/twelve-widgets-walk.md
@@ -0,0 +1,7 @@
+---
+'@use-voltra/compiler': minor
+'@use-voltra/ios-client': minor
+'@use-voltra/metro': minor
+---
+
+Add the Voltra compiler package for shared directive scanning, wire Metro and iOS prebuild validation to it, and keep the Metro scanner subpath as a re-export.
diff --git a/.gitignore b/.gitignore
index 34294cb3..7df4354e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -49,4 +49,5 @@ npm-debug.log
 
 ## Build
 /build
-/packages/ios-client/ios/.build/
+# SPM build caches under any iOS package (ios-client, voltra, etc.)
+/packages/*/ios/.build/
diff --git a/example/.gitignore b/example/.gitignore
index d0e12830..aa83371d 100644
--- a/example/.gitignore
+++ b/example/.gitignore
@@ -20,6 +20,7 @@ expo-env.d.ts
 
 # Metro
 .metro-health-check*
+.voltra/
 
 # debug
 npm-debug.*
@@ -37,4 +38,4 @@ yarn-error.*
 *.tsbuildinfo
 
 /ios
-/android
\ No newline at end of file
+/android
diff --git a/example/app.json b/example/app.json
index 752d545d..b09bb2b9 100644
--- a/example/app.json
+++ b/example/app.json
@@ -49,6 +49,29 @@
                 "pl": "./widgets/ios/ios-weather-initial.tsx"
               }
             },
+            {
+              "id": "ClientRenderedDemoWidget",
+              "entry": "./widgets/ios/ClientRenderedDemoWidget.tsx",
+              "displayName": {
+                "en": "Client-Rendered Demo",
+                "pl": "Client-Rendered Demo"
+              },
+              "description": {
+                "en": "Plain widget showing env values — for verifying client-rendered hot reload.",
+                "pl": "Prosty widget pokazujący wartości env — do weryfikacji hot reload."
+              },
+              "supportedFamilies": ["systemSmall", "systemMedium", "systemLarge"],
+              "initialStatePath": "./widgets/ios/ClientRenderedDemoWidget.tsx",
+              "appIntent": {
+                "parameters": [
+                  {
+                    "name": "label",
+                    "title": "Label",
+                    "default": "Hello"
+                  }
+                ]
+              }
+            },
             {
               "id": "portfolio",
               "displayName": {
@@ -204,6 +227,32 @@
                 "intervalMinutes": 15,
                 "refresh": true
               }
+            },
+            {
+              "id": "AndroidClientDemoWidget",
+              "entry": "./widgets/android/AndroidClientDemoWidget.tsx",
+              "displayName": {
+                "en": "Client Demo"
+              },
+              "description": {
+                "en": "Client-rendered Voltra widget (on-device Hermes)"
+              },
+              "minCellWidth": 2,
+              "minCellHeight": 2,
+              "targetCellWidth": 2,
+              "targetCellHeight": 2,
+              "resizeMode": "horizontal|vertical",
+              "widgetCategory": "home_screen",
+              "initialStatePath": "./widgets/android/AndroidClientDemoWidget.tsx",
+              "appIntent": {
+                "parameters": [
+                  {
+                    "name": "label",
+                    "title": "Label",
+                    "default": "Hello"
+                  }
+                ]
+              }
             }
           ],
           "fonts": [
diff --git a/example/app/_layout.tsx b/example/app/_layout.tsx
index 5b9e45a4..20b3dee1 100644
--- a/example/app/_layout.tsx
+++ b/example/app/_layout.tsx
@@ -1,10 +1,19 @@
 import { Stack } from 'expo-router'
+import { Platform } from 'react-native'
 import { SafeAreaProvider } from 'react-native-safe-area-context'
+import { enableWidgetHotReload as enableIosWidgetHotReload } from '@use-voltra/ios-client'
+import { enableWidgetHotReload as enableAndroidWidgetHotReload } from '@use-voltra/android-client'
+import '@use-voltra/widget-hot-reload'
 
 import { useVoltraEvents } from '~/hooks/useVoltraEvents'
 import { useServerDrivenWidgetToken } from '~/hooks/useServerDrivenWidgetToken'
 import { updateAndroidVoltraWidget } from '~/widgets/android/updateAndroidVoltraWidget'
 
+if (Platform.OS === 'android') {
+  enableAndroidWidgetHotReload()
+} else {
+  enableIosWidgetHotReload()
+}
 updateAndroidVoltraWidget({ width: 300, height: 200 })
 
 const STACK_SCREEN_OPTIONS = {
diff --git a/example/metro.config.js b/example/metro.config.js
new file mode 100644
index 00000000..7faad9a8
--- /dev/null
+++ b/example/metro.config.js
@@ -0,0 +1,23 @@
+const path = require('node:path')
+
+const { getDefaultConfig } = require('expo/metro-config')
+const { withVoltra } = require('@use-voltra/metro')
+
+const config = getDefaultConfig(__dirname)
+const repoRoot = path.resolve(__dirname, '..')
+
+config.resolver.extraNodeModules = {
+  ...config.resolver.extraNodeModules,
+  '@use-voltra/android': path.join(repoRoot, 'packages/android'),
+  '@use-voltra/android-client': path.join(repoRoot, 'packages/android-client'),
+  '@use-voltra/core': path.join(repoRoot, 'packages/core'),
+  '@use-voltra/expo-plugin': path.join(repoRoot, 'packages/expo-plugin'),
+  '@use-voltra/ios': path.join(repoRoot, 'packages/ios'),
+  '@use-voltra/ios-client': path.join(repoRoot, 'packages/ios-client'),
+  '@use-voltra/server': path.join(repoRoot, 'packages/server'),
+  '~': __dirname,
+}
+
+config.watchFolders = Array.from(new Set([...(config.watchFolders || []), path.join(repoRoot, 'packages')]))
+
+module.exports = withVoltra(config)
diff --git a/example/package.json b/example/package.json
index 23ea1d9f..7095fd19 100644
--- a/example/package.json
+++ b/example/package.json
@@ -51,6 +51,7 @@
     "react-native-web": "^0.21.0",
     "react-native-webview": "13.16.0",
     "react-native-worklets": "~0.7.0",
+    "@use-voltra/metro": "workspace:*",
     "@use-voltra/ios": "workspace:*",
     "@use-voltra/ios-client": "workspace:*",
     "@use-voltra/android": "workspace:*",
diff --git a/example/screens/android/AndroidWidgetPinScreen.tsx b/example/screens/android/AndroidWidgetPinScreen.tsx
index f2771085..6cc24f74 100644
--- a/example/screens/android/AndroidWidgetPinScreen.tsx
+++ b/example/screens/android/AndroidWidgetPinScreen.tsx
@@ -1,7 +1,7 @@
 import { useRouter } from 'expo-router'
 import React, { useState } from 'react'
 import { Alert, Platform, StyleSheet, Text, TextInput, View } from 'react-native'
-import { requestPinAndroidWidget } from '@use-voltra/android-client'
+import { requestPinAndroidWidget, setWidgetConfiguration } from '@use-voltra/android-client'
 
 import { Button } from '~/components/Button'
 import { ScreenLayout } from '~/components/ScreenLayout'
@@ -28,6 +28,13 @@ const AVAILABLE_WIDGETS = [
     defaultPreviewWidth: 250,
     defaultPreviewHeight: 150,
   },
+  {
+    id: 'AndroidClientDemoWidget',
+    name: 'Client-Rendered Demo',
+    description: 'On-device JSX render (Hermes) with live env',
+    defaultPreviewWidth: 250,
+    defaultPreviewHeight: 150,
+  },
 ]
 
 export default function AndroidWidgetPinScreen() {
@@ -36,6 +43,19 @@ export default function AndroidWidgetPinScreen() {
   const [previewWidth, setPreviewWidth] = useState<string>('250')
   const [previewHeight, setPreviewHeight] = useState<string>('150')
   const [isPinning, setIsPinning] = useState(false)
+  const [configLabel, setConfigLabel] = useState<string>('')
+
+  const handleSetConfig = async () => {
+    if (Platform.OS !== 'android') {
+      return
+    }
+    try {
+      await setWidgetConfiguration(selectedWidgetId, 'label', configLabel)
+      Alert.alert('Saved', `Set config "label" = "${configLabel}" for ${selectedWidgetId}. The widget re-renders.`)
+    } catch (error: any) {
+      Alert.alert('Error', error?.message || String(error))
+    }
+  }
 
   const selectedWidget = AVAILABLE_WIDGETS.find((w) => w.id === selectedWidgetId) || AVAILABLE_WIDGETS[0]
 
@@ -110,6 +130,22 @@ export default function AndroidWidgetPinScreen() {
         ))}
       </View>
 
+      <View style={styles.section}>
+        <Text style={styles.sectionTitle}>Configuration (client-rendered)</Text>
+        <View style={styles.inputGroup}>
+          <Text style={styles.inputLabel}>env.configuration.label</Text>
+          <TextInput
+            style={styles.input}
+            value={configLabel}
+            onChangeText={setConfigLabel}
+            placeholder="label value"
+            placeholderTextColor="#64748B"
+            autoCapitalize="none"
+          />
+        </View>
+        <Button title="Set configuration" onPress={handleSetConfig} style={styles.resetButton} />
+      </View>
+
       <View style={styles.section}>
         <Text style={styles.sectionTitle}>Preview Dimensions (optional)</Text>
         <View style={styles.previewInputs}>
diff --git a/example/widgets/android/AndroidClientDemoWidget.tsx b/example/widgets/android/AndroidClientDemoWidget.tsx
new file mode 100644
index 00000000..9ee9c477
--- /dev/null
+++ b/example/widgets/android/AndroidClientDemoWidget.tsx
@@ -0,0 +1,69 @@
+import { AndroidDynamicColors, VoltraAndroid, type WidgetEnvironment } from '@use-voltra/android'
+
+// Minimal Dynamic Widget example for Android: its JSX runs on-device in Hermes on every render,
+// receiving the live `env`. Edit the marker literal below and save — the home-screen widget
+// updates via Fast Refresh (dev). Mirrors the iOS ClientRenderedDemoWidget. Themes itself from
+// Material You via AndroidDynamicColors tokens, which the native renderer resolves to the system
+// dynamic color scheme (and which follow light/dark automatically).
+
+export default function AndroidClientDemoWidget(_props: object, env: WidgetEnvironment = {} as WidgetEnvironment) {
+  // ▼ EDIT THIS LITERAL TO TEST HOT RELOAD ▼
+  const hotReloadMarker = 'edit me'
+
+  const date = env.date ? new Date(env.date) : new Date()
+  const renderedAt = date.toLocaleTimeString('en-US', {
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hour12: false,
+  })
+
+  const config = env.configuration as Record<string, unknown> | undefined
+  const configLabel = typeof config?.label === 'string' ? config.label : '(unset)'
+
+  // Material You tokens — resolved natively from the system dynamic color scheme.
+  const bg = AndroidDynamicColors.surface
+  const fg = AndroidDynamicColors.onSurface
+  const muted = AndroidDynamicColors.onSurfaceVariant
+  const accent = AndroidDynamicColors.primary
+
+  const label = { fontSize: 10, color: muted } as const
+  const value = { fontSize: 10, color: fg } as const
+
+  const row = (k: string, v: string) => (
+    <VoltraAndroid.Row>
+      <VoltraAndroid.Text style={label}>{k} </VoltraAndroid.Text>
+      <VoltraAndroid.Text style={value}>{v}</VoltraAndroid.Text>
+    </VoltraAndroid.Row>
+  )
+
+  const swatch = (color: string) => (
+    <VoltraAndroid.Box style={{ width: 16, height: 16, backgroundColor: color, cornerRadius: 4 }} />
+  )
+
+  return (
+    <VoltraAndroid.Column
+      style={{ backgroundColor: bg, width: '100%', height: '100%', padding: 12 }}
+      verticalAlignment="center-vertically"
+    >
+      <VoltraAndroid.Text style={{ fontSize: 12, color: fg }}>Client-rendered demo</VoltraAndroid.Text>
+      <VoltraAndroid.Text style={{ fontSize: 14, color: accent }}>{hotReloadMarker}</VoltraAndroid.Text>
+      <VoltraAndroid.Spacer style={{ height: 6 }} />
+      {row('size:', env.widgetFamily ?? '?')}
+      {row('scheme:', env.colorScheme ?? '?')}
+      {row('locale:', env.locale ?? '?')}
+      {row('config:', configLabel)}
+      {row('time:', renderedAt)}
+      <VoltraAndroid.Spacer style={{ height: 8 }} />
+      <VoltraAndroid.Row>
+        {swatch(AndroidDynamicColors.primary)}
+        <VoltraAndroid.Spacer style={{ width: 6 }} />
+        {swatch(AndroidDynamicColors.secondary)}
+        <VoltraAndroid.Spacer style={{ width: 6 }} />
+        {swatch(AndroidDynamicColors.tertiary)}
+        <VoltraAndroid.Spacer style={{ width: 6 }} />
+        {swatch(AndroidDynamicColors.error)}
+      </VoltraAndroid.Row>
+    </VoltraAndroid.Column>
+  )
+}
diff --git a/example/widgets/ios/ClientRenderedDemoWidget.tsx b/example/widgets/ios/ClientRenderedDemoWidget.tsx
new file mode 100644
index 00000000..80a6ec49
--- /dev/null
+++ b/example/widgets/ios/ClientRenderedDemoWidget.tsx
@@ -0,0 +1,63 @@
+import { Voltra, type WidgetEnvironment } from '@use-voltra/ios'
+
+// Minimal Dynamic Widget example for verifying the dev loop.
+//
+// Plain black tile with the env values the runtime captured per render, plus a single
+// editable literal (`hotReloadMarker` below) for proving hot reload end-to-end.
+// Edit the literal, save, watch the home-screen widget update within ~1 second.
+
+export default function ClientRenderedDemoWidget(_props: object, env: WidgetEnvironment = {} as WidgetEnvironment) {
+  // ▼ EDIT THIS LITERAL TO TEST HOT RELOAD ▼
+  const hotReloadMarker = 'edit me'
+
+  const date = env.date ? new Date(env.date) : new Date()
+  const renderedAt = date.toLocaleTimeString('en-US', {
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hour12: false,
+  })
+
+  const config = env.configuration as Record<string, unknown> | undefined
+  const configLabel = typeof config?.label === 'string' ? config.label : '(unset)'
+
+  const labelStyle = { fontSize: 9, color: '#FFFFFF' } as const
+  const valueStyle = { fontSize: 9, color: '#94A3B8' } as const
+
+  return (
+    <Voltra.VStack alignment="leading" spacing={4} style={{ flex: 1, padding: 12, backgroundColor: '#000000' }}>
+      <Voltra.Text style={{ fontSize: 11, fontWeight: '700', color: '#FFFFFF' }}>Client-rendered demo</Voltra.Text>
+
+      <Voltra.Text style={{ fontSize: 14, fontWeight: '600', color: '#34D399' }}>{hotReloadMarker}</Voltra.Text>
+
+      <Voltra.HStack spacing={4}>
+        <Voltra.Text style={labelStyle}>family:</Voltra.Text>
+        <Voltra.Text style={valueStyle}>{env.widgetFamily ?? '?'}</Voltra.Text>
+      </Voltra.HStack>
+      <Voltra.HStack spacing={4}>
+        <Voltra.Text style={labelStyle}>scheme:</Voltra.Text>
+        <Voltra.Text style={valueStyle}>{env.colorScheme ?? '?'}</Voltra.Text>
+      </Voltra.HStack>
+      <Voltra.HStack spacing={4}>
+        <Voltra.Text style={labelStyle}>mode:</Voltra.Text>
+        <Voltra.Text style={valueStyle}>{env.widgetRenderingMode ?? '?'}</Voltra.Text>
+      </Voltra.HStack>
+      <Voltra.HStack spacing={4}>
+        <Voltra.Text style={labelStyle}>locale:</Voltra.Text>
+        <Voltra.Text style={valueStyle}>{env.locale ?? '?'}</Voltra.Text>
+      </Voltra.HStack>
+      <Voltra.HStack spacing={4}>
+        <Voltra.Text style={labelStyle}>config:</Voltra.Text>
+        <Voltra.Text style={valueStyle}>{configLabel}</Voltra.Text>
+      </Voltra.HStack>
+      <Voltra.HStack spacing={4}>
+        <Voltra.Text style={labelStyle}>dev:</Voltra.Text>
+        <Voltra.Text style={valueStyle}>{String(env.build?.isDev ?? '?')}</Voltra.Text>
+      </Voltra.HStack>
+      <Voltra.HStack spacing={4}>
+        <Voltra.Text style={labelStyle}>time:</Voltra.Text>
+        <Voltra.Text style={valueStyle}>{renderedAt}</Voltra.Text>
+      </Voltra.HStack>
+    </Voltra.VStack>
+  )
+}
diff --git a/packages/android-client/README.md b/packages/android-client/README.md
index f275ff1a..7e9feaa0 100644
--- a/packages/android-client/README.md
+++ b/packages/android-client/README.md
@@ -10,6 +10,8 @@
 
 - **Home Screen widgets**: Update, reload, pin, and query widgets with `updateAndroidWidget`, `reloadAndroidWidgets`, `getActiveWidgets`, and more.
 
+- **Dynamic Widgets** _(experimental)_: Declare a widget in app.json with an `id` and `entry`, default-export the widget module, and render it on-device with live env (size, color scheme, Material You colors, locale, configuration).
+
 - **Ongoing notifications**: Start and update promoted ongoing notifications with `useAndroidOngoingNotification` and related APIs.
 
 - **Fast Refresh**: Previews integrate with your React Native dev workflow via `VoltraWidgetPreview` and `VoltraView`.
@@ -18,7 +20,28 @@
 
 - **Server-driven widgets**: Store credentials for background widget fetches with `setWidgetServerCredentials`.
 
-- **Expo config plugin**: Add `"@use-voltra/android-client"` to `app.json` to register widgets, optional notifications, and build-time initial states.
+- **Expo config plugin**: Add `"@use-voltra/android-client"` to `app.json` to declare widgets, optional notifications, and build-time initial states.
+
+## Dynamic Widgets (experimental)
+
+> [!WARNING]
+> Dynamic Widgets are **experimental** — usable in production at your own risk. The API may
+> change between releases.
+
+Declare the widget in app.json with a stable `id` and a project-relative `entry` path. The entry
+module must default-export the widget function or component; the exported name does not need to
+match the widget id. The widget renders on-device, so it can react to live environment values
+(size, color scheme, Material You `materialColors`, locale, and `configuration`).
+
+Configuration parameters declared in `app.json` (`appIntent.parameters`, with code-defined
+defaults) surface as `env.configuration`. Android has no system-managed widget configuration UI
+(unlike iOS's Edit Widget), so runtime values are set in-app via `setWidgetConfiguration` and
+override the declared defaults.
+
+Notes:
+
+- iOS and Android widget declarations stay separate, and the same widget id can exist on both platforms as separate entries.
+- Verify release rendering on a **real device** — emulators are unreliable for widget rendering.
 
 ## Documentation
 
@@ -26,7 +49,7 @@ The documentation is available at [use-voltra.dev](https://use-voltra.dev). Rele
 
 - [Installation](https://use-voltra.dev/getting-started/installation)
 - [Android Setup](https://use-voltra.dev/android/setup)
-- [Developing Widgets](https://use-voltra.dev/android/development/developing-widgets)
+- [Developing Dynamic Widgets](https://use-voltra.dev/android/development/dynamic-widgets)
 - [Managing Ongoing Notifications](https://use-voltra.dev/android/development/managing-ongoing-notifications)
 - [Plugin Configuration](https://use-voltra.dev/android/api/plugin-configuration)
 
diff --git a/packages/android-client/android/CMakeLists.txt b/packages/android-client/android/CMakeLists.txt
new file mode 100644
index 00000000..ce0f06c1
--- /dev/null
+++ b/packages/android-client/android/CMakeLists.txt
@@ -0,0 +1,33 @@
+cmake_minimum_required(VERSION 3.13)
+project(voltra)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# React Native publishes JSI + Hermes via Prefab modules in their AARs.
+# We consume them through find_package below.
+#
+# NOTE: find_package does NOT error on a wrong target *name* — the failure only
+# surfaces at target_link_libraries. The correct Hermes prefab target on Android
+# (RN 0.83, com.facebook.react:hermes-android) is `hermes-engine::hermesvm`.
+find_package(ReactAndroid REQUIRED CONFIG)
+find_package(hermes-engine REQUIRED CONFIG)
+find_package(fbjni REQUIRED CONFIG)
+
+# ---------------------------------------------------------------------------
+# Voltra JS Renderer (client-rendered widgets on Android)
+# ---------------------------------------------------------------------------
+# Standalone Hermes runtime owned by Voltra, independent of the React Native
+# bridge. Evaluates a per-widget Metro bundle that exposes `render(props, env)`
+# and invokes it on every Glance render. JNI surface in voltra_js_renderer.cpp.
+add_library(voltra_js_renderer SHARED
+  src/main/cpp/voltra_js_renderer.cpp
+)
+
+target_link_libraries(voltra_js_renderer
+  android
+  log
+  ReactAndroid::jsi
+  hermes-engine::hermesvm
+  fbjni::fbjni
+)
\ No newline at end of file
diff --git a/packages/android-client/android/build.gradle b/packages/android-client/android/build.gradle
index b020d862..a7038005 100644
--- a/packages/android-client/android/build.gradle
+++ b/packages/android-client/android/build.gradle
@@ -39,11 +39,39 @@ android {
     versionCode 1
     versionName "0.1.0"
     buildConfigField "String", "VOLTRA_VERSION", "\"${voltraVersion}\""
+
+    // Standalone Hermes runtime for client-rendered widgets, via custom JNI.
+    // See CMakeLists.txt / src/main/cpp/voltra_js_renderer.cpp.
+    externalNativeBuild {
+      cmake {
+        cppFlags "-std=c++17", "-fexceptions", "-frtti"
+        arguments "-DANDROID_STL=c++_shared"
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
   }
 
   buildFeatures {
     buildConfig true
     compose true
+    // Required to consume React Native's published prefab modules (jsi, hermesvm, fbjni).
+    prefab true
+  }
+
+  packagingOptions {
+    // These .so files are already provided by the host app's React Native runtime;
+    // bundling Voltra's copies would cause duplicate-library conflicts at install time.
+    excludes += [
+      "**/libreact_nativemodule_core.so",
+      "**/libfbjni.so",
+      "**/libjsi.so",
+      "**/libhermes.so",
+    ]
   }
 
   lintOptions {
@@ -67,6 +95,11 @@ android {
 dependencies {
   // React Native
   implementation "com.facebook.react:react-android"
+  // Provides the `hermes-engine` prefab (libhermesvm) that CMakeLists.txt's
+  // find_package(hermes-engine) consumes for the standalone Hermes JS runtime. Without it the
+  // native build fails to configure in release variants (react-android alone does not publish the
+  // Hermes prefab). Version is substituted by the React Native Gradle Plugin (applied above).
+  implementation "com.facebook.react:hermes-android"
 
   // Jetpack Glance
   api "androidx.glance:glance:1.2.0-rc01"
@@ -75,6 +108,10 @@ dependencies {
   // Compose runtime (required for Glance)
   api "androidx.compose.runtime:runtime:1.6.8"
 
+  // Material3 — used to read Material You dynamic color tokens for client widgets'
+  // env.materialColors (dynamicLightColorScheme / dynamicDarkColorScheme).
+  implementation "androidx.compose.material3:material3:1.3.2"
+
   // WorkManager (for periodic server-driven widget updates)
   api "androidx.work:work-runtime-ktx:2.9.1"
 
diff --git a/packages/android-client/android/src/main/cpp/voltra_js_renderer.cpp b/packages/android-client/android/src/main/cpp/voltra_js_renderer.cpp
new file mode 100644
index 00000000..6cf5358b
--- /dev/null
+++ b/packages/android-client/android/src/main/cpp/voltra_js_renderer.cpp
@@ -0,0 +1,186 @@
+// Voltra JS Renderer — Hermes-on-Android JNI wrapper for client-rendered widgets.
+//
+// Owns a single standalone Hermes runtime per process, independent of the React
+// Native bridge. Each per-widget Metro bundle is evaluated once; the evaluation
+// captures the bundle's `render(props, env)` export under
+// `globalThis.__voltraWidgets[<widgetId>]` (the capture bootstrap is appended on
+// the Kotlin side, mirroring iOS `VoltraJSRenderer.swift`). `nativeRender` then
+// invokes that function on every Glance render.
+//
+// Architectural mirror of iOS's VoltraJSRenderer.swift (JSC), one layer lower at
+// the JNI boundary because Android has no Kotlin/Java Hermes API.
+
+#include <jni.h>
+#include <android/log.h>
+
+#include <hermes/hermes.h>
+#include <jsi/jsi.h>
+
+#include <chrono>
+#include <memory>
+#include <mutex>
+#include <string>
+
+#define LOG_TAG "VoltraJSRenderer"
+#define LOGI(...) __android_log_print(ANDROID_LOG_INFO, LOG_TAG, __VA_ARGS__)
+#define LOGE(...) __android_log_print(ANDROID_LOG_ERROR, LOG_TAG, __VA_ARGS__)
+
+// Perf timing logs — debug builds only (release CMake defines NDEBUG).
+#ifndef NDEBUG
+#define LOGPERF(...) __android_log_print(ANDROID_LOG_INFO, LOG_TAG, __VA_ARGS__)
+#else
+#define LOGPERF(...) ((void)0)
+#endif
+
+namespace jsi = facebook::jsi;
+
+namespace {
+
+using Clock = std::chrono::steady_clock;
+
+double millisSince(Clock::time_point start) {
+  return std::chrono::duration<double, std::milli>(Clock::now() - start).count();
+}
+
+std::mutex g_mutex;
+std::unique_ptr<jsi::Runtime> g_runtime;
+
+jsi::Runtime &runtime() {
+  if (!g_runtime) {
+    g_runtime = facebook::hermes::makeHermesRuntime();
+    LOGI("standalone Hermes runtime created");
+  }
+  return *g_runtime;
+}
+
+std::string jstringToStd(JNIEnv *env, jstring jstr) {
+  if (jstr == nullptr) {
+    return {};
+  }
+  const char *chars = env->GetStringUTFChars(jstr, nullptr);
+  std::string out(chars);
+  env->ReleaseStringUTFChars(jstr, chars);
+  return out;
+}
+
+} // namespace
+
+// Evaluate a (Kotlin-wrapped) widget bundle and verify the capture bootstrap
+// registered `globalThis.__voltraWidgets[<widgetId>].render`. Returns false on
+// any JS error or if the render function was not captured.
+extern "C" JNIEXPORT jboolean JNICALL
+Java_voltra_runtime_VoltraJSRenderer_nativeEvaluateBundle(
+    JNIEnv *env, jobject /* this */, jstring jWrappedSource, jstring jSourceURL,
+    jstring jWidgetId) {
+  std::lock_guard<std::mutex> lock(g_mutex);
+  try {
+    const std::string source = jstringToStd(env, jWrappedSource);
+    const std::string sourceURL = jstringToStd(env, jSourceURL);
+    const std::string widgetId = jstringToStd(env, jWidgetId);
+
+    const bool firstRuntime = (g_runtime == nullptr);
+    auto tRuntime = Clock::now();
+    auto &rt = runtime();
+    if (firstRuntime) {
+      LOGPERF("[perf] runtime init: %.2f ms", millisSince(tRuntime));
+    }
+
+    auto tEval = Clock::now();
+    rt.evaluateJavaScript(
+        std::make_unique<jsi::StringBuffer>(source), sourceURL);
+    LOGPERF("[perf] bundle eval: %.2f ms (%zu chars)", millisSince(tEval), source.size());
+
+    auto registry = rt.global().getProperty(rt, "__voltraWidgets");
+    if (!registry.isObject()) {
+      LOGE("evaluateBundle: globalThis.__voltraWidgets missing after eval");
+      return JNI_FALSE;
+    }
+    auto widget = registry.asObject(rt).getProperty(rt, widgetId.c_str());
+    if (!widget.isObject()) {
+      LOGE("evaluateBundle: no entry for widgetId=%s", widgetId.c_str());
+      return JNI_FALSE;
+    }
+    auto renderFn = widget.asObject(rt).getProperty(rt, "render");
+    if (!renderFn.isObject() ||
+        !renderFn.asObject(rt).isFunction(rt)) {
+      LOGE("evaluateBundle: __voltraWidgets[%s].render is not a function",
+           widgetId.c_str());
+      return JNI_FALSE;
+    }
+
+    LOGI("evaluateBundle: render() captured for widgetId=%s (%zu chars)",
+         widgetId.c_str(), source.size());
+    return JNI_TRUE;
+  } catch (const jsi::JSError &e) {
+    LOGE("evaluateBundle JSError: %s", e.getMessage().c_str());
+    return JNI_FALSE;
+  } catch (const std::exception &e) {
+    LOGE("evaluateBundle threw: %s", e.what());
+    return JNI_FALSE;
+  } catch (...) {
+    LOGE("evaluateBundle threw: unknown");
+    return JNI_FALSE;
+  }
+}
+
+// Invoke the previously-captured `render(propsJSON, envJSON)` for a widget.
+// Props/env cross the boundary as JSON strings (the JS entry parses them); the
+// entry returns a JSON string (the resolved Voltra node tree), so no JSON
+// marshaling is needed here. Returns null on any error.
+extern "C" JNIEXPORT jstring JNICALL
+Java_voltra_runtime_VoltraJSRenderer_nativeRender(
+    JNIEnv *env, jobject /* this */, jstring jWidgetId, jstring jPropsJSON,
+    jstring jEnvJSON) {
+  std::lock_guard<std::mutex> lock(g_mutex);
+  if (!g_runtime) {
+    LOGE("render called before evaluateBundle");
+    return nullptr;
+  }
+  try {
+    auto &rt = *g_runtime;
+    const std::string widgetId = jstringToStd(env, jWidgetId);
+    const std::string propsJSON = jstringToStd(env, jPropsJSON);
+    const std::string envJSON = jstringToStd(env, jEnvJSON);
+
+    auto registry = rt.global().getProperty(rt, "__voltraWidgets");
+    if (!registry.isObject()) {
+      LOGE("render: __voltraWidgets missing (bundle not evaluated?)");
+      return nullptr;
+    }
+    auto widget = registry.asObject(rt).getProperty(rt, widgetId.c_str());
+    if (!widget.isObject()) {
+      LOGE("render: no captured widget for widgetId=%s", widgetId.c_str());
+      return nullptr;
+    }
+    auto renderProp = widget.asObject(rt).getProperty(rt, "render");
+    if (!renderProp.isObject() ||
+        !renderProp.asObject(rt).isFunction(rt)) {
+      LOGE("render: render is not a function for widgetId=%s",
+           widgetId.c_str());
+      return nullptr;
+    }
+    auto renderFn = renderProp.asObject(rt).asFunction(rt);
+
+    auto tRender = Clock::now();
+    jsi::Value result = renderFn.call(
+        rt, jsi::String::createFromUtf8(rt, propsJSON),
+        jsi::String::createFromUtf8(rt, envJSON));
+    LOGPERF("[perf] render: %.2f ms (widgetId=%s)", millisSince(tRender), widgetId.c_str());
+
+    if (!result.isString()) {
+      LOGE("render: did not return a string for widgetId=%s", widgetId.c_str());
+      return nullptr;
+    }
+    std::string resultStr = result.asString(rt).utf8(rt);
+    return env->NewStringUTF(resultStr.c_str());
+  } catch (const jsi::JSError &e) {
+    LOGE("render JSError: %s", e.getMessage().c_str());
+    return nullptr;
+  } catch (const std::exception &e) {
+    LOGE("render threw: %s", e.what());
+    return nullptr;
+  } catch (...) {
+    LOGE("render threw: unknown");
+    return nullptr;
+  }
+}
\ No newline at end of file
diff --git a/packages/android-client/android/src/main/java/voltra/VoltraModule.kt b/packages/android-client/android/src/main/java/voltra/VoltraModule.kt
index 825fd1d9..3565d52b 100644
--- a/packages/android-client/android/src/main/java/voltra/VoltraModule.kt
+++ b/packages/android-client/android/src/main/java/voltra/VoltraModule.kt
@@ -1,6 +1,8 @@
 package voltra
 
 import android.appwidget.AppWidgetManager
+import android.content.ComponentCallbacks
+import android.content.res.Configuration
 import android.util.Log
 import androidx.compose.ui.unit.DpSize
 import androidx.compose.ui.unit.dp
@@ -11,12 +13,17 @@ import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.bridge.ReadableArray
 import com.facebook.react.bridge.ReadableMap
 import com.facebook.react.bridge.WritableNativeMap
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.async
 import kotlinx.coroutines.awaitAll
+import kotlinx.coroutines.launch
 import kotlinx.coroutines.runBlocking
 import voltra.images.VoltraImageManager
+import voltra.runtime.VoltraConfigurationStore
 import voltra.widget.VoltraGlanceWidget
 import voltra.widget.VoltraWidgetManager
+import voltra.widget.VoltraWidgetReceiver
 
 class VoltraModule(
     reactContext: ReactApplicationContext,
@@ -37,6 +44,48 @@ class VoltraModule(
         VoltraImageManager(reactApplicationContext)
     }
 
+    // Last-seen night-mode bit. ACTION_CONFIGURATION_CHANGED also fires for rotation, font scale,
+    // locale, etc., so we re-render only when the light/dark bit actually changes.
+    private var lastNightMode: Int =
+        reactContext.resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK
+
+    // Re-renders client widgets when the system color scheme (light/dark) flips. Client widgets read
+    // env.colorScheme on-device, so a flip must re-run their render. Uses ComponentCallbacks rather
+    // than an ACTION_CONFIGURATION_CHANGED BroadcastReceiver: onConfigurationChanged delivers the
+    // authoritative new Configuration (a receiver's context.resources lags the change), and it isn't
+    // subject to the cached-process broadcast restrictions. Active while the host process is alive.
+    private val configurationCallbacks =
+        object : ComponentCallbacks {
+            override fun onConfigurationChanged(newConfig: Configuration) {
+                val nightMode = newConfig.uiMode and Configuration.UI_MODE_NIGHT_MASK
+                if (nightMode == lastNightMode) return
+                lastNightMode = nightMode
+                CoroutineScope(Dispatchers.IO).launch {
+                    try {
+                        widgetManager.reloadClientWidgets()
+                    } catch (e: Exception) {
+                        Log.e(TAG, "Color-scheme reload failed: ${e.message}")
+                    }
+                }
+            }
+
+            override fun onLowMemory() = Unit
+        }
+
+    override fun initialize() {
+        super.initialize()
+        reactApplicationContext.registerComponentCallbacks(configurationCallbacks)
+    }
+
+    override fun invalidate() {
+        try {
+            reactApplicationContext.unregisterComponentCallbacks(configurationCallbacks)
+        } catch (e: Exception) {
+            Log.w(TAG, "Failed to unregister configuration callbacks: ${e.message}")
+        }
+        super.invalidate()
+    }
+
     override fun startAndroidOngoingNotification(
         payload: String,
         options: ReadableMap,
@@ -153,6 +202,26 @@ class VoltraModule(
         promise.resolve(null)
     }
 
+    override fun setWidgetConfiguration(
+        widgetId: String,
+        key: String,
+        value: String,
+        promise: Promise,
+    ) {
+        // Stand-in for a Glance configuration activity: persist a config value and re-render the
+        // widget so its client render picks it up via env.configuration.
+        runBlocking {
+            try {
+                VoltraConfigurationStore(reactApplicationContext).set(widgetId, key, value)
+                VoltraWidgetReceiver.triggerGlanceUpdate(reactApplicationContext, widgetId)
+                promise.resolve(null)
+            } catch (e: Exception) {
+                Log.e(TAG, "setWidgetConfiguration failed", e)
+                promise.reject("VOLTRA_WIDGET_CONFIG_ERROR", e.message, e)
+            }
+        }
+    }
+
     override fun clearAndroidWidget(
         widgetId: String,
         promise: Promise,
diff --git a/packages/android-client/android/src/main/java/voltra/parsing/VoltraDecompressor.kt b/packages/android-client/android/src/main/java/voltra/parsing/VoltraDecompressor.kt
index 761ac53b..e55c714a 100644
--- a/packages/android-client/android/src/main/java/voltra/parsing/VoltraDecompressor.kt
+++ b/packages/android-client/android/src/main/java/voltra/parsing/VoltraDecompressor.kt
@@ -25,7 +25,12 @@ object VoltraDecompressor {
             e = payload.e?.map { decompressNode(it) },
         )
 
-    private fun decompressNode(node: VoltraNode): VoltraNode =
+    /**
+     * Expand short keys in a standalone node tree (no surrounding payload). Used by the
+     * client-rendered path, where the on-device renderer emits a single node with the same
+     * short-key format as server payloads but without the `{v, variants, s, e}` envelope.
+     */
+    fun decompressNode(node: VoltraNode): VoltraNode =
         when (node) {
             is VoltraNode.Element -> VoltraNode.Element(decompressElement(node.element))
             is VoltraNode.Array -> VoltraNode.Array(node.elements.map { decompressNode(it) })
diff --git a/packages/android-client/android/src/main/java/voltra/runtime/VoltraConfigurationStore.kt b/packages/android-client/android/src/main/java/voltra/runtime/VoltraConfigurationStore.kt
new file mode 100644
index 00000000..b2cf1d5a
--- /dev/null
+++ b/packages/android-client/android/src/main/java/voltra/runtime/VoltraConfigurationStore.kt
@@ -0,0 +1,94 @@
+package voltra.runtime
+
+import android.content.Context
+import android.util.Log
+import androidx.datastore.preferences.core.edit
+import androidx.datastore.preferences.core.stringPreferencesKey
+import androidx.datastore.preferences.preferencesDataStore
+import kotlinx.coroutines.flow.first
+import org.json.JSONObject
+import java.io.IOException
+
+/**
+ * DataStore-backed per-widget configuration for client-rendered widgets — the values surfaced as
+ * `env.configuration` in the widget's `(props, env) => JSX` render.
+ *
+ * Two layers, merged at read time:
+ *  - **Defaults** declared in code (`app.json` widget `appIntent.parameters[].default`), emitted by
+ *    the config plugin to `assets/voltra/widget_config_defaults.json`. These are the values the
+ *    widget shows before the user configures anything — the Android equivalent of iOS's
+ *    `@Parameter(default:)`.
+ *  - **Stored** values written at runtime (see setWidgetConfiguration), which override the defaults.
+ *
+ * Stands in for a real Glance configuration activity: Android has no system-managed widget
+ * configuration equivalent of iOS's WidgetConfigurationIntent, so runtime values are written by an
+ * in-app screen and read here at render time. Keys are namespaced `voltra.config.<widgetId>.<key>`.
+ */
+internal class VoltraConfigurationStore(
+    private val context: Context,
+) {
+    /** Code-declared defaults merged with stored runtime values (stored wins). */
+    suspend fun get(widgetId: String): Map<String, String> = loadDefaults(widgetId) + getStored(widgetId)
+
+    suspend fun set(
+        widgetId: String,
+        key: String,
+        value: String,
+    ) {
+        val prefKey = stringPreferencesKey(keyPrefix(widgetId) + key)
+        context.voltraConfigurationDataStore.edit { it[prefKey] = value }
+    }
+
+    private suspend fun getStored(widgetId: String): Map<String, String> {
+        val prefix = keyPrefix(widgetId)
+        val snapshot = context.voltraConfigurationDataStore.data.first()
+        val out = mutableMapOf<String, String>()
+        snapshot.asMap().forEach { (key, value) ->
+            if (key.name.startsWith(prefix) && value is String) {
+                out[key.name.substring(prefix.length)] = value
+            }
+        }
+        return out
+    }
+
+    // Reads the plugin-emitted defaults once and caches them: { "<widgetId>": { "<key>": "<value>" } }.
+    private fun loadDefaults(widgetId: String): Map<String, String> {
+        val cached = defaultsCache
+        if (cached != null) return cached[widgetId] ?: emptyMap()
+
+        val parsed =
+            try {
+                context.assets
+                    .open(DEFAULTS_ASSET_PATH)
+                    .bufferedReader()
+                    .use { it.readText() }
+            } catch (e: IOException) {
+                Log.d(TAG, "No $DEFAULTS_ASSET_PATH — client widget configuration starts empty")
+                defaultsCache = emptyMap()
+                return emptyMap()
+            }
+
+        val root = JSONObject(parsed)
+        val all = mutableMapOf<String, Map<String, String>>()
+        root.keys().forEach { id ->
+            val obj = root.getJSONObject(id)
+            val widgetMap = mutableMapOf<String, String>()
+            obj.keys().forEach { key -> widgetMap[key] = obj.getString(key) }
+            all[id] = widgetMap
+        }
+        defaultsCache = all
+        return all[widgetId] ?: emptyMap()
+    }
+
+    private fun keyPrefix(widgetId: String): String = "voltra.config.$widgetId."
+
+    companion object {
+        private const val TAG = "VoltraConfigurationStore"
+        private const val DEFAULTS_ASSET_PATH = "voltra/widget_config_defaults.json"
+
+        @Volatile
+        private var defaultsCache: Map<String, Map<String, String>>? = null
+    }
+}
+
+private val Context.voltraConfigurationDataStore by preferencesDataStore(name = "voltra_widget_configuration")
diff --git a/packages/android-client/android/src/main/java/voltra/runtime/VoltraJSRenderer.kt b/packages/android-client/android/src/main/java/voltra/runtime/VoltraJSRenderer.kt
new file mode 100644
index 00000000..9ff215d3
--- /dev/null
+++ b/packages/android-client/android/src/main/java/voltra/runtime/VoltraJSRenderer.kt
@@ -0,0 +1,147 @@
+package voltra.runtime
+
+import android.util.Log
+
+/**
+ * Standalone Hermes runtime for Voltra **client-rendered widgets**.
+ *
+ * Architectural mirror of iOS `VoltraJSRenderer.swift` (JSC). Each per-widget Metro bundle
+ * exposes `render(props, env)`; [evaluateBundle] evaluates it once in a single process-wide
+ * Hermes runtime, capturing the bundle's exports under `globalThis.__voltraWidgets[<id>]`,
+ * and [render] invokes that function on every Glance render.
+ *
+ * Lifecycle: one Hermes runtime per process (created lazily in native code on first
+ * evaluate). Re-evaluating the same widget overwrites its captured exports — used by
+ * dev-mode hot reload (always-refetch).
+ *
+ * Thread safety: a single lock guards both evaluate and render, matching iOS's NSLock.
+ */
+object VoltraJSRenderer {
+    private const val TAG = "VoltraJSRenderer"
+
+    init {
+        System.loadLibrary("voltra_js_renderer")
+    }
+
+    private val lock = Any()
+
+    private external fun nativeEvaluateBundle(
+        wrappedSource: String,
+        sourceURL: String,
+        widgetId: String,
+    ): Boolean
+
+    private external fun nativeRender(
+        widgetId: String,
+        propsJSON: String,
+        envJSON: String,
+    ): String?
+
+    /**
+     * Minimal global shims. The widget Metro bundle runs in a *bare* Hermes runtime (no RN
+     * preamble — the widget Metro config strips polyfills), but React's dev build and a few
+     * helpers reference `console` / timers that Hermes does not define out of the box. JSC
+     * (iOS) happened to tolerate their absence; Hermes does not, so we inject no-op stand-ins
+     * before the bundle. Voltra's renderer is fully synchronous, so timers are never actually
+     * needed during a render — the no-ops exist only so references don't throw.
+     */
+    private val GLOBAL_SHIMS =
+        """
+        (function (g) {
+          if (typeof g.console === 'undefined') {
+            var noop = function () {};
+            g.console = {
+              log: noop, info: noop, warn: noop, error: noop, debug: noop, trace: noop,
+              group: noop, groupCollapsed: noop, groupEnd: noop, table: noop, assert: noop,
+              dir: noop, count: noop, time: noop, timeEnd: noop
+            };
+          }
+          if (typeof g.setTimeout === 'undefined') { g.setTimeout = function () { return 0; }; }
+          if (typeof g.clearTimeout === 'undefined') { g.clearTimeout = function () {}; }
+          if (typeof g.setInterval === 'undefined') { g.setInterval = function () { return 0; }; }
+          if (typeof g.clearInterval === 'undefined') { g.clearInterval = function () {}; }
+          if (typeof g.setImmediate === 'undefined') { g.setImmediate = function () { return 0; }; }
+        })(typeof globalThis !== 'undefined' ? globalThis : this);
+        """.trimIndent()
+
+    /**
+     * Evaluate a widget bundle (raw Metro `/voltra/widgets/<id>.bundle` output) and capture
+     * its `render(props, env)` export. Idempotent: re-evaluating overwrites the capture.
+     *
+     * The raw bundle ends with Metro's entry invocation `__r(<entryId>);`. We re-invoke that
+     * entry and stash its exports in `globalThis.__voltraWidgets[<id>]` (Metro's `__r` caches
+     * module exports, so the second invocation returns the already-evaluated module).
+     */
+    fun evaluateBundle(
+        source: String,
+        widgetId: String,
+    ): Boolean =
+        synchronized(lock) {
+            val entryModuleId = extractEntryModuleId(source) ?: 0
+            val wrapped =
+                buildString {
+                    append(GLOBAL_SHIMS)
+                    append('\n')
+                    append(source)
+                    append('\n')
+                    append(";(function () {\n")
+                    append("  if (!globalThis.__voltraWidgets) { globalThis.__voltraWidgets = {}; }\n")
+                    append("  globalThis.__voltraWidgets[")
+                    append(jsStringLiteral(widgetId))
+                    append("] = __r(")
+                    append(entryModuleId)
+                    append(");\n")
+                    append("})();\n")
+                }
+            val ok =
+                try {
+                    nativeEvaluateBundle(wrapped, "voltra/$widgetId.bundle", widgetId)
+                } catch (t: Throwable) {
+                    Log.e(TAG, "nativeEvaluateBundle threw for widgetId=$widgetId", t)
+                    false
+                }
+            ok
+        }
+
+    /**
+     * Invoke the previously-evaluated widget's `render(propsJSON, envJSON)` and return its
+     * resolved JSON string. Returns null if the widget was not evaluated, the function throws,
+     * or it did not return a string.
+     */
+    fun render(
+        widgetId: String,
+        propsJSON: String,
+        envJSON: String,
+    ): String? =
+        synchronized(lock) {
+            try {
+                nativeRender(widgetId, propsJSON, envJSON)
+            } catch (t: Throwable) {
+                Log.e(TAG, "nativeRender threw for widgetId=$widgetId", t)
+                null
+            }
+        }
+
+    /**
+     * Find the entry module id Metro emitted in the bundle's trailing `__r(<id>);`. Every
+     * `__d(...)` module body also contains internal `__r(...)` calls, so we take the LAST
+     * match — the entry invocation Metro appends at the end of the bundle. Mirrors iOS's
+     * `extractEntryModuleId`.
+     */
+    private fun extractEntryModuleId(source: String): Int? =
+        Regex("""__r\((\d+)\);""")
+            .findAll(source)
+            .lastOrNull()
+            ?.groupValues
+            ?.get(1)
+            ?.toIntOrNull()
+
+    private fun jsStringLiteral(value: String): String =
+        "\"" +
+            value
+                .replace("\\", "\\\\")
+                .replace("\"", "\\\"")
+                .replace("\n", "\\n")
+                .replace("\r", "\\r") +
+            "\""
+}
diff --git a/packages/android-client/android/src/main/java/voltra/widget/VoltraClientGlanceWidget.kt b/packages/android-client/android/src/main/java/voltra/widget/VoltraClientGlanceWidget.kt
new file mode 100644
index 00000000..9bdd4d20
--- /dev/null
+++ b/packages/android-client/android/src/main/java/voltra/widget/VoltraClientGlanceWidget.kt
@@ -0,0 +1,261 @@
+package voltra.widget
+
+import android.content.Context
+import android.content.pm.ApplicationInfo
+import android.content.res.Configuration
+import android.util.Log
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.unit.DpSize
+import androidx.compose.ui.unit.dp
+import androidx.glance.GlanceId
+import androidx.glance.GlanceModifier
+import androidx.glance.LocalContext
+import androidx.glance.LocalSize
+import androidx.glance.appwidget.GlanceAppWidget
+import androidx.glance.appwidget.SizeMode
+import androidx.glance.appwidget.provideContent
+import androidx.glance.layout.Alignment
+import androidx.glance.layout.Box
+import androidx.glance.layout.fillMaxSize
+import androidx.glance.layout.padding
+import androidx.glance.text.Text
+import androidx.glance.unit.ColorProvider
+import com.facebook.react.modules.systeminfo.AndroidInfoHelpers
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import kotlinx.serialization.json.Json
+import org.json.JSONObject
+import voltra.BuildConfig
+import voltra.glance.GlanceFactory
+import voltra.models.VoltraNode
+import voltra.parsing.VoltraDecompressor
+import voltra.runtime.VoltraConfigurationStore
+import voltra.runtime.VoltraJSRenderer
+import java.net.HttpURLConnection
+import java.net.URL
+
+/**
+ * Client-rendered Voltra widget: downloads a per-widget JS bundle (Metro in dev), evaluates it
+ * in the standalone Hermes runtime, and invokes its `render(props, env)` on every Glance render
+ * — the Android counterpart of iOS's VoltraClientWidgetProvider.
+ *
+ * Pipeline:
+ *  1. provideGlance (suspend, off the composition): fetch the bundle from Metro and evaluate it
+ *     via [VoltraJSRenderer.evaluateBundle].
+ *  2. Content (composable): read LocalSize/locale/scheme, build the WidgetEnvironment JSON, call
+ *     [VoltraJSRenderer.render], decompress the resulting node, and hand it to [GlanceFactory] —
+ *     the same renderer server-rendered widgets use, so the two look identical.
+ *
+ * On fetch/eval/render failure the widget shows a minimal fallback; the config plugin supplies
+ * a prerendered placeholder for the first paint and the offline case.
+ */
+class VoltraClientGlanceWidget(
+    private val widgetId: String = "default",
+) : GlanceAppWidget() {
+    companion object {
+        private const val TAG = "VoltraClientGlanceWidget"
+
+        private val json =
+            Json {
+                ignoreUnknownKeys = true
+                explicitNulls = false
+            }
+
+        /** Fetch the raw widget bundle from Metro (dev). Returns null on any network error. */
+        private suspend fun fetchDevBundle(
+            context: Context,
+            widgetId: String,
+        ): String? =
+            withContext(Dispatchers.IO) {
+                // AndroidInfoHelpers resolves the dev server host for emulator (10.0.2.2),
+                // physical device, or adb-reverse — the RN-native equivalent of iOS's
+                // RCTBundleURLProvider.
+                val host = AndroidInfoHelpers.getServerHost(context)
+                val urlString = "http://$host/voltra/widgets/$widgetId.bundle?platform=android&dev=true"
+                val t0 = System.nanoTime()
+                try {
+                    val connection = URL(urlString).openConnection() as HttpURLConnection
+                    connection.connectTimeout = 5_000
+                    connection.readTimeout = 5_000
+                    connection.requestMethod = "GET"
+                    try {
+                        val code = connection.responseCode
+                        if (code !in 200..299) {
+                            Log.e(TAG, "Metro HTTP $code for $urlString")
+                            return@withContext null
+                        }
+                        val body = connection.inputStream.bufferedReader().use { it.readText() }
+                        if (BuildConfig.DEBUG) {
+                            Log.i(
+                                TAG,
+                                "[perf] metro fetch: ${"%.2f".format(
+                                    (System.nanoTime() - t0) / 1_000_000.0,
+                                )} ms (${body.length} chars)",
+                            )
+                        }
+                        body
+                    } finally {
+                        connection.disconnect()
+                    }
+                } catch (e: Exception) {
+                    Log.e(TAG, "Metro fetch failed ($urlString): ${e.message}")
+                    null
+                }
+            }
+
+        /**
+         * Read the release bundle baked into the app's assets by the Gradle bundling task
+         * (assets/voltra/voltra-widget-<id>.bundle). The release counterpart of [fetchDevBundle];
+         * returns null (→ prerendered fallback) when the asset is missing.
+         */
+        private fun loadBakedBundle(
+            context: Context,
+            widgetId: String,
+        ): String? =
+            try {
+                context.assets
+                    .open("voltra/voltra-widget-$widgetId.bundle")
+                    .bufferedReader()
+                    .use { it.readText() }
+            } catch (e: java.io.IOException) {
+                Log.w(TAG, "No baked bundle for widgetId=$widgetId (assets/voltra/voltra-widget-$widgetId.bundle)")
+                null
+            }
+
+        private fun isDev(context: Context): Boolean =
+            (context.applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE) != 0
+
+        /**
+         * Build the WidgetEnvironment JSON (see packages/core/src/widget-environment.ts) for the
+         * current render.
+         */
+        private fun buildEnvJson(
+            context: Context,
+            size: DpSize,
+            configuration: Map<String, String>,
+        ): String {
+            val family = "${size.width.value.toInt()}x${size.height.value.toInt()}"
+            val nightMode =
+                context.resources.configuration.uiMode and Configuration.UI_MODE_NIGHT_MASK
+            val colorScheme = if (nightMode == Configuration.UI_MODE_NIGHT_YES) "dark" else "light"
+            val locale =
+                context.resources.configuration.locales[0]
+                    .toLanguageTag()
+            val dev = isDev(context)
+            val appVersion =
+                try {
+                    context.packageManager.getPackageInfo(context.packageName, 0).versionName ?: "unknown"
+                } catch (e: Exception) {
+                    "unknown"
+                }
+
+            val build =
+                JSONObject()
+                    .put("isDev", dev)
+                    .put(
+                        "metroUrl",
+                        if (dev) "http://${AndroidInfoHelpers.getServerHost(context)}" else JSONObject.NULL,
+                    ).put("appVersion", appVersion)
+                    .put("voltraVersion", BuildConfig.VOLTRA_VERSION)
+
+            val configObject = JSONObject()
+            configuration.forEach { (key, value) -> configObject.put(key, value) }
+
+            return JSONObject()
+                .put("date", System.currentTimeMillis())
+                .put("widgetFamily", family)
+                .put("colorScheme", colorScheme)
+                .put("locale", locale)
+                .put("configuration", configObject)
+                .put("build", build)
+                .toString()
+        }
+    }
+
+    // One node is rendered for the actual on-screen size (env carries the size); no multi-variant
+    // selection on the client path. SizeMode.Exact re-composes provideGlance with the real
+    // LocalSize on every resize, so env.widgetFamily and the node track the new size.
+    override val sizeMode = SizeMode.Exact
+
+    override suspend fun provideGlance(
+        context: Context,
+        id: GlanceId,
+    ) {
+        val source = if (isDev(context)) fetchDevBundle(context, widgetId) else loadBakedBundle(context, widgetId)
+        val bundleReady = source != null && VoltraJSRenderer.evaluateBundle(source, widgetId)
+        if (!bundleReady) {
+            Log.w(TAG, "Bundle not ready for widgetId=$widgetId (dev=${isDev(context)})")
+        }
+
+        // Read user-configured params (DataStore) off the composition so env.configuration is
+        // available synchronously during render.
+        val configuration = VoltraConfigurationStore(context).get(widgetId)
+
+        provideContent {
+            Content(bundleReady, configuration)
+        }
+    }
+
+    @Composable
+    private fun Content(
+        bundleReady: Boolean,
+        configuration: Map<String, String>,
+    ) {
+        val context = LocalContext.current
+        val size = LocalSize.current
+
+        // Live render when the bundle is ready; otherwise fall back to the plugin-prerendered
+        // placeholder node (first paint / offline / Metro down).
+        val node = (if (bundleReady) renderNode(context, size, configuration) else null) ?: placeholderNode(context)
+        if (node != null) {
+            GlanceFactory(widgetId, null, null, size).Render(node)
+        } else {
+            Fallback()
+        }
+    }
+
+    private fun renderNode(
+        context: Context,
+        size: DpSize,
+        configuration: Map<String, String>,
+    ): VoltraNode? {
+        val envJson = buildEnvJson(context, size, configuration)
+        val resolved = VoltraJSRenderer.render(widgetId, "{}", envJson) ?: return null
+        return parseNode(resolved)
+    }
+
+    /** Decode the plugin-prerendered single-node placeholder from the initial-states asset. */
+    private fun placeholderNode(context: Context): VoltraNode? {
+        val raw = VoltraWidgetManager(context).readWidgetJson(widgetId) ?: return null
+        return parseNode(raw)
+    }
+
+    private fun parseNode(jsonString: String): VoltraNode? =
+        try {
+            val t0 = System.nanoTime()
+            val node = VoltraDecompressor.decompressNode(json.decodeFromString<VoltraNode>(jsonString))
+            if (BuildConfig.DEBUG) {
+                Log.i(
+                    TAG,
+                    "[perf] decode+decompress: ${"%.2f".format(
+                        (System.nanoTime() - t0) / 1_000_000.0,
+                    )} ms (${jsonString.length} chars)",
+                )
+            }
+            node
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to parse node for widgetId=$widgetId: ${e.message}")
+            null
+        }
+
+    @Composable
+    private fun Fallback() {
+        Box(
+            modifier = GlanceModifier.fillMaxSize().padding(16.dp),
+            contentAlignment = Alignment.Center,
+        ) {
+            Text(text = "Loading…", style = androidx.glance.text.TextStyle(color = ColorProvider(Color.Gray)))
+        }
+    }
+}
diff --git a/packages/android-client/android/src/main/java/voltra/widget/VoltraClientWidgetReceiver.kt b/packages/android-client/android/src/main/java/voltra/widget/VoltraClientWidgetReceiver.kt
new file mode 100644
index 00000000..cd718ca2
--- /dev/null
+++ b/packages/android-client/android/src/main/java/voltra/widget/VoltraClientWidgetReceiver.kt
@@ -0,0 +1,19 @@
+package voltra.widget
+
+import android.content.Context
+import androidx.glance.appwidget.GlanceAppWidget
+
+/**
+ * Base receiver for client-rendered Voltra widgets. Identical lifecycle to
+ * [VoltraWidgetReceiver] but hosts a [VoltraClientGlanceWidget] (on-device JS render) instead
+ * of the server-rendered [VoltraGlanceWidget].
+ *
+ * Generated client receivers extend this and provide their `widgetId`.
+ */
+abstract class VoltraClientWidgetReceiver : VoltraWidgetReceiver() {
+    override fun createGlanceAppWidget(): GlanceAppWidget = VoltraClientGlanceWidget(widgetId)
+
+    // Client widgets use SizeMode.Exact, so Glance re-composes provideGlance for the new size on
+    // resize. The server-cache re-render path doesn't apply (there is no cached payload).
+    override fun onWidgetResized(context: Context) = Unit
+}
diff --git a/packages/android-client/android/src/main/java/voltra/widget/VoltraWidgetManager.kt b/packages/android-client/android/src/main/java/voltra/widget/VoltraWidgetManager.kt
index a5a2543e..55381a08 100644
--- a/packages/android-client/android/src/main/java/voltra/widget/VoltraWidgetManager.kt
+++ b/packages/android-client/android/src/main/java/voltra/widget/VoltraWidgetManager.kt
@@ -399,19 +399,83 @@ class VoltraWidgetManager(
 
             // Also include server-driven widgets that may not have cached data yet
             val serverDrivenIds = VoltraWidgetUpdateScheduler.getAllServerDrivenWidgetIds(context)
-            val allWidgetIds = widgetIds + serverDrivenIds
+            val cachedAndServerIds = widgetIds + serverDrivenIds
+
+            // Pinned widgets that have neither cached data nor a server URL are client-rendered
+            // (they render from Metro). reloadSingleWidget's cache path can't refresh them, so
+            // trigger their Glance update directly to re-run provideGlance.
+            val pinnedIds = pinnedVoltraWidgetIds()
+            val clientIds = pinnedIds - cachedAndServerIds
 
             Log.d(
                 TAG,
-                "Found ${allWidgetIds.size} widgets to reload (${widgetIds.size} cached, ${serverDrivenIds.size} server-driven)",
+                "Found ${cachedAndServerIds.size + clientIds.size} widgets to reload " +
+                    "(${widgetIds.size} cached, ${serverDrivenIds.size} server-driven, ${clientIds.size} client-rendered)",
             )
 
-            for (widgetId in allWidgetIds) {
+            for (widgetId in cachedAndServerIds) {
                 try {
                     reloadSingleWidget(widgetId)
                 } catch (e: Exception) {
                     Log.e(TAG, "Failed to update widget $widgetId: ${e.message}")
                 }
             }
+            for (widgetId in clientIds) {
+                try {
+                    VoltraWidgetReceiver.triggerGlanceUpdate(context, widgetId)
+                } catch (e: Exception) {
+                    Log.e(TAG, "Failed to update client widget $widgetId: ${e.message}")
+                }
+            }
+        }
+
+    /**
+     * Re-render only client-rendered widgets (pinned widgets with neither cached data nor a server
+     * URL — they render on-device from `provideGlance`). Used to react to environment changes that
+     * affect `env` but not server payloads, e.g. a light/dark (color scheme) toggle.
+     */
+    suspend fun reloadClientWidgets() =
+        withContext(Dispatchers.Main) {
+            val cachedIds =
+                prefs.all.keys
+                    .filter { it.startsWith(KEY_JSON_PREFIX) }
+                    .map { it.removePrefix(KEY_JSON_PREFIX) }
+                    .toSet()
+            val serverDrivenIds = VoltraWidgetUpdateScheduler.getAllServerDrivenWidgetIds(context)
+            val clientIds = pinnedVoltraWidgetIds() - cachedIds - serverDrivenIds
+
+            Log.d(TAG, "reloadClientWidgets: ${clientIds.size} client widget(s)")
+            for (widgetId in clientIds) {
+                try {
+                    VoltraWidgetReceiver.triggerGlanceUpdate(context, widgetId)
+                } catch (e: Exception) {
+                    Log.e(TAG, "Failed to reload client widget $widgetId: ${e.message}")
+                }
+            }
+        }
+
+    /**
+     * Widget ids of all currently-pinned Voltra widgets, derived from bound AppWidget providers
+     * named `<pkg>.widget.VoltraWidget_<id>Receiver`. Covers client-rendered widgets, which keep no
+     * cached prefs data, so reloadAllWidgets reaches them too.
+     */
+    private fun pinnedVoltraWidgetIds(): Set<String> {
+        val appWidgetManager = AppWidgetManager.getInstance(context)
+        val prefix = "VoltraWidget_"
+        val suffix = "Receiver"
+        val ids = mutableSetOf<String>()
+        try {
+            for (provider in appWidgetManager.installedProviders) {
+                val componentName = provider.provider
+                if (componentName.packageName != context.packageName) continue
+                val simpleName = componentName.className.substringAfterLast('.')
+                if (!simpleName.startsWith(prefix) || !simpleName.endsWith(suffix)) continue
+                if (appWidgetManager.getAppWidgetIds(componentName).isEmpty()) continue // not pinned
+                ids.add(simpleName.removePrefix(prefix).removeSuffix(suffix))
+            }
+        } catch (e: Exception) {
+            Log.e(TAG, "pinnedVoltraWidgetIds failed: ${e.message}")
         }
+        return ids
+    }
 }
diff --git a/packages/android-client/android/src/main/java/voltra/widget/VoltraWidgetReceiver.kt b/packages/android-client/android/src/main/java/voltra/widget/VoltraWidgetReceiver.kt
index 3b2a3b02..3a0173ad 100644
--- a/packages/android-client/android/src/main/java/voltra/widget/VoltraWidgetReceiver.kt
+++ b/packages/android-client/android/src/main/java/voltra/widget/VoltraWidgetReceiver.kt
@@ -102,18 +102,23 @@ abstract class VoltraWidgetReceiver : GlanceAppWidgetReceiver() {
      */
     abstract val widgetId: String
 
+    /**
+     * The GlanceAppWidget this receiver hosts. Defaults to the server-rendered
+     * [VoltraGlanceWidget]; client-rendered receivers override this to return a
+     * [voltra.widget.VoltraClientGlanceWidget]. Kept as a factory (not a direct property) so
+     * the shared registry registration in [glanceAppWidget] stays in one place.
+     */
+    protected open fun createGlanceAppWidget(): GlanceAppWidget = VoltraGlanceWidget(widgetId)
+
     override val glanceAppWidget: GlanceAppWidget by lazy {
-        Log.d(TAG, "Creating VoltraGlanceWidget for widgetId=$widgetId")
-        val widget = VoltraGlanceWidget(widgetId)
+        Log.d(TAG, "Creating GlanceAppWidget for widgetId=$widgetId")
+        val widget = createGlanceAppWidget()
         widgetRegistry[widgetId] = widget
         widget
     }
 
     /**
      * Called when the user resizes a widget on the home screen.
-     * The server returns all size variants in every response, so we just
-     * re-render from cached data — RemoteViews(sizeMapping) picks the closest match.
-     * No network request needed.
      */
     override fun onAppWidgetOptionsChanged(
         context: Context,
@@ -125,8 +130,19 @@ abstract class VoltraWidgetReceiver : GlanceAppWidgetReceiver() {
 
         val w = newOptions.getInt(AppWidgetManager.OPTION_APPWIDGET_MIN_WIDTH, 0)
         val h = newOptions.getInt(AppWidgetManager.OPTION_APPWIDGET_MIN_HEIGHT, 0)
-        Log.d(TAG, "Widget '$widgetId' resized to ${w}x$h, re-rendering from cache")
+        Log.d(TAG, "Widget '$widgetId' resized to ${w}x$h")
 
+        onWidgetResized(context)
+    }
+
+    /**
+     * Re-render after a resize. Server-rendered widgets re-render from cached data — the payload
+     * carries all size variants, so RemoteViews(sizeMapping) picks the closest match; no network
+     * request needed. Client-rendered widgets override this to no-op: they use
+     * `SizeMode.Exact`, so Glance already re-composes `provideGlance` for the new size (and there
+     * is no cached payload to re-render from).
+     */
+    protected open fun onWidgetResized(context: Context) {
         CoroutineScope(Dispatchers.IO).launch {
             val widgetManager = VoltraWidgetManager(context.applicationContext)
             widgetManager.updateWidgetDirect(widgetId)
diff --git a/packages/android-client/android/src/test/java/voltra/parsing/VoltraDecompressorNodeTest.kt b/packages/android-client/android/src/test/java/voltra/parsing/VoltraDecompressorNodeTest.kt
new file mode 100644
index 00000000..c4555144
--- /dev/null
+++ b/packages/android-client/android/src/test/java/voltra/parsing/VoltraDecompressorNodeTest.kt
@@ -0,0 +1,57 @@
+package voltra.parsing
+
+import kotlinx.serialization.json.Json
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import voltra.models.VoltraNode
+
+/**
+ * Verifies [VoltraDecompressor.decompressNode] expands short keys in a standalone node tree —
+ * the client-rendered path decodes the on-device renderer's output as a bare [VoltraNode]
+ * (no `{v, variants, s, e}` envelope) and must decompress it before handing it to the Glance
+ * renderer, which expects expanded keys.
+ */
+@RunWith(RobolectricTestRunner::class)
+class VoltraDecompressorNodeTest {
+    private val json =
+        Json {
+            ignoreUnknownKeys = true
+            explicitNulls = false
+        }
+
+    @Test
+    fun expandsShortKeysInStandaloneNode() {
+        // Shape mirrors what renderAndroidVariantToJson emits: a Column with an inline style and
+        // a Text child with its own style. `s` -> style, `bg` -> backgroundColor, `fs` -> fontSize.
+        val node =
+            json.decodeFromString<VoltraNode>(
+                """
+                {"t":9,"p":{"s":{"bg":"#000000"}},"c":[{"t":18,"c":"Hi","p":{"s":{"fs":14}}}]}
+                """.trimIndent(),
+            )
+
+        val decompressed = VoltraDecompressor.decompressNode(node)
+
+        assertTrue("root should be an Element", decompressed is VoltraNode.Element)
+        val root = (decompressed as VoltraNode.Element).element
+        assertEquals(9, root.t)
+
+        @Suppress("UNCHECKED_CAST")
+        val rootStyle = root.p?.get("style") as? Map<String, Any?>
+        assertTrue("root prop 's' should expand to 'style'", rootStyle != null)
+        assertEquals("#000000", rootStyle!!["backgroundColor"])
+
+        val childNode = root.c
+        assertTrue("child should be an Array", childNode is VoltraNode.Array)
+        val child = (childNode as VoltraNode.Array).elements[0]
+        assertTrue("child should be an Element", child is VoltraNode.Element)
+
+        @Suppress("UNCHECKED_CAST")
+        val childStyle = (child as VoltraNode.Element).element.p?.get("style") as? Map<String, Any?>
+        assertTrue("child prop 's' should expand to 'style'", childStyle != null)
+        assertTrue("child style should contain expanded 'fontSize'", childStyle!!.containsKey("fontSize"))
+    }
+}
diff --git a/packages/android-client/expo-plugin/src/android/clientRendered.node.test.ts b/packages/android-client/expo-plugin/src/android/clientRendered.node.test.ts
new file mode 100644
index 00000000..b04820d3
--- /dev/null
+++ b/packages/android-client/expo-plugin/src/android/clientRendered.node.test.ts
@@ -0,0 +1,145 @@
+import * as fs from 'fs'
+import * as os from 'os'
+import * as path from 'path'
+
+import type { AndroidWidgetConfig } from '../types'
+import { detectClientRenderedWidgets } from './clientRendered'
+
+function makeTempProject(files: Record<string, string>): { projectRoot: string; cleanup: () => void } {
+  const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'voltra-android-client-rendered-test-'))
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = path.join(projectRoot, rel)
+    fs.mkdirSync(path.dirname(abs), { recursive: true })
+    fs.writeFileSync(abs, content)
+  }
+  return {
+    projectRoot,
+    cleanup: () => fs.rmSync(projectRoot, { recursive: true, force: true }),
+  }
+}
+
+function asWidget(partial: Partial<AndroidWidgetConfig>): AndroidWidgetConfig {
+  return {
+    id: 'placeholder',
+    entry: './widgets/placeholder.tsx',
+    displayName: 'Placeholder',
+    description: 'Placeholder',
+    targetCellWidth: 2,
+    targetCellHeight: 2,
+    ...partial,
+  }
+}
+
+// Detection emits a one-time EXPERIMENTAL console.warn; keep it out of test output (the dedicated
+// suite below asserts on it explicitly).
+beforeEach(() => {
+  jest.spyOn(console, 'warn').mockImplementation(() => {})
+})
+afterEach(() => {
+  jest.restoreAllMocks()
+})
+
+describe('detectClientRenderedWidgets (android)', () => {
+  it('keeps widgets without an entry on the server-rendered path', () => {
+    const { projectRoot, cleanup } = makeTempProject({})
+    try {
+      const [detected] = detectClientRenderedWidgets(
+        [
+          {
+            id: 'legacy',
+            displayName: 'Legacy',
+            description: 'Server-rendered widget',
+            targetCellWidth: 2,
+            targetCellHeight: 2,
+          },
+        ],
+        projectRoot
+      )
+
+      expect(detected.clientRendered).toBe(false)
+      expect(detected).not.toHaveProperty('clientSourcePath')
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('flags a default-exported entry module as a Dynamic Widget even when the export name differs', () => {
+    const { projectRoot, cleanup } = makeTempProject({
+      'widgets/Foo.tsx': `
+        export default function NotTheWidgetId(props, env) {
+          return null
+        }
+      `,
+    })
+    try {
+      const [detected] = detectClientRenderedWidgets([asWidget({ id: 'Foo', entry: './widgets/Foo.tsx' })], projectRoot)
+      expect(detected.clientRendered).toBe(true)
+      if (detected.clientRendered) {
+        expect(detected.clientSourcePath).toBe(path.join(projectRoot, 'widgets/Foo.tsx'))
+      }
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('throws when the entry default export is not a function', () => {
+    const { projectRoot, cleanup } = makeTempProject({
+      'widgets/Bar.tsx': `
+        export default { kind: 'widget-state' }
+      `,
+    })
+    try {
+      expect(() =>
+        detectClientRenderedWidgets([asWidget({ id: 'Bar', entry: './widgets/Bar.tsx' })], projectRoot)
+      ).toThrow(/Dynamic Widget "Bar" at widgets\/Bar\.tsx must default-export a function or component\./)
+    } finally {
+      cleanup()
+    }
+  })
+})
+
+describe('detectClientRenderedWidgets (android) — experimental warning', () => {
+  // The warning fires at most once per module instance, so re-require a fresh module per test.
+  function freshDetect(): typeof detectClientRenderedWidgets {
+    let fn: typeof detectClientRenderedWidgets = detectClientRenderedWidgets
+    jest.isolateModules(() => {
+      fn = require('./clientRendered').detectClientRenderedWidgets
+    })
+    return fn
+  }
+
+  it('warns once (with EXPERIMENTAL + the widget id) when a client-rendered widget is detected', () => {
+    const detect = freshDetect()
+    const warn = console.warn as jest.Mock
+    const { projectRoot, cleanup } = makeTempProject({
+      'widgets/Foo.tsx': `
+        export default function Foo(props, env) {
+          return null
+        }
+      `,
+    })
+    try {
+      const widgets = [asWidget({ id: 'Foo', entry: './widgets/Foo.tsx' })]
+      detect(widgets, projectRoot)
+      detect(widgets, projectRoot)
+
+      expect(warn).toHaveBeenCalledTimes(1)
+      expect(warn.mock.calls[0][0]).toContain('EXPERIMENTAL')
+      expect(warn.mock.calls[0][0]).toContain('Foo')
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('does not warn when no Dynamic Widgets are detected', () => {
+    const detect = freshDetect()
+    const warn = console.warn as jest.Mock
+    const { projectRoot, cleanup } = makeTempProject({})
+    try {
+      detect([], projectRoot)
+      expect(warn).not.toHaveBeenCalled()
+    } finally {
+      cleanup()
+    }
+  })
+})
diff --git a/packages/android-client/expo-plugin/src/android/clientRendered.ts b/packages/android-client/expo-plugin/src/android/clientRendered.ts
new file mode 100644
index 00000000..8dd63f51
--- /dev/null
+++ b/packages/android-client/expo-plugin/src/android/clientRendered.ts
@@ -0,0 +1,85 @@
+import * as fs from 'fs'
+import * as path from 'path'
+
+import { evaluateWidgetModuleExports } from '@use-voltra/expo-plugin'
+
+import type { AndroidWidgetConfig } from '../types'
+
+/**
+ * Dynamic Widget detection for Android — the counterpart of the iOS plugin's
+ * clientRendered.ts.
+ *
+ * Widgets without `entry` remain server-rendered/server-updated legacy widgets.
+ * A widget is client-rendered when the module referenced by `entry` default-exports a function
+ * or component. Such widgets download a JS bundle and render on-device (Hermes) instead of
+ * consuming server JSON.
+ */
+
+export type DetectedAndroidWidget =
+  | (AndroidWidgetConfig & { clientRendered: false })
+  | (AndroidWidgetConfig & { clientRendered: true; clientSourcePath: string })
+
+// Emit the experimental notice at most once per prebuild process (detection runs from several
+// plugin steps).
+let hasWarnedExperimental = false
+
+export function detectClientRenderedWidgets(
+  widgets: AndroidWidgetConfig[],
+  projectRoot: string
+): DetectedAndroidWidget[] {
+  const detected = widgets.map((widget) => detectSingleWidget(widget, projectRoot))
+
+  if (!hasWarnedExperimental) {
+    const clientWidgetIds = detected.filter((widget) => widget.clientRendered).map((widget) => widget.id)
+    if (clientWidgetIds.length > 0) {
+      hasWarnedExperimental = true
+      console.warn(
+        `[voltra] Dynamic Widgets are EXPERIMENTAL (${clientWidgetIds.join(', ')}). ` +
+          'The widget JSX runs on-device in a separate JS engine; the API and build output may change, ' +
+          'and production rendering should be verified on a real device. Use at your own risk.'
+      )
+    }
+  }
+
+  return detected
+}
+
+function detectSingleWidget(widget: AndroidWidgetConfig, projectRoot: string): DetectedAndroidWidget {
+  if (widget.entry === undefined) {
+    return {
+      ...widget,
+      clientRendered: false,
+    }
+  }
+
+  const sourcePath = resolveWidgetEntryPath(widget.entry, projectRoot)
+  if (!sourcePath || !fs.existsSync(sourcePath)) {
+    throw new Error(
+      `[voltra] Dynamic Widget "${widget.id}" entry not found at ${path.relative(
+        projectRoot,
+        sourcePath ?? widget.entry
+      )}`
+    )
+  }
+
+  const widgetModule = evaluateWidgetModuleExports(projectRoot, sourcePath)
+  const widgetFn = widgetModule?.default ?? widgetModule
+  if (typeof widgetFn !== 'function') {
+    throw new Error(
+      `[voltra] Dynamic Widget "${widget.id}" at ${path.relative(
+        projectRoot,
+        sourcePath
+      )} must default-export a function or component.`
+    )
+  }
+
+  return {
+    ...widget,
+    clientRendered: true,
+    clientSourcePath: sourcePath,
+  }
+}
+
+function resolveWidgetEntryPath(entry: string, projectRoot: string): string | null {
+  return path.resolve(projectRoot, entry)
+}
diff --git a/packages/android-client/expo-plugin/src/android/files/clientRenderedPrerender.node.test.ts b/packages/android-client/expo-plugin/src/android/files/clientRenderedPrerender.node.test.ts
new file mode 100644
index 00000000..5da00c3d
--- /dev/null
+++ b/packages/android-client/expo-plugin/src/android/files/clientRenderedPrerender.node.test.ts
@@ -0,0 +1,68 @@
+import * as fs from 'fs'
+import * as os from 'os'
+import * as path from 'path'
+
+import { prerenderClientRenderedAndroidWidgets } from './clientRenderedPrerender'
+import type { DetectedAndroidWidget } from '../clientRendered'
+
+jest.mock('@use-voltra/android', () => ({
+  renderAndroidVariantToJson: jest.fn((value: unknown) => value),
+}))
+
+const { renderAndroidVariantToJson } = jest.requireMock('@use-voltra/android') as {
+  renderAndroidVariantToJson: jest.Mock
+}
+
+function makeTempProject(files: Record<string, string>): { projectRoot: string; cleanup: () => void } {
+  const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'voltra-android-client-prerender-'))
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = path.join(projectRoot, rel)
+    fs.mkdirSync(path.dirname(abs), { recursive: true })
+    fs.writeFileSync(abs, content)
+  }
+  return {
+    projectRoot,
+    cleanup: () => fs.rmSync(projectRoot, { recursive: true, force: true }),
+  }
+}
+
+describe('prerenderClientRenderedAndroidWidgets', () => {
+  afterEach(() => {
+    renderAndroidVariantToJson.mockClear()
+  })
+
+  it('evaluates the entry default export for a Dynamic Widget placeholder', async () => {
+    const { projectRoot, cleanup } = makeTempProject({
+      'widgets/Dynamic.tsx': `
+        export default function NotTheWidgetId(props, env) {
+          return {
+            source: 'entry',
+            widgetFamily: env.widgetFamily,
+            hasProps: typeof props === 'object',
+          }
+        }
+      `,
+    })
+
+    try {
+      const widget: DetectedAndroidWidget = {
+        id: 'dynamic_widget',
+        entry: './widgets/Dynamic.tsx',
+        displayName: 'Dynamic Widget',
+        description: 'Uses the entry default export',
+        targetCellWidth: 2,
+        targetCellHeight: 2,
+        clientRendered: true,
+        clientSourcePath: path.join(projectRoot, 'widgets/Dynamic.tsx'),
+      }
+
+      const result = await prerenderClientRenderedAndroidWidgets([widget], projectRoot)
+
+      expect(renderAndroidVariantToJson).toHaveBeenCalledTimes(1)
+      expect(result.get('dynamic_widget')?.get('__default')).toContain('"source":"entry"')
+      expect(result.get('dynamic_widget')?.get('__default')).toContain('"widgetFamily":"200x200"')
+    } finally {
+      cleanup()
+    }
+  })
+})
diff --git a/packages/android-client/expo-plugin/src/android/files/clientRenderedPrerender.ts b/packages/android-client/expo-plugin/src/android/files/clientRenderedPrerender.ts
new file mode 100644
index 00000000..58965685
--- /dev/null
+++ b/packages/android-client/expo-plugin/src/android/files/clientRenderedPrerender.ts
@@ -0,0 +1,79 @@
+import { evaluateWidgetModuleExports, logger, type PrerenderedWidgetStates } from '@use-voltra/expo-plugin'
+
+import type { DetectedAndroidWidget } from '../clientRendered'
+
+/**
+ * Placeholder prerender for Dynamic Android Widgets — the counterpart of the iOS
+ * plugin's clientRenderedPrerender.ts.
+ *
+ * Widgets with `initialStatePath` prerender from `exports.default` (a variants object).
+ * Dynamic Widgets instead default-export a `(props, env) => JSX` function, so there is no
+ * default state to prerender. To still show something before the first Metro fetch (and when
+ * offline), we call that function once at prebuild with empty props + a minimal env, render the
+ * single node via `renderAndroidVariantToJson`, and store it in the same
+ * `voltra_initial_states.json` the runtime already reads. `VoltraClientGlanceWidget` decodes that
+ * node for its fallback.
+ */
+
+const SINGLE_LOCALE_KEY = '__default'
+
+function buildPlaceholderEnv(): Record<string, unknown> {
+  return {
+    date: Date.now(),
+    widgetFamily: '200x200',
+    colorScheme: 'light',
+    locale: 'en-US',
+    configuration: undefined,
+    build: {
+      isDev: false,
+      metroUrl: null,
+      appVersion: 'unknown',
+      voltraVersion: '1.4.1',
+    },
+  }
+}
+
+export async function prerenderClientRenderedAndroidWidgets(
+  widgets: DetectedAndroidWidget[],
+  projectRoot: string
+): Promise<PrerenderedWidgetStates> {
+  const results: PrerenderedWidgetStates = new Map()
+
+  const clientWidgets = widgets.filter(
+    (w): w is Extract<DetectedAndroidWidget, { clientRendered: true }> => w.clientRendered
+  )
+  if (clientWidgets.length === 0) {
+    return results
+  }
+
+  // Dynamic import keeps the plugin CommonJS-compatible and resolves the current package entry.
+  const androidModuleId = '@use-voltra/android'
+  const { renderAndroidVariantToJson } = (await import(androidModuleId)) as {
+    renderAndroidVariantToJson: (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 = renderAndroidVariantToJson(element)
+      results.set(widget.id, new Map([[SINGLE_LOCALE_KEY, JSON.stringify(json)]]))
+    } 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 Android Widget placeholder(s)`)
+  return results
+}
diff --git a/packages/android-client/expo-plugin/src/android/files/configDefaults.node.test.ts b/packages/android-client/expo-plugin/src/android/files/configDefaults.node.test.ts
new file mode 100644
index 00000000..02835cc3
--- /dev/null
+++ b/packages/android-client/expo-plugin/src/android/files/configDefaults.node.test.ts
@@ -0,0 +1,71 @@
+import * as fs from 'fs'
+import * as os from 'os'
+import * as path from 'path'
+
+import type { AndroidWidgetConfig } from '../../types'
+import { generateAndroidConfigDefaults } from './configDefaults'
+
+function makeTempProjectRoot(): { platformProjectRoot: string; cleanup: () => void } {
+  const platformProjectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'voltra-android-config-defaults-'))
+  return {
+    platformProjectRoot,
+    cleanup: () => fs.rmSync(platformProjectRoot, { recursive: true, force: true }),
+  }
+}
+
+function widget(partial: Partial<AndroidWidgetConfig>): AndroidWidgetConfig {
+  return {
+    id: 'W',
+    entry: './widgets/W.tsx',
+    displayName: 'W',
+    description: 'W',
+    targetCellWidth: 2,
+    targetCellHeight: 2,
+    ...partial,
+  }
+}
+
+const DEFAULTS_PATH = ['app', 'src', 'main', 'assets', 'voltra', 'widget_config_defaults.json']
+
+describe('generateAndroidConfigDefaults', () => {
+  it('emits the declared defaults keyed by widget id', async () => {
+    const { platformProjectRoot, cleanup } = makeTempProjectRoot()
+    try {
+      await generateAndroidConfigDefaults({
+        platformProjectRoot,
+        widgets: [
+          widget({
+            id: 'AndroidClientDemoWidget',
+            appIntent: { parameters: [{ name: 'label', title: 'Label', default: 'Hello' }] },
+          }),
+        ],
+      })
+
+      const file = path.join(platformProjectRoot, ...DEFAULTS_PATH)
+      expect(fs.existsSync(file)).toBe(true)
+      expect(JSON.parse(fs.readFileSync(file, 'utf8'))).toEqual({
+        AndroidClientDemoWidget: { label: 'Hello' },
+      })
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('omits parameters without a default, and writes nothing when no widget declares defaults', async () => {
+    const { platformProjectRoot, cleanup } = makeTempProjectRoot()
+    try {
+      await generateAndroidConfigDefaults({
+        platformProjectRoot,
+        widgets: [
+          widget({ id: 'NoConfig' }),
+          widget({ id: 'NoDefault', appIntent: { parameters: [{ name: 'city', title: 'City' }] } }),
+        ],
+      })
+
+      const file = path.join(platformProjectRoot, ...DEFAULTS_PATH)
+      expect(fs.existsSync(file)).toBe(false)
+    } finally {
+      cleanup()
+    }
+  })
+})
diff --git a/packages/android-client/expo-plugin/src/android/files/configDefaults.ts b/packages/android-client/expo-plugin/src/android/files/configDefaults.ts
new file mode 100644
index 00000000..8b05e173
--- /dev/null
+++ b/packages/android-client/expo-plugin/src/android/files/configDefaults.ts
@@ -0,0 +1,48 @@
+import fs from 'fs'
+import path from 'path'
+
+import { logger } from '@use-voltra/expo-plugin'
+
+import type { AndroidWidgetConfig } from '../../types'
+
+export interface GenerateConfigDefaultsOptions {
+  widgets: AndroidWidgetConfig[]
+  platformProjectRoot: string
+}
+
+/**
+ * Emits the code-declared widget configuration defaults to
+ * `assets/voltra/widget_config_defaults.json`, read at render time by VoltraConfigurationStore and
+ * surfaced as `env.configuration` before the user configures anything (the Android equivalent of
+ * iOS's `@Parameter(default:)`).
+ *
+ * Shape: `{ "<widgetId>": { "<paramName>": "<default>" } }`. Only parameters that declare a
+ * `default` are emitted. No file is written when nothing declares defaults.
+ */
+export async function generateAndroidConfigDefaults(options: GenerateConfigDefaultsOptions): Promise<void> {
+  const { widgets, platformProjectRoot } = options
+
+  const defaults: Record<string, Record<string, string>> = {}
+  for (const widget of widgets) {
+    const params = widget.appIntent?.parameters ?? []
+    const widgetDefaults: Record<string, string> = {}
+    for (const param of params) {
+      if (typeof param.default === 'string') {
+        widgetDefaults[param.name] = param.default
+      }
+    }
+    if (Object.keys(widgetDefaults).length > 0) {
+      defaults[widget.id] = widgetDefaults
+    }
+  }
+
+  if (Object.keys(defaults).length === 0) {
+    return
+  }
+
+  const voltraAssetsDir = path.join(platformProjectRoot, 'app', 'src', 'main', 'assets', 'voltra')
+  fs.mkdirSync(voltraAssetsDir, { recursive: true })
+  fs.writeFileSync(path.join(voltraAssetsDir, 'widget_config_defaults.json'), JSON.stringify(defaults, null, 2))
+
+  logger.info(`Generated widget_config_defaults.json for ${Object.keys(defaults).length} widget(s)`)
+}
diff --git a/packages/android-client/expo-plugin/src/android/files/index.ts b/packages/android-client/expo-plugin/src/android/files/index.ts
index b0212c9b..36cc0b27 100644
--- a/packages/android-client/expo-plugin/src/android/files/index.ts
+++ b/packages/android-client/expo-plugin/src/android/files/index.ts
@@ -1,7 +1,9 @@
 import { ConfigPlugin, withDangerousMod } from '@expo/config-plugins'
 
 import type { AndroidWidgetConfig } from '../../types'
+import { detectClientRenderedWidgets } from '../clientRendered'
 import { generateAndroidAssets } from './assets'
+import { generateAndroidConfigDefaults } from './configDefaults'
 import { copyAndroidFonts } from './fonts'
 import { generateAndroidInitialStates } from './initialStates'
 import { generateWidgetReceivers } from './kotlin'
@@ -44,6 +46,10 @@ export const generateAndroidWidgetFiles: ConfigPlugin<GenerateAndroidWidgetFiles
         )
       }
 
+      // Tag each widget once; Dynamic Widget detection drives receiver wiring and placeholder
+      // prerendering. Other generators ignore the extra fields.
+      const detectedWidgets = detectClientRenderedWidgets(widgets, projectRoot)
+
       // Generate assets (drawable images and preview images)
       const previewImageMap = await generateAndroidAssets({
         platformProjectRoot,
@@ -56,7 +62,7 @@ export const generateAndroidWidgetFiles: ConfigPlugin<GenerateAndroidWidgetFiles
       await generateWidgetReceivers({
         platformProjectRoot,
         packageName,
-        widgets,
+        widgets: detectedWidgets,
       })
 
       // Generate XML files (widget info, layouts, strings)
@@ -89,6 +95,12 @@ export const generateAndroidWidgetFiles: ConfigPlugin<GenerateAndroidWidgetFiles
       await generateAndroidInitialStates({
         platformProjectRoot,
         projectRoot: config.modRequest.projectRoot,
+        widgets: detectedWidgets,
+      })
+
+      // Emit code-declared client widget configuration defaults (env.configuration).
+      await generateAndroidConfigDefaults({
+        platformProjectRoot,
         widgets,
       })
 
diff --git a/packages/android-client/expo-plugin/src/android/files/initialStates.ts b/packages/android-client/expo-plugin/src/android/files/initialStates.ts
index b8ecc551..7a6c174d 100644
--- a/packages/android-client/expo-plugin/src/android/files/initialStates.ts
+++ b/packages/android-client/expo-plugin/src/android/files/initialStates.ts
@@ -1,14 +1,16 @@
 import fs from 'fs'
 import path from 'path'
 
-import type { AndroidWidgetConfig } from '../../types'
 import { logger, prerenderWidgetState, type PrerenderedWidgetStates } from '@use-voltra/expo-plugin'
 
+import type { DetectedAndroidWidget } from '../clientRendered'
+import { prerenderClientRenderedAndroidWidgets } from './clientRenderedPrerender'
+
 /** Wrapped asset shape when multiple locales are built; matches Android reader in VoltraWidgetManager */
 export const VOLTRA_LOCALIZED_INITIAL_STATE_KEY = '__voltraLocales'
 
 export interface GenerateInitialStatesOptions {
-  widgets: AndroidWidgetConfig[]
+  widgets: DetectedAndroidWidget[]
   projectRoot: string
   platformProjectRoot: string
 }
@@ -30,13 +32,22 @@ export async function generateAndroidInitialStates(options: GenerateInitialState
     renderAndroidWidgetToString: RenderAndroidWidgetToString
   }
 
-  // Prerender widget states (per locale when `initialStatePath` is a locale map)
+  // Widgets with `initialStatePath` prerender from `exports.default`. Dynamic Widgets instead
+  // default-export a `(props, env) => JSX` function, so they're excluded here and prerendered
+  // separately below — feeding a client file to the initial-state prerender would throw.
+  const serverWidgets = widgets.filter((w) => !w.clientRendered)
   const prerenderedStates: PrerenderedWidgetStates = await prerenderWidgetState(
-    widgets,
+    serverWidgets,
     projectRoot,
     renderAndroidWidgetToString
   )
 
+  // Single-node placeholders for Dynamic Widgets (first paint / offline fallback).
+  const clientStates = await prerenderClientRenderedAndroidWidgets(widgets, projectRoot)
+  for (const [id, perLocale] of clientStates.entries()) {
+    prerenderedStates.set(id, perLocale)
+  }
+
   if (prerenderedStates.size === 0) {
     return
   }
diff --git a/packages/android-client/expo-plugin/src/android/files/kotlin.ts b/packages/android-client/expo-plugin/src/android/files/kotlin.ts
index bff40b0a..2e07a4fb 100644
--- a/packages/android-client/expo-plugin/src/android/files/kotlin.ts
+++ b/packages/android-client/expo-plugin/src/android/files/kotlin.ts
@@ -2,13 +2,14 @@ import dedent from 'dedent'
 import * as fs from 'fs'
 import * as path from 'path'
 
-import type { AndroidWidgetConfig } from '../../types'
 import { widgetLabelEnglish } from '@use-voltra/expo-plugin'
 
+import type { DetectedAndroidWidget } from '../clientRendered'
+
 export interface GenerateKotlinFilesProps {
   platformProjectRoot: string
   packageName: string
-  widgets: AndroidWidgetConfig[]
+  widgets: DetectedAndroidWidget[]
 }
 
 // ============================================================================
@@ -48,10 +49,28 @@ export async function generateWidgetReceivers(props: GenerateKotlinFilesProps):
  * Generates Kotlin code for a single widget receiver class.
  * If the widget has serverUpdate configured, includes WorkManager scheduling.
  */
-function generateWidgetReceiverClass(widget: AndroidWidgetConfig, packageName: string): string {
+function generateWidgetReceiverClass(widget: DetectedAndroidWidget, packageName: string): string {
   const className = `VoltraWidget_${widget.id}Receiver`
   const labelForComment = widgetLabelEnglish(widget.displayName)
 
+  // Client-rendered widgets host VoltraClientGlanceWidget (on-device JS render) and have no
+  // server payload, so they never schedule WorkManager server updates.
+  if (widget.clientRendered) {
+    return dedent`
+      package ${packageName}.widget
+
+      import voltra.widget.VoltraClientWidgetReceiver
+
+      /**
+       * Auto-generated client-rendered widget receiver for ${labelForComment}
+       * Widget ID: ${widget.id}
+       */
+      class ${className} : VoltraClientWidgetReceiver() {
+          override val widgetId: String = "${widget.id}"
+      }
+    `
+  }
+
   if (widget.serverUpdate) {
     const refreshEnabled = widget.serverUpdate.refresh === true
     // Widget with server-driven updates: schedule WorkManager periodic task
diff --git a/packages/android-client/expo-plugin/src/android/files/manifest.node.test.ts b/packages/android-client/expo-plugin/src/android/files/manifest.node.test.ts
new file mode 100644
index 00000000..868ce048
--- /dev/null
+++ b/packages/android-client/expo-plugin/src/android/files/manifest.node.test.ts
@@ -0,0 +1,141 @@
+import * as fs from 'fs'
+import * as os from 'os'
+import * as path from 'path'
+
+import { createAndroidDynamicWidgetsManifest, writeAndroidDynamicWidgetsManifest } from './manifest'
+
+function makeTempProject(files: Record<string, string>): { projectRoot: string; cleanup: () => void } {
+  const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'voltra-android-manifest-'))
+
+  for (const [relativePath, contents] of Object.entries(files)) {
+    const filePath = path.join(projectRoot, relativePath)
+    fs.mkdirSync(path.dirname(filePath), { recursive: true })
+    fs.writeFileSync(filePath, contents)
+  }
+
+  return {
+    projectRoot,
+    cleanup: () => fs.rmSync(projectRoot, { recursive: true, force: true }),
+  }
+}
+
+describe('createAndroidDynamicWidgetsManifest', () => {
+  it('normalizes entries relative to the project root', () => {
+    const { projectRoot, cleanup } = makeTempProject({
+      'widgets/home.tsx': 'export default function HomeWidget() {}',
+    })
+
+    try {
+      const manifest = createAndroidDynamicWidgetsManifest(projectRoot, [
+        {
+          id: 'home',
+          entry: './widgets/home.tsx',
+          displayName: 'Home',
+          description: 'Home widget',
+          targetCellWidth: 2,
+          targetCellHeight: 2,
+        },
+      ])
+
+      expect(manifest).toEqual({
+        version: 1,
+        platform: 'android',
+        widgets: [{ id: 'home', entry: 'widgets/home.tsx' }],
+      })
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('omits legacy widgets without entries', () => {
+    const { projectRoot, cleanup } = makeTempProject({
+      'widgets/home.tsx': 'export default function HomeWidget() {}',
+    })
+
+    try {
+      const manifest = createAndroidDynamicWidgetsManifest(projectRoot, [
+        {
+          id: 'legacy',
+          displayName: 'Legacy',
+          description: 'Server-rendered widget',
+          targetCellWidth: 2,
+          targetCellHeight: 2,
+        },
+        {
+          id: 'home',
+          entry: './widgets/home.tsx',
+          displayName: 'Home',
+          description: 'Dynamic widget',
+          targetCellWidth: 2,
+          targetCellHeight: 2,
+        },
+      ])
+
+      expect(manifest).toEqual({
+        version: 1,
+        platform: 'android',
+        widgets: [{ id: 'home', entry: 'widgets/home.tsx' }],
+      })
+    } finally {
+      cleanup()
+    }
+  })
+})
+
+describe('writeAndroidDynamicWidgetsManifest', () => {
+  it('writes the Android manifest with deterministic formatting', () => {
+    const { projectRoot, cleanup } = makeTempProject({
+      '.voltra/manifest.android.json': '{\n  "stale": true\n}\n',
+      'widgets/home.tsx': 'export default function HomeWidget() {}',
+    })
+
+    try {
+      writeAndroidDynamicWidgetsManifest(projectRoot, [
+        {
+          id: 'home',
+          entry: './widgets/home.tsx',
+          displayName: 'Home',
+          description: 'Home widget',
+          targetCellWidth: 2,
+          targetCellHeight: 2,
+        },
+      ])
+
+      const manifestPath = path.join(projectRoot, '.voltra', 'manifest.android.json')
+      expect(fs.readFileSync(manifestPath, 'utf8')).toBe(
+        [
+          '{',
+          '  "version": 1,',
+          '  "platform": "android",',
+          '  "widgets": [',
+          '    {',
+          '      "id": "home",',
+          '      "entry": "widgets/home.tsx"',
+          '    }',
+          '  ]',
+          '}',
+          '',
+        ].join('\n')
+      )
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('writes an empty manifest instead of leaving stale widget declarations behind', () => {
+    const { projectRoot, cleanup } = makeTempProject({
+      '.voltra/manifest.android.json':
+        '{\n  "version": 1,\n  "platform": "android",\n  "widgets": [{ "id": "old", "entry": "old.tsx" }]\n}\n',
+    })
+
+    try {
+      writeAndroidDynamicWidgetsManifest(projectRoot, [])
+
+      expect(fs.readFileSync(path.join(projectRoot, '.voltra', 'manifest.android.json'), 'utf8')).toBe(
+        ['{', '  "version": 1,', '  "platform": "android",', '  "widgets": []', '}', ''].join('\n')
+      )
+    } finally {
+      cleanup()
+    }
+  })
+})
diff --git a/packages/android-client/expo-plugin/src/android/files/manifest.ts b/packages/android-client/expo-plugin/src/android/files/manifest.ts
new file mode 100644
index 00000000..446cb69a
--- /dev/null
+++ b/packages/android-client/expo-plugin/src/android/files/manifest.ts
@@ -0,0 +1,74 @@
+import { ConfigPlugin, withDangerousMod } from '@expo/config-plugins'
+import * as fs from 'fs'
+import * as path from 'path'
+
+import { type DynamicWidgetManifest, logger, validateWidgetEntry } from '@use-voltra/expo-plugin'
+
+import type { AndroidWidgetConfig } from '../../types'
+
+const MANIFEST_PATH = path.join('.voltra', 'manifest.android.json')
+
+export interface GenerateAndroidDynamicWidgetsManifestOptions {
+  widgets?: AndroidWidgetConfig[]
+}
+
+export function createAndroidDynamicWidgetsManifest(
+  projectRoot: string,
+  widgets: AndroidWidgetConfig[]
+): 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: 'android',
+    widgets: manifestWidgets,
+  }
+}
+
+export function writeAndroidDynamicWidgetsManifest(projectRoot: string, widgets: AndroidWidgetConfig[]): void {
+  const manifestPath = path.join(projectRoot, MANIFEST_PATH)
+  const manifest = createAndroidDynamicWidgetsManifest(projectRoot, widgets)
+
+  fs.mkdirSync(path.dirname(manifestPath), { recursive: true })
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
+  logger.info(`Generated ${MANIFEST_PATH}`)
+}
+
+/**
+ * Writes the Android-owned Dynamic Widgets manifest during prebuild.
+ */
+export const generateAndroidDynamicWidgetsManifest: ConfigPlugin<GenerateAndroidDynamicWidgetsManifestOptions> = (
+  config,
+  props
+) => {
+  const { widgets } = props
+
+  return withDangerousMod(config, [
+    'android',
+    async (config) => {
+      if (config.modRequest.introspect) {
+        return config
+      }
+
+      const { projectRoot } = config.modRequest
+      if (!projectRoot) {
+        throw new Error('Voltra Android manifest generation requires expo mod projectRoot to be set.')
+      }
+
+      writeAndroidDynamicWidgetsManifest(projectRoot, widgets ?? [])
+
+      return config
+    },
+  ])
+}
diff --git a/packages/android-client/expo-plugin/src/android/files/xml.ts b/packages/android-client/expo-plugin/src/android/files/xml.ts
index 54cafa00..bd67a558 100644
--- a/packages/android-client/expo-plugin/src/android/files/xml.ts
+++ b/packages/android-client/expo-plugin/src/android/files/xml.ts
@@ -5,6 +5,7 @@ import * as path from 'path'
 import { isWidgetLocalizedMap, logger, widgetLabelEnglish } from '@use-voltra/expo-plugin'
 
 import type { AndroidWidgetConfig } from '../../types'
+import { androidWidgetResourceId } from '../resourceName'
 
 export interface GenerateXmlFilesProps {
   platformProjectRoot: string
@@ -95,7 +96,7 @@ export async function generateWidgetPreviewLayouts(props: GenerateXmlFilesProps)
 
   // Write widget info XML for all widgets, including preview references where available
   for (const widget of widgets) {
-    const widgetInfoPath = path.join(xmlPath, `voltra_widget_${widget.id}_info.xml`)
+    const widgetInfoPath = path.join(xmlPath, `voltra_widget_${androidWidgetResourceId(widget.id)}_info.xml`)
     const previewImageResourceName = previewImageMap.get(widget.id)
     const previewLayoutResourceName = previewLayoutMap.get(widget.id)
     const widgetInfoContent = generateWidgetInfoXml(widget, previewImageResourceName, previewLayoutResourceName)
@@ -147,7 +148,9 @@ function generateWidgetInfoXml(
         android:initialLayout="@layout/voltra_widget_placeholder"
         android:resizeMode="${resizeMode}"
         android:widgetCategory="${widgetCategory}"
-        android:description="@string/voltra_widget_${widget.id}_description"${previewImageAttr}${previewLayoutAttr}>
+        android:description="@string/voltra_widget_${androidWidgetResourceId(
+          widget.id
+        )}_description"${previewImageAttr}${previewLayoutAttr}>
     </appwidget-provider>
   `
 }
@@ -284,7 +287,8 @@ function generateVoltraWidgetsStringResourcesXml(widgets: AndroidWidgetConfig[],
     .map((widget) => {
       const label = escapeAndroidStringRes(resolveAndroidWidgetLabel(widget, 'displayName', localeKey))
       const desc = escapeAndroidStringRes(resolveAndroidWidgetLabel(widget, 'description', localeKey))
-      return `<string name="voltra_widget_${widget.id}_label">${label}</string>\n    <string name="voltra_widget_${widget.id}_description">${desc}</string>`
+      const resId = androidWidgetResourceId(widget.id)
+      return `<string name="voltra_widget_${resId}_label">${label}</string>\n    <string name="voltra_widget_${resId}_description">${desc}</string>`
     })
     .join('\n    ')
 
@@ -376,7 +380,7 @@ function generateAutoImagePreviewLayout(widgetId: string, drawableResourceName:
             android:layout_height="match_parent"
             android:src="@drawable/${drawableResourceName}"
             android:scaleType="centerCrop"
-            android:contentDescription="@string/voltra_widget_${widgetId}_description" />
+            android:contentDescription="@string/voltra_widget_${androidWidgetResourceId(widgetId)}_description" />
     </FrameLayout>
   `
 }
@@ -405,7 +409,7 @@ async function generatePreviewLayouts(
 
   for (const widget of widgets) {
     let layoutContent: string | null = null
-    const layoutResourceName = `voltra_widget_${widget.id}_preview`
+    const layoutResourceName = `voltra_widget_${androidWidgetResourceId(widget.id)}_preview`
     const layoutFilePath = path.join(layoutPath, `${layoutResourceName}.xml`)
 
     // Strategy 1: User provided custom preview layout
diff --git a/packages/android-client/expo-plugin/src/android/gradle.node.test.ts b/packages/android-client/expo-plugin/src/android/gradle.node.test.ts
new file mode 100644
index 00000000..cdf3e2b8
--- /dev/null
+++ b/packages/android-client/expo-plugin/src/android/gradle.node.test.ts
@@ -0,0 +1,32 @@
+import { __test__ } from './gradle'
+
+const { MARKER, addWidgetBundleGradle } = __test__
+
+const BASE_GRADLE = `apply plugin: "com.android.application"
+
+android {
+    namespace "com.example.app"
+}
+`
+
+describe('addWidgetBundleGradle', () => {
+  it('appends the release widget-bundling wiring', () => {
+    const result = addWidgetBundleGradle(BASE_GRADLE)
+    expect(result).toContain(MARKER)
+    expect(result).toContain('tasks.register("voltraBundleWidgets", Exec)')
+    expect(result).toContain("resolve('@use-voltra/metro/bundle-widgets')")
+    expect(result).toContain('--platform android')
+    // release-gated + wired into the asset merge
+    expect(result).toContain('variant.buildType.name == "release"')
+    expect(result).toContain('merge${variant.name.capitalize()}Assets')
+    // original contents preserved
+    expect(result).toContain('apply plugin: "com.android.application"')
+  })
+
+  it('is idempotent — a second pass does not duplicate the snippet', () => {
+    const once = addWidgetBundleGradle(BASE_GRADLE)
+    const twice = addWidgetBundleGradle(once)
+    expect(twice).toBe(once)
+    expect(twice.match(new RegExp(MARKER.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&'), 'g'))).toHaveLength(1)
+  })
+})
diff --git a/packages/android-client/expo-plugin/src/android/gradle.ts b/packages/android-client/expo-plugin/src/android/gradle.ts
new file mode 100644
index 00000000..5e351a26
--- /dev/null
+++ b/packages/android-client/expo-plugin/src/android/gradle.ts
@@ -0,0 +1,71 @@
+import { ConfigPlugin, withAppBuildGradle } from '@expo/config-plugins'
+
+import { logger } from '@use-voltra/expo-plugin'
+
+import type { AndroidWidgetConfig } from '../types'
+import { detectClientRenderedWidgets } from './clientRendered'
+
+const MARKER = '// @voltra-widget-bundling'
+
+// Release-only Gradle wiring that bakes each Dynamic Widget's production JS bundle into the
+// app's assets — the Android analog of iOS's release "Bundle Voltra client widgets" build phase.
+// Debug keeps fetching from Metro (and hot-reloading); only release variants depend on the task,
+// and the generated dir is empty otherwise. Re-bakes every build (it can't enumerate widget-source
+// inputs). The bundle lands at assets/voltra/voltra-widget-<id>.bundle, which the runtime's release
+// loader reads from Bundle assets.
+const GRADLE_SNIPPET = `
+${MARKER} — generated by @use-voltra/android-client; do not edit
+def voltraProjectRoot = file("\${rootDir}/..")
+def voltraWidgetAssetsDir = file("\${buildDir}/generated/voltra/assets")
+android.sourceSets.getByName("main").assets.srcDir(voltraWidgetAssetsDir)
+
+def voltraBundleWidgets = tasks.register("voltraBundleWidgets", Exec) {
+    description = "Bake client-rendered Voltra widget bundles into assets (release)."
+    workingDir voltraProjectRoot
+    environment "VOLTRA_PROJECT_ROOT", voltraProjectRoot.absolutePath
+    environment "VOLTRA_OUT_DIR", new File(voltraWidgetAssetsDir, "voltra").absolutePath
+    environment "VOLTRA_BUNDLER_RESOLVER", "const m=require('module'),p=require('path');process.stdout.write(m.createRequire(p.join(process.argv[1],'package.json')).resolve('@use-voltra/metro/bundle-widgets'))"
+    commandLine "bash", "-c", 'BUNDLER="$(node -e "$VOLTRA_BUNDLER_RESOLVER" "$VOLTRA_PROJECT_ROOT")"; if [ -z "$BUNDLER" ]; then echo "error: Voltra could not resolve @use-voltra/metro/bundle-widgets from $VOLTRA_PROJECT_ROOT — install @use-voltra/metro so release widgets can be baked." >&2; exit 1; fi; node "$BUNDLER" --platform android --out-dir "$VOLTRA_OUT_DIR" --project-root "$VOLTRA_PROJECT_ROOT"'
+    outputs.upToDateWhen { false }
+}
+
+android.applicationVariants.all { variant ->
+    if (variant.buildType.name == "release") {
+        tasks.named("merge\${variant.name.capitalize()}Assets").configure { dependsOn voltraBundleWidgets }
+    }
+}
+`
+
+/**
+ * Appends the release widget-bundling Gradle wiring to `app/build.gradle`, idempotently, and only
+ * when at least one Dynamic Widget is present (server-rendered apps need no JS bundle baked).
+ */
+export const withWidgetBundleGradle: ConfigPlugin<{ widgets: AndroidWidgetConfig[] }> = (config, { widgets }) => {
+  return withAppBuildGradle(config, (cfg) => {
+    const hasClientRenderedWidgets = detectClientRenderedWidgets(widgets, cfg.modRequest.projectRoot).some(
+      (widget) => widget.clientRendered
+    )
+    if (!hasClientRenderedWidgets) {
+      return cfg
+    }
+
+    if (cfg.modResults.language !== 'groovy') {
+      logger.warn('Voltra: app/build.gradle is not Groovy — skipping client widget release bundling wiring.')
+      return cfg
+    }
+
+    cfg.modResults.contents = addWidgetBundleGradle(cfg.modResults.contents)
+    return cfg
+  })
+}
+
+/** Append the widget-bundling snippet to build.gradle contents, idempotently (returns unchanged
+ *  contents if already present). */
+export function addWidgetBundleGradle(contents: string): string {
+  if (contents.includes(MARKER)) {
+    return contents
+  }
+  return `${contents.trimEnd()}\n${GRADLE_SNIPPET}\n`
+}
+
+export const __test__ = { MARKER, addWidgetBundleGradle }
diff --git a/packages/android-client/expo-plugin/src/android/index.ts b/packages/android-client/expo-plugin/src/android/index.ts
index 311f6d79..6be478f6 100644
--- a/packages/android-client/expo-plugin/src/android/index.ts
+++ b/packages/android-client/expo-plugin/src/android/index.ts
@@ -3,6 +3,7 @@ import { ConfigPlugin, withPlugins } from '@expo/config-plugins'
 import type { AndroidPluginProps } from '../types'
 import { validateAndroidWidgetConfig } from '../validation'
 import { generateAndroidWidgetFiles } from './files'
+import { withWidgetBundleGradle } from './gradle'
 import { configureAndroidManifest } from './manifest'
 
 /**
@@ -24,5 +25,6 @@ export const withAndroid: ConfigPlugin<AndroidPluginProps> = (config, props) =>
   return withPlugins(config, [
     [generateAndroidWidgetFiles, { widgets, userImagesPath, fonts }],
     [configureAndroidManifest, { enableNotifications, widgets }],
+    [withWidgetBundleGradle, { widgets }],
   ])
 }
diff --git a/packages/android-client/expo-plugin/src/android/manifest.ts b/packages/android-client/expo-plugin/src/android/manifest.ts
index 51c97002..4f45b15c 100644
--- a/packages/android-client/expo-plugin/src/android/manifest.ts
+++ b/packages/android-client/expo-plugin/src/android/manifest.ts
@@ -2,6 +2,7 @@ import { ConfigPlugin, withAndroidManifest } from '@expo/config-plugins'
 import { AndroidConfig } from 'expo/config-plugins'
 
 import type { AndroidWidgetConfig } from '../types'
+import { androidWidgetResourceId } from './resourceName'
 
 export interface ConfigureAndroidManifestProps {
   enableNotifications?: boolean
@@ -63,6 +64,7 @@ export const configureAndroidManifest: ConfigPlugin<ConfigureAndroidManifestProp
     // Add a receiver for each widget
     for (const widget of widgets) {
       const receiverClassName = `.widget.VoltraWidget_${widget.id}Receiver`
+      const resId = androidWidgetResourceId(widget.id)
 
       // Check if receiver already exists
       const alreadyExists = existingReceivers.some(
@@ -75,7 +77,7 @@ export const configureAndroidManifest: ConfigPlugin<ConfigureAndroidManifestProp
           $: {
             'android:name': receiverClassName,
             'android:exported': 'true' as const,
-            'android:label': `@string/voltra_widget_${widget.id}_label`,
+            'android:label': `@string/voltra_widget_${resId}_label`,
           },
           'intent-filter': [
             {
@@ -92,7 +94,7 @@ export const configureAndroidManifest: ConfigPlugin<ConfigureAndroidManifestProp
             {
               $: {
                 'android:name': 'android.appwidget.provider',
-                'android:resource': `@xml/voltra_widget_${widget.id}_info`,
+                'android:resource': `@xml/voltra_widget_${resId}_info`,
               },
             },
           ],
diff --git a/packages/android-client/expo-plugin/src/android/resourceName.ts b/packages/android-client/expo-plugin/src/android/resourceName.ts
new file mode 100644
index 00000000..07b07f2e
--- /dev/null
+++ b/packages/android-client/expo-plugin/src/android/resourceName.ts
@@ -0,0 +1,11 @@
+/**
+ * Android resource names (XML filenames, string names, etc.) must contain only lowercase a-z,
+ * 0-9, or underscore. Widget ids may be PascalCase — client-rendered widgets use their component
+ * name as the id (it is also the Metro bundle URL key and the receiver class-name segment), which
+ * is invalid as a resource name. Derive a valid resource-name segment from the id.
+ *
+ * Idempotent for already-valid (lowercase/underscore) ids, so server widgets are unaffected.
+ */
+export function androidWidgetResourceId(id: string): string {
+  return id.toLowerCase().replace(/[^a-z0-9_]/g, '_')
+}
diff --git a/packages/android-client/expo-plugin/src/index.ts b/packages/android-client/expo-plugin/src/index.ts
index 4ba2beb0..860dfa0a 100644
--- a/packages/android-client/expo-plugin/src/index.ts
+++ b/packages/android-client/expo-plugin/src/index.ts
@@ -1,5 +1,6 @@
 import { withAndroid } from './android'
-import type { AndroidConfigPluginProps, VoltraAndroidConfigPlugin } from './types'
+import { generateAndroidDynamicWidgetsManifest } from './android/files/manifest'
+import type { VoltraAndroidConfigPlugin } from './types'
 import { validateAndroidConfigPluginProps } from './validation'
 
 /**
@@ -12,6 +13,12 @@ const withVoltraAndroid: VoltraAndroidConfigPlugin = (config, props = {}) => {
   validateAndroidConfigPluginProps(props, projectRoot)
 
   const widgets = props.widgets ?? []
+  config = generateAndroidDynamicWidgetsManifest(config, { widgets })
+
+  if (!config.android?.package) {
+    return config
+  }
+
   if (widgets.length === 0 && !props.enableNotifications) {
     return config
   }
diff --git a/packages/android-client/expo-plugin/src/types.ts b/packages/android-client/expo-plugin/src/types.ts
index e173f0b0..95896537 100644
--- a/packages/android-client/expo-plugin/src/types.ts
+++ b/packages/android-client/expo-plugin/src/types.ts
@@ -1,11 +1,30 @@
 import type { ConfigPlugin } from '@expo/config-plugins'
 
-import type { WidgetInitialStatePath, WidgetLabel } from '@use-voltra/expo-plugin'
+import type { DynamicWidgetEntryConfig, WidgetInitialStatePath, WidgetLabel } from '@use-voltra/expo-plugin'
+
+/**
+ * A single user-configurable parameter for a client-rendered widget. Android has no system-managed
+ * widget configuration UI (unlike iOS's WidgetConfigurationIntent), so the value is set at runtime
+ * via `setWidgetConfiguration`; `default` is the code-declared value shown before any runtime edit.
+ * The same `appIntent` key is used as on iOS for a single cross-platform `app.json` schema.
+ */
+export interface AppIntentParameter {
+  name: string
+  title?: string
+  default?: string
+}
+
+export interface AndroidWidgetAppIntentConfig {
+  parameters: AppIntentParameter[]
+}
 
 /**
  * Configuration for a single Android home screen widget.
+ *
+ * `entry` is required only for Dynamic Widgets. Widgets without `entry` remain server-rendered /
+ * server-updated legacy widgets and are excluded from the Dynamic Widgets manifest.
  */
-export interface AndroidWidgetConfig {
+export interface AndroidWidgetConfig extends DynamicWidgetEntryConfig {
   id: string
   displayName: WidgetLabel
   description: WidgetLabel
@@ -21,6 +40,12 @@ export interface AndroidWidgetConfig {
   serverUpdate?: AndroidWidgetServerUpdateConfig
   previewImage?: string
   previewLayout?: string
+  /**
+   * Code-declared configuration parameters surfaced to a client-rendered widget as
+   * `env.configuration`. `parameters[].default` is emitted to the app's assets so the widget shows
+   * it before any runtime configuration; runtime values (set via `setWidgetConfiguration`) override.
+   */
+  appIntent?: AndroidWidgetAppIntentConfig
 }
 
 /**
diff --git a/packages/android-client/expo-plugin/src/validation.node.test.ts b/packages/android-client/expo-plugin/src/validation.node.test.ts
index 6b0ca687..4dfdfa4e 100644
--- a/packages/android-client/expo-plugin/src/validation.node.test.ts
+++ b/packages/android-client/expo-plugin/src/validation.node.test.ts
@@ -1,5 +1,24 @@
+import * as fs from 'fs'
+import * as os from 'os'
+import * as path from 'path'
+
 import { validateAndroidConfigPluginProps } from './validation'
 
+function makeTempProject(files: Record<string, string>): { projectRoot: string; cleanup: () => void } {
+  const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'voltra-android-validation-'))
+
+  for (const [relativePath, contents] of Object.entries(files)) {
+    const filePath = path.join(projectRoot, relativePath)
+    fs.mkdirSync(path.dirname(filePath), { recursive: true })
+    fs.writeFileSync(filePath, contents)
+  }
+
+  return {
+    projectRoot,
+    cleanup: () => fs.rmSync(projectRoot, { recursive: true, force: true }),
+  }
+}
+
 describe('validateAndroidConfigPluginProps', () => {
   it('accepts widgets with required cell sizes', () => {
     expect(() =>
@@ -7,6 +26,7 @@ describe('validateAndroidConfigPluginProps', () => {
         widgets: [
           {
             id: 'demo',
+            entry: './widgets/demo.tsx',
             displayName: 'Demo',
             description: 'Demo widget',
             targetCellWidth: 2,
@@ -23,6 +43,7 @@ describe('validateAndroidConfigPluginProps', () => {
         widgets: [
           {
             id: 'demo',
+            entry: './widgets/demo-one.tsx',
             displayName: 'Demo',
             description: 'One',
             targetCellWidth: 2,
@@ -30,6 +51,7 @@ describe('validateAndroidConfigPluginProps', () => {
           },
           {
             id: 'demo',
+            entry: './widgets/demo-two.tsx',
             displayName: 'Demo',
             description: 'Two',
             targetCellWidth: 2,
@@ -39,4 +61,74 @@ describe('validateAndroidConfigPluginProps', () => {
       })
     ).toThrow(/Duplicate Android widget ID/)
   })
+
+  it('accepts legacy widgets without an entry', () => {
+    expect(() =>
+      validateAndroidConfigPluginProps({
+        widgets: [
+          {
+            id: 'demo',
+            displayName: 'Demo',
+            description: 'Demo widget',
+            targetCellWidth: 2,
+            targetCellHeight: 2,
+          },
+        ],
+      })
+    ).not.toThrow()
+  })
+
+  it('requires a valid entry when present and normalizes it against the project root', () => {
+    const { projectRoot, cleanup } = makeTempProject({
+      'widgets/demo.tsx': 'export default () => null\n',
+    })
+
+    try {
+      expect(() =>
+        validateAndroidConfigPluginProps(
+          {
+            widgets: [
+              {
+                id: 'demo',
+                entry: './widgets/demo.tsx',
+                displayName: 'Demo',
+                description: 'Demo widget',
+                targetCellWidth: 2,
+                targetCellHeight: 2,
+              },
+            ],
+          },
+          projectRoot
+        )
+      ).not.toThrow()
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('rejects invalid widget entries when present', () => {
+    const projectRoot = makeTempProject({}).projectRoot
+
+    try {
+      expect(() =>
+        validateAndroidConfigPluginProps(
+          {
+            widgets: [
+              {
+                id: 'demo',
+                entry: './widgets/missing.tsx',
+                displayName: 'Demo',
+                description: 'Demo widget',
+                targetCellWidth: 2,
+                targetCellHeight: 2,
+              },
+            ],
+          },
+          projectRoot
+        )
+      ).toThrow(/Widget 'demo': entry file not found at widgets\/missing\.tsx/)
+    } finally {
+      fs.rmSync(projectRoot, { recursive: true, force: true })
+    }
+  })
 })
diff --git a/packages/android-client/expo-plugin/src/validation.ts b/packages/android-client/expo-plugin/src/validation.ts
index 40124711..9140ad50 100644
--- a/packages/android-client/expo-plugin/src/validation.ts
+++ b/packages/android-client/expo-plugin/src/validation.ts
@@ -1,7 +1,12 @@
 import * as fs from 'fs'
 import * as path from 'path'
 
-import { validateHomeScreenWidgetId, validateInitialStatePath, validateWidgetLabel } from '@use-voltra/expo-plugin'
+import {
+  validateHomeScreenWidgetId,
+  validateInitialStatePath,
+  validateWidgetEntry,
+  validateWidgetLabel,
+} from '@use-voltra/expo-plugin'
 
 import type { AndroidConfigPluginProps, AndroidWidgetConfig } from './types'
 
@@ -11,6 +16,10 @@ export function validateAndroidWidgetConfig(widget: AndroidWidgetConfig, project
   validateWidgetLabel(widget.description, widget.id, 'description')
   validateInitialStatePath(widget.initialStatePath, widget.id, projectRoot)
 
+  if (widget.entry !== undefined) {
+    validateWidgetEntry(widget.entry, widget.id, projectRoot)
+  }
+
   if (typeof widget.targetCellWidth !== 'number') {
     throw new Error(`Widget '${widget.id}': targetCellWidth is required and must be a number`)
   }
diff --git a/packages/android-client/expo-plugin/tsconfig.typecheck.json b/packages/android-client/expo-plugin/tsconfig.typecheck.json
index 58e6f899..0b484180 100644
--- a/packages/android-client/expo-plugin/tsconfig.typecheck.json
+++ b/packages/android-client/expo-plugin/tsconfig.typecheck.json
@@ -5,6 +5,7 @@
     "rootDir": "../../..",
     "baseUrl": "../../..",
     "paths": {
+      "@use-voltra/compiler": ["packages/compiler/src/index.ts"],
       "@use-voltra/expo-plugin": ["packages/expo-plugin/src/index.ts"]
     }
   },
diff --git a/packages/android-client/package.json b/packages/android-client/package.json
index c0cb4095..93d3f5ff 100644
--- a/packages/android-client/package.json
+++ b/packages/android-client/package.json
@@ -48,6 +48,7 @@
     "@babel/core": "^7.27.4",
     "@expo/config-plugins": "~10.1.2",
     "@use-voltra/android": "workspace:^",
+    "@use-voltra/compiler": "workspace:^",
     "@use-voltra/expo-plugin": "workspace:^",
     "dedent": "^1.7.1",
     "vd-tool": "^4.0.2"
diff --git a/packages/android-client/src/index.ts b/packages/android-client/src/index.ts
index efa2cd96..9f9ef0e0 100644
--- a/packages/android-client/src/index.ts
+++ b/packages/android-client/src/index.ts
@@ -50,6 +50,7 @@ export {
   getActiveWidgets,
   reloadAndroidWidgets,
   requestPinAndroidWidget,
+  setWidgetConfiguration,
   updateAndroidWidget,
 } from './widgets/api.js'
 export type {
@@ -72,3 +73,4 @@ export {
   VoltraWidgetPreview,
   type VoltraWidgetPreviewProps,
 } from './components/VoltraWidgetPreview.js'
+export { enableWidgetHotReload } from './utils/enableWidgetHotReload.js'
diff --git a/packages/android-client/src/native/NativeVoltraAndroid.ts b/packages/android-client/src/native/NativeVoltraAndroid.ts
index 272cf439..118a3d6d 100644
--- a/packages/android-client/src/native/NativeVoltraAndroid.ts
+++ b/packages/android-client/src/native/NativeVoltraAndroid.ts
@@ -93,6 +93,7 @@ export interface Spec extends TurboModule {
   openAndroidNotificationSettings(): Promise<void>
   updateAndroidWidget(widgetId: string, jsonString: string, options?: Readonly<{ deepLinkUrl?: string }>): Promise<void>
   reloadAndroidWidgets(widgetIds?: string[] | null): Promise<void>
+  setWidgetConfiguration(widgetId: string, key: string, value: string): Promise<void>
   clearAndroidWidget(widgetId: string): Promise<void>
   clearAllAndroidWidgets(): Promise<void>
   requestPinGlanceAppWidget(widgetId: string, options?: RequestPinGlanceAppWidgetOptionsSpec): Promise<boolean>
diff --git a/packages/android-client/src/utils/enableWidgetHotReload.ts b/packages/android-client/src/utils/enableWidgetHotReload.ts
new file mode 100644
index 00000000..980d9bbd
--- /dev/null
+++ b/packages/android-client/src/utils/enableWidgetHotReload.ts
@@ -0,0 +1,32 @@
+import { reloadAndroidWidgets } from '../widgets/api.js'
+
+declare global {
+  var __accept: (...args: unknown[]) => void
+}
+
+/**
+ * Trigger a widget reload on every Metro Fast Refresh patch (DEV only).
+ *
+ * Hooks the global `__accept` callback Metro fires when a Fast Refresh patch lands in the host
+ * app's JS runtime. When fired, reloads all widgets — for client-rendered widgets this re-runs
+ * `provideGlance`, which re-fetches the freshest bundle from Metro and re-renders. Counterpart of
+ * iOS's `enableWidgetHotReload`.
+ *
+ * Effective while the host app's JS thread is alive (foreground). Call once at app startup.
+ * Returns `dispose()` to restore the prior `__accept`. No-op in release builds.
+ */
+export function enableWidgetHotReload(): () => void {
+  if (!__DEV__) {
+    return () => {}
+  }
+
+  const oldAccept = global['__accept']
+  global['__accept'] = (...args) => {
+    void reloadAndroidWidgets()
+    oldAccept?.(...args)
+  }
+
+  return () => {
+    global['__accept'] = oldAccept
+  }
+}
diff --git a/packages/android-client/src/utils/index.ts b/packages/android-client/src/utils/index.ts
index 49f45673..25cfc113 100644
--- a/packages/android-client/src/utils/index.ts
+++ b/packages/android-client/src/utils/index.ts
@@ -1 +1,2 @@
+export * from './enableWidgetHotReload.js'
 export * from './useUpdateOnHMR.js'
diff --git a/packages/android-client/src/widgets/api.ts b/packages/android-client/src/widgets/api.ts
index 8ce67d34..7eabc58a 100644
--- a/packages/android-client/src/widgets/api.ts
+++ b/packages/android-client/src/widgets/api.ts
@@ -49,3 +49,12 @@ export const requestPinAndroidWidget = async (
 export const getActiveWidgets = async (): Promise<WidgetInfo[]> => {
   return getNativeVoltraAndroid().getActiveWidgets() as Promise<WidgetInfo[]>
 }
+
+/**
+ * Set a configuration value for a client-rendered widget and re-render it. The value is
+ * surfaced as `env.configuration[key]` in the widget's `(props, env) => JSX` render. Stand-in
+ * for a Glance configuration activity.
+ */
+export const setWidgetConfiguration = async (widgetId: string, key: string, value: string): Promise<void> => {
+  return getNativeVoltraAndroid().setWidgetConfiguration(widgetId, key, value)
+}
diff --git a/packages/android/src/index.ts b/packages/android/src/index.ts
index 6472195f..ab67f5bd 100644
--- a/packages/android/src/index.ts
+++ b/packages/android/src/index.ts
@@ -13,6 +13,10 @@ export { renderAndroidLiveUpdateToJson, renderAndroidLiveUpdateToString } from '
 export { AndroidOngoingNotification } from './ongoing-notification/components.js'
 export { renderAndroidOngoingNotificationPayload } from './ongoing-notification/renderer.js'
 export { renderAndroidViewToJson, renderAndroidWidgetToJson, renderAndroidWidgetToString } from './widgets/renderer.js'
+// Single-node renderer used by client-rendered widgets (on-device Hermes render). Analog of
+// iOS `renderVoltraVariantToJson`. Invoked with `(props, env)` per render via the generated
+// widget entry.
+export { renderAndroidVariantToJson } from './renderer/index.js'
 
 // Android types
 export type { VoltraAndroidBaseProps } from './jsx/baseProps.js'
@@ -91,3 +95,5 @@ export type { LinearProgressIndicatorProps } from './jsx/LinearProgressIndicator
 export type { RowProps } from './jsx/Row.js'
 export type { SpacerProps } from './jsx/Spacer.js'
 export type { TextProps } from './jsx/Text.js'
+export { isAndroidEnv, isIosEnv } from '@use-voltra/core'
+export type { WidgetBuildEnvironment, WidgetEnvironment } from '@use-voltra/core'
diff --git a/packages/compiler/README.md b/packages/compiler/README.md
new file mode 100644
index 00000000..7609f8f7
--- /dev/null
+++ b/packages/compiler/README.md
@@ -0,0 +1,93 @@
+![voltra-banner](https://use-voltra.dev/voltra-baner.jpg)
+
+### Shared source analysis utilities for Voltra
+
+[![mit licence][license-badge]][license] [![npm downloads][npm-downloads-badge]][npm-downloads] [![PRs Welcome][prs-welcome-badge]][prs-welcome]
+
+`@use-voltra/compiler` contains the source analysis helpers that power Voltra's widget toolchain. It can still parse JavaScript and TypeScript files, find `'use voltra'` metadata, and return widget records for legacy or future tooling, but registration now comes from app.json and the platform manifests written during prebuild.
+
+## Features
+
+- **Optional directive scanning**: Detect `'use voltra'` in function declarations, function expressions, and arrow functions when tooling needs source metadata or validation.
+
+- **Export-aware analysis**: Match directives to named and default exports so only real widget entry points are returned.
+
+- **TypeScript and JSX support**: Parse common React and React Native source formats, including `.ts`, `.tsx`, `.js`, and `.jsx` files.
+
+- **Shared by Voltra tooling**: Powers `@use-voltra/metro` and other build-time widget workflows.
+
+## Documentation
+
+This package is an internal building block for Voltra's widget toolchain. Relevant topics:
+
+- [Getting Started](https://use-voltra.dev/getting-started/installation)
+- [iOS Widgets](https://use-voltra.dev/ios/development/developing-widgets)
+- [Android Widgets](https://use-voltra.dev/android/development/developing-widgets)
+
+## Getting started
+
+`@use-voltra/compiler` is usually installed as a transitive dependency of the Metro package, but you can install it directly if you want to build custom tooling on top of Voltra's source scanner.
+
+```sh
+npm install @use-voltra/compiler
+```
+
+Use `scanVoltraDirectives()` to inspect a file for optional source metadata:
+
+```ts
+import { scanVoltraDirectives } from '@use-voltra/compiler'
+
+const widgets = scanVoltraDirectives({
+  filePath: '/app/widgets/OrderTracker.tsx',
+  source: `
+    export function OrderTracker() {
+      'use voltra'
+      return null
+    }
+  `,
+})
+
+console.log(widgets)
+```
+
+## Quick example
+
+```ts
+import { scanVoltraDirectives } from '@use-voltra/compiler'
+
+const widgets = scanVoltraDirectives({
+  filePath: 'src/widgets/WeatherWidget.tsx',
+  source: `
+    export const WeatherWidget = () => {
+      'use voltra'
+      return null
+    }
+  `,
+})
+
+for (const widget of widgets) {
+  console.log(widget.id, widget.exportName, widget.sourcePath)
+}
+```
+
+## Platform compatibility
+
+This package is runtime-agnostic and works in Node.js or build-time tooling that needs to analyze Voltra widget source code.
+
+## Authors
+
+Voltra is an open source collaboration between [Saúl Sharma](https://github.com/saulsharma) and [Szymon Chmal](https://github.com/szymonchmal) at [Callstack][callstack-readme-with-love].
+
+If you think it's cool, please star it 🌟. This project will always remain free to use.
+
+[Callstack][callstack-readme-with-love] is a group of React and React Native geeks, contact us at [hello@callstack.com](mailto:hello@callstack.com) if you need any help with these or just want to say hi!
+
+Like the project? ⚛️ [Join the Callstack team](https://callstack.com/careers/?utm_campaign=Senior_RN&utm_source=github&utm_medium=readme) who does amazing stuff for clients and drives React Native Open Source! 🔥
+
+[callstack-readme-with-love]: https://callstack.com/?utm_source=github.com&utm_medium=referral&utm_campaign=voltra&utm_term=readme-with-love
+[license-badge]: https://img.shields.io/npm/l/@use-voltra/compiler?style=for-the-badge
+[license]: https://github.com/callstackincubator/voltra/blob/main/LICENSE.txt
+[npm-downloads-badge]: https://img.shields.io/npm/dm/@use-voltra/compiler?style=for-the-badge
+[npm-downloads]: https://www.npmjs.com/package/@use-voltra/compiler
+[prs-welcome-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge
+[prs-welcome]: ../../CONTRIBUTING.md
diff --git a/packages/compiler/package.json b/packages/compiler/package.json
new file mode 100644
index 00000000..0121af7b
--- /dev/null
+++ b/packages/compiler/package.json
@@ -0,0 +1,48 @@
+{
+  "name": "@use-voltra/compiler",
+  "version": "1.4.1",
+  "description": "Shared Voltra source analysis utilities",
+  "main": "build/cjs/index.js",
+  "module": "build/esm/index.js",
+  "types": "build/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/types/index.d.ts",
+      "require": "./build/cjs/index.js",
+      "import": "./build/esm/index.js",
+      "default": "./build/esm/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "build",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs packages/compiler",
+    "clean": "rm -rf build",
+    "lint": "oxlint src",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@babel/parser": "^7.27.4",
+    "@babel/types": "^7.27.4"
+  },
+  "keywords": [
+    "voltra",
+    "compiler",
+    "directive"
+  ],
+  "author": "Saúl Sharma (https://x.com/saul_sharma), Szymon Chmal (https://x.com/chmalszymon)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/callstackincubator/voltra.git",
+    "directory": "packages/compiler"
+  },
+  "bugs": {
+    "url": "https://github.com/callstackincubator/voltra/issues"
+  },
+  "license": "MIT",
+  "homepage": "https://use-voltra.dev"
+}
diff --git a/packages/compiler/src/index.ts b/packages/compiler/src/index.ts
new file mode 100644
index 00000000..e9f7b266
--- /dev/null
+++ b/packages/compiler/src/index.ts
@@ -0,0 +1,241 @@
+import path from 'node:path'
+
+import * as parser from '@babel/parser'
+
+const supportedExtensions = new Set(['.cjs', '.js', '.jsx', '.mjs', '.ts', '.tsx'])
+
+export type VoltraDirectiveWidget = {
+  id: string
+  componentName: string
+  exportName: string
+  sourcePath: string
+}
+
+type ExportedLocals = Map<string, Set<string>>
+
+type DirectiveFunction =
+  | import('@babel/types').FunctionDeclaration
+  | import('@babel/types').FunctionExpression
+  | import('@babel/types').ArrowFunctionExpression
+
+function hasVoltraDirective(
+  functionNode: import('@babel/types').Node | null | undefined
+): functionNode is DirectiveFunction {
+  if (
+    !functionNode ||
+    (functionNode.type !== 'FunctionDeclaration' &&
+      functionNode.type !== 'FunctionExpression' &&
+      functionNode.type !== 'ArrowFunctionExpression')
+  ) {
+    return false
+  }
+
+  const { body } = functionNode
+  if (body.type !== 'BlockStatement') {
+    return false
+  }
+
+  return body.directives.some((item) => item.value?.value === 'use voltra')
+}
+
+function parseSource(source: string, filePath: string): ReturnType<typeof parser.parse> {
+  return parser.parse(source, {
+    sourceFilename: filePath,
+    sourceType: 'unambiguous',
+    plugins: [
+      'classProperties',
+      'decorators-legacy',
+      'dynamicImport',
+      'exportDefaultFrom',
+      'importMeta',
+      'jsx',
+      'topLevelAwait',
+      'typescript',
+    ],
+  })
+}
+
+function identifierName(node: import('@babel/types').Node | null | undefined): string | null {
+  return node?.type === 'Identifier' ? node.name : null
+}
+
+function exportName(
+  node: import('@babel/types').Identifier | import('@babel/types').StringLiteral | null | undefined
+): string | null {
+  if (!node) {
+    return null
+  }
+  if (node.type === 'Identifier') {
+    return node.name
+  }
+  if (node.type === 'StringLiteral') {
+    return node.value
+  }
+  return null
+}
+
+function collectExportedLocals(program: import('@babel/types').Program): ExportedLocals {
+  const exportedLocals: ExportedLocals = new Map()
+
+  function add(localName: string | null, exportedName: string | null) {
+    if (!localName || !exportedName) {
+      return
+    }
+
+    const exports = exportedLocals.get(localName) || new Set<string>()
+    exports.add(exportedName)
+    exportedLocals.set(localName, exports)
+  }
+
+  for (const statement of program.body) {
+    if (statement.type === 'ExportNamedDeclaration') {
+      if (statement.declaration) {
+        if (statement.declaration.type === 'FunctionDeclaration') {
+          add(statement.declaration.id?.name ?? null, statement.declaration.id?.name ?? null)
+        }
+
+        if (statement.declaration.type === 'VariableDeclaration') {
+          for (const declaration of statement.declaration.declarations) {
+            const name = identifierName(declaration.id)
+            add(name, name)
+          }
+        }
+      }
+
+      for (const specifier of statement.specifiers) {
+        if (specifier.type === 'ExportSpecifier') {
+          add(exportName(specifier.local), exportName(specifier.exported))
+        }
+      }
+    }
+
+    if (statement.type === 'ExportDefaultDeclaration' && statement.declaration.type === 'Identifier') {
+      add(statement.declaration.name, 'default')
+    }
+  }
+
+  return exportedLocals
+}
+
+function createWidgetRecord({
+  componentName,
+  exportedName,
+  filePath,
+}: {
+  componentName: string | null
+  exportedName: string
+  filePath: string
+}): VoltraDirectiveWidget | null {
+  if (!componentName || componentName === 'default') {
+    return null
+  }
+
+  return {
+    id: componentName,
+    componentName,
+    exportName: exportedName,
+    sourcePath: filePath,
+  }
+}
+
+function scanDeclaration({
+  declaration,
+  exportedLocals,
+  filePath,
+}: {
+  declaration: import('@babel/types').Declaration | import('@babel/types').Statement | null | undefined
+  exportedLocals: ExportedLocals
+  filePath: string
+}): VoltraDirectiveWidget[] {
+  if (!declaration) {
+    return []
+  }
+
+  if (declaration.type === 'FunctionDeclaration') {
+    const componentName = declaration.id?.name ?? null
+    const exportNames = componentName ? exportedLocals.get(componentName) : null
+
+    if (!hasVoltraDirective(declaration) || !exportNames) {
+      return []
+    }
+
+    return Array.from(exportNames)
+      .map((name) => createWidgetRecord({ componentName, exportedName: name, filePath }))
+      .filter((widget): widget is VoltraDirectiveWidget => widget !== null)
+  }
+
+  if (declaration.type === 'VariableDeclaration') {
+    const widgets: VoltraDirectiveWidget[] = []
+
+    for (const variableDeclarator of declaration.declarations) {
+      const componentName = identifierName(variableDeclarator.id)
+      const init = variableDeclarator.init
+      const exportNames = componentName ? exportedLocals.get(componentName) : null
+
+      if (!hasVoltraDirective(init) || !exportNames) {
+        continue
+      }
+
+      for (const name of exportNames) {
+        const widget = createWidgetRecord({ componentName, exportedName: name, filePath })
+
+        if (widget) {
+          widgets.push(widget)
+        }
+      }
+    }
+
+    return widgets
+  }
+
+  return []
+}
+
+export function scanVoltraDirectives({
+  filePath,
+  source,
+}: {
+  filePath: string
+  source: string
+}): VoltraDirectiveWidget[] {
+  if (!supportedExtensions.has(path.extname(filePath))) {
+    return []
+  }
+
+  if (!source.includes("'use voltra'") && !source.includes('"use voltra"')) {
+    return []
+  }
+
+  const ast = parseSource(source, filePath)
+  const exportedLocals = collectExportedLocals(ast.program)
+  const widgets: VoltraDirectiveWidget[] = []
+
+  for (const statement of ast.program.body) {
+    if (statement.type === 'ExportDefaultDeclaration') {
+      if (hasVoltraDirective(statement.declaration)) {
+        const componentName =
+          statement.declaration.type === 'FunctionDeclaration' ? statement.declaration.id?.name ?? null : null
+        const widget = createWidgetRecord({
+          componentName,
+          exportedName: 'default',
+          filePath,
+        })
+
+        if (widget) {
+          widgets.push(widget)
+        }
+      }
+
+      continue
+    }
+
+    if (statement.type === 'ExportNamedDeclaration') {
+      widgets.push(...scanDeclaration({ declaration: statement.declaration, exportedLocals, filePath }))
+      continue
+    }
+
+    widgets.push(...scanDeclaration({ declaration: statement, exportedLocals, filePath }))
+  }
+
+  return widgets
+}
diff --git a/packages/compiler/tsconfig.base.json b/packages/compiler/tsconfig.base.json
new file mode 100644
index 00000000..452d729b
--- /dev/null
+++ b/packages/compiler/tsconfig.base.json
@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "rootDir": "./src",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "types": ["node"]
+  },
+  "include": ["./src"],
+  "exclude": ["**/__mocks__/*", "**/__tests__/*", "**/__rsc_tests__/*"]
+}
diff --git a/packages/compiler/tsconfig.cjs.json b/packages/compiler/tsconfig.cjs.json
new file mode 100644
index 00000000..a6b3ca9c
--- /dev/null
+++ b/packages/compiler/tsconfig.cjs.json
@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "module": "CommonJS",
+    "outDir": "./build/cjs",
+    "declaration": false,
+    "sourceMap": true
+  }
+}
diff --git a/packages/compiler/tsconfig.esm.json b/packages/compiler/tsconfig.esm.json
new file mode 100644
index 00000000..2bb18d33
--- /dev/null
+++ b/packages/compiler/tsconfig.esm.json
@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ES2020",
+    "outDir": "./build/esm",
+    "declaration": false,
+    "sourceMap": true
+  }
+}
diff --git a/packages/compiler/tsconfig.json b/packages/compiler/tsconfig.json
new file mode 100644
index 00000000..09b0ecb8
--- /dev/null
+++ b/packages/compiler/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.esm.json" },
+    { "path": "./tsconfig.cjs.json" },
+    { "path": "./tsconfig.types.json" }
+  ]
+}
diff --git a/packages/compiler/tsconfig.typecheck.json b/packages/compiler/tsconfig.typecheck.json
new file mode 100644
index 00000000..77b33299
--- /dev/null
+++ b/packages/compiler/tsconfig.typecheck.json
@@ -0,0 +1,23 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ES2020",
+    "rootDir": "../..",
+    "baseUrl": "../..",
+    "paths": {
+      "@use-voltra/android": ["packages/android/src/index.ts"],
+      "@use-voltra/android-client": ["packages/android-client/src/index.ts"],
+      "@use-voltra/android/client": ["packages/android-client/src/index.ts"],
+      "@use-voltra/android/server": ["packages/android/src/server.ts"],
+      "@use-voltra/android-server": ["packages/android-server/src/index.ts"],
+      "@use-voltra/compiler": ["packages/compiler/src/index.ts"],
+      "@use-voltra/core": ["packages/core/src/index.ts"],
+      "@use-voltra/ios": ["packages/ios/src/index.ts"],
+      "@use-voltra/ios-client": ["packages/ios-client/src/index.ts"],
+      "@use-voltra/ios/client": ["packages/ios-client/src/index.ts"],
+      "@use-voltra/ios/server": ["packages/ios/src/server.ts"],
+      "@use-voltra/ios-server": ["packages/ios-server/src/index.ts"],
+      "@use-voltra/server": ["packages/server/src/index.ts"]
+    }
+  }
+}
diff --git a/packages/compiler/tsconfig.types.json b/packages/compiler/tsconfig.types.json
new file mode 100644
index 00000000..8ec821ee
--- /dev/null
+++ b/packages/compiler/tsconfig.types.json
@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ES2020",
+    "outDir": "./build/types",
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "declarationMap": true
+  }
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index cf73c506..442aa610 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -3,3 +3,4 @@ export * from './payload.js'
 export * from './payload/short-names.js'
 export * from './renderer/index.js'
 export * from './types.js'
+export * from './widget-environment.js'
diff --git a/packages/core/src/widget-environment.ts b/packages/core/src/widget-environment.ts
new file mode 100644
index 00000000..e0805576
--- /dev/null
+++ b/packages/core/src/widget-environment.ts
@@ -0,0 +1,114 @@
+/**
+ * Env shape consumed by client-rendered widgets.
+ *
+ * Client-rendered widgets are functions of `(props, env) => JSX`, evaluated inside the
+ * Voltra JS runtime (JSC on iOS, Hermes on Android) at every render. The `env` second
+ * argument is populated by the native runtime at draw time and carries:
+ *
+ * - **Runtime device state** (`colorScheme`, `widgetFamily`, etc.) captured per render
+ * - **Platform-specific runtime state** (`widgetRenderingMode` on iOS), present only on the
+ *   platform that has the concept
+ * - **AppIntent / user-configured params** under `env.configuration` (TypeScript-typed per
+ *   widget via the generic parameter)
+ * - **Build env** under `env.build.*` — values that don't change between renders inside a
+ *   process (isDev, Metro URL, app version, Voltra version)
+ *
+ * The shape mirrors expo-widgets' `WidgetEnvironment` for the runtime device fields, with
+ * a Voltra-specific `env.build.*` namespace added for dev-mode tooling.
+ *
+ * @typeParam TConfig - Shape of `env.configuration` (AppIntent / user-configured params).
+ *   Defaults to `undefined` for widgets that don't accept user configuration. Widget authors
+ *   can supply a more specific type per widget for typed access.
+ */
+export type WidgetEnvironment<TConfig extends Record<string, unknown> | undefined = undefined> = {
+  /** Date the widget is being rendered for. Transported as epoch ms over the JS boundary
+   * and reconstructed as `Date` by the runtime entry. */
+  date: Date
+
+  /** Widget size family. iOS values: `systemSmall`, `systemMedium`, `systemLarge`, etc.
+   * Android values: synthesized from Glance `LocalSize` (e.g. `"200x200"`). */
+  widgetFamily: string
+
+  /** Current color scheme of the widget's environment. May be `undefined` if the platform
+   * doesn't expose it (rare). */
+  colorScheme?: 'light' | 'dark'
+
+  /** BCP-47 locale tag — for example `"en-US"` or `"pl-PL"`. */
+  locale?: string
+
+  // ---------------------------------------------------------------------------
+  // iOS-only runtime values
+  // Present only when rendering on iOS; `undefined` on Android.
+  // ---------------------------------------------------------------------------
+
+  /** iOS — rendering mode the widget is being drawn in. `fullColor` on home screen,
+   * `accented` on tinted/Liquid Glass widgets (iOS 18+) and watchOS, `vibrant` on lock
+   * screen. Maps to SwiftUI `@Environment(\.widgetRenderingMode)`. */
+  widgetRenderingMode?: 'fullColor' | 'accented' | 'vibrant'
+
+  /** iOS — whether the system is drawing a container background behind the widget.
+   * Maps to SwiftUI `@Environment(\.showsWidgetContainerBackground)`. iOS 17+. */
+  showsWidgetContainerBackground?: boolean
+
+  // ---------------------------------------------------------------------------
+  // System-managed configuration
+  // ---------------------------------------------------------------------------
+
+  /** AppIntent / user-configured parameters for this widget. `undefined` for widgets that
+   * don't accept user configuration. Typed per widget via the [TConfig] generic. */
+  configuration: TConfig
+
+  // ---------------------------------------------------------------------------
+  // Build env — static for the process lifetime, supplied by the runtime
+  // ---------------------------------------------------------------------------
+
+  /** Build / process-level metadata, populated by the runtime once per process. Static for
+   * the JS runtime's lifetime; does not change between renders. */
+  build: WidgetBuildEnvironment
+}
+
+/**
+ * Build / process metadata available inside the widget render function. Populated by the
+ * native runtime; identical across every render in a process.
+ */
+export type WidgetBuildEnvironment = {
+  /** True when running against a development build (DEBUG / `__DEV__`). Used to gate
+   * dev-mode behaviour like fetching bundles from Metro. */
+  isDev: boolean
+
+  /** URL of the Metro dev server when `isDev` is true. Used by the runtime to fetch widget
+   * bundles for hot-reload. `undefined` in release builds. */
+  metroUrl?: string
+
+  /** App version string (`CFBundleShortVersionString` on iOS, `versionName` on Android). */
+  appVersion: string
+
+  /** Voltra package version (`@use-voltra/core`). Surfaces in error reports and lets
+   * widgets gate behaviour by compatibility level if needed. */
+  voltraVersion: string
+}
+
+/**
+ * Type guard — returns true when the runtime env is an iOS-platform env.
+ *
+ * @example
+ *   if (isIosEnv(env)) {
+ *     // env.widgetRenderingMode is narrowed to the concrete value (not undefined)
+ *   }
+ */
+export function isIosEnv(
+  env: WidgetEnvironment
+): env is WidgetEnvironment & { widgetRenderingMode: NonNullable<WidgetEnvironment['widgetRenderingMode']> } {
+  return env.widgetRenderingMode !== undefined
+}
+
+/**
+ * Type guard — returns true when the runtime env is an Android-platform env.
+ *
+ * Android carries no platform-only runtime field (Material You colors are consumed via
+ * `AndroidDynamicColors` tokens resolved by the native renderer, not through `env`), so this is
+ * the complement of {@link isIosEnv}.
+ */
+export function isAndroidEnv(env: WidgetEnvironment): boolean {
+  return !isIosEnv(env)
+}
diff --git a/packages/expo-plugin/src/index.ts b/packages/expo-plugin/src/index.ts
index ad57c946..8968f78f 100644
--- a/packages/expo-plugin/src/index.ts
+++ b/packages/expo-plugin/src/index.ts
@@ -1,9 +1,19 @@
 export { MAX_IMAGE_SIZE_BYTES, MODULE_EXTENSIONS } from './constants'
-export type { WidgetInitialStatePath, WidgetLabel, WidgetLocalizedCopy } from './types'
+export type {
+  DynamicWidgetEntryConfig,
+  DynamicWidgetManifest,
+  DynamicWidgetManifestWidget,
+  DynamicWidgetPlatform,
+  WidgetInitialStatePath,
+  WidgetLabel,
+  WidgetLocalizedCopy,
+} from './types'
 export {
   assertValidLocaleKey,
+  normalizeWidgetEntryPath,
   validateHomeScreenWidgetId,
   validateInitialStatePath,
+  validateWidgetEntry,
   validateWidgetLabel,
 } from './validation'
 export { addApplicationGroupsEntitlement } from './utils/entitlements'
@@ -11,5 +21,5 @@ 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 { prerenderWidgetState } from './utils/prerender'
+export { evaluateWidgetModule, evaluateWidgetModuleExports, prerenderWidgetState } from './utils/prerender'
 export { isWidgetLocalizedMap, widgetLabelEnglish } from './utils/widgetLabel'
diff --git a/packages/expo-plugin/src/types.ts b/packages/expo-plugin/src/types.ts
index 55f1c958..641ace16 100644
--- a/packages/expo-plugin/src/types.ts
+++ b/packages/expo-plugin/src/types.ts
@@ -3,6 +3,29 @@
  * Platform widget config types live in each client's expo-plugin package.
  */
 
+export type DynamicWidgetPlatform = 'ios' | 'android'
+
+/**
+ * Shared app.json entry contract for Dynamic Widgets.
+ *
+ * `entry` stays optional during rollout so platform packages can adopt the shared contract
+ * incrementally, but validation should require it for real widget declarations.
+ */
+export interface DynamicWidgetEntryConfig {
+  entry?: string
+}
+
+export interface DynamicWidgetManifestWidget {
+  id: string
+  entry: string
+}
+
+export interface DynamicWidgetManifest {
+  version: 1
+  platform: DynamicWidgetPlatform
+  widgets: DynamicWidgetManifestWidget[]
+}
+
 /**
  * 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.
diff --git a/packages/expo-plugin/src/utils/prerender.ts b/packages/expo-plugin/src/utils/prerender.ts
index 828e0c01..4d7e5ac0 100644
--- a/packages/expo-plugin/src/utils/prerender.ts
+++ b/packages/expo-plugin/src/utils/prerender.ts
@@ -96,8 +96,12 @@ function transpileFile(filePath: string, projectRoot: string): string {
  * 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.
+ *
+ * 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.
  */
-function evaluateWidgetModule(projectRoot: string, filePath: string): any {
+export function evaluateWidgetModuleExports(projectRoot: string, filePath: string): any {
   // Cache for already-evaluated modules to handle circular dependencies
   const moduleCache = new Map<string, any>()
 
@@ -152,8 +156,14 @@ function evaluateWidgetModule(projectRoot: string, filePath: string): any {
     return mockModule.exports
   }
 
-  // Evaluate the entry module
-  const exports = customRequire(filePath, path.dirname(filePath))
+  return customRequire(filePath, path.dirname(filePath))
+}
+
+/**
+ * Evaluate a widget file as a server-style WidgetVariants module and return its object export.
+ */
+export function evaluateWidgetModule(projectRoot: string, filePath: string): any {
+  const exports = evaluateWidgetModuleExports(projectRoot, filePath)
   const widgetVariants: any = exports.default || exports
 
   if (!widgetVariants || typeof widgetVariants !== 'object') {
diff --git a/packages/expo-plugin/src/validation.node.test.ts b/packages/expo-plugin/src/validation.node.test.ts
index 9ac4394b..b9ec8f88 100644
--- a/packages/expo-plugin/src/validation.node.test.ts
+++ b/packages/expo-plugin/src/validation.node.test.ts
@@ -1,4 +1,84 @@
-import { validateInitialStatePath } from './validation'
+import fs from 'fs'
+import os from 'os'
+import path from 'path'
+
+import { validateInitialStatePath, validateWidgetEntry } from './validation'
+
+function createProjectRoot(files: Record<string, string>): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'voltra-widget-entry-'))
+
+  for (const [relativePath, contents] of Object.entries(files)) {
+    const filePath = path.join(root, relativePath)
+    fs.mkdirSync(path.dirname(filePath), { recursive: true })
+    fs.writeFileSync(filePath, contents)
+  }
+
+  return root
+}
+
+describe('validateWidgetEntry', () => {
+  it('accepts a relative entry and normalizes it to a POSIX project-relative path', () => {
+    const projectRoot = createProjectRoot({
+      'widgets/home.tsx': 'export default function HomeWidget() {}',
+    })
+
+    try {
+      expect(validateWidgetEntry('./widgets/home.tsx', 'home', projectRoot)).toBe('widgets/home.tsx')
+    } finally {
+      fs.rmSync(projectRoot, { recursive: true, force: true })
+    }
+  })
+
+  it('accepts a valid relative entry without a project root', () => {
+    expect(validateWidgetEntry('./widgets/home.mjs', 'home')).toBe('widgets/home.mjs')
+  })
+
+  it('rejects missing entries', () => {
+    expect(() => validateWidgetEntry(undefined, 'home')).toThrow(/Widget 'home': entry is required/)
+  })
+
+  it('rejects absolute entry paths', () => {
+    const projectRoot = createProjectRoot({})
+
+    try {
+      expect(() => validateWidgetEntry(path.join(projectRoot, 'widgets/home.tsx'), 'home', projectRoot)).toThrow(
+        /Widget 'home': entry must be a relative path, not an absolute path/
+      )
+    } finally {
+      fs.rmSync(projectRoot, { recursive: true, force: true })
+    }
+  })
+
+  it('rejects entries that escape the project root', () => {
+    const projectRoot = createProjectRoot({})
+
+    try {
+      expect(() => validateWidgetEntry('../outside.tsx', 'home', projectRoot)).toThrow(
+        /Widget 'home': entry must stay within the project root after normalization/
+      )
+    } finally {
+      fs.rmSync(projectRoot, { recursive: true, force: true })
+    }
+  })
+
+  it('rejects unsupported entry extensions', () => {
+    expect(() => validateWidgetEntry('./widgets/home.txt', 'home')).toThrow(
+      /Widget 'home': entry must use a Metro-importable source extension/
+    )
+  })
+
+  it('rejects missing entry files when a project root is supplied', () => {
+    const projectRoot = createProjectRoot({})
+
+    try {
+      expect(() => validateWidgetEntry('./widgets/missing.tsx', 'home', projectRoot)).toThrow(
+        /Widget 'home': entry file not found at widgets\/missing\.tsx/
+      )
+    } finally {
+      fs.rmSync(projectRoot, { recursive: true, force: true })
+    }
+  })
+})
 
 describe('validateInitialStatePath', () => {
   it('accepts a plain path without projectRoot', () => {
diff --git a/packages/expo-plugin/src/validation.ts b/packages/expo-plugin/src/validation.ts
index 9b78a102..aba5b0cf 100644
--- a/packages/expo-plugin/src/validation.ts
+++ b/packages/expo-plugin/src/validation.ts
@@ -12,6 +12,20 @@ const WIDGET_ID_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/
 const LOCALE_KEY_PATTERN = /^[a-zA-Z][a-zA-Z0-9]*([_-][a-zA-Z0-9]+)*$/
 
 const MAX_LOCALE_KEY_LENGTH = 32
+const WIDGET_ENTRY_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'])
+const WIDGET_ENTRY_FIELD_NAME = 'entry'
+
+function isAbsoluteWidgetPath(value: string): boolean {
+  return path.isAbsolute(value) || path.win32.isAbsolute(value) || /^[a-zA-Z]:[\\/]/.test(value)
+}
+
+function normalizeWidgetEntry(entry: string): string {
+  return path.posix.normalize(entry.replace(/\\/g, '/'))
+}
+
+function widgetEntryExtension(entry: string): string {
+  return path.posix.extname(entry)
+}
 
 export function validateHomeScreenWidgetId(widgetId: unknown): asserts widgetId is string {
   if (!widgetId || typeof widgetId !== 'string') {
@@ -88,6 +102,69 @@ export function validateWidgetLabel(value: unknown, widgetId: string, fieldName:
   }
 }
 
+export function normalizeWidgetEntryPath(entry: string, projectRoot?: string): string {
+  const normalizedInput = normalizeWidgetEntry(entry)
+
+  if (projectRoot) {
+    const absolutePath = path.resolve(projectRoot, normalizedInput)
+    const relativePath = path.relative(projectRoot, absolutePath)
+    return normalizeWidgetEntry(relativePath)
+  }
+
+  return normalizedInput
+}
+
+export function validateWidgetEntry(value: unknown, widgetId: string, projectRoot?: string): string {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new Error(`Widget '${widgetId}': ${WIDGET_ENTRY_FIELD_NAME} is required`)
+  }
+
+  if (isAbsoluteWidgetPath(value)) {
+    throw new Error(`Widget '${widgetId}': ${WIDGET_ENTRY_FIELD_NAME} must be a relative path, not an absolute path`)
+  }
+
+  const normalizedEntry = normalizeWidgetEntryPath(value)
+  if (!normalizedEntry || normalizedEntry === '.') {
+    throw new Error(`Widget '${widgetId}': ${WIDGET_ENTRY_FIELD_NAME} must point to a file inside the project root`)
+  }
+
+  if (normalizedEntry === '..' || normalizedEntry.startsWith('../')) {
+    throw new Error(
+      `Widget '${widgetId}': ${WIDGET_ENTRY_FIELD_NAME} must stay within the project root after normalization`
+    )
+  }
+
+  const extension = widgetEntryExtension(normalizedEntry)
+  if (!WIDGET_ENTRY_EXTENSIONS.has(extension)) {
+    throw new Error(
+      `Widget '${widgetId}': ${WIDGET_ENTRY_FIELD_NAME} must use a Metro-importable source extension ` +
+        `(${Array.from(WIDGET_ENTRY_EXTENSIONS).join(', ')}); received '${extension || '(none)'}'`
+    )
+  }
+
+  if (!projectRoot) {
+    return normalizedEntry
+  }
+
+  const normalizedInput = normalizeWidgetEntry(value)
+  const absolutePath = path.resolve(projectRoot, normalizedInput)
+  const normalizedProjectRelativePath = normalizeWidgetEntryPath(normalizedInput, projectRoot)
+
+  if (normalizedProjectRelativePath === '..' || normalizedProjectRelativePath.startsWith('../')) {
+    throw new Error(
+      `Widget '${widgetId}': ${WIDGET_ENTRY_FIELD_NAME} must stay within the project root after normalization`
+    )
+  }
+
+  if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) {
+    throw new Error(
+      `Widget '${widgetId}': ${WIDGET_ENTRY_FIELD_NAME} file not found at ${normalizedProjectRelativePath}`
+    )
+  }
+
+  return normalizedProjectRelativePath
+}
+
 /**
  * Validates optional initialStatePath: plain string or locale map of project-relative file paths.
  */
diff --git a/packages/ios-client/README.md b/packages/ios-client/README.md
index f636a4bc..aaf991a7 100644
--- a/packages/ios-client/README.md
+++ b/packages/ios-client/README.md
@@ -12,6 +12,8 @@
 
 - **iOS Widgets**: Update, schedule, reload, and query widgets with `updateWidget`, `scheduleWidget`, `getActiveWidgets`, and more.
 
+- **Dynamic Widgets** _(experimental)_: Declare a widget in app.json with an `id` and `entry`, default-export the widget module, and render it on-device with live env (family, color scheme, locale, configuration).
+
 - **Fast Refresh**: Hooks and previews integrate with your React Native dev workflow.
 
 - **Push & events**: Capture ActivityKit push tokens and component interactions via `addVoltraListener`.
@@ -20,6 +22,23 @@
 
 - **Expo config plugin**: Add `"@use-voltra/ios-client"` to `app.json` to generate the Live Activity extension, widget targets, and entitlements.
 
+## Dynamic Widgets (experimental)
+
+> [!WARNING]
+> Dynamic Widgets are **experimental** — usable in production at your own risk. The API may
+> change between releases.
+
+Declare the widget in app.json with a stable `id` and a project-relative `entry` path. The entry
+module must default-export the widget function or component; the exported name does not need to
+match the widget id. The widget renders on-device, so it can react to live environment values
+(widget family, color scheme, locale, and user `configuration` from the native Edit Widget sheet).
+
+Notes:
+
+- iOS and Android widget declarations stay separate, and the same widget id can exist on both platforms as separate entries.
+- Verify release rendering on a **real device** — the iOS Simulator is unreliable for widget
+  rendering.
+
 ## Documentation
 
 The documentation is available at [use-voltra.dev](https://use-voltra.dev). Relevant topics for this package:
@@ -27,7 +46,7 @@ The documentation is available at [use-voltra.dev](https://use-voltra.dev). Rele
 - [Installation](https://use-voltra.dev/getting-started/installation)
 - [iOS Setup](https://use-voltra.dev/ios/setup)
 - [Developing Live Activities](https://use-voltra.dev/ios/development/developing-live-activities)
-- [Developing Widgets](https://use-voltra.dev/ios/development/developing-widgets)
+- [Developing Dynamic Widgets](https://use-voltra.dev/ios/development/dynamic-widgets)
 - [Plugin Configuration](https://use-voltra.dev/ios/api/plugin-configuration)
 - [API Reference](https://use-voltra.dev/ios/api/configuration)
 
diff --git a/packages/ios-client/expo-plugin/jest.config.js b/packages/ios-client/expo-plugin/jest.config.js
index 5835d68b..4e24b4de 100644
--- a/packages/ios-client/expo-plugin/jest.config.js
+++ b/packages/ios-client/expo-plugin/jest.config.js
@@ -4,8 +4,10 @@ module.exports = {
   testMatch: ['<rootDir>/src/**/*.node.test.ts'],
   modulePathIgnorePatterns: ['<rootDir>/build'],
   moduleNameMapper: {
+    '^@use-voltra/compiler$': '<rootDir>/../../compiler/src/index.ts',
     '^@use-voltra/expo-plugin$': '<rootDir>/../../expo-plugin/src/index.ts',
     '^@use-voltra/expo-plugin/(.*)$': '<rootDir>/../../expo-plugin/src/$1',
+    '^@use-voltra/metro/scanner$': '<rootDir>/../../metro/src/scanner.ts',
   },
   transform: {
     '^.+\\.tsx?$': [
diff --git a/packages/ios-client/expo-plugin/src/index.ts b/packages/ios-client/expo-plugin/src/index.ts
index 97742c44..7d701a2a 100644
--- a/packages/ios-client/expo-plugin/src/index.ts
+++ b/packages/ios-client/expo-plugin/src/index.ts
@@ -3,7 +3,7 @@ import { IOSConfig } from 'expo/config-plugins'
 import { IOS } from './constants'
 import { withIOS, withPushNotifications } from './ios'
 import { withIOS as withIOSWidget } from './ios-widget'
-import type { IOSConfigPluginProps, VoltraIosConfigPlugin } from './types'
+import type { VoltraIosConfigPlugin } from './types'
 import { ensureURLScheme } from './utils/urlScheme'
 import { validateIOSConfigPluginProps } from './validation'
 
@@ -13,7 +13,8 @@ import { validateIOSConfigPluginProps } from './validation'
  * Configures Live Activities, the widget extension, and optional push-to-start support.
  */
 const withVoltraIos: VoltraIosConfigPlugin = (config, props = {}) => {
-  validateIOSConfigPluginProps(props)
+  const projectRoot = (config as { modRequest?: { projectRoot?: string } }).modRequest?.projectRoot
+  validateIOSConfigPluginProps(props, projectRoot)
 
   const iosBundleIdentifier = config.ios?.bundleIdentifier
   if (!iosBundleIdentifier) {
diff --git a/packages/ios-client/expo-plugin/src/ios-widget/clientRendered.node.test.ts b/packages/ios-client/expo-plugin/src/ios-widget/clientRendered.node.test.ts
new file mode 100644
index 00000000..56e6d569
--- /dev/null
+++ b/packages/ios-client/expo-plugin/src/ios-widget/clientRendered.node.test.ts
@@ -0,0 +1,142 @@
+import * as fs from 'fs'
+import * as os from 'os'
+import * as path from 'path'
+
+import type { IOSWidgetConfig } from '../types'
+
+import { detectClientRenderedWidgets } from './clientRendered'
+
+function makeTempProject(files: Record<string, string>): { projectRoot: string; cleanup: () => void } {
+  const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'voltra-client-rendered-test-'))
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = path.join(projectRoot, rel)
+    fs.mkdirSync(path.dirname(abs), { recursive: true })
+    fs.writeFileSync(abs, content)
+  }
+  return {
+    projectRoot,
+    cleanup: () => fs.rmSync(projectRoot, { recursive: true, force: true }),
+  }
+}
+
+function asWidget(partial: Partial<IOSWidgetConfig>): IOSWidgetConfig {
+  return {
+    id: 'placeholder',
+    entry: './widgets/placeholder.tsx',
+    displayName: 'Placeholder',
+    description: 'Placeholder',
+    ...partial,
+  }
+}
+
+// Detection emits a one-time EXPERIMENTAL console.warn; keep it out of test output (the dedicated
+// suite below asserts on it explicitly).
+beforeEach(() => {
+  jest.spyOn(console, 'warn').mockImplementation(() => {})
+})
+afterEach(() => {
+  jest.restoreAllMocks()
+})
+
+describe('detectClientRenderedWidgets', () => {
+  it('keeps widgets without an entry on the server-rendered path', () => {
+    const { projectRoot, cleanup } = makeTempProject({})
+    try {
+      const [detected] = detectClientRenderedWidgets(
+        [
+          {
+            id: 'legacy',
+            displayName: 'Legacy',
+            description: 'Server-rendered widget',
+          },
+        ],
+        projectRoot
+      )
+
+      expect(detected.clientRendered).toBe(false)
+      expect(detected).not.toHaveProperty('clientSourcePath')
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('flags a default-exported entry module as a Dynamic Widget even when the export name differs', () => {
+    const { projectRoot, cleanup } = makeTempProject({
+      'widgets/Foo.tsx': `
+        export default function NotTheWidgetId(props, env) {
+          return null
+        }
+      `,
+    })
+    try {
+      const [detected] = detectClientRenderedWidgets([asWidget({ id: 'Foo', entry: './widgets/Foo.tsx' })], projectRoot)
+      expect(detected.clientRendered).toBe(true)
+      if (detected.clientRendered) {
+        expect(detected.clientSourcePath).toBe(path.join(projectRoot, 'widgets/Foo.tsx'))
+      }
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('throws when the entry default export is not a function', () => {
+    const { projectRoot, cleanup } = makeTempProject({
+      'widgets/Bar.tsx': `
+        export const Bar = () => null
+      `,
+    })
+    try {
+      expect(() =>
+        detectClientRenderedWidgets([asWidget({ id: 'Bar', entry: './widgets/Bar.tsx' })], projectRoot)
+      ).toThrow(/Dynamic Widget "Bar" at widgets\/Bar\.tsx must default-export a function or component\./)
+    } finally {
+      cleanup()
+    }
+  })
+})
+
+describe('detectClientRenderedWidgets — experimental warning', () => {
+  // The warning fires at most once per module instance, so re-require a fresh module per test.
+  function freshDetect(): typeof detectClientRenderedWidgets {
+    let fn: typeof detectClientRenderedWidgets = detectClientRenderedWidgets
+    jest.isolateModules(() => {
+      fn = require('./clientRendered').detectClientRenderedWidgets
+    })
+    return fn
+  }
+
+  it('warns once (with EXPERIMENTAL + the widget id) when a client-rendered widget is detected', () => {
+    const detect = freshDetect()
+    const warn = console.warn as jest.Mock
+    const { projectRoot, cleanup } = makeTempProject({
+      'widgets/Foo.tsx': `
+        export default function Foo(props, env) {
+          return null
+        }
+      `,
+    })
+    try {
+      const widgets = [asWidget({ id: 'Foo', entry: './widgets/Foo.tsx' })]
+      detect(widgets, projectRoot)
+      detect(widgets, projectRoot) // second detection in the same process must not re-warn
+
+      expect(warn).toHaveBeenCalledTimes(1)
+      expect(warn.mock.calls[0][0]).toContain('EXPERIMENTAL')
+      expect(warn.mock.calls[0][0]).toContain('Foo')
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('does not warn when no Dynamic Widgets are detected', () => {
+    const detect = freshDetect()
+    const warn = console.warn as jest.Mock
+    const { projectRoot, cleanup } = makeTempProject({})
+    try {
+      detect([], projectRoot)
+      expect(warn).not.toHaveBeenCalled()
+    } finally {
+      cleanup()
+    }
+  })
+})
diff --git a/packages/ios-client/expo-plugin/src/ios-widget/clientRendered.ts b/packages/ios-client/expo-plugin/src/ios-widget/clientRendered.ts
new file mode 100644
index 00000000..fa47447d
--- /dev/null
+++ b/packages/ios-client/expo-plugin/src/ios-widget/clientRendered.ts
@@ -0,0 +1,88 @@
+import * as fs from 'fs'
+import * as path from 'path'
+
+import { evaluateWidgetModuleExports } from '@use-voltra/expo-plugin'
+
+import type { IOSWidgetConfig } from '../types'
+
+/**
+ * Dynamic Widget detection.
+ *
+ * Dynamic Widgets are detected from the module referenced by `entry`.
+ * A widget is treated as dynamic when its entry module default-exports a function or
+ * component. The widget id is independent from the exported symbol name.
+ */
+
+/**
+ * Widget config augmented with the prebuild-time derived rendering mode.
+ *
+ * `clientRendered: false` is the existing server-rendered path.
+ * `clientRendered: true` adds `clientSourcePath` (absolute path to the Dynamic Widget entry,
+ * used by the prerender step and by the generated Swift Provider's Metro URL).
+ */
+export type DetectedIOSWidget =
+  | (IOSWidgetConfig & { clientRendered: false })
+  | (IOSWidgetConfig & { clientRendered: true; clientSourcePath: string })
+
+// Emit the experimental notice at most once per prebuild process (detection runs from several
+// plugin steps).
+let hasWarnedExperimental = false
+
+/** Inspect every widget once and tag entry-backed widgets as Dynamic Widgets. */
+export function detectClientRenderedWidgets(widgets: IOSWidgetConfig[], projectRoot: string): DetectedIOSWidget[] {
+  const detected = widgets.map((widget) => detectSingleWidget(widget, projectRoot))
+
+  if (!hasWarnedExperimental) {
+    const clientWidgetIds = detected.filter((widget) => widget.clientRendered).map((widget) => widget.id)
+    if (clientWidgetIds.length > 0) {
+      hasWarnedExperimental = true
+      console.warn(
+        `[voltra] Dynamic Widgets are EXPERIMENTAL (${clientWidgetIds.join(', ')}). ` +
+          'The widget JSX runs on-device in a separate JS engine; the API and build output may change, ' +
+          'and production rendering should be verified on a real device. Use at your own risk.'
+      )
+    }
+  }
+
+  return detected
+}
+
+function detectSingleWidget(widget: IOSWidgetConfig, projectRoot: string): DetectedIOSWidget {
+  if (widget.entry === undefined) {
+    return {
+      ...widget,
+      clientRendered: false,
+    }
+  }
+
+  const sourcePath = resolveWidgetEntryPath(widget.entry, projectRoot)
+  if (!sourcePath || !fs.existsSync(sourcePath)) {
+    throw new Error(
+      `[voltra] Dynamic Widget "${widget.id}" entry not found at ${path.relative(
+        projectRoot,
+        sourcePath ?? widget.entry
+      )}`
+    )
+  }
+
+  const widgetModule = evaluateWidgetModuleExports(projectRoot, sourcePath)
+  const widgetFn = widgetModule?.default ?? widgetModule
+  if (typeof widgetFn !== 'function') {
+    throw new Error(
+      `[voltra] Dynamic Widget "${widget.id}" at ${path.relative(
+        projectRoot,
+        sourcePath
+      )} must default-export a function or component.`
+    )
+  }
+
+  return {
+    ...widget,
+    clientRendered: true,
+    clientSourcePath: sourcePath,
+  }
+}
+
+function resolveWidgetEntryPath(entry: string, projectRoot: string): string | null {
+  return path.resolve(projectRoot, entry)
+}
diff --git a/packages/ios-client/expo-plugin/src/ios-widget/clientRenderedPrerender.node.test.ts b/packages/ios-client/expo-plugin/src/ios-widget/clientRenderedPrerender.node.test.ts
new file mode 100644
index 00000000..279bf691
--- /dev/null
+++ b/packages/ios-client/expo-plugin/src/ios-widget/clientRenderedPrerender.node.test.ts
@@ -0,0 +1,66 @@
+import * as fs from 'fs'
+import * as os from 'os'
+import * as path from 'path'
+
+import { prerenderClientRenderedWidgets } from './clientRenderedPrerender'
+import type { DetectedIOSWidget } from './clientRendered'
+
+jest.mock('@use-voltra/ios', () => ({
+  renderVoltraVariantToJson: jest.fn((value: unknown) => value),
+}))
+
+const { renderVoltraVariantToJson } = jest.requireMock('@use-voltra/ios') as {
+  renderVoltraVariantToJson: jest.Mock
+}
+
+function makeTempProject(files: Record<string, string>): { projectRoot: string; cleanup: () => void } {
+  const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'voltra-ios-client-prerender-'))
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = path.join(projectRoot, rel)
+    fs.mkdirSync(path.dirname(abs), { recursive: true })
+    fs.writeFileSync(abs, content)
+  }
+  return {
+    projectRoot,
+    cleanup: () => fs.rmSync(projectRoot, { recursive: true, force: true }),
+  }
+}
+
+describe('prerenderClientRenderedWidgets', () => {
+  afterEach(() => {
+    renderVoltraVariantToJson.mockClear()
+  })
+
+  it('evaluates the entry default export for a Dynamic Widget placeholder', async () => {
+    const { projectRoot, cleanup } = makeTempProject({
+      'widgets/Dynamic.tsx': `
+        export default function NotTheWidgetId(props, env) {
+          return {
+            source: 'entry',
+            widgetFamily: env.widgetFamily,
+            hasProps: typeof props === 'object',
+          }
+        }
+      `,
+    })
+
+    try {
+      const widget: DetectedIOSWidget = {
+        id: 'dynamic_widget',
+        entry: './widgets/Dynamic.tsx',
+        displayName: 'Dynamic Widget',
+        description: 'Uses the entry default export',
+        clientRendered: true,
+        clientSourcePath: path.join(projectRoot, 'widgets/Dynamic.tsx'),
+      }
+
+      const result = await prerenderClientRenderedWidgets([widget], projectRoot)
+
+      expect(renderVoltraVariantToJson).toHaveBeenCalledTimes(1)
+      expect(result.get('dynamic_widget')?.get('__default')).toContain('"source":"entry"')
+      expect(result.get('dynamic_widget')?.get('__default')).toContain('"widgetFamily":"systemMedium"')
+    } finally {
+      cleanup()
+    }
+  })
+})
diff --git a/packages/ios-client/expo-plugin/src/ios-widget/clientRenderedPrerender.ts b/packages/ios-client/expo-plugin/src/ios-widget/clientRenderedPrerender.ts
new file mode 100644
index 00000000..81d5fd28
--- /dev/null
+++ b/packages/ios-client/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
+}
diff --git a/packages/ios-client/expo-plugin/src/ios-widget/files/index.ts b/packages/ios-client/expo-plugin/src/ios-widget/files/index.ts
index 1a59927c..f4d9f734 100644
--- a/packages/ios-client/expo-plugin/src/ios-widget/files/index.ts
+++ b/packages/ios-client/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,
diff --git a/packages/ios-client/expo-plugin/src/ios-widget/files/manifest.node.test.ts b/packages/ios-client/expo-plugin/src/ios-widget/files/manifest.node.test.ts
new file mode 100644
index 00000000..a4308892
--- /dev/null
+++ b/packages/ios-client/expo-plugin/src/ios-widget/files/manifest.node.test.ts
@@ -0,0 +1,139 @@
+import * as fs from 'fs'
+import * as os from 'os'
+import * as path from 'path'
+
+import { createIOSDynamicWidgetsManifest, generateIOSDynamicWidgetsManifest } from './manifest'
+
+function makeTempProject(files: Record<string, string>): { projectRoot: string; cleanup: () => void } {
+  const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'voltra-ios-manifest-'))
+
+  for (const [relativePath, contents] of Object.entries(files)) {
+    const filePath = path.join(projectRoot, relativePath)
+    fs.mkdirSync(path.dirname(filePath), { recursive: true })
+    fs.writeFileSync(filePath, contents)
+  }
+
+  return {
+    projectRoot,
+    cleanup: () => fs.rmSync(projectRoot, { recursive: true, force: true }),
+  }
+}
+
+describe('createIOSDynamicWidgetsManifest', () => {
+  it('normalizes entries relative to the project root', () => {
+    const { projectRoot, cleanup } = makeTempProject({
+      'widgets/home.tsx': 'export default function HomeWidget() {}',
+    })
+
+    try {
+      const manifest = createIOSDynamicWidgetsManifest(projectRoot, [
+        {
+          id: 'home',
+          entry: './widgets/home.tsx',
+          displayName: 'Home',
+          description: 'Home widget',
+        },
+      ])
+
+      expect(manifest).toEqual({
+        version: 1,
+        platform: 'ios',
+        widgets: [{ id: 'home', entry: 'widgets/home.tsx' }],
+      })
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('omits legacy widgets without entries', () => {
+    const { projectRoot, cleanup } = makeTempProject({
+      'widgets/home.tsx': 'export default function HomeWidget() {}',
+    })
+
+    try {
+      const manifest = createIOSDynamicWidgetsManifest(projectRoot, [
+        {
+          id: 'legacy',
+          displayName: 'Legacy',
+          description: 'Server-rendered widget',
+        },
+        {
+          id: 'home',
+          entry: './widgets/home.tsx',
+          displayName: 'Home',
+          description: 'Dynamic widget',
+        },
+      ])
+
+      expect(manifest).toEqual({
+        version: 1,
+        platform: 'ios',
+        widgets: [{ id: 'home', entry: 'widgets/home.tsx' }],
+      })
+    } finally {
+      cleanup()
+    }
+  })
+})
+
+describe('generateIOSDynamicWidgetsManifest', () => {
+  it('writes the iOS manifest with deterministic formatting', () => {
+    const { projectRoot, cleanup } = makeTempProject({
+      '.voltra/manifest.ios.json': '{\n  "stale": true\n}\n',
+      'widgets/home.tsx': 'export default function HomeWidget() {}',
+    })
+
+    try {
+      generateIOSDynamicWidgetsManifest({
+        projectRoot,
+        widgets: [
+          {
+            id: 'home',
+            entry: './widgets/home.tsx',
+            displayName: 'Home',
+            description: 'Home widget',
+          },
+        ],
+      })
+
+      const manifestPath = path.join(projectRoot, '.voltra', 'manifest.ios.json')
+      expect(fs.readFileSync(manifestPath, 'utf8')).toBe(
+        [
+          '{',
+          '  "version": 1,',
+          '  "platform": "ios",',
+          '  "widgets": [',
+          '    {',
+          '      "id": "home",',
+          '      "entry": "widgets/home.tsx"',
+          '    }',
+          '  ]',
+          '}',
+          '',
+        ].join('\n')
+      )
+    } finally {
+      cleanup()
+    }
+  })
+
+  it('writes an empty manifest instead of leaving stale widget declarations behind', () => {
+    const { projectRoot, cleanup } = makeTempProject({
+      '.voltra/manifest.ios.json':
+        '{\n  "version": 1,\n  "platform": "ios",\n  "widgets": [{ "id": "old", "entry": "old.tsx" }]\n}\n',
+    })
+
+    try {
+      generateIOSDynamicWidgetsManifest({
+        projectRoot,
+        widgets: [],
+      })
+
+      expect(fs.readFileSync(path.join(projectRoot, '.voltra', 'manifest.ios.json'), 'utf8')).toBe(
+        ['{', '  "version": 1,', '  "platform": "ios",', '  "widgets": []', '}', ''].join('\n')
+      )
+    } finally {
+      cleanup()
+    }
+  })
+})
diff --git a/packages/ios-client/expo-plugin/src/ios-widget/files/manifest.ts b/packages/ios-client/expo-plugin/src/ios-widget/files/manifest.ts
new file mode 100644
index 00000000..c26ad1a2
--- /dev/null
+++ b/packages/ios-client/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}`)
+}
diff --git a/packages/ios-client/expo-plugin/src/ios-widget/files/swift.node.test.ts b/packages/ios-client/expo-plugin/src/ios-widget/files/swift.node.test.ts
index 8fa35bd7..b21b7932 100644
--- a/packages/ios-client/expo-plugin/src/ios-widget/files/swift.node.test.ts
+++ b/packages/ios-client/expo-plugin/src/ios-widget/files/swift.node.test.ts
@@ -1,3 +1,5 @@
+import type { DetectedIOSWidget } from '../clientRendered'
+
 import { __test__ } from './swift'
 
 describe('generateInitialStatesSwift', () => {
@@ -20,3 +22,102 @@ describe('generateInitialStatesSwift', () => {
     expect(swift).not.toContain('VoltraInitialStateLocale.preferredLanguageTags()')
   })
 })
+
+describe('generateWidgetBundleSwift — Dynamic Widget dispatch', () => {
+  const serverWidget: DetectedIOSWidget = {
+    id: 'weather',
+    entry: './widgets/weather.tsx',
+    displayName: 'Weather',
+    description: 'Shows weather',
+    clientRendered: false,
+  }
+  const clientWidget: DetectedIOSWidget = {
+    id: 'IosWeatherWidget',
+    entry: './widgets/IosWeatherWidget.tsx',
+    displayName: 'Client Weather',
+    description: 'Client-rendered weather',
+    clientRendered: true,
+    clientSourcePath: '/tmp/IosWeatherWidget.tsx',
+  }
+
+  it('emits VoltraHomeWidgetProvider for server-rendered widgets', () => {
+    const swift = __test__.generateWidgetBundleSwift([serverWidget])
+    expect(swift).toContain('VoltraHomeWidgetProvider(')
+    expect(swift).toContain('VoltraHomeWidgetView(entry: entry)')
+    expect(swift).not.toContain('VoltraClientWidgetProvider')
+  })
+
+  it('emits VoltraClientWidgetProvider + VoltraClientWidgetContentView for client-rendered widgets', () => {
+    const swift = __test__.generateWidgetBundleSwift([clientWidget])
+    expect(swift).toContain('VoltraClientWidgetProvider(')
+    expect(swift).toContain('VoltraClientWidgetContentView(')
+    expect(swift).toContain('initialState: VoltraWidgetInitialStates.getInitialState(for: widgetId)')
+    expect(swift).not.toContain('VoltraHomeWidgetProvider(')
+  })
+
+  it('handles mixed server + client widgets in one bundle', () => {
+    const swift = __test__.generateWidgetBundleSwift([serverWidget, clientWidget])
+    expect(swift).toContain('VoltraWidget_weather()')
+    expect(swift).toContain('VoltraWidget_IosWeatherWidget()')
+    expect(swift).toContain('VoltraHomeWidgetProvider(')
+    expect(swift).toContain('VoltraClientWidgetProvider(')
+  })
+
+  it('keeps WidgetKit kind, supportedFamilies, contentMarginsDisabled identical across modes', () => {
+    const serverSwift = __test__.generateWidgetBundleSwift([serverWidget])
+    const clientSwift = __test__.generateWidgetBundleSwift([clientWidget])
+    for (const swift of [serverSwift, clientSwift]) {
+      expect(swift).toMatch(/StaticConfiguration\(\s*\n\s*kind: "Voltra_Widget_/)
+      expect(swift).toContain('.supportedFamilies(')
+      expect(swift).toContain('.contentMarginsDisabled()')
+    }
+  })
+})
+
+describe('generateWidgetBundleSwift — AppIntent configuration', () => {
+  const configurableWidget: DetectedIOSWidget = {
+    id: 'IosWeatherWidget',
+    entry: './widgets/IosWeatherWidget.tsx',
+    displayName: 'Client Weather',
+    description: 'Client-rendered weather',
+    clientRendered: true,
+    clientSourcePath: '/tmp/IosWeatherWidget.tsx',
+    appIntent: {
+      parameters: [{ name: 'label', title: 'Label', default: 'Hello' }],
+    },
+  }
+  const plainClientWidget: DetectedIOSWidget = {
+    id: 'PlainClient',
+    entry: './widgets/PlainClient.tsx',
+    displayName: 'Plain Client',
+    description: 'Client-rendered, no config',
+    clientRendered: true,
+    clientSourcePath: '/tmp/PlainClient.tsx',
+  }
+
+  it('generates an AppIntentConfiguration with a code-default @Parameter for a configurable widget', () => {
+    const swift = __test__.generateWidgetBundleSwift([configurableWidget])
+    expect(swift).toContain('import AppIntents')
+    expect(swift).toContain('struct VoltraWidget_IosWeatherWidget_Intent: WidgetConfigurationIntent')
+    expect(swift).toContain('@Parameter(title: "Label", default: "Hello")')
+    expect(swift).toContain('AppIntentConfiguration(')
+    expect(swift).toContain('VoltraWidget_IosWeatherWidget_ClientProvider')
+    // iOS 17+ gating, since AppIntentConfiguration is unavailable below 17
+    expect(swift).toContain('if #available(iOS 17.0, *)')
+    expect(swift).toContain('@available(iOS 17.0, *)')
+  })
+
+  it('passes the configured parameter into the entry (env.configuration)', () => {
+    const swift = __test__.generateWidgetBundleSwift([configurableWidget])
+    expect(swift).toContain('VoltraClientWidgetProvider.loadEntry(widgetId:')
+    expect(swift).toContain('["label": configuration.label]')
+  })
+
+  it('does NOT emit AppIntent code for a client widget without appIntent', () => {
+    const swift = __test__.generateWidgetBundleSwift([plainClientWidget])
+    expect(swift).toContain('VoltraClientWidgetProvider(')
+    expect(swift).not.toContain('AppIntentConfiguration(')
+    expect(swift).not.toContain('WidgetConfigurationIntent')
+    expect(swift).not.toContain('import AppIntents')
+  })
+})
diff --git a/packages/ios-client/expo-plugin/src/ios-widget/files/swift.ts b/packages/ios-client/expo-plugin/src/ios-widget/files/swift.ts
index 2fef4df8..9da2fd6a 100644
--- a/packages/ios-client/expo-plugin/src/ios-widget/files/swift.ts
+++ b/packages/ios-client/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,
 }
diff --git a/packages/ios-client/expo-plugin/src/ios-widget/index.ts b/packages/ios-client/expo-plugin/src/ios-widget/index.ts
index f372bdb6..67652dc0 100644
--- a/packages/ios-client/expo-plugin/src/ios-widget/index.ts
+++ b/packages/ios-client/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 }],
diff --git a/packages/ios-client/expo-plugin/src/ios-widget/widgetPlist.ts b/packages/ios-client/expo-plugin/src/ios-widget/widgetPlist.ts
index 7494f885..c8bba9bc 100644
--- a/packages/ios-client/expo-plugin/src/ios-widget/widgetPlist.ts
+++ b/packages/ios-client/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
 
+        // Client-rendered 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
+        // client-rendered 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
diff --git a/packages/ios-client/expo-plugin/src/ios-widget/xcode/buildPhases.node.test.ts b/packages/ios-client/expo-plugin/src/ios-widget/xcode/buildPhases.node.test.ts
new file mode 100644
index 00000000..542f990f
--- /dev/null
+++ b/packages/ios-client/expo-plugin/src/ios-widget/xcode/buildPhases.node.test.ts
@@ -0,0 +1,68 @@
+import { ensureWidgetBundleScriptPhase } from './buildPhases'
+
+// The xcode lib normally parses a .pbxproj from disk; for a unit test we build the minimal hash
+// the real methods touch (native target + the file/build-file sections addBuildPhase reads) and
+// exercise the actual library code rather than a mock.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const xcode = require('xcode')
+
+const TARGET_UUID = 'A'.repeat(24)
+
+function makeProject() {
+  const project = xcode.project('/noop.pbxproj')
+  project.hash = {
+    project: {
+      objects: {
+        PBXNativeTarget: { [TARGET_UUID]: { buildPhases: [] } },
+        PBXFileReference: {},
+        PBXBuildFile: {},
+      },
+    },
+  }
+  return project
+}
+
+function shellPhaseObjects(project: any): any[] {
+  const section = project.hash.project.objects.PBXShellScriptBuildPhase || {}
+  return Object.keys(section)
+    .filter((key) => !/_comment$/.test(key))
+    .map((key) => section[key])
+}
+
+describe('ensureWidgetBundleScriptPhase', () => {
+  it('adds a release-only widget-bundling shell phase to the target', () => {
+    const project = makeProject()
+    ensureWidgetBundleScriptPhase(project, TARGET_UUID)
+
+    const phases = shellPhaseObjects(project)
+    expect(phases).toHaveLength(1)
+
+    const phase = phases[0]
+    expect(phase.name).toContain('Bundle Voltra client widgets')
+    expect(phase.shellScript).toContain('@use-voltra/metro/bundle-widgets')
+    // Debug builds use Metro, so the script must skip them...
+    expect(phase.shellScript).toContain('Debug')
+    // ...and bake into the extension's resources dir in release.
+    expect(phase.shellScript).toContain('UNLOCALIZED_RESOURCES_FOLDER_PATH')
+    // Re-bakes every release build (can't enumerate widget-source inputs) without warning.
+    expect(phase.alwaysOutOfDate).toBe(1)
+
+    // Phase is attached to the (extension) target.
+    expect(project.hash.project.objects.PBXNativeTarget[TARGET_UUID].buildPhases).toHaveLength(1)
+  })
+
+  it('is idempotent — re-running does not add a second phase', () => {
+    const project = makeProject()
+    ensureWidgetBundleScriptPhase(project, TARGET_UUID)
+    ensureWidgetBundleScriptPhase(project, TARGET_UUID)
+
+    expect(shellPhaseObjects(project)).toHaveLength(1)
+    expect(project.hash.project.objects.PBXNativeTarget[TARGET_UUID].buildPhases).toHaveLength(1)
+  })
+
+  it('does nothing when the target is absent', () => {
+    const project = makeProject()
+    ensureWidgetBundleScriptPhase(project, 'B'.repeat(24))
+    expect(shellPhaseObjects(project)).toHaveLength(0)
+  })
+})
diff --git a/packages/ios-client/expo-plugin/src/ios-widget/xcode/buildPhases.ts b/packages/ios-client/expo-plugin/src/ios-widget/xcode/buildPhases.ts
index da554df2..372bb262 100644
--- a/packages/ios-client/expo-plugin/src/ios-widget/xcode/buildPhases.ts
+++ b/packages/ios-client/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 client widgets'
+
+// Release-only build phase that bakes each client-rendered 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 — client-rendered 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 client-rendered 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
diff --git a/packages/ios-client/expo-plugin/src/ios-widget/xcode/index.ts b/packages/ios-client/expo-plugin/src/ios-widget/xcode/index.ts
index 48f47fb6..1165e7ce 100644
--- a/packages/ios-client/expo-plugin/src/ios-widget/xcode/index.ts
+++ b/packages/ios-client/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 client-rendered (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,
diff --git a/packages/ios-client/expo-plugin/src/types.ts b/packages/ios-client/expo-plugin/src/types.ts
index 26f85ce3..b3a3c0ae 100644
--- a/packages/ios-client/expo-plugin/src/types.ts
+++ b/packages/ios-client/expo-plugin/src/types.ts
@@ -1,6 +1,6 @@
 import type { ConfigPlugin } from '@expo/config-plugins'
 
-import type { WidgetInitialStatePath, WidgetLabel } from '@use-voltra/expo-plugin'
+import type { DynamicWidgetEntryConfig, WidgetInitialStatePath, WidgetLabel } from '@use-voltra/expo-plugin'
 
 /**
  * Supported iOS Home Screen widget size families.
@@ -14,10 +14,33 @@ export type IOSWidgetFamily =
   | 'accessoryRectangular'
   | 'accessoryInline'
 
+/**
+ * A single user-configurable parameter exposed via AppIntent (the native "Edit Widget" sheet).
+ */
+export interface AppIntentParameter {
+  /** Swift property name + the key under `env.configuration`. */
+  name: string
+  /** Label shown in the widget configuration sheet. */
+  title: string
+  /** Default value used before the user configures the widget (the "from code" default). */
+  default?: string
+}
+
+/**
+ * AppIntent configuration for a user-configurable widget (iOS 17+).
+ */
+export interface IOSWidgetAppIntentConfig {
+  /** Parameters the user can edit via "Edit Widget"; surfaced as `env.configuration`. */
+  parameters: AppIntentParameter[]
+}
+
 /**
  * Configuration for a single iOS home screen widget.
+ *
+ * `entry` is required only for Dynamic Widgets. Widgets without `entry` remain server-rendered /
+ * server-updated legacy widgets and are excluded from the Dynamic Widgets manifest.
  */
-export interface IOSWidgetConfig {
+export interface IOSWidgetConfig extends DynamicWidgetEntryConfig {
   /**
    * Unique identifier for the widget (used as the widget kind and in JS API)
    */
@@ -28,6 +51,13 @@ export interface IOSWidgetConfig {
   supportedFamilies?: IOSWidgetFamily[]
   initialStatePath?: WidgetInitialStatePath
   serverUpdate?: IOSWidgetServerUpdateConfig
+  /**
+   * AppIntent configuration (iOS 17+). When set on a client-rendered widget, the plugin generates
+   * an `AppIntentConfiguration` so users configure parameters via the native "Edit Widget" sheet;
+   * defaults come from `parameters[].default`, and the configured values are passed into the
+   * widget's `env.configuration` on each render.
+   */
+  appIntent?: IOSWidgetAppIntentConfig
 }
 
 /**
diff --git a/packages/ios-client/expo-plugin/src/validation.node.test.ts b/packages/ios-client/expo-plugin/src/validation.node.test.ts
index bd456a16..36b72d0c 100644
--- a/packages/ios-client/expo-plugin/src/validation.node.test.ts
+++ b/packages/ios-client/expo-plugin/src/validation.node.test.ts
@@ -1,5 +1,21 @@
+import * as fs from 'fs'
+import * as os from 'os'
+import * as path from 'path'
+
 import { validateIOSConfigPluginProps } from './validation'
 
+function createProjectRoot(files: Record<string, string>): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'voltra-ios-validation-'))
+
+  for (const [relativePath, contents] of Object.entries(files)) {
+    const filePath = path.join(root, relativePath)
+    fs.mkdirSync(path.dirname(filePath), { recursive: true })
+    fs.writeFileSync(filePath, contents)
+  }
+
+  return root
+}
+
 describe('validateIOSConfigPluginProps', () => {
   it('accepts valid groupIdentifier', () => {
     expect(() =>
@@ -16,4 +32,68 @@ describe('validateIOSConfigPluginProps', () => {
       })
     ).toThrow(/must start with 'group.'/)
   })
+
+  it('accepts legacy widgets without an entry', () => {
+    expect(() =>
+      validateIOSConfigPluginProps({
+        widgets: [
+          {
+            id: 'home',
+            displayName: 'Home',
+            description: 'Home widget',
+          },
+        ],
+      })
+    ).not.toThrow()
+  })
+
+  it('requires a valid widget entry when present and resolves it against the project root', () => {
+    const projectRoot = createProjectRoot({
+      'widgets/home.tsx': 'export default function HomeWidget() {}',
+    })
+
+    try {
+      expect(() =>
+        validateIOSConfigPluginProps(
+          {
+            widgets: [
+              {
+                id: 'home',
+                entry: './widgets/home.tsx',
+                displayName: 'Home',
+                description: 'Home widget',
+              },
+            ],
+          },
+          projectRoot
+        )
+      ).not.toThrow()
+    } finally {
+      fs.rmSync(projectRoot, { recursive: true, force: true })
+    }
+  })
+
+  it('rejects invalid widget entries when present', () => {
+    const projectRoot = createProjectRoot({})
+
+    try {
+      expect(() =>
+        validateIOSConfigPluginProps(
+          {
+            widgets: [
+              {
+                id: 'home',
+                entry: './widgets/missing.tsx',
+                displayName: 'Home',
+                description: 'Home widget',
+              },
+            ],
+          },
+          projectRoot
+        )
+      ).toThrow(/Widget 'home': entry file not found at widgets\/missing\.tsx/)
+    } finally {
+      fs.rmSync(projectRoot, { recursive: true, force: true })
+    }
+  })
 })
diff --git a/packages/ios-client/expo-plugin/src/validation.ts b/packages/ios-client/expo-plugin/src/validation.ts
index 0f30f5aa..560c739f 100644
--- a/packages/ios-client/expo-plugin/src/validation.ts
+++ b/packages/ios-client/expo-plugin/src/validation.ts
@@ -1,4 +1,9 @@
-import { validateHomeScreenWidgetId, validateInitialStatePath, validateWidgetLabel } from '@use-voltra/expo-plugin'
+import {
+  validateHomeScreenWidgetId,
+  validateInitialStatePath,
+  validateWidgetEntry,
+  validateWidgetLabel,
+} from '@use-voltra/expo-plugin'
 
 import type { IOSConfigPluginProps, IOSWidgetConfig, IOSWidgetFamily } from './types'
 
@@ -12,11 +17,15 @@ const VALID_FAMILIES: Set<IOSWidgetFamily> = new Set([
   'accessoryInline',
 ])
 
-export function validateIOSWidgetConfig(widget: IOSWidgetConfig): void {
+export function validateIOSWidgetConfig(widget: IOSWidgetConfig, projectRoot?: string): void {
   validateHomeScreenWidgetId(widget.id)
   validateWidgetLabel(widget.displayName, widget.id, 'displayName')
   validateWidgetLabel(widget.description, widget.id, 'description')
-  validateInitialStatePath(widget.initialStatePath, widget.id)
+  validateInitialStatePath(widget.initialStatePath, widget.id, projectRoot)
+
+  if (widget.entry !== undefined) {
+    validateWidgetEntry(widget.entry, widget.id, projectRoot)
+  }
 
   if (widget.supportedFamilies) {
     if (!Array.isArray(widget.supportedFamilies)) {
@@ -34,7 +43,7 @@ export function validateIOSWidgetConfig(widget: IOSWidgetConfig): void {
   }
 }
 
-export function validateIOSConfigPluginProps(props: IOSConfigPluginProps): void {
+export function validateIOSConfigPluginProps(props: IOSConfigPluginProps, projectRoot?: string): void {
   if (props.groupIdentifier !== undefined) {
     if (typeof props.groupIdentifier !== 'string') {
       throw new Error('groupIdentifier must be a string')
@@ -52,7 +61,7 @@ export function validateIOSConfigPluginProps(props: IOSConfigPluginProps): void
 
     const seenIds = new Set<string>()
     for (const widget of props.widgets) {
-      validateIOSWidgetConfig(widget)
+      validateIOSWidgetConfig(widget, projectRoot)
 
       if (seenIds.has(widget.id)) {
         throw new Error(`Duplicate widget ID: '${widget.id}'`)
diff --git a/packages/ios-client/expo-plugin/tsconfig.typecheck.json b/packages/ios-client/expo-plugin/tsconfig.typecheck.json
index 58e6f899..eb1a3623 100644
--- a/packages/ios-client/expo-plugin/tsconfig.typecheck.json
+++ b/packages/ios-client/expo-plugin/tsconfig.typecheck.json
@@ -5,7 +5,9 @@
     "rootDir": "../../..",
     "baseUrl": "../../..",
     "paths": {
-      "@use-voltra/expo-plugin": ["packages/expo-plugin/src/index.ts"]
+      "@use-voltra/compiler": ["packages/compiler/src/index.ts"],
+      "@use-voltra/expo-plugin": ["packages/expo-plugin/src/index.ts"],
+      "@use-voltra/metro/scanner": ["packages/metro/src/scanner.ts"]
     }
   },
   "include": ["./src"]
diff --git a/packages/ios-client/ios/app/VoltraModuleImpl.swift b/packages/ios-client/ios/app/VoltraModuleImpl.swift
index 86ec3b51..c52e8185 100644
--- a/packages/ios-client/ios/app/VoltraModuleImpl.swift
+++ b/packages/ios-client/ios/app/VoltraModuleImpl.swift
@@ -2,6 +2,7 @@ import ActivityKit
 import Compression
 import Foundation
 import os
+import React
 import UIKit
 
 @objc(VoltraHeadlessState)
@@ -59,7 +60,26 @@ public class VoltraModuleImpl {
   public init() {
     // Clean up data for widgets that are no longer installed
     VoltraWidgetService.cleanupOrphanedData()
-  }
+    #if DEBUG
+      syncDevServerURL()
+    #endif
+  }
+
+  #if DEBUG
+    /// Resolve the Metro dev-server base URL via React Native's own provider and relay it to the
+    /// widget extension through the app group. The extension is React-free (can't call
+    /// RCTBundleURLProvider itself), so the app resolves it and the extension reads it — fixing the
+    /// case where Metro isn't on localhost:8081 (custom port, LAN dev server, physical device).
+    private func syncDevServerURL() {
+      guard
+        let url = RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index"),
+        let scheme = url.scheme,
+        let host = url.host
+      else { return }
+      let port = url.port.map { ":\($0)" } ?? ""
+      VoltraWidgetDefaults.setDevServerURL("\(scheme)://\(host)\(port)")
+    }
+  #endif
 
   func isHeadless() -> Bool {
     VoltraHeadlessState.shared.isHeadless()
@@ -255,6 +275,11 @@ public class VoltraModuleImpl {
   }
 
   func reloadWidgets(widgetIds: [String]?) async {
+    #if DEBUG
+      // Refresh the relayed dev-server URL before reloading (hot-reload path) so the extension
+      // fetches from the current Metro host.
+      syncDevServerURL()
+    #endif
     if let ids = widgetIds, !ids.isEmpty {
       for widgetId in ids {
         VoltraWidgetService.reloadTimeline(for: widgetId)
diff --git a/packages/ios-client/ios/shared/VoltraConstants.swift b/packages/ios-client/ios/shared/VoltraConstants.swift
index e051d591..0d9651a3 100644
--- a/packages/ios-client/ios/shared/VoltraConstants.swift
+++ b/packages/ios-client/ios/shared/VoltraConstants.swift
@@ -32,6 +32,10 @@ public enum VoltraStorageKeys {
 
   public static let widgetKindPrefix = "Voltra_Widget_"
 
+  /// Metro dev-server base URL, relayed app → widget extension (DEBUG only). The extension is
+  /// React-free, so it can't resolve the URL itself; the app writes it via RCTBundleURLProvider.
+  public static let devServerURL = "Voltra_DevServerURL"
+
   // MARK: - Info.plist keys
 
   public static let widgetIds = "Voltra_WidgetIds"
diff --git a/packages/ios-client/ios/shared/VoltraJSRenderer.swift b/packages/ios-client/ios/shared/VoltraJSRenderer.swift
new file mode 100644
index 00000000..27c0991b
--- /dev/null
+++ b/packages/ios-client/ios/shared/VoltraJSRenderer.swift
@@ -0,0 +1,201 @@
+import Foundation
+import JavaScriptCore
+
+/// JavaScriptCore-backed runtime for Voltra **client-rendered widgets**.
+///
+/// Each widget ships its own Metro bundle that defines `module.exports.render(props, env)`
+/// (see `example/metro/widgetRegistry.js`). When evaluated, the bundle ends with `__r(0)`
+/// which executes its entry module; the source is wrapped with a small bootstrap that
+/// captures those exports into `globalThis.__voltraWidgets[<widgetId>]` so `render` can be
+/// called from native at any later moment.
+///
+/// One shared `JSContext` per process. Each subsequent bundle evaluation overwrites Metro's
+/// `__r`/`__d` globals (they're closure-scoped per bundle's IIFE), but the captured
+/// `globalThis.__voltraWidgets[<widgetId>]` reference retains each widget's render function
+/// indefinitely.
+public enum VoltraJSRenderer {
+  private static var _context: JSContext?
+  private static let lock = NSLock()
+  private static let TAG = "VoltraJSRenderer"
+
+  // MARK: - Public API
+
+  /// Evaluate a Voltra widget bundle in the shared JSContext, capturing the bundle's
+  /// `render(props, env)` export under `globalThis.__voltraWidgets[<widgetId>]`.
+  ///
+  /// The bundle source is the raw output of Metro's
+  /// `/voltra/widgets/<widgetId>.bundle` endpoint. We append a small bootstrap line
+  /// that runs after the bundle's `__r(0)` to capture the entry module's exports.
+  ///
+  /// Idempotent: re-evaluating the same widget overwrites the captured exports — used
+  /// by dev-mode hot-reload (always-refetch policy).
+  public static func evaluateBundle(source: String, widgetId: String) -> Bool {
+    lock.lock()
+    defer { lock.unlock() }
+
+    guard let ctx = context() else {
+      VoltraLogger.widget.error("[\(TAG)] No JSContext available")
+      return false
+    }
+
+    let escapedId = jsStringLiteral(widgetId)
+    // Metro emits the bundle's entry invocation as `__r(<entryModuleId>);` near the
+    // end of the file (before the sourcemap/sourceURL comments). The entry id is NOT
+    // always 0 — when Metro serves multiple widget bundles from the same process, it
+    // shares its module-id registry across bundles so the second/third widget's entry
+    // gets a higher id (e.g. `__r(74);`). We extract whatever id Metro produced and
+    // re-invoke it; Metro's `__r` caches module exports, so the second invocation
+    // returns the same exports the bundle already evaluated.
+    let entryModuleId = extractEntryModuleId(from: source) ?? 0
+    let wrapped = """
+    \(source)
+    ;(function () {
+      if (!globalThis.__voltraWidgets) { globalThis.__voltraWidgets = {}; }
+      globalThis.__voltraWidgets[\(escapedId)] = __r(\(entryModuleId));
+    })();
+    """
+
+    ctx.exception = nil
+    ctx.evaluateScript(wrapped)
+    if let message = exceptionMessage(ctx) {
+      VoltraLogger.widget.error("[\(TAG)] Bundle eval failed for widgetId=\(widgetId): \(message)")
+      return false
+    }
+
+    // Verify the bootstrap captured the exports correctly
+    guard
+      let registry = ctx.objectForKeyedSubscript("__voltraWidgets"),
+      !registry.isUndefined,
+      let widget = registry.objectForKeyedSubscript(widgetId),
+      !widget.isUndefined,
+      let renderFn = widget.objectForKeyedSubscript("render"),
+      renderFn.isObject,
+      renderFn.objectForKeyedSubscript("call") != nil
+    else {
+      VoltraLogger.widget.error("[\(TAG)] Bundle evaluated but did not expose render() for widgetId=\(widgetId)")
+      return false
+    }
+    _ = renderFn
+
+    VoltraLogger.widget.info("[\(TAG)] Bundle evaluated for widgetId=\(widgetId) (\(source.count) chars)")
+    return true
+  }
+
+  /// Ensure the widget's bundle is evaluated in *this process's* JSContext, returning true if its
+  /// `render()` is available afterward.
+  ///
+  /// Cheap no-op when the widget is already captured in this process (the warm case: the provider
+  /// just evaluated it). Evaluates from `source` when the context is fresh — which is what happens
+  /// when WidgetKit re-renders an archived entry in a new extension process, where the provider's
+  /// evaluation never ran. The View calls this before `render()` so rendering never depends on
+  /// which process evaluated the bundle.
+  public static func ensureEvaluated(widgetId: String, source: String) -> Bool {
+    lock.lock()
+    let alreadyEvaluated =
+      _context?
+        .objectForKeyedSubscript("__voltraWidgets")?
+        .objectForKeyedSubscript(widgetId)?
+        .objectForKeyedSubscript("render")?
+        .isObject ?? false
+    lock.unlock()
+
+    if alreadyEvaluated {
+      return true
+    }
+    return evaluateBundle(source: source, widgetId: widgetId)
+  }
+
+  /// Invoke the previously-evaluated widget's `render(propsJSON, envJSON)` function and
+  /// return its resolved JSON string output.
+  ///
+  /// Returns `nil` if the widget hasn't been evaluated, the function throws, or the
+  /// result is not a string.
+  public static func render(
+    widgetId: String,
+    propsJSON: String,
+    envJSON: String
+  ) -> String? {
+    lock.lock()
+    defer { lock.unlock() }
+
+    guard let ctx = _context else {
+      VoltraLogger.widget.error("[\(TAG)] render(\(widgetId)): no JSContext (call evaluateBundle first)")
+      return nil
+    }
+
+    guard
+      let registry = ctx.objectForKeyedSubscript("__voltraWidgets"),
+      !registry.isUndefined,
+      let widget = registry.objectForKeyedSubscript(widgetId),
+      !widget.isUndefined,
+      let renderFn = widget.objectForKeyedSubscript("render"),
+      renderFn.isObject
+    else {
+      VoltraLogger.widget.error("[\(TAG)] render(\(widgetId)): no captured render() — bundle not evaluated?")
+      return nil
+    }
+
+    ctx.exception = nil
+    guard let result = renderFn.call(withArguments: [propsJSON, envJSON]) else {
+      VoltraLogger.widget.error("[\(TAG)] render(\(widgetId)): call returned nil")
+      return nil
+    }
+    if let message = exceptionMessage(ctx) {
+      VoltraLogger.widget.error("[\(TAG)] render(\(widgetId)) threw: \(message)")
+      return nil
+    }
+
+    guard result.isString else {
+      VoltraLogger.widget.error("[\(TAG)] render(\(widgetId)) did not return a string")
+      return nil
+    }
+    return result.toString()
+  }
+
+  // MARK: - Lifecycle
+
+  private static func context() -> JSContext? {
+    if let existing = _context { return existing }
+    guard let ctx = JSContext() else {
+      VoltraLogger.widget.error("[\(TAG)] Failed to create JSContext")
+      return nil
+    }
+    ctx.exceptionHandler = { _, exception in
+      VoltraLogger.widget.error("[\(TAG)] JS exception: \(exception?.toString() ?? "unknown")")
+    }
+    _context = ctx
+    return ctx
+  }
+
+  // MARK: - Helpers
+
+  private static func exceptionMessage(_ ctx: JSContext) -> String? {
+    guard let exc = ctx.exception, !exc.isUndefined, !exc.isNull else { return nil }
+    ctx.exception = nil
+    return exc.toString()
+  }
+
+  private static func jsStringLiteral(_ value: String) -> String {
+    let escaped = value
+      .replacingOccurrences(of: "\\", with: "\\\\")
+      .replacingOccurrences(of: "\"", with: "\\\"")
+      .replacingOccurrences(of: "\n", with: "\\n")
+      .replacingOccurrences(of: "\r", with: "\\r")
+    return "\"\(escaped)\""
+  }
+
+  /// Find the entry module id Metro emitted in the bundle's trailing `__r(<id>);`.
+  /// Scans the LAST occurrence of `__r(<digits>);` in the source — every `__d(...)`
+  /// module declaration also contains internal `__r(...)` calls, so taking the last
+  /// match (the entrypoint invocation Metro appends at bundle's end) is what we want.
+  private static func extractEntryModuleId(from source: String) -> Int? {
+    guard let regex = try? NSRegularExpression(pattern: #"__r\((\d+)\);"#) else { return nil }
+    let nsRange = NSRange(source.startIndex ..< source.endIndex, in: source)
+    let matches = regex.matches(in: source, range: nsRange)
+    guard let last = matches.last,
+          let range = Range(last.range(at: 1), in: source),
+          let id = Int(source[range])
+    else { return nil }
+    return id
+  }
+}
diff --git a/packages/ios-client/ios/shared/VoltraWidgetDefaults.swift b/packages/ios-client/ios/shared/VoltraWidgetDefaults.swift
index 22e1f86e..18e794c6 100644
--- a/packages/ios-client/ios/shared/VoltraWidgetDefaults.swift
+++ b/packages/ios-client/ios/shared/VoltraWidgetDefaults.swift
@@ -37,6 +37,12 @@ public enum VoltraWidgetDefaults {
     try? resolvedDefaults().string(forKey: VoltraStorageKeys.widgetTimeline(widgetId))
   }
 
+  /// Metro dev-server base URL relayed from the app (DEBUG). Read by the client-widget runtime;
+  /// nil falls back to localhost.
+  public static func devServerURL() -> String? {
+    try? resolvedDefaults().string(forKey: VoltraStorageKeys.devServerURL)
+  }
+
   // MARK: - Write
 
   public static func setWidgetJson(_ json: String, for widgetId: String, deepLinkUrl: String?) throws {
@@ -70,6 +76,14 @@ public enum VoltraWidgetDefaults {
     defaults.synchronize()
   }
 
+  /// Relay the Metro dev-server base URL to the widget extension (DEBUG). Best-effort: a missing
+  /// app group just leaves the extension on its localhost fallback.
+  public static func setDevServerURL(_ url: String) {
+    guard let defaults = try? resolvedDefaults() else { return }
+    defaults.set(url, forKey: VoltraStorageKeys.devServerURL)
+    defaults.synchronize()
+  }
+
   // MARK: - Remove
 
   /// Removes all persisted data (json, deepLinkUrl, timeline) for a single widget.
diff --git a/packages/ios-client/ios/target/VoltraClientWidgetRuntime.swift b/packages/ios-client/ios/target/VoltraClientWidgetRuntime.swift
new file mode 100644
index 00000000..2d9bc250
--- /dev/null
+++ b/packages/ios-client/ios/target/VoltraClientWidgetRuntime.swift
@@ -0,0 +1,379 @@
+import Foundation
+import SwiftUI
+import WidgetKit
+
+// Shared runtime for client-rendered widgets.
+//
+// This file is compiled into the VoltraWidget framework alongside the existing
+// VoltraHomeWidget.swift, so widget extension code generated by the plugin can
+// reference VoltraClientWidget* types without any per-widget glue duplicated.
+//
+// Pipeline:
+//
+//   1. Provider runs on a WidgetKit timeline tick.
+//      - Fetches the JS bundle (dev = Metro HTTP, prod = baked asset stub).
+//      - Evaluates it once in the shared JSContext via VoltraJSRenderer.
+//      - Emits a VoltraClientWidgetEntry with `bundleReady = true` (or errorMessage on failure).
+//
+//   2. ContentView body runs per (family, scheme, renderingMode) combo.
+//      - Reads SwiftUI @Environment values (which are ONLY accessible inside a View body).
+//      - Builds envJSON matching WidgetEnvironment in packages/core/src/widget-environment.ts.
+//      - Calls VoltraJSRenderer.render(widgetId, propsJSON, envJSON) → resolved JSON string.
+//      - Parses the resolved JSON into a VoltraNode and hands a VoltraHomeWidgetEntry to
+//        the existing VoltraHomeWidgetView so client-rendered widgets reach the same UI
+//        renderer as server-rendered ones.
+//
+// On bundle-load failure the View falls back to the prerendered initial state.
+
+// MARK: - Entry
+
+public struct VoltraClientWidgetEntry: TimelineEntry {
+  public let date: Date
+  public let widgetId: String
+  public let bundleReady: Bool
+  public let errorMessage: String?
+  /// User-configured AppIntent parameters → `env.configuration`. Empty for widgets without an
+  /// AppIntent configuration; populated by the generated AppIntentTimelineProvider from the
+  /// configured intent.
+  public let configuration: [String: String]
+  /// The evaluated widget's JS bundle. Carried on the entry (not just left in the provider's
+  /// JSContext) because WidgetKit archives entries and re-renders the View in a *fresh* extension
+  /// process, where the provider's process-static JSContext is empty. The View re-evaluates from
+  /// this source so `render()` always has the widget's function available in its own process.
+  public let bundleSource: String?
+
+  public init(
+    date: Date,
+    widgetId: String,
+    bundleReady: Bool,
+    errorMessage: String? = nil,
+    configuration: [String: String] = [:],
+    bundleSource: String? = nil
+  ) {
+    self.date = date
+    self.widgetId = widgetId
+    self.bundleReady = bundleReady
+    self.errorMessage = errorMessage
+    self.configuration = configuration
+    self.bundleSource = bundleSource
+  }
+}
+
+// MARK: - Provider
+
+//
+// Refresh model:
+//
+//   - DEBUG builds: Provider fetches `<id>.bundle` from Metro on every
+//        `getTimeline`/`getSnapshot`, evaluates it in the shared JSContext, and emits
+//        `bundleReady = true`. The ContentView then runs the freshly evaluated
+//        `render(props, env)` and feeds the result to `VoltraHomeWidgetView`.
+//
+//   - Release builds: Provider attempts to load a baked-in bundle (release-path loader is
+//        a future addition); on failure the ContentView renders the prerendered initial state.
+//
+//   - Timeline policy is ALWAYS `.never`. The widget refreshes only when something
+//        explicitly calls `WidgetCenter.shared.reloadAllTimelines()` or when WidgetKit
+//        naturally re-invokes the Provider on its own lifecycle events (e.g., host app
+//        foregrounding). iOS rate-limits timeline-policy-driven refresh aggressively
+//        (~5-minute floor even in the simulator), so explicit reloads or natural
+//        lifecycle re-invocations are the only mechanisms that deliver fresh content.
+
+public struct VoltraClientWidgetProvider: TimelineProvider {
+  public let widgetId: String
+  /// Prerendered initial state JSON from `VoltraWidgetInitialStates.getInitialState(for:)`.
+  /// Used as the placeholder, the Loading fallback, and the steady-state view if a bundle
+  /// load fails.
+  public let initialState: Data?
+
+  public init(widgetId: String, initialState: Data? = nil) {
+    self.widgetId = widgetId
+    self.initialState = initialState
+  }
+
+  public func placeholder(in _: Context) -> VoltraClientWidgetEntry {
+    VoltraClientWidgetEntry(date: Date(), widgetId: widgetId, bundleReady: false)
+  }
+
+  public func getSnapshot(in _: Context, completion: @escaping (VoltraClientWidgetEntry) -> Void) {
+    Task { completion(await loadBundleEntry()) }
+  }
+
+  public func getTimeline(in _: Context, completion: @escaping (Timeline<VoltraClientWidgetEntry>) -> Void) {
+    Task {
+      let entry = await loadBundleEntry()
+      completion(Timeline(entries: [entry], policy: .never))
+    }
+  }
+
+  private func loadBundleEntry() async -> VoltraClientWidgetEntry {
+    await VoltraClientWidgetProvider.loadEntry(widgetId: widgetId, configuration: [:])
+  }
+
+  /// Fetch + evaluate the widget bundle and build an entry. Shared by this `TimelineProvider` and
+  /// the plugin-generated `AppIntentTimelineProvider`s (which pass the user-configured params as
+  /// `configuration`).
+  public static func loadEntry(widgetId: String, configuration: [String: String]) async -> VoltraClientWidgetEntry {
+    let date = Date()
+
+    let source: String
+    do {
+      source = try await VoltraClientWidgetBundleSource.load(widgetId: widgetId)
+    } catch {
+      return VoltraClientWidgetEntry(
+        date: date,
+        widgetId: widgetId,
+        bundleReady: false,
+        errorMessage: error.localizedDescription,
+        configuration: configuration
+      )
+    }
+
+    let okEval = VoltraJSRenderer.evaluateBundle(source: source, widgetId: widgetId)
+    if !okEval {
+      return VoltraClientWidgetEntry(
+        date: date,
+        widgetId: widgetId,
+        bundleReady: false,
+        errorMessage: "Bundle eval failed (see logs)",
+        configuration: configuration
+      )
+    }
+    return VoltraClientWidgetEntry(
+      date: date,
+      widgetId: widgetId,
+      bundleReady: true,
+      configuration: configuration,
+      bundleSource: source
+    )
+  }
+}
+
+// MARK: - Bundle source (dev vs prod)
+
+//
+// Dual-path bundle loader. Dev reads from Metro localhost; prod reads from a baked asset
+// in the .app bundle. The build-time bundle writer that produces the baked asset is a
+// future addition; until then prod throws a clear error.
+
+public enum VoltraClientWidgetBundleSource {
+  public enum LoadError: LocalizedError {
+    case metroHTTP(Int)
+    case nonUTF8
+    case bakedBundleNotFound(widgetId: String)
+
+    public var errorDescription: String? {
+      switch self {
+      case let .metroHTTP(code):
+        return "Metro HTTP \(code) — is the dev server running?"
+      case .nonUTF8:
+        return "Bundle response was not UTF-8 text"
+      case let .bakedBundleNotFound(id):
+        return "Production bundle missing for widgetId=\(id) (release path not yet implemented)"
+      }
+    }
+  }
+
+  public static func load(widgetId: String) async throws -> String {
+    #if DEBUG
+      return try await loadFromMetro(widgetId: widgetId)
+    #else
+      return try loadFromBakedAsset(widgetId: widgetId)
+    #endif
+  }
+
+  private static func loadFromMetro(widgetId: String) async throws -> String {
+    // Dev mode = always-refetch. URLSession default cache policy is fine —
+    // Metro's bundle responses are not cacheable, so each request hits the server.
+    //
+    // The base URL is relayed from the app via the app group (the app resolves it with
+    // RCTBundleURLProvider; this extension is React-free). Falls back to localhost:8081 when the
+    // app hasn't written it yet (e.g. first render before the host app has run).
+    let base = VoltraWidgetDefaults.devServerURL() ?? "http://localhost:8081"
+    let urlString = "\(base)/voltra/widgets/\(widgetId).bundle?platform=ios&dev=true"
+    guard let url = URL(string: urlString) else {
+      throw LoadError.metroHTTP(-1)
+    }
+    let (data, response) = try await URLSession.shared.data(from: url)
+    if let httpResponse = response as? HTTPURLResponse, !(200 ... 299).contains(httpResponse.statusCode) {
+      throw LoadError.metroHTTP(httpResponse.statusCode)
+    }
+    guard let text = String(data: data, encoding: .utf8) else {
+      throw LoadError.nonUTF8
+    }
+    return text
+  }
+
+  /// Release-path stub — currently always throws. The plan is to emit the baked bundle
+  /// at `expo prebuild` (config plugin step) into the extension target's resources, then
+  /// read it here with Bundle.main.url(forResource:withExtension:).
+  private static func loadFromBakedAsset(widgetId: String) throws -> String {
+    if let url = Bundle.main.url(forResource: "voltra-widget-\(widgetId)", withExtension: "bundle"),
+       let text = try? String(contentsOf: url, encoding: .utf8)
+    {
+      return text
+    }
+    throw LoadError.bakedBundleNotFound(widgetId: widgetId)
+  }
+}
+
+// MARK: - Env capture + JSON marshaling
+
+//
+// SwiftUI @Environment values are read inside the View body (see ContentView below) and
+// passed here as plain values. This helper emits a JSON string matching the
+// WidgetEnvironment type from packages/core/src/widget-environment.ts. We hand-roll the
+// JSON instead of going through JSONSerialization so the shape is locked to that type and
+// any drift produces a Swift compile error rather than a runtime parse failure.
+
+public enum VoltraClientWidgetEnvBuilder {
+  public static func build(
+    date: Date,
+    widgetFamily: WidgetFamily,
+    colorScheme: ColorScheme?,
+    widgetRenderingMode: WidgetRenderingMode,
+    showsWidgetContainerBackground: Bool,
+    locale: Locale,
+    configuration: [String: String]
+  ) -> String {
+    let timestampMs = Int(date.timeIntervalSince1970 * 1000)
+    let appVersion = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "unknown"
+
+    #if DEBUG
+      let isDev = true
+      let metroUrl: String? = VoltraWidgetDefaults.devServerURL() ?? "http://localhost:8081"
+    #else
+      let isDev = false
+      let metroUrl: String? = nil
+    #endif
+
+    let metroUrlLiteral = metroUrl.map(jsonString) ?? "null"
+    let buildJSON = """
+    {
+      "isDev": \(isDev),
+      "metroUrl": \(metroUrlLiteral),
+      "appVersion": \(jsonString(appVersion)),
+      "voltraVersion": \(jsonString("1.4.1"))
+    }
+    """
+
+    let configurationJSON: String
+    if configuration.isEmpty {
+      configurationJSON = "{}"
+    } else {
+      let entries = configuration
+        .map { "\(jsonString($0.key)): \(jsonString($0.value))" }
+        .joined(separator: ", ")
+      configurationJSON = "{ \(entries) }"
+    }
+
+    return """
+    {
+      "date": \(timestampMs),
+      "widgetFamily": \(jsonString(familyString(widgetFamily))),
+      "colorScheme": \(jsonString(schemeString(colorScheme))),
+      "locale": \(jsonString(locale.identifier)),
+      "widgetRenderingMode": \(jsonString(renderingModeString(widgetRenderingMode))),
+      "showsWidgetContainerBackground": \(showsWidgetContainerBackground),
+      "configuration": \(configurationJSON),
+      "build": \(buildJSON)
+    }
+    """
+  }
+
+  /// All three SwiftUI enums have String(describing:) representations that match their
+  /// case names exactly (e.g. "systemMedium", "fullColor", "dark"). Using String(describing:)
+  /// keeps these helpers forward-compatible when Apple adds new cases in a future SDK.
+  private static func familyString(_ family: WidgetFamily) -> String {
+    String(describing: family)
+  }
+
+  private static func renderingModeString(_ mode: WidgetRenderingMode) -> String {
+    String(describing: mode)
+  }
+
+  private static func schemeString(_ scheme: ColorScheme?) -> String {
+    guard let scheme else { return "light" }
+    return String(describing: scheme)
+  }
+
+  private static func jsonString(_ value: String) -> String {
+    let escaped = value
+      .replacingOccurrences(of: "\\", with: "\\\\")
+      .replacingOccurrences(of: "\"", with: "\\\"")
+      .replacingOccurrences(of: "\n", with: "\\n")
+      .replacingOccurrences(of: "\r", with: "\\r")
+    return "\"\(escaped)\""
+  }
+}
+
+// MARK: - Content view
+
+//
+// Per Q5 grilling: the resolved JSON is parsed into a VoltraNode and rendered via the
+// existing VoltraHomeWidgetView so client-rendered widgets are visually indistinguishable
+// from server-rendered ones at the UI layer.
+
+public struct VoltraClientWidgetContentView: View {
+  public let entry: VoltraClientWidgetEntry
+  public let initialState: Data?
+
+  @Environment(\.widgetFamily) private var widgetFamily
+  @Environment(\.colorScheme) private var colorScheme
+  @Environment(\.widgetRenderingMode) private var widgetRenderingMode
+  @Environment(\.showsWidgetContainerBackground) private var showsWidgetContainerBackground
+  @Environment(\.locale) private var locale
+
+  public init(entry: VoltraClientWidgetEntry, initialState: Data?) {
+    self.entry = entry
+    self.initialState = initialState
+  }
+
+  public var body: some View {
+    let homeEntry = makeHomeEntry()
+    return VoltraHomeWidgetView(entry: homeEntry)
+  }
+
+  private func makeHomeEntry() -> VoltraHomeWidgetEntry {
+    if entry.bundleReady {
+      // WidgetKit may render this archived entry in a fresh extension process where the provider's
+      // bundle evaluation didn't happen. Re-evaluate from the entry's carried source (no-op if this
+      // process already has it) so render() finds the widget's function.
+      if let source = entry.bundleSource {
+        _ = VoltraJSRenderer.ensureEvaluated(widgetId: entry.widgetId, source: source)
+      }
+      let envJSON = VoltraClientWidgetEnvBuilder.build(
+        date: entry.date,
+        widgetFamily: widgetFamily,
+        colorScheme: colorScheme,
+        widgetRenderingMode: widgetRenderingMode,
+        showsWidgetContainerBackground: showsWidgetContainerBackground,
+        locale: locale,
+        configuration: entry.configuration
+      )
+      if let resolved = VoltraJSRenderer.render(
+        widgetId: entry.widgetId,
+        propsJSON: "{}",
+        envJSON: envJSON
+      ), let node = parseResolvedNode(jsonString: resolved) {
+        return VoltraHomeWidgetEntry(date: entry.date, rootNode: node, widgetId: entry.widgetId)
+      }
+      // render() or VoltraNode.parse failed — fall through to the prerendered initial state
+      // so the widget still shows real UI instead of a blank tile.
+    }
+    let fallbackNode = initialState.flatMap(parseResolvedNode(jsonData:))
+    return VoltraHomeWidgetEntry(date: entry.date, rootNode: fallbackNode, widgetId: entry.widgetId)
+  }
+
+  private func parseResolvedNode(jsonString: String) -> VoltraNode? {
+    guard let json = try? JSONValue.parse(from: jsonString) else { return nil }
+    let node = VoltraNode.parse(from: json)
+    if case .empty = node { return nil }
+    return node
+  }
+
+  private func parseResolvedNode(jsonData: Data) -> VoltraNode? {
+    guard let text = String(data: jsonData, encoding: .utf8) else { return nil }
+    return parseResolvedNode(jsonString: text)
+  }
+}
diff --git a/packages/ios-client/package.json b/packages/ios-client/package.json
index 0a4816de..66d130b4 100644
--- a/packages/ios-client/package.json
+++ b/packages/ios-client/package.json
@@ -49,6 +49,7 @@
     "@babel/core": "^7.27.4",
     "@expo/config-plugins": "~10.1.2",
     "@expo/plist": "^0.3.5",
+    "@use-voltra/compiler": "workspace:^",
     "@use-voltra/expo-plugin": "workspace:^",
     "@use-voltra/ios": "workspace:^",
     "dedent": "^1.7.1",
diff --git a/packages/ios-client/src/index.ts b/packages/ios-client/src/index.ts
index 3f9e3d15..f53fb4f3 100644
--- a/packages/ios-client/src/index.ts
+++ b/packages/ios-client/src/index.ts
@@ -31,6 +31,7 @@ export {
   reloadLiveActivities,
 } from './preload.js'
 export { assertRunningOnApple } from './utils/assertRunningOnApple.js'
+export { enableWidgetHotReload } from './utils/enableWidgetHotReload.js'
 export { useUpdateOnHMR } from './utils/useUpdateOnHMR.js'
 export * from './utils/helpers.js'
 export type { VoltraElementJson, VoltraNodeJson } from './types.js'
diff --git a/packages/ios-client/src/utils/enableWidgetHotReload.ts b/packages/ios-client/src/utils/enableWidgetHotReload.ts
new file mode 100644
index 00000000..8d88ec29
--- /dev/null
+++ b/packages/ios-client/src/utils/enableWidgetHotReload.ts
@@ -0,0 +1,39 @@
+import { reloadWidgets } from '../widgets/widget-api.js'
+
+declare global {
+  var __accept: (...args: unknown[]) => void
+}
+
+/**
+ * Trigger `reloadWidgets()` on every Metro Fast Refresh patch (DEV only).
+ *
+ * Hooks the global `__accept` callback Metro fires when a Fast Refresh patch
+ * lands in the host app's JS runtime. When fired, calls
+ * `WidgetCenter.shared.reloadAllTimelines()` so WidgetKit re-invokes each widget
+ * Provider, which re-fetches the freshest bundle from Metro and renders the
+ * updated UI.
+ *
+ * Only effective while the host app's JS thread is alive — iOS suspends the
+ * RN runtime within ~5 seconds of backgrounding, so the "edit while staring at
+ * the home screen, never touch the host app" case is not covered. For that
+ * workflow the dev still relies on WidgetKit's natural lifecycle refresh on
+ * app foreground.
+ *
+ * Call once at app startup. Returns `dispose()` to restore the prior
+ * `__accept` (rarely needed in practice). No-op in release builds.
+ */
+export function enableWidgetHotReload(): () => void {
+  if (!__DEV__) {
+    return () => {}
+  }
+
+  const oldAccept = global['__accept']
+  global['__accept'] = (...args) => {
+    void reloadWidgets()
+    oldAccept?.(...args)
+  }
+
+  return () => {
+    global['__accept'] = oldAccept
+  }
+}
diff --git a/packages/ios/src/index.ts b/packages/ios/src/index.ts
index 8266b377..f296104f 100644
--- a/packages/ios/src/index.ts
+++ b/packages/ios/src/index.ts
@@ -32,3 +32,5 @@ export type {
 } from './types.js'
 export { renderWidgetToJson, renderWidgetToString } from './widgets/renderer.js'
 export type { ScheduledWidgetEntry, WidgetFamily, WidgetInfo, WidgetVariants } from './widgets/types.js'
+export { isAndroidEnv, isIosEnv } from '@use-voltra/core'
+export type { WidgetBuildEnvironment, WidgetEnvironment } from '@use-voltra/core'
diff --git a/packages/metro/README.md b/packages/metro/README.md
new file mode 100644
index 00000000..3b0406e2
--- /dev/null
+++ b/packages/metro/README.md
@@ -0,0 +1,86 @@
+![voltra-banner](https://use-voltra.dev/voltra-baner.jpg)
+
+### Metro integration for Voltra Dynamic Widgets
+
+[![mit licence][license-badge]][license] [![npm downloads][npm-downloads-badge]][npm-downloads] [![PRs Welcome][prs-welcome-badge]][prs-welcome]
+
+`@use-voltra/metro` helps Voltra Dynamic Widgets work in Metro-based React Native apps.
+
+## Features
+
+- **Metro config transformer**: Wrap your app's Metro config with `withVoltra()` to enable Voltra's widget pipeline.
+
+- **Widget registry**: Work with widgets declared in app.json and keep the widget pipeline organized per platform.
+
+- **Project-aware module resolution**: Resolve app dependencies from the consuming project's install layout, including pnpm setups.
+
+## Documentation
+
+This package supports the Dynamic Widgets workflow in Voltra. Relevant topics:
+
+- [Getting Started](https://use-voltra.dev/getting-started/installation)
+- [iOS Dynamic Widgets](https://use-voltra.dev/ios/development/dynamic-widgets)
+- [Android Dynamic Widgets](https://use-voltra.dev/android/development/dynamic-widgets)
+- [iOS API Reference](https://use-voltra.dev/ios/api/configuration)
+- [Android API Reference](https://use-voltra.dev/android/api/plugin-configuration)
+
+## Getting started
+
+`@use-voltra/metro` is usually consumed through `@use-voltra/ios-client` or `@use-voltra/android-client`, but you can install it directly if you need to customize Metro yourself.
+
+```sh
+npm install @use-voltra/metro
+```
+
+Wrap your Metro config with `withVoltra`:
+
+```ts
+import { withVoltra } from '@use-voltra/metro'
+
+export default withVoltra({
+  projectRoot: __dirname,
+  resolver: {
+    sourceExts: ['ts', 'tsx', 'js', 'jsx'],
+  },
+})
+```
+
+Declare Dynamic Widgets in app.json with a stable `id` and an explicit `entry` path, then default-export the widget module.
+
+## Quick example
+
+```ts
+import { bundleWidgets, createWidgetRegistry } from '@use-voltra/metro'
+
+const registry = createWidgetRegistry({ projectRoot: process.cwd() })
+console.log(registry.listWidgets('ios'))
+registry.close()
+
+await bundleWidgets({
+  projectRoot: process.cwd(),
+  outDir: './dist/widgets',
+  platform: 'ios',
+})
+```
+
+## Platform compatibility
+
+This package works with Metro-based React Native apps on **iOS** and **Android** when you are using Voltra Dynamic Widgets.
+
+## Authors
+
+Voltra is an open source collaboration between [Saúl Sharma](https://github.com/saulsharma) and [Szymon Chmal](https://github.com/szymonchmal) at [Callstack][callstack-readme-with-love].
+
+If you think it's cool, please star it 🌟. This project will always remain free to use.
+
+[Callstack][callstack-readme-with-love] is a group of React and React Native geeks, contact us at [hello@callstack.com](mailto:hello@callstack.com) if you need any help with these or just want to say hi!
+
+Like the project? ⚛️ [Join the Callstack team](https://callstack.com/careers/?utm_campaign=Senior_RN&utm_source=github&utm_medium=readme) who does amazing stuff for clients and drives React Native Open Source! 🔥
+
+[callstack-readme-with-love]: https://callstack.com/?utm_source=github.com&utm_medium=referral&utm_campaign=voltra&utm_term=readme-with-love
+[license-badge]: https://img.shields.io/npm/l/@use-voltra/metro?style=for-the-badge
+[license]: https://github.com/callstackincubator/voltra/blob/main/LICENSE.txt
+[npm-downloads-badge]: https://img.shields.io/npm/dm/@use-voltra/metro?style=for-the-badge
+[npm-downloads]: https://www.npmjs.com/package/@use-voltra/metro
+[prs-welcome-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge
+[prs-welcome]: ../../CONTRIBUTING.md
diff --git a/packages/metro/package.json b/packages/metro/package.json
new file mode 100644
index 00000000..936605ef
--- /dev/null
+++ b/packages/metro/package.json
@@ -0,0 +1,84 @@
+{
+  "name": "@use-voltra/metro",
+  "version": "1.4.1",
+  "description": "Metro integration for Voltra client-rendered widgets",
+  "main": "build/cjs/index.js",
+  "module": "build/esm/index.js",
+  "types": "build/types/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "scanner": [
+        "build/types/scanner.d.ts"
+      ],
+      "bundle-widgets": [
+        "build/types/bin/bundle-widgets.d.ts"
+      ],
+      "*": [
+        "build/types/*"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./build/types/index.d.ts",
+      "require": "./build/cjs/index.js",
+      "import": "./build/esm/index.js",
+      "default": "./build/esm/index.js"
+    },
+    "./scanner": {
+      "types": "./build/types/scanner.d.ts",
+      "require": "./build/cjs/scanner.js",
+      "import": "./build/esm/scanner.js",
+      "default": "./build/esm/scanner.js"
+    },
+    "./bundle-widgets": {
+      "types": "./build/types/bin/bundle-widgets.d.ts",
+      "require": "./build/cjs/bin/bundle-widgets.js",
+      "import": "./build/esm/bin/bundle-widgets.js",
+      "default": "./build/cjs/bin/bundle-widgets.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "bundle-widgets": "./build/cjs/bin/bundle-widgets.js"
+  },
+  "files": [
+    "build",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs packages/metro",
+    "clean": "rm -rf build",
+    "lint": "oxlint src",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
+    "test": "node --import tsx --test"
+  },
+  "dependencies": {
+    "@use-voltra/expo-plugin": "workspace:^",
+    "@use-voltra/compiler": "workspace:^",
+    "metro-config-transformers": "^1.0.0"
+  },
+  "peerDependencies": {
+    "expo": "*",
+    "metro": "*",
+    "react": "*",
+    "react-native": "*"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "metro",
+    "voltra"
+  ],
+  "author": "Saúl Sharma (https://x.com/saul_sharma), Szymon Chmal (https://x.com/chmalszymon)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/callstackincubator/voltra.git",
+    "directory": "packages/metro"
+  },
+  "bugs": {
+    "url": "https://github.com/callstackincubator/voltra/issues"
+  },
+  "license": "MIT",
+  "homepage": "https://use-voltra.dev"
+}
diff --git a/packages/metro/src/bin/bundle-widgets.ts b/packages/metro/src/bin/bundle-widgets.ts
new file mode 100644
index 00000000..22f7814f
--- /dev/null
+++ b/packages/metro/src/bin/bundle-widgets.ts
@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { runBundleWidgetsCli } from '../bundleWidgets'
+
+runBundleWidgetsCli()
+  .then(() => {
+    process.exit(0)
+  })
+  .catch((error) => {
+    console.error(
+      `[voltra] widget bundling failed: ${error instanceof Error ? error.stack || error.message : String(error)}`
+    )
+    process.exit(1)
+  })
diff --git a/packages/metro/src/bundleWidgets.ts b/packages/metro/src/bundleWidgets.ts
new file mode 100644
index 00000000..451660ca
--- /dev/null
+++ b/packages/metro/src/bundleWidgets.ts
@@ -0,0 +1,107 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+import type { DynamicWidgetPlatform } from '@use-voltra/expo-plugin'
+
+import { createWidgetMetroConfig } from './createWidgetMetroConfig'
+import { requireProjectModule } from './resolveProjectModule'
+import { createWidgetRegistry } from './widgetRegistry'
+
+export type BundleWidgetsOptions = {
+  projectRoot: string
+  outDir: string
+  platform: DynamicWidgetPlatform
+}
+
+type ParsedArgs = {
+  outDir: string | null
+  platform: DynamicWidgetPlatform
+  projectRoot: string
+}
+
+function parsePlatform(value: string | undefined): DynamicWidgetPlatform {
+  if (value === 'ios' || value === 'android') {
+    return value
+  }
+
+  throw new Error(`Invalid platform '${value}'. Expected 'ios' or 'android'.`)
+}
+
+export function parseBundleWidgetsArgs(argv: string[]): ParsedArgs {
+  const args: ParsedArgs = { outDir: null, platform: 'ios', projectRoot: process.cwd() }
+  for (let i = 2; i < argv.length; i += 1) {
+    const value = argv[i + 1]
+    switch (argv[i]) {
+      case '--out-dir':
+        args.outDir = value
+        i += 1
+        break
+      case '--platform':
+        args.platform = parsePlatform(value)
+        i += 1
+        break
+      case '--project-root':
+        args.projectRoot = path.resolve(value)
+        i += 1
+        break
+      default:
+        break
+    }
+  }
+  return args
+}
+
+async function loadAppMetroConfig(projectRoot: string): Promise<any> {
+  const { loadConfig } = requireProjectModule<{ loadConfig(argv?: any): Promise<any> }>('metro-config', projectRoot)
+  return loadConfig({ cwd: projectRoot })
+}
+
+export async function bundleWidgets({ projectRoot, outDir, platform }: BundleWidgetsOptions): Promise<void> {
+  if (!outDir) {
+    throw new Error('bundleWidgets: --out-dir is required')
+  }
+
+  const Metro = requireProjectModule<{ runBuild(config: any, options: any): Promise<{ code: string }> }>(
+    'metro',
+    projectRoot
+  )
+  const appConfig = await loadAppMetroConfig(projectRoot)
+  const widgetConfig = await createWidgetMetroConfig({ projectRoot, appConfig })
+  const registry = createWidgetRegistry({ projectRoot })
+
+  try {
+    const widgets = registry.listWidgets(platform)
+
+    if (widgets.length === 0) {
+      console.log(`[voltra] no client-rendered widgets to bundle for platform "${platform}"`)
+      return
+    }
+
+    fs.mkdirSync(outDir, { recursive: true })
+
+    for (const widget of widgets) {
+      const entry = path.resolve(projectRoot, widget.generatedEntryRelativePath)
+      const { code } = await Metro.runBuild(widgetConfig, {
+        entry,
+        platform,
+        dev: false,
+        minify: true,
+      })
+
+      const outPath = path.join(outDir, `voltra-widget-${widget.id}.bundle`)
+      fs.writeFileSync(outPath, code)
+      console.log(`[voltra] baked ${path.basename(outPath)} (${code.length} bytes)`)
+    }
+  } finally {
+    registry.close()
+  }
+}
+
+export async function runBundleWidgetsCli(argv = process.argv): Promise<void> {
+  const args = parseBundleWidgetsArgs(argv)
+  await bundleWidgets({
+    projectRoot: args.projectRoot,
+    outDir: args.outDir ?? '',
+    platform: args.platform,
+  })
+}
diff --git a/packages/metro/src/createVoltraMiddleware.ts b/packages/metro/src/createVoltraMiddleware.ts
new file mode 100644
index 00000000..1187ff21
--- /dev/null
+++ b/packages/metro/src/createVoltraMiddleware.ts
@@ -0,0 +1,100 @@
+import type { WidgetRegistry } from './widgetRegistry'
+
+type Middleware = (req: any, res: any, next: () => void) => void
+
+function parsePlatform(value: string | null): 'ios' | 'android' | null {
+  if (value === 'ios' || value === 'android') {
+    return value
+  }
+
+  return null
+}
+
+function sendJson(res: any, status: number, value: unknown): void {
+  res.writeHead(status, {
+    'Content-Type': 'application/json; charset=utf-8',
+  })
+  res.end(JSON.stringify(value, null, 2))
+}
+
+function createBundleRequest(
+  widget: { generatedEntryRelativePath: string; platform: 'ios' | 'android' },
+  originalSearchParams: URLSearchParams
+): string {
+  const query = new URLSearchParams(originalSearchParams)
+  query.set('bundleEntry', widget.generatedEntryRelativePath)
+  query.set('platform', widget.platform)
+
+  return `/voltra-widget.bundle?${query.toString()}`
+}
+
+export function createVoltraMiddleware({
+  registry,
+  widgetMetro,
+}: {
+  registry: WidgetRegistry
+  widgetMetro: { middleware: Middleware }
+}): Middleware {
+  return (req, res, next) => {
+    const requestUrl = new URL(req.url, 'http://localhost')
+    const pathname = requestUrl.pathname || '/'
+    const requestedPlatform = parsePlatform(requestUrl.searchParams.get('platform'))
+    const hasPlatformParam = requestUrl.searchParams.has('platform')
+
+    if (hasPlatformParam && !requestedPlatform) {
+      sendJson(res, 400, {
+        error: 'Missing or invalid platform query parameter. Expected "ios" or "android".',
+      })
+      return
+    }
+
+    if (pathname === '/' || pathname === '/widgets') {
+      try {
+        sendJson(res, 200, {
+          ready: registry.isReady(),
+          platform: requestedPlatform,
+          widgets: registry.listWidgets(requestedPlatform ?? undefined),
+        })
+      } catch (error) {
+        sendJson(res, 500, {
+          error: error instanceof Error ? error.message : String(error),
+        })
+      }
+      return
+    }
+
+    const widgetBundleMatch = pathname.match(/^\/widgets\/([^/]+)\.bundle$/)
+    if (widgetBundleMatch) {
+      const widgetId = decodeURIComponent(widgetBundleMatch[1])
+      if (!requestedPlatform) {
+        sendJson(res, 400, {
+          error: 'Missing or invalid platform query parameter. Expected "ios" or "android".',
+        })
+        return
+      }
+
+      try {
+        const widget = registry.getWidget(requestedPlatform, widgetId)
+
+        if (!widget) {
+          sendJson(res, 404, {
+            error: `Unknown Voltra widget "${widgetId}" for platform "${requestedPlatform}".`,
+          })
+          return
+        }
+
+        req.url = createBundleRequest(widget, requestUrl.searchParams)
+        widgetMetro.middleware(req, res, next)
+        return
+      } catch (error) {
+        sendJson(res, 500, {
+          error: error instanceof Error ? error.message : String(error),
+        })
+      }
+    }
+
+    sendJson(res, 404, {
+      error: `Unknown Voltra endpoint "${pathname}".`,
+    })
+  }
+}
diff --git a/packages/metro/src/createWidgetMetroConfig.ts b/packages/metro/src/createWidgetMetroConfig.ts
new file mode 100644
index 00000000..bc6654ea
--- /dev/null
+++ b/packages/metro/src/createWidgetMetroConfig.ts
@@ -0,0 +1,82 @@
+import path from 'node:path'
+
+import { requireProjectModule, resolveProjectModulePath } from './resolveProjectModule'
+
+const blockedModules = new Set(['react-native'])
+
+function unique<T>(items: Array<T | null | undefined>): T[] {
+  return Array.from(new Set(items.filter((item): item is T => item !== null && item !== undefined)))
+}
+
+function resolvePnpmTransitive(name: string, projectRoot: string): string | null {
+  try {
+    return path.dirname(resolveProjectModulePath(`${name}/package.json`, projectRoot))
+  } catch {
+    return null
+  }
+}
+
+export async function createWidgetMetroConfig({
+  projectRoot,
+  appConfig,
+}: {
+  projectRoot: string
+  appConfig: any
+}): Promise<any> {
+  const appNodeModules = path.join(projectRoot, 'node_modules')
+  const { getDefaultConfig } = requireProjectModule<{ getDefaultConfig(rootPath: string): Promise<any> }>(
+    'metro-config',
+    projectRoot
+  )
+  const config = await getDefaultConfig(projectRoot)
+  const sourceExts = unique([...(config.resolver?.sourceExts ?? []), ...(appConfig.resolver?.sourceExts ?? [])])
+  const pnpmTransitives = {
+    '@babel/runtime': resolvePnpmTransitive('@babel/runtime', projectRoot),
+    'metro-runtime': resolvePnpmTransitive('metro-runtime', projectRoot),
+  }
+  const pnpmTransitiveModules = Object.fromEntries(
+    Object.entries(pnpmTransitives).filter((entry): entry is [string, string] => entry[1] !== null)
+  )
+
+  return {
+    ...config,
+    projectRoot,
+    watchFolders: unique([...(config.watchFolders ?? []), ...(appConfig.watchFolders ?? [])]),
+    resolver: {
+      ...config.resolver,
+      sourceExts,
+      extraNodeModules: {
+        ...config.resolver?.extraNodeModules,
+        ...appConfig.resolver?.extraNodeModules,
+        ...pnpmTransitiveModules,
+        react: path.join(appNodeModules, 'react'),
+      },
+      nodeModulesPaths: unique([
+        appNodeModules,
+        ...(config.resolver?.nodeModulesPaths ?? []),
+        ...(appConfig.resolver?.nodeModulesPaths ?? []),
+      ]),
+      resolveRequest(context: any, moduleName: string, platform: string | null) {
+        if (blockedModules.has(moduleName) || moduleName.startsWith('react-native/')) {
+          throw new Error(`Voltra widget bundles cannot import "${moduleName}"`)
+        }
+
+        return context.resolveRequest(context, moduleName, platform)
+      },
+    },
+    serializer: {
+      ...config.serializer,
+      getModulesRunBeforeMainModule: () => [],
+      getPolyfills: () => [],
+      polyfillModuleNames: [],
+    },
+    transformer: {
+      ...config.transformer,
+      babelTransformerPath: appConfig.transformer?.babelTransformerPath,
+    },
+    server: {
+      ...config.server,
+      enhanceMiddleware: (middleware: unknown) => middleware,
+    },
+  }
+}
diff --git a/packages/metro/src/index.ts b/packages/metro/src/index.ts
new file mode 100644
index 00000000..01d243f6
--- /dev/null
+++ b/packages/metro/src/index.ts
@@ -0,0 +1,98 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { createMetroConfigTransformer } from 'metro-config-transformers'
+
+import { bundleWidgets } from './bundleWidgets'
+import { createVoltraMiddleware } from './createVoltraMiddleware'
+import { createWidgetMetroConfig } from './createWidgetMetroConfig'
+import { requireProjectModule } from './resolveProjectModule'
+import { createWidgetRegistry, ensureEmptyDevBarrel } from './widgetRegistry'
+
+const HOT_RELOAD_ALIAS = '@use-voltra/widget-hot-reload'
+const DEV_BARREL_PLATFORMS = new Set(['ios', 'android'])
+
+type ResolveRequest = (context: any, moduleName: string, platform: string | null) => unknown
+
+function resolveHotReloadAlias(projectRoot: string, context: any, platform: string | null): unknown {
+  if (!context.dev) {
+    return { type: 'empty' }
+  }
+
+  if (!platform || !DEV_BARREL_PLATFORMS.has(platform)) {
+    return { type: 'sourceFile', filePath: ensureEmptyDevBarrel(projectRoot) }
+  }
+
+  const platformBarrel = path.join(projectRoot, '.voltra', 'metro', `widget-hot-reload.${platform}.js`)
+  if (!fs.existsSync(platformBarrel)) {
+    return { type: 'sourceFile', filePath: ensureEmptyDevBarrel(projectRoot) }
+  }
+
+  return { type: 'sourceFile', filePath: platformBarrel }
+}
+
+function createResolveRequest(
+  projectRoot: string,
+  previousResolveRequest: ResolveRequest | null | undefined
+): ResolveRequest {
+  return (context, moduleName, platform) => {
+    if (moduleName === HOT_RELOAD_ALIAS) {
+      return resolveHotReloadAlias(projectRoot, context, platform)
+    }
+
+    if (previousResolveRequest) {
+      return previousResolveRequest(context, moduleName, platform)
+    }
+
+    return context.resolveRequest(context, moduleName, platform)
+  }
+}
+
+export const withVoltra = createMetroConfigTransformer(async (metroConfig: any) => {
+  const projectRoot = metroConfig.projectRoot ?? process.cwd()
+  const registry = createWidgetRegistry({ projectRoot })
+  const widgetConfig = await createWidgetMetroConfig({
+    projectRoot,
+    appConfig: metroConfig,
+  })
+  const Metro = requireProjectModule<{ createConnectMiddleware(config: any, options?: any): Promise<any> }>(
+    'metro',
+    projectRoot
+  )
+  const connect = requireProjectModule<() => { use(pathOrMiddleware: string | unknown, middleware?: unknown): any }>(
+    'connect',
+    projectRoot
+  )
+  const widgetMetro = await Metro.createConnectMiddleware(widgetConfig, {
+    port: metroConfig.server?.port,
+  })
+  const voltraMiddleware = createVoltraMiddleware({
+    registry,
+    widgetMetro,
+  })
+
+  const previousEnhanceMiddleware = metroConfig.server?.enhanceMiddleware || ((middleware: unknown) => middleware)
+  const previousResolveRequest = metroConfig.resolver?.resolveRequest
+
+  return {
+    ...metroConfig,
+    projectRoot,
+    resolver: {
+      ...metroConfig.resolver,
+      resolveRequest: createResolveRequest(projectRoot, previousResolveRequest),
+    },
+    server: {
+      ...metroConfig.server,
+      enhanceMiddleware(metroMiddleware: unknown, metroServer: unknown) {
+        const enhancedAppMetroMiddleware = previousEnhanceMiddleware(metroMiddleware, metroServer)
+
+        return connect().use('/voltra', voltraMiddleware).use(enhancedAppMetroMiddleware)
+      },
+    },
+  }
+})
+
+export { bundleWidgets, createVoltraMiddleware, createWidgetMetroConfig, createWidgetRegistry }
+export { requireProjectModule, resolveProjectModulePath } from './resolveProjectModule'
+export { scanVoltraDirectives, type VoltraDirectiveWidget } from './scanner'
+export { DuplicateVoltraWidgetError, type RegisteredVoltraWidget, type WidgetRegistry } from './widgetRegistry'
diff --git a/packages/metro/src/resolveProjectModule.ts b/packages/metro/src/resolveProjectModule.ts
new file mode 100644
index 00000000..9a2295d0
--- /dev/null
+++ b/packages/metro/src/resolveProjectModule.ts
@@ -0,0 +1,29 @@
+import { createRequire } from 'node:module'
+import path from 'node:path'
+
+function createProjectRequire(projectRoot: string): NodeRequire {
+  return createRequire(path.join(projectRoot, 'package.json'))
+}
+
+function createExpoMetroRequire(projectRoot: string): NodeRequire {
+  const requireFromProject = createProjectRequire(projectRoot)
+  return createRequire(requireFromProject.resolve('expo/metro-config'))
+}
+
+export function requireProjectModule<T = unknown>(moduleName: string, projectRoot = process.cwd()): T {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return require(moduleName) as T
+  } catch {
+    return createExpoMetroRequire(projectRoot)(moduleName) as T
+  }
+}
+
+export function resolveProjectModulePath(moduleName: string, projectRoot = process.cwd()): string {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return require.resolve(moduleName)
+  } catch {
+    return createExpoMetroRequire(projectRoot).resolve(moduleName)
+  }
+}
diff --git a/packages/metro/src/scanner.ts b/packages/metro/src/scanner.ts
new file mode 100644
index 00000000..4dab287c
--- /dev/null
+++ b/packages/metro/src/scanner.ts
@@ -0,0 +1,2 @@
+export { scanVoltraDirectives } from '@use-voltra/compiler'
+export type { VoltraDirectiveWidget } from '@use-voltra/compiler'
diff --git a/packages/metro/src/widgetRegistry.node.test.ts b/packages/metro/src/widgetRegistry.node.test.ts
new file mode 100644
index 00000000..cf8218cd
--- /dev/null
+++ b/packages/metro/src/widgetRegistry.node.test.ts
@@ -0,0 +1,315 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import Module from 'node:module'
+import { fileURLToPath } from 'node:url'
+import { afterEach, describe, mock, test } from 'node:test'
+
+import { bundleWidgets } from './bundleWidgets.ts'
+import { createVoltraMiddleware } from './createVoltraMiddleware.ts'
+import { createWidgetRegistry } from './widgetRegistry.ts'
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..')
+
+type TempProject = {
+  projectRoot: string
+  cleanup: () => void
+}
+
+function writeFile(filePath: string, contents: string): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, contents)
+}
+
+function makeTempProject(files: Record<string, string>): TempProject {
+  const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'voltra-metro-manifest-'))
+  fs.symlinkSync(path.join(repoRoot, 'node_modules'), path.join(projectRoot, 'node_modules'), 'dir')
+  writeFile(
+    path.join(projectRoot, 'package.json'),
+    JSON.stringify({ name: 'voltra-metro-test-project', private: true }, null, 2)
+  )
+
+  for (const [relativePath, contents] of Object.entries(files)) {
+    writeFile(path.join(projectRoot, relativePath), contents)
+  }
+
+  return {
+    projectRoot,
+    cleanup: () => fs.rmSync(projectRoot, { recursive: true, force: true }),
+  }
+}
+
+function toPosix(value: string): string {
+  return value.split(path.sep).join('/')
+}
+
+describe('@use-voltra/metro manifest registry', () => {
+  const cleanups: Array<() => void> = []
+
+  afterEach(() => {
+    while (cleanups.length > 0) {
+      cleanups.pop()?.()
+    }
+    mock.restoreAll()
+  })
+
+  test('loads platform manifests independently and generates default-export adapters', () => {
+    const { projectRoot, cleanup } = makeTempProject({
+      '.voltra/manifest.ios.json': JSON.stringify(
+        {
+          version: 1,
+          platform: 'ios',
+          widgets: [{ id: 'home', entry: 'widgets/ios-home.js' }],
+        },
+        null,
+        2
+      ),
+      '.voltra/manifest.android.json': JSON.stringify(
+        {
+          version: 1,
+          platform: 'android',
+          widgets: [{ id: 'home', entry: 'widgets/android-home.js' }],
+        },
+        null,
+        2
+      ),
+      'widgets/ios-home.js': 'export default function IosHomeWidget() { return null }\n',
+      'widgets/android-home.js': 'export default function AndroidHomeWidget() { return null }\n',
+    })
+    cleanups.push(cleanup)
+
+    const registry = createWidgetRegistry({ projectRoot })
+
+    try {
+      const iosWidget = registry.getWidget('ios', 'home')
+      const androidWidget = registry.getWidget('android', 'home')
+
+      assert.ok(iosWidget)
+      assert.ok(androidWidget)
+      assert.equal(iosWidget?.platform, 'ios')
+      assert.equal(androidWidget?.platform, 'android')
+      assert.notEqual(iosWidget?.generatedEntryPath, androidWidget?.generatedEntryPath)
+      assert.ok(path.basename(iosWidget!.generatedEntryPath).startsWith('ios-home-'))
+      assert.ok(path.basename(androidWidget!.generatedEntryPath).startsWith('android-home-'))
+      assert.deepEqual(
+        registry.listWidgets('ios').map((widget) => widget.id),
+        ['home']
+      )
+      assert.deepEqual(
+        registry
+          .listWidgets()
+          .map((widget) => `${widget.platform}:${widget.id}`)
+          .sort(),
+        ['android:home', 'ios:home']
+      )
+
+      const iosGenerated = fs.readFileSync(iosWidget!.generatedEntryPath, 'utf8')
+      const iosEntryImport = toPosix(
+        path.relative(path.dirname(iosWidget!.generatedEntryPath), path.join(projectRoot, iosWidget!.entry))
+      )
+      assert.ok(iosGenerated.includes(`import Widget from ${JSON.stringify(iosEntryImport)}`))
+      assert.ok(!iosGenerated.includes('import * as WidgetModule'))
+      assert.ok(!iosGenerated.includes('export { Widget }'))
+      assert.match(iosGenerated, /export function render\(propsJSON, envJSON\)/)
+
+      const iosBarrel = fs.readFileSync(path.join(projectRoot, '.voltra', 'metro', 'widget-hot-reload.ios.js'), 'utf8')
+      const iosBarrelImport = `./${toPosix(
+        path.relative(path.join(projectRoot, '.voltra', 'metro'), iosWidget!.generatedEntryPath)
+      )}`
+      assert.ok(iosBarrel.includes(`import ${JSON.stringify(iosBarrelImport)}`))
+      assert.ok(iosBarrel.includes('manifest-declared Voltra widgets'))
+    } finally {
+      registry.close()
+    }
+  })
+
+  test('surfaces a missing platform manifest when a widget is requested', () => {
+    const { projectRoot, cleanup } = makeTempProject({
+      '.voltra/manifest.ios.json': JSON.stringify(
+        {
+          version: 1,
+          platform: 'ios',
+          widgets: [{ id: 'home', entry: 'widgets/home.js' }],
+        },
+        null,
+        2
+      ),
+      'widgets/home.js': 'export default function HomeWidget() { return null }\n',
+    })
+    cleanups.push(cleanup)
+
+    const registry = createWidgetRegistry({ projectRoot })
+
+    try {
+      assert.throws(
+        () => registry.getWidget('android', 'home'),
+        /Missing Voltra dynamic widgets manifest for android at \.voltra\/manifest\.android\.json\. Run Expo prebuild for android to generate it\./
+      )
+    } finally {
+      registry.close()
+    }
+  })
+})
+
+describe('@use-voltra/metro middleware and bundling', () => {
+  const cleanups: Array<() => void> = []
+
+  afterEach(() => {
+    while (cleanups.length > 0) {
+      cleanups.pop()?.()
+    }
+    mock.restoreAll()
+  })
+
+  test('routes bundle requests by platform and widget id', () => {
+    const { projectRoot, cleanup } = makeTempProject({
+      '.voltra/manifest.ios.json': JSON.stringify(
+        {
+          version: 1,
+          platform: 'ios',
+          widgets: [{ id: 'home', entry: 'widgets/ios-home.js' }],
+        },
+        null,
+        2
+      ),
+      '.voltra/manifest.android.json': JSON.stringify(
+        {
+          version: 1,
+          platform: 'android',
+          widgets: [{ id: 'home', entry: 'widgets/android-home.js' }],
+        },
+        null,
+        2
+      ),
+      'widgets/ios-home.js': 'export default function IosHomeWidget() { return null }\n',
+      'widgets/android-home.js': 'export default function AndroidHomeWidget() { return null }\n',
+    })
+    cleanups.push(cleanup)
+
+    const registry = createWidgetRegistry({ projectRoot })
+    const calls: string[] = []
+    const middleware = createVoltraMiddleware({
+      registry,
+      widgetMetro: {
+        middleware(req: { url: string }, _res: unknown, _next: () => void) {
+          calls.push(req.url)
+        },
+      },
+    })
+
+    const response = {
+      status: 0,
+      body: '',
+      writeHead(status: number) {
+        this.status = status
+      },
+      end(chunk: string) {
+        this.body = chunk
+      },
+    }
+
+    try {
+      middleware({ url: '/widgets/home.bundle?platform=android&dev=true' }, response, () => {
+        throw new Error('next() should not be called for a matched widget bundle')
+      })
+
+      assert.equal(calls.length, 1)
+      assert.ok(calls[0].startsWith('/voltra-widget.bundle?'))
+      assert.match(calls[0], /platform=android/)
+      assert.match(calls[0], /bundleEntry=.*android-home/)
+      assert.equal(response.status, 0)
+      assert.equal(response.body, '')
+    } finally {
+      registry.close()
+    }
+  })
+
+  test('bakes no bundles for an empty manifest', async () => {
+    const { projectRoot, cleanup } = makeTempProject({
+      '.voltra/manifest.ios.json': JSON.stringify(
+        {
+          version: 1,
+          platform: 'ios',
+          widgets: [],
+        },
+        null,
+        2
+      ),
+      '.voltra/manifest.android.json': JSON.stringify(
+        {
+          version: 1,
+          platform: 'android',
+          widgets: [],
+        },
+        null,
+        2
+      ),
+    })
+    cleanups.push(cleanup)
+
+    const outDir = path.join(projectRoot, 'dist', 'widgets')
+    await bundleWidgets({
+      projectRoot,
+      outDir,
+      platform: 'ios',
+    })
+
+    assert.equal(fs.existsSync(outDir), false)
+  })
+
+  test('keeps release bundle filenames aligned with native loaders', async () => {
+    const { projectRoot, cleanup } = makeTempProject({
+      '.voltra/manifest.ios.json': JSON.stringify(
+        {
+          version: 1,
+          platform: 'ios',
+          widgets: [{ id: 'home', entry: 'widgets/home.js' }],
+        },
+        null,
+        2
+      ),
+      'widgets/home.js': 'export default function HomeWidget() { return null }\n',
+    })
+    cleanups.push(cleanup)
+
+    const originalLoad = (Module as any)._load
+    mock.method(Module as any, '_load', function (request: string, parent: unknown, isMain: boolean) {
+      if (request === 'metro') {
+        return {
+          runBuild: async () => ({ code: 'bundle' }),
+        }
+      }
+
+      if (request === 'metro-config') {
+        return {
+          loadConfig: async () => ({
+            resolver: { sourceExts: [] },
+            watchFolders: [],
+            serializer: {},
+            transformer: {},
+            server: {},
+          }),
+          getDefaultConfig: async () => ({
+            resolver: { sourceExts: [] },
+            watchFolders: [],
+            serializer: {},
+            transformer: {},
+            server: {},
+          }),
+        }
+      }
+
+      return originalLoad.call(this, request, parent, isMain)
+    })
+
+    const outDir = path.join(projectRoot, 'dist', 'widgets')
+    await bundleWidgets({
+      projectRoot,
+      outDir,
+      platform: 'ios',
+    })
+
+    assert.deepEqual(fs.readdirSync(outDir), ['voltra-widget-home.bundle'])
+  })
+})
diff --git a/packages/metro/src/widgetRegistry.ts b/packages/metro/src/widgetRegistry.ts
new file mode 100644
index 00000000..0897f182
--- /dev/null
+++ b/packages/metro/src/widgetRegistry.ts
@@ -0,0 +1,558 @@
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+
+import {
+  type DynamicWidgetManifest,
+  type DynamicWidgetManifestWidget,
+  type DynamicWidgetPlatform,
+  validateHomeScreenWidgetId,
+  validateWidgetEntry,
+} from '@use-voltra/expo-plugin'
+
+const MANIFEST_PLATFORMS = ['ios', 'android'] as const
+const DEV_BARREL_PLATFORMS = MANIFEST_PLATFORMS
+
+const RENDER_SHIM_BASENAME = 'voltra-render-shim'
+const RENDER_SHIM_FILES: Record<string, string> = {
+  [`${RENDER_SHIM_BASENAME}.ios.js`]:
+    "export { renderVoltraVariantToJson as renderVariantToJson } from '@use-voltra/ios'\n",
+  [`${RENDER_SHIM_BASENAME}.android.js`]:
+    "export { renderAndroidVariantToJson as renderVariantToJson } from '@use-voltra/android'\n",
+}
+
+type FileWatcher = {
+  on(event: string, callback: (filePath: string) => void): void
+  close(): void
+}
+
+type PlatformState = {
+  error: Error | null
+  widgetsById: Map<string, RegisteredVoltraWidget>
+  widgets: RegisteredVoltraWidget[]
+}
+
+export type RegisteredVoltraWidget = DynamicWidgetManifestWidget & {
+  platform: DynamicWidgetPlatform
+  manifestPath: string
+  generatedEntryPath: string
+  generatedEntryRelativePath: string
+}
+
+export type WidgetRegistry = {
+  projectRoot: string
+  getWidget(platform: DynamicWidgetPlatform, widgetId: string): RegisteredVoltraWidget | null
+  isReady(): boolean
+  listWidgets(platform?: DynamicWidgetPlatform): RegisteredVoltraWidget[]
+  close(): void
+}
+
+function toPosixPath(value: string): string {
+  return value.split(path.sep).join('/')
+}
+
+function ensureDirectory(directory: string): void {
+  fs.mkdirSync(directory, { recursive: true })
+}
+
+function writeFileIfChanged(filePath: string, content: string): void {
+  try {
+    if (fs.readFileSync(filePath, 'utf8') === content) {
+      return
+    }
+  } catch {
+    // File does not exist yet or is unreadable.
+  }
+
+  fs.writeFileSync(filePath, content)
+}
+
+function hash(value: string): string {
+  return crypto.createHash('sha1').update(value).digest('hex').slice(0, 10)
+}
+
+function safeFileName(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_.-]+/g, '-')
+}
+
+function getManifestPath(projectRoot: string, platform: DynamicWidgetPlatform): string {
+  return path.join(projectRoot, '.voltra', `manifest.${platform}.json`)
+}
+
+function createManifestErrorPrefix(projectRoot: string, manifestPath: string, platform: DynamicWidgetPlatform): string {
+  return `Voltra dynamic widgets manifest at ${toPosixPath(path.relative(projectRoot, manifestPath))} for ${platform}`
+}
+
+export class MissingVoltraManifestError extends Error {
+  constructor({
+    projectRoot,
+    manifestPath,
+    platform,
+  }: {
+    projectRoot: string
+    manifestPath: string
+    platform: DynamicWidgetPlatform
+  }) {
+    super(
+      `Missing Voltra dynamic widgets manifest for ${platform} at ${toPosixPath(
+        path.relative(projectRoot, manifestPath)
+      )}. Run Expo prebuild for ${platform} to generate it.`
+    )
+
+    this.name = 'MissingVoltraManifestError'
+  }
+}
+
+export class InvalidVoltraManifestError extends Error {
+  constructor({
+    projectRoot,
+    manifestPath,
+    platform,
+    reason,
+  }: {
+    projectRoot: string
+    manifestPath: string
+    platform: DynamicWidgetPlatform
+    reason: string
+  }) {
+    super(`${createManifestErrorPrefix(projectRoot, manifestPath, platform)} is invalid: ${reason}`)
+
+    this.name = 'InvalidVoltraManifestError'
+  }
+}
+
+export class DuplicateVoltraWidgetError extends Error {
+  constructor({
+    projectRoot,
+    manifestPath,
+    platform,
+    widgetId,
+  }: {
+    projectRoot: string
+    manifestPath: string
+    platform: DynamicWidgetPlatform
+    widgetId: string
+  }) {
+    super(
+      `${createManifestErrorPrefix(
+        projectRoot,
+        manifestPath,
+        platform
+      )} contains duplicate widget id "${widgetId}". Widget ids must be unique within a single platform manifest.`
+    )
+
+    this.name = 'DuplicateVoltraWidgetError'
+  }
+}
+
+export function ensureEmptyDevBarrel(projectRoot: string): string {
+  const generatedRoot = path.join(projectRoot, '.voltra', 'metro')
+  const emptyBarrelPath = path.join(generatedRoot, 'widget-hot-reload.empty.js')
+  ensureDirectory(generatedRoot)
+  writeFileIfChanged(emptyBarrelPath, '// AUTO-GENERATED - empty Voltra widget hot-reload barrel.\n')
+  return emptyBarrelPath
+}
+
+function ensureRenderShim(generatedRoot: string): void {
+  ensureDirectory(generatedRoot)
+
+  for (const [fileName, content] of Object.entries(RENDER_SHIM_FILES)) {
+    writeFileIfChanged(path.join(generatedRoot, fileName), content)
+  }
+}
+
+function normalizeImportPath(filePath: string): string {
+  const normalized = toPosixPath(filePath)
+  return normalized.startsWith('.') ? normalized : `./${normalized}`
+}
+
+function readJsonFile(filePath: string): unknown {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'))
+}
+
+function validateManifest(
+  projectRoot: string,
+  platform: DynamicWidgetPlatform,
+  manifestPath: string,
+  rawManifest: unknown
+): DynamicWidgetManifest {
+  if (!rawManifest || typeof rawManifest !== 'object' || Array.isArray(rawManifest)) {
+    throw new InvalidVoltraManifestError({
+      projectRoot,
+      manifestPath,
+      platform,
+      reason: 'manifest root must be a JSON object',
+    })
+  }
+
+  const manifest = rawManifest as Record<string, unknown>
+
+  if (manifest.version !== 1) {
+    throw new InvalidVoltraManifestError({
+      projectRoot,
+      manifestPath,
+      platform,
+      reason: `expected version 1, received ${JSON.stringify(manifest.version)}`,
+    })
+  }
+
+  if (manifest.platform !== platform) {
+    throw new InvalidVoltraManifestError({
+      projectRoot,
+      manifestPath,
+      platform,
+      reason: `expected platform "${platform}", received ${JSON.stringify(manifest.platform)}`,
+    })
+  }
+
+  if (!Array.isArray(manifest.widgets)) {
+    throw new InvalidVoltraManifestError({
+      projectRoot,
+      manifestPath,
+      platform,
+      reason: 'widgets must be an array',
+    })
+  }
+
+  const widgetIds = new Set<string>()
+  const widgets: DynamicWidgetManifestWidget[] = []
+
+  for (const [index, value] of manifest.widgets.entries()) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+      throw new InvalidVoltraManifestError({
+        projectRoot,
+        manifestPath,
+        platform,
+        reason: `widgets[${index}] must be an object with id and entry`,
+      })
+    }
+
+    const widget = value as Record<string, unknown>
+
+    if (typeof widget.id !== 'string' || !widget.id.trim()) {
+      throw new InvalidVoltraManifestError({
+        projectRoot,
+        manifestPath,
+        platform,
+        reason: `widgets[${index}].id must be a non-empty string`,
+      })
+    }
+
+    try {
+      validateHomeScreenWidgetId(widget.id)
+    } catch (error) {
+      throw new InvalidVoltraManifestError({
+        projectRoot,
+        manifestPath,
+        platform,
+        reason: error instanceof Error ? error.message : String(error),
+      })
+    }
+
+    if (widgetIds.has(widget.id)) {
+      throw new DuplicateVoltraWidgetError({
+        projectRoot,
+        manifestPath,
+        platform,
+        widgetId: widget.id,
+      })
+    }
+
+    widgetIds.add(widget.id)
+
+    let entry: string
+    try {
+      entry = validateWidgetEntry(widget.entry, widget.id, projectRoot)
+    } catch (error) {
+      throw new InvalidVoltraManifestError({
+        projectRoot,
+        manifestPath,
+        platform,
+        reason: error instanceof Error ? error.message : String(error),
+      })
+    }
+
+    widgets.push({
+      id: widget.id,
+      entry,
+    })
+  }
+
+  return {
+    version: 1,
+    platform,
+    widgets,
+  }
+}
+
+function loadManifest(projectRoot: string, platform: DynamicWidgetPlatform): DynamicWidgetManifest {
+  const manifestPath = getManifestPath(projectRoot, platform)
+
+  if (!fs.existsSync(manifestPath)) {
+    throw new MissingVoltraManifestError({ projectRoot, manifestPath, platform })
+  }
+
+  let rawManifest: unknown
+  try {
+    rawManifest = readJsonFile(manifestPath)
+  } catch (error) {
+    throw new InvalidVoltraManifestError({
+      projectRoot,
+      manifestPath,
+      platform,
+      reason: error instanceof Error ? error.message : String(error),
+    })
+  }
+
+  try {
+    return validateManifest(projectRoot, platform, manifestPath, rawManifest)
+  } catch (error) {
+    if (error instanceof Error) {
+      throw error
+    }
+
+    throw new InvalidVoltraManifestError({
+      projectRoot,
+      manifestPath,
+      platform,
+      reason: String(error),
+    })
+  }
+}
+
+function createGeneratedEntry(
+  projectRoot: string,
+  generatedRoot: string,
+  widget: RegisteredVoltraWidget
+): Pick<RegisteredVoltraWidget, 'generatedEntryPath' | 'generatedEntryRelativePath'> {
+  const generatedEntryRoot = path.join(generatedRoot, 'widgets')
+  ensureDirectory(generatedEntryRoot)
+  ensureRenderShim(generatedRoot)
+
+  const entryFileName = `${widget.platform}-${safeFileName(widget.id)}-${hash(widget.entry)}.js`
+  const generatedEntryPath = path.join(generatedEntryRoot, entryFileName)
+  const entryImportPath = normalizeImportPath(path.relative(generatedEntryRoot, path.join(projectRoot, widget.entry)))
+  const renderShimImportPath = normalizeImportPath(
+    path.relative(generatedEntryRoot, path.join(generatedRoot, RENDER_SHIM_BASENAME))
+  )
+
+  const content = [
+    "import { createElement } from 'react'",
+    `import { renderVariantToJson } from ${JSON.stringify(renderShimImportPath)}`,
+    `import Widget from ${JSON.stringify(entryImportPath)}`,
+    '',
+    `if (typeof Widget === 'undefined') {`,
+    `  throw new Error(${JSON.stringify(
+      `Voltra widget "${widget.id}" at "${widget.entry}" is missing a default export.`
+    )})`,
+    '}',
+    '',
+    'function parseJSONInput(input, label) {',
+    '  if (typeof input !== "string") {',
+    '    return input || {}',
+    '  }',
+    '  if (!input) {',
+    '    return {}',
+    '  }',
+    '  try {',
+    '    return JSON.parse(input)',
+    '  } catch (error) {',
+    `    throw new Error(\`Voltra widget "${widget.id}" failed to parse \${label}: \${error instanceof Error ? error.message : String(error)}\`)`,
+    '  }',
+    '}',
+    '',
+    'export function render(propsJSON, envJSON) {',
+    '  const props = parseJSONInput(propsJSON, "propsJSON")',
+    '  const env = parseJSONInput(envJSON, "envJSON")',
+    '  const WidgetWithEnv = (forwardedProps) => Widget(forwardedProps, env)',
+    '  const resolved = renderVariantToJson(createElement(WidgetWithEnv, props))',
+    '  return JSON.stringify(resolved)',
+    '}',
+    '',
+    'export default render',
+    '',
+  ].join('\n')
+
+  writeFileIfChanged(generatedEntryPath, content)
+
+  return {
+    generatedEntryPath,
+    generatedEntryRelativePath: toPosixPath(path.relative(projectRoot, generatedEntryPath)),
+  }
+}
+
+function createPlatformBarrel(
+  generatedRoot: string,
+  platform: DynamicWidgetPlatform,
+  widgets: RegisteredVoltraWidget[]
+): void {
+  const barrelPath = path.join(generatedRoot, `widget-hot-reload.${platform}.js`)
+  const imports = widgets.map(
+    (widget) => `import ${JSON.stringify(normalizeImportPath(path.relative(generatedRoot, widget.generatedEntryPath)))}`
+  )
+
+  const content = [
+    '// AUTO-GENERATED - do not edit. Side-effect imports that place manifest-declared Voltra widgets in',
+    '// the host app dependency graph so Metro Fast Refresh drives dev hot reload of widgets.',
+    ...imports,
+    '',
+  ].join('\n')
+
+  writeFileIfChanged(barrelPath, content)
+}
+
+function createEmptyPlatformState(): PlatformState {
+  return {
+    error: null,
+    widgetsById: new Map(),
+    widgets: [],
+  }
+}
+
+export function createWidgetRegistry({ projectRoot = process.cwd() }: { projectRoot?: string } = {}): WidgetRegistry {
+  const generatedRoot = path.join(projectRoot, '.voltra', 'metro')
+  const platformStates: Record<DynamicWidgetPlatform, PlatformState> = {
+    ios: createEmptyPlatformState(),
+    android: createEmptyPlatformState(),
+  }
+  let ready = false
+  let watcher: FileWatcher | null = null
+
+  function recordPlatformWidgets(platform: DynamicWidgetPlatform, widgets: RegisteredVoltraWidget[]): void {
+    const state = platformStates[platform]
+    state.error = null
+    state.widgets = widgets
+    state.widgetsById = new Map(widgets.map((widget) => [widget.id, widget]))
+    createPlatformBarrel(generatedRoot, platform, widgets)
+  }
+
+  function recordPlatformError(platform: DynamicWidgetPlatform, error: Error): void {
+    const state = platformStates[platform]
+    state.error = error
+    state.widgets = []
+    state.widgetsById = new Map()
+    createPlatformBarrel(generatedRoot, platform, [])
+  }
+
+  function refreshPlatform(platform: DynamicWidgetPlatform): void {
+    try {
+      const manifest = loadManifest(projectRoot, platform)
+      const previousGeneratedPaths = new Set(
+        platformStates[platform].widgets.map((widget) => widget.generatedEntryPath)
+      )
+
+      const widgets = manifest.widgets.map((widget) => {
+        const baseWidget: RegisteredVoltraWidget = {
+          platform,
+          manifestPath: getManifestPath(projectRoot, platform),
+          ...widget,
+          generatedEntryPath: '',
+          generatedEntryRelativePath: '',
+        }
+
+        return {
+          ...baseWidget,
+          ...createGeneratedEntry(projectRoot, generatedRoot, baseWidget),
+        }
+      })
+
+      recordPlatformWidgets(platform, widgets)
+
+      for (const stalePath of previousGeneratedPaths) {
+        if (!widgets.some((widget) => widget.generatedEntryPath === stalePath)) {
+          try {
+            fs.rmSync(stalePath, { force: true })
+          } catch {
+            // Ignore stale cleanup failures.
+          }
+        }
+      }
+    } catch (error) {
+      const normalizedError = error instanceof Error ? error : new Error(String(error))
+      recordPlatformError(platform, normalizedError)
+    }
+  }
+
+  function watchManifestFiles(): void {
+    let chokidar: { watch(paths: string[], options: unknown): FileWatcher }
+
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      chokidar = require('chokidar')
+    } catch {
+      try {
+        const metroDir = path.dirname(require.resolve('metro/package.json', { paths: [projectRoot] }))
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        chokidar = require(require.resolve('chokidar', { paths: [metroDir] }))
+      } catch {
+        console.warn('[voltra:metro] chokidar unavailable - manifest updates are startup-scan only (no live updates)')
+        return
+      }
+    }
+
+    const manifestPaths = DEV_BARREL_PLATFORMS.map((platform) => getManifestPath(projectRoot, platform))
+    watcher = chokidar.watch(manifestPaths, {
+      ignoreInitial: true,
+    })
+
+    const handleManifestChange = (filePath: string) => {
+      const normalizedFilePath = path.resolve(filePath)
+      for (const platform of DEV_BARREL_PLATFORMS) {
+        if (path.resolve(getManifestPath(projectRoot, platform)) === normalizedFilePath) {
+          refreshPlatform(platform)
+          break
+        }
+      }
+    }
+
+    watcher.on('add', handleManifestChange)
+    watcher.on('change', handleManifestChange)
+    watcher.on('unlink', handleManifestChange)
+  }
+
+  ensureDirectory(generatedRoot)
+  ensureEmptyDevBarrel(projectRoot)
+  for (const platform of DEV_BARREL_PLATFORMS) {
+    refreshPlatform(platform)
+  }
+  ready = true
+  watchManifestFiles()
+
+  return {
+    projectRoot,
+    getWidget(platform: DynamicWidgetPlatform, widgetId: string) {
+      const state = platformStates[platform]
+
+      if (state.error) {
+        throw state.error
+      }
+
+      return state.widgetsById.get(widgetId) || null
+    },
+    isReady() {
+      return ready
+    },
+    listWidgets(platform?: DynamicWidgetPlatform) {
+      if (platform) {
+        const state = platformStates[platform]
+
+        if (state.error) {
+          throw state.error
+        }
+
+        return [...state.widgets]
+      }
+
+      return DEV_BARREL_PLATFORMS.flatMap((currentPlatform) => {
+        const state = platformStates[currentPlatform]
+        return state.error ? [] : state.widgets
+      })
+    },
+    close() {
+      if (watcher) {
+        watcher.close()
+        watcher = null
+      }
+    },
+  }
+}
diff --git a/packages/metro/tsconfig.base.json b/packages/metro/tsconfig.base.json
new file mode 100644
index 00000000..4fe5c5f4
--- /dev/null
+++ b/packages/metro/tsconfig.base.json
@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM"],
+    "rootDir": "./src",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "types": ["node"]
+  },
+  "include": ["./src"],
+  "exclude": ["**/__mocks__/*", "**/__tests__/*", "**/__rsc_tests__/*", "**/*.node.test.ts"]
+}
diff --git a/packages/metro/tsconfig.cjs.json b/packages/metro/tsconfig.cjs.json
new file mode 100644
index 00000000..a6b3ca9c
--- /dev/null
+++ b/packages/metro/tsconfig.cjs.json
@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "module": "CommonJS",
+    "outDir": "./build/cjs",
+    "declaration": false,
+    "sourceMap": true
+  }
+}
diff --git a/packages/metro/tsconfig.esm.json b/packages/metro/tsconfig.esm.json
new file mode 100644
index 00000000..2bb18d33
--- /dev/null
+++ b/packages/metro/tsconfig.esm.json
@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ES2020",
+    "outDir": "./build/esm",
+    "declaration": false,
+    "sourceMap": true
+  }
+}
diff --git a/packages/metro/tsconfig.json b/packages/metro/tsconfig.json
new file mode 100644
index 00000000..09b0ecb8
--- /dev/null
+++ b/packages/metro/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.esm.json" },
+    { "path": "./tsconfig.cjs.json" },
+    { "path": "./tsconfig.types.json" }
+  ]
+}
diff --git a/packages/metro/tsconfig.typecheck.json b/packages/metro/tsconfig.typecheck.json
new file mode 100644
index 00000000..8d869f11
--- /dev/null
+++ b/packages/metro/tsconfig.typecheck.json
@@ -0,0 +1,25 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ES2020",
+    "rootDir": "../..",
+    "baseUrl": "../..",
+    "paths": {
+      "@use-voltra/android": ["packages/android/src/index.ts"],
+      "@use-voltra/android-client": ["packages/android-client/src/index.ts"],
+      "@use-voltra/android/client": ["packages/android-client/src/index.ts"],
+      "@use-voltra/android/server": ["packages/android/src/server.ts"],
+      "@use-voltra/android-server": ["packages/android-server/src/index.ts"],
+      "@use-voltra/compiler": ["packages/compiler/src/index.ts"],
+      "@use-voltra/core": ["packages/core/src/index.ts"],
+      "@use-voltra/expo-plugin": ["packages/expo-plugin/src/index.ts"],
+      "@use-voltra/ios": ["packages/ios/src/index.ts"],
+      "@use-voltra/ios-client": ["packages/ios-client/src/index.ts"],
+      "@use-voltra/ios/client": ["packages/ios-client/src/index.ts"],
+      "@use-voltra/ios/server": ["packages/ios/src/server.ts"],
+      "@use-voltra/ios-server": ["packages/ios-server/src/index.ts"],
+      "@use-voltra/server": ["packages/server/src/index.ts"]
+    }
+  },
+  "exclude": ["**/*.node.test.ts"]
+}
diff --git a/packages/metro/tsconfig.types.json b/packages/metro/tsconfig.types.json
new file mode 100644
index 00000000..8ec821ee
--- /dev/null
+++ b/packages/metro/tsconfig.types.json
@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ES2020",
+    "outDir": "./build/types",
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "declarationMap": true
+  }
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 4ef98cc4..b67824d6 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -100,6 +100,9 @@ importers:
       '@use-voltra/ios-server':
         specifier: workspace:*
         version: link:../packages/ios-server
+      '@use-voltra/metro':
+        specifier: workspace:*
+        version: link:../packages/metro
       '@use-voltra/server':
         specifier: workspace:*
         version: link:../packages/server
@@ -237,6 +240,9 @@ importers:
       '@use-voltra/android':
         specifier: workspace:^
         version: link:../android
+      '@use-voltra/compiler':
+        specifier: workspace:^
+        version: link:../compiler
       '@use-voltra/expo-plugin':
         specifier: workspace:^
         version: link:../expo-plugin
@@ -318,6 +324,15 @@ importers:
         specifier: ^7.20.5
         version: 7.20.5
 
+  packages/compiler:
+    dependencies:
+      '@babel/parser':
+        specifier: ^7.27.4
+        version: 7.29.3
+      '@babel/types':
+        specifier: ^7.27.4
+        version: 7.29.0
+
   packages/core:
     dependencies:
       react:
@@ -394,6 +409,9 @@ importers:
       '@expo/plist':
         specifier: ^0.3.5
         version: 0.3.5
+      '@use-voltra/compiler':
+        specifier: workspace:^
+        version: link:../compiler
       '@use-voltra/expo-plugin':
         specifier: workspace:^
         version: link:../expo-plugin
@@ -444,6 +462,30 @@ importers:
         specifier: '*'
         version: 19.2.4
 
+  packages/metro:
+    dependencies:
+      '@use-voltra/compiler':
+        specifier: workspace:^
+        version: link:../compiler
+      '@use-voltra/expo-plugin':
+        specifier: workspace:^
+        version: link:../expo-plugin
+      expo:
+        specifier: '*'
+        version: 55.0.25(@babel/core@7.29.0)(@expo/dom-webview@55.0.6)(@expo/metro-runtime@55.0.11)(expo-router@55.0.15)(react-dom@19.2.4(react@19.2.4))(react-native-webview@13.16.0(react-native@0.83.2(@babel/core@7.29.0)(@types/react@19.2.15)(react@19.2.4))(react@19.2.4))(react-native-worklets@0.7.4(@babel/core@7.29.0)(react-native@0.83.2(@babel/core@7.29.0)(@types/react@19.2.15)(react@19.2.4))(react@19.2.4))(react-native@0.83.2(@babel/core@7.29.0)(@types/react@19.2.15)(react@19.2.4))(react@19.2.4)(typescript@5.9.3)
+      metro:
+        specifier: '*'
+        version: 0.83.7
+      metro-config-transformers:
+        specifier: ^1.0.0
+        version: 1.0.0(metro-config@0.83.7)
+      react:
+        specifier: '*'
+        version: 19.2.4
+      react-native:
+        specifier: '*'
+        version: 0.83.2(@babel/core@7.29.0)(@types/react@19.2.15)(react@19.2.4)
+
   packages/server: {}
 
   website:
@@ -8050,6 +8092,12 @@ packages:
       { integrity: sha512-E9SRePXQ1Zvlj79VcOk57q7VC7rMHMFQ+jhmPHBiq+dJ0bJB5BL87lWZF6oh5X76Cci5tpDuQNaDwwuSCToEeg== }
     engines: { node: '>=20.19.4' }
 
+  metro-config-transformers@1.0.0:
+    resolution:
+      { integrity: sha512-aF8bEBf9ocxWHpIbh95PGRTgk2C4gNM2scq/2uA87xl4vRoPr78AFz/bSh666FN3ak1LW3K5qkO5e6uolQeYYg== }
+    peerDependencies:
+      metro-config: '*'
+
   metro-config@0.83.7:
     resolution:
       { integrity: sha512-83mjWFbFOt2GeJ6pFIum5mSnc1uTsZJAtD8o4ej0s4NVsYsA7fB+pHvTfHhFrpeMONaobu2riKavkPei05Er/Q== }
@@ -18885,6 +18933,10 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  metro-config-transformers@1.0.0(metro-config@0.83.7):
+    dependencies:
+      metro-config: 0.83.7
+
   metro-config@0.83.7:
     dependencies:
       connect: 3.7.0
diff --git a/tsconfig.json b/tsconfig.json
index 9a268a1c..a6c4e8ae 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -9,7 +9,10 @@
       "@use-voltra/android/internal": ["./packages/android/src/internal.ts"],
       "@use-voltra/android/server": ["./packages/android/src/server.ts"],
       "@use-voltra/android-server": ["./packages/android-server/src/index.ts"],
+      "@use-voltra/compiler": ["./packages/compiler/src/index.ts"],
       "@use-voltra/core": ["./packages/core/src/index.ts"],
+      "@use-voltra/metro": ["./packages/metro/src/index.ts"],
+      "@use-voltra/metro/scanner": ["./packages/metro/src/scanner.ts"],
       "@use-voltra/ios": ["./packages/ios/src/index.ts"],
       "@use-voltra/ios-client": ["./packages/ios-client/src/index.ts"],
       "@use-voltra/ios/client": ["./packages/ios-client/src/index.ts"],
diff --git a/website/docs/v2/android/development/_meta.json b/website/docs/v2/android/development/_meta.json
index 9dd1d5a6..70d2c62b 100644
--- a/website/docs/v2/android/development/_meta.json
+++ b/website/docs/v2/android/development/_meta.json
@@ -4,6 +4,11 @@
     "name": "developing-widgets",
     "label": "Developing Widgets"
   },
+  {
+    "type": "file",
+    "name": "dynamic-widgets",
+    "label": "Dynamic Widgets"
+  },
   {
     "type": "file",
     "name": "managing-ongoing-notifications",
diff --git a/website/docs/v2/android/development/dynamic-widgets.md b/website/docs/v2/android/development/dynamic-widgets.md
new file mode 100644
index 00000000..02c7b46b
--- /dev/null
+++ b/website/docs/v2/android/development/dynamic-widgets.md
@@ -0,0 +1,93 @@
+# Dynamic Widgets
+
+:::warning Experimental Feature
+Dynamic widgets are experimental. Please [report any issues](https://github.com/callstackincubator/voltra/issues) you find.
+:::
+
+Dynamic Widgets let your widget react to the current device state on Android. Declare them in `app.json` with a stable `id` and an explicit `entry`, then default-export the widget from that file.
+
+Your widget can react to:
+
+- `env.widgetFamily`
+- `env.colorScheme`
+- `env.locale`
+- `env.configuration`
+- `AndroidDynamicColors` tokens, which resolve to the current Material You palette natively
+
+When you change `app.json`, run Expo Prebuild or Voltra Apply so the updated widget configuration is available on device. If you change only the widget JS, reopen the app in development and the widget updates automatically.
+
+## How to use it
+
+1. Add an Android widget declaration to `app.json` with an `id`, an `entry`, and any widget metadata you need.
+2. Default-export the widget function or component from the module named by `entry`.
+3. Use `initialStatePath` if you want a pre-rendered first view.
+4. Re-run Expo Prebuild or Voltra Apply after updating `app.json`.
+5. Keep Android and iOS widget declarations separate; the same `id` can exist on both platforms because each platform is configured separately.
+
+```tsx
+import { AndroidDynamicColors, VoltraAndroid, type WidgetEnvironment } from '@use-voltra/android'
+
+export default function WeatherWidget(_props: object, env: WidgetEnvironment = {} as WidgetEnvironment) {
+
+  const renderedAt = env.date.toLocaleTimeString('en-US', {
+    hour: '2-digit',
+    minute: '2-digit',
+  })
+
+  return (
+    <VoltraAndroid.Column
+      style={{ width: '100%', height: '100%', padding: 16, backgroundColor: AndroidDynamicColors.surface }}
+      verticalAlignment="center-vertically"
+    >
+      <VoltraAndroid.Text style={{ color: AndroidDynamicColors.onSurface, fontSize: 18 }}>
+        Weather Widget
+      </VoltraAndroid.Text>
+      <VoltraAndroid.Text style={{ color: AndroidDynamicColors.onSurfaceVariant }}>
+        Size: {env.widgetFamily}
+      </VoltraAndroid.Text>
+      <VoltraAndroid.Text style={{ color: AndroidDynamicColors.onSurfaceVariant }}>
+        Scheme: {env.colorScheme ?? 'light'}
+      </VoltraAndroid.Text>
+      <VoltraAndroid.Text style={{ color: AndroidDynamicColors.onSurfaceVariant }}>
+        Rendered: {renderedAt}
+      </VoltraAndroid.Text>
+    </VoltraAndroid.Column>
+  )
+}
+```
+
+Example plugin config:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "@use-voltra/android-client",
+        {
+          "widgets": [
+            {
+              "id": "weather_widget",
+              "entry": "./widgets/android/weather-widget.tsx",
+              "displayName": "Weather Widget",
+              "description": "A Dynamic Widget that reacts to live device state",
+              "targetCellWidth": 2,
+              "targetCellHeight": 2,
+              "initialStatePath": "./widgets/android/weather-widget.tsx"
+            }
+          ]
+        }
+      ]
+    ]
+  }
+}
+```
+
+If you need user-controlled values, add `appIntent.parameters` and update them in-app with `setWidgetConfiguration(widgetId, key, value)`.
+
+## Notes
+
+- There is no `export` field in app.json for Dynamic Widgets.
+- The default-exported function or component name does not need to match the widget `id`.
+- Use a real device to verify release rendering.
+- `initialStatePath` gives the widget a pre-rendered first view.
diff --git a/website/docs/v2/ios/development/_meta.json b/website/docs/v2/ios/development/_meta.json
index 71d6d2b8..71de8d23 100644
--- a/website/docs/v2/ios/development/_meta.json
+++ b/website/docs/v2/ios/development/_meta.json
@@ -14,6 +14,16 @@
     "name": "developing-widgets",
     "label": "Developing Widgets"
   },
+  {
+    "type": "file",
+    "name": "dynamic-widgets",
+    "label": "Dynamic Widgets"
+  },
+  {
+    "type": "file",
+    "name": "configurable-widgets",
+    "label": "Configurable Widgets"
+  },
   {
     "type": "file",
     "name": "querying-active-widgets",
diff --git a/website/docs/v2/ios/development/configurable-widgets.md b/website/docs/v2/ios/development/configurable-widgets.md
new file mode 100644
index 00000000..7813a079
--- /dev/null
+++ b/website/docs/v2/ios/development/configurable-widgets.md
@@ -0,0 +1,101 @@
+# Configurable Widgets
+
+:::warning Experimental Feature
+Configurable widgets are experimental. Please [report any issues](https://github.com/callstackincubator/voltra/issues) you find.
+:::
+
+Configurable widgets let users edit widget parameters in the native iOS Edit Widget sheet. Use them when a Dynamic Widget needs a few user-editable knobs, such as a label, unit, theme, or source.
+
+It requires iOS 17+, because Voltra wires it through `AppIntentConfiguration`.
+
+## How it works
+
+1. Define a Dynamic Widget module with a default export.
+2. Add `entry` and `appIntent.parameters` to the widget config in `app.json`.
+3. Read the selected values in your widget.
+4. Let the user edit the widget from the iOS widget sheet.
+
+Each parameter has:
+
+- `name`: key that appears in `env.configuration`
+- `title`: label shown in the Edit Widget sheet
+- `default`: code-defined starting value before the user changes anything
+
+## How to use it
+
+```tsx
+import { Voltra, type WidgetEnvironment } from '@use-voltra/ios'
+
+type GreetingConfig = { label?: string }
+
+export default function GreetingWidget(
+  _props: object,
+  env: WidgetEnvironment<GreetingConfig> = {} as WidgetEnvironment<GreetingConfig>
+) {
+
+  const label = env.configuration?.label ?? 'Hello'
+
+  return (
+    <Voltra.VStack style={{ padding: 16, backgroundColor: '#0F172A' }}>
+      <Voltra.Text style={{ color: 'white', fontSize: 18, fontWeight: '700' }}>
+        {label}
+      </Voltra.Text>
+      <Voltra.Text style={{ color: '#94A3B8', marginTop: 6 }}>
+        Edit me from the widget sheet.
+      </Voltra.Text>
+    </Voltra.VStack>
+  )
+}
+```
+
+Plugin config:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "@use-voltra/ios-client",
+        {
+          "widgets": [
+            {
+              "id": "greeting_widget",
+              "entry": "./widgets/ios/greeting-widget.tsx",
+              "displayName": "Greeting Widget",
+              "description": "A Dynamic Widget with user-editable parameters",
+              "supportedFamilies": ["systemSmall", "systemMedium"],
+              "initialStatePath": "./widgets/ios/greeting-widget.tsx",
+              "appIntent": {
+                "parameters": [
+                  {
+                    "name": "label",
+                    "title": "Label",
+                    "default": "Hello"
+                  }
+                ]
+              }
+            }
+          ]
+        }
+      ]
+    ]
+  }
+}
+```
+
+## Using it in app
+
+1. Build and install the app on a real iPhone.
+2. Add the widget to Home Screen.
+3. Long-press it and tap **Edit Widget**.
+4. Change parameters.
+5. Read values from `env.configuration` in your JSX.
+
+If you need more than one value, add more entries to `appIntent.parameters` and read each key from `env.configuration`.
+
+## Notes
+
+- `appIntent` only wires up for Dynamic Widgets.
+- Defaults come from code, not from the native sheet.
+- There is no `export` field in app.json for Dynamic Widgets.
+- Use a real device to verify the Edit Widget flow.
diff --git a/website/docs/v2/ios/development/dynamic-widgets.md b/website/docs/v2/ios/development/dynamic-widgets.md
new file mode 100644
index 00000000..f53c361e
--- /dev/null
+++ b/website/docs/v2/ios/development/dynamic-widgets.md
@@ -0,0 +1,90 @@
+# Dynamic Widgets
+
+:::warning Experimental Feature
+Dynamic widgets are experimental. Please [report any issues](https://github.com/callstackincubator/voltra/issues) you find.
+:::
+
+Dynamic Widgets let your widget react to the current device state on iOS. Declare them in `app.json` with a stable `id` and an explicit `entry`, then default-export the widget from that file.
+
+That means your widget can react to:
+
+- `env.widgetFamily`
+- `env.colorScheme`
+- `env.locale`
+- `env.widgetRenderingMode`
+- `env.showsWidgetContainerBackground`
+- `env.configuration` when you also add widget parameters
+
+When you change `app.json`, run Expo Prebuild or Voltra Apply so the updated widget configuration is available on device. If you change only the widget JS, reopen the app in development and the widget updates automatically.
+
+## How to use it
+
+1. Add an iOS widget declaration to `app.json` with an `id`, an `entry`, and any widget metadata you need.
+2. Default-export the widget function or component from the module named by `entry`.
+3. Use `initialStatePath` if you want a pre-rendered first view.
+4. Re-run Expo Prebuild or Voltra Apply after updating `app.json`.
+5. Keep iOS and Android widget declarations separate; the same `id` can exist on both platforms because each platform is configured separately.
+
+```tsx
+import { Voltra, type WidgetEnvironment } from '@use-voltra/ios'
+
+export default function WeatherWidget(_props: object, env: WidgetEnvironment = {} as WidgetEnvironment) {
+
+  const renderedAt = env.date.toLocaleTimeString('en-US', {
+    hour: '2-digit',
+    minute: '2-digit',
+  })
+
+  return (
+    <Voltra.VStack style={{ padding: 16, backgroundColor: '#111827' }}>
+      <Voltra.Text style={{ color: 'white', fontSize: 18, fontWeight: '700' }}>
+        Weather Widget
+      </Voltra.Text>
+      <Voltra.Text style={{ color: '#9CA3AF', marginTop: 6 }}>
+        Family: {env.widgetFamily}
+      </Voltra.Text>
+      <Voltra.Text style={{ color: '#9CA3AF' }}>
+        Scheme: {env.colorScheme ?? 'light'}
+      </Voltra.Text>
+      <Voltra.Text style={{ color: '#9CA3AF' }}>
+        Rendered: {renderedAt}
+      </Voltra.Text>
+    </Voltra.VStack>
+  )
+}
+```
+
+Example plugin config:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "@use-voltra/ios-client",
+        {
+          "widgets": [
+            {
+              "id": "weather_widget",
+              "entry": "./widgets/ios/weather-widget.tsx",
+              "displayName": "Weather Widget",
+              "description": "A Dynamic Widget that reacts to live device state",
+              "supportedFamilies": ["systemSmall", "systemMedium", "systemLarge"],
+              "initialStatePath": "./widgets/ios/weather-widget.tsx"
+            }
+          ]
+        }
+      ]
+    ]
+  }
+}
+```
+
+If you want user-editable values, add `appIntent` too. See [Configurable Widgets](./configurable-widgets).
+
+## Notes
+
+- There is no `export` field in app.json for Dynamic Widgets.
+- The default-exported function or component name does not need to match the widget `id`.
+- Use a real device to verify release rendering.
+- `initialStatePath` gives the widget a pre-rendered first view.