feat: client-rendered widgets on Android

.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.

example/app.json

@@ -226,6 +226,31 @@
                 "intervalMinutes": 15,
                 "refresh": true
               }
+            },
+            {
+              "id": "AndroidClientDemoWidget",
+              "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": [

example/app/_layout.tsx

@@ -1,13 +1,19 @@
 import { Stack } from 'expo-router'
+import { Platform } from 'react-native'
 import { SafeAreaProvider } from 'react-native-safe-area-context'
-import { enableWidgetHotReload } from '@use-voltra/ios-client'
+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'
 
-enableWidgetHotReload()
+if (Platform.OS === 'android') {
+  enableAndroidWidgetHotReload()
+} else {
+  enableIosWidgetHotReload()
+}
 updateAndroidVoltraWidget({ width: 300, height: 200 })
 
 const STACK_SCREEN_OPTIONS = {

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}>

example/widgets/android/AndroidClientDemoWidget.tsx

@@ -0,0 +1,71 @@
+import { AndroidDynamicColors, VoltraAndroid, type WidgetEnvironment } from '@use-voltra/android'
+
+// Client-rendered Android widget: 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 const AndroidClientDemoWidget = (_props: object, env: WidgetEnvironment = {} as WidgetEnvironment) => {
+  'use voltra'
+
+  // ▼ 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>
+  )
+}

packages/android-client/README.md

@@ -10,6 +10,8 @@
 
 - **Home Screen widgets**: Update, reload, pin, and query widgets with `updateAndroidWidget`, `reloadAndroidWidgets`, `getActiveWidgets`, and more.
 
+- **Client-rendered widgets** _(experimental)_: Write a widget as a `'use voltra'` JSX component and have it render on-device (standalone Hermes) from its own JS bundle, with live env (size, color scheme, Material You colors, locale, configuration). See the note below.
+
 - **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`.
@@ -20,6 +22,28 @@
 
 - **Expo config plugin**: Add `"@use-voltra/android-client"` to `app.json` to register widgets, optional notifications, and build-time initial states.
 
+## Client-rendered widgets (experimental)
+
+> [!WARNING]
+> Client-rendered widgets are **experimental** — usable in production at your own risk. The API
+> and generated build output may change between releases.
+
+A widget whose component carries the `'use voltra'` directive is rendered **on-device**: its JS
+bundle is evaluated in a standalone Hermes runtime on each render and called as `(props, env) => JSX`,
+so the widget reacts to live environment values (size, color scheme, Material You `materialColors`,
+locale, and `configuration`). In development the bundle is served by Metro (editing the JSX
+hot-reloads the pinned widget); in release builds it 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`. 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:
+
+- The dev loop and release baking rely on Metro scaffolding in your project (see `example/metro`).
+- Verify release rendering on a **real device** — emulators are unreliable for widget rendering.
+
 ## Documentation
 
 The documentation is available at [use-voltra.dev](https://use-voltra.dev). Relevant topics for this package:

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
+)

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"