voltra 1.0.1 → 1.1.1

package/README.md

@@ -1,32 +1,33 @@
 ![voltra-banner](https://use-voltra.dev/voltra-baner.jpg)
 
-### Build Live Activities with JSX in React Native
+### Build Live Activities and Widgets with JSX in React Native
 
 [![mit licence][license-badge]][license] [![npm downloads][npm-downloads-badge]][npm-downloads] [![PRs Welcome][prs-welcome-badge]][prs-welcome]
 
-Voltra turns React Native JSX into SwiftUI so you can ship custom Live Activities, Dynamic Island layouts without touching Xcode. Author everything in React, keep hot reload, and let the config plugin handle the extension targets.
+Voltra turns React Native JSX into SwiftUI and Jetpack Compose Glance so you can ship custom Live Activities, Dynamic Island layouts, and Android Widgets without touching native code. Author everything in React, keep hot reload, and let the config plugin handle the native extension targets.
 
 ## Features
 
-- **Ship Native iOS Surfaces**: Create Live Activities, Dynamic Island variants, and static widgets directly from React components - no Swift or Xcode required.
+- **Ship Native Surfaces**: Create iOS Live Activities, Dynamic Island variants, and Android Home Screen widgets directly from React components - no Swift, Kotlin, or Xcode/Android Studio UI work required.
 
-- **Fast Development Workflow**: Hooks respect Fast Refresh and both JS and native layers enforce ActivityKit payload budgets.
+- **Fast Development Workflow**: Hooks respect Fast Refresh and both JS and native layers enforce platform-specific payload budgets.
 
-- **Production-Ready Push Notifications**: Collect ActivityKit push tokens and push-to-start tokens, stream lifecycle updates, and build server-driven refreshes.
+- **Production-Ready Push Notifications**: Support for ActivityKit push tokens (iOS) and FCM (Android) to stream lifecycle updates and build server-driven refreshes.
 
-- **Familiar Styling**: Use React Native style props and ordered SwiftUI modifiers in one place.
+- **Familiar Styling**: Use React Native style props and platform-native modifiers (SwiftUI/Glance) in one place.
 
 - **Type-Safe & Developer-Friendly**: The Voltra schema, hooks, and examples ship with TypeScript definitions, tests, and docs so AI coding agents stay productive.
 
-- **Works With Your Setup**: Compatible with Expo Dev Client and bare React Native projects. The config plugin automatically wires iOS extension targets for you.
+- **Works With Your Setup**: Compatible with Expo Dev Client and bare React Native projects. The config plugin automatically wires native extension targets for you.
 
 ## Documentation
 
 The documentation is available at [use-voltra.dev](https://use-voltra.dev). You can also use the following links to jump to specific topics:
 
-- [Quick Start](https://use-voltra.dev/docs/getting-started/quick-start)
-- [API Reference](https://use-voltra.dev/docs/api/overview)
-- [Examples](https://use-voltra.dev/docs/examples)
+- [Quick Start](https://use-voltra.dev/getting-started/quick-start)
+- [Development](https://www.use-voltra.dev/development/developing-live-activities)
+- [Components](https://www.use-voltra.dev/components/overview)
+- [API Reference](https://use-voltra.dev/api/configuration)
 
 ## Getting started
 
@@ -49,9 +50,9 @@ Add the config plugin to your `app.json`:
 }
 ```
 
-Then run `npx expo prebuild --clean` to generate the iOS extension target.
+Then run `npx expo prebuild --clean` to generate the native extension targets.
 
-See the [documentation](https://use-voltra.dev/docs/getting-started/quick-start) for detailed setup instructions.
+See the [documentation](https://use-voltra.dev/getting-started/quick-start) for detailed setup instructions.
 
 ## Quick example
 
@@ -82,7 +83,10 @@ export function OrderTracker({ orderId }: { orderId: string }) {
 
 ## Platform compatibility
 
-**Note:** This module is intended for use on **iOS devices only**.
+Voltra is a cross-platform library that supports:
+
+- **iOS**: Live Activities and Dynamic Island (SwiftUI).
+- **Android**: Home Screen Widgets (Jetpack Compose Glance).
 
 ## Authors
 

package/android/.gradle/buildOutputCleanup/cache.properties

@@ -0,0 +1,2 @@
+#Wed Jan 28 15:59:43 CET 2026
+gradle.version=8.9

package/android/build.gradle

@@ -0,0 +1,84 @@
+buildscript {
+  // 1. ADD THIS BLOCK TO RESOLVE THE PLUGIN
+  repositories {
+    google()
+    mavenCentral()
+  }
+  dependencies {
+    // Ensure this version matches your project's Kotlin version (e.g., 2.0.0, 2.0.20)
+    classpath "org.jetbrains.kotlin:compose-compiler-gradle-plugin:2.0.0"
+    classpath "org.jetbrains.kotlin:kotlin-serialization:2.0.21"
+  }
+
+  // Existing helper
+  ext.safeExtGet = { prop, fallback ->
+    rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+  }
+}
+
+apply plugin: 'com.android.library'
+apply plugin: 'org.jetbrains.kotlin.plugin.compose'
+apply plugin: 'org.jetbrains.kotlin.plugin.serialization'
+
+group = 'voltra'
+version = '0.1.0'
+
+def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
+apply from: expoModulesCorePlugin
+applyKotlinExpoModulesCorePlugin()
+useCoreDependencies()
+useExpoPublishing()
+
+// If you want to use the managed Android SDK versions from expo-modules-core, set this to true.
+// The Android SDK versions will be bumped from time to time in SDK releases and may introduce breaking changes in your module code.
+// Most of the time, you may like to manage the Android SDK versions yourself.
+def useManagedAndroidSdkVersions = false
+if (useManagedAndroidSdkVersions) {
+  useDefaultAndroidSdkVersions()
+} else {
+  buildscript {
+    // Simple helper that allows the root project to override versions declared by this library.
+    ext.safeExtGet = { prop, fallback ->
+      rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback
+    }
+  }
+  project.android {
+    compileSdkVersion safeExtGet("compileSdkVersion", 36)
+    defaultConfig {
+      minSdkVersion safeExtGet("minSdkVersion", 31)
+      targetSdkVersion safeExtGet("targetSdkVersion", 36)
+    }
+  }
+}
+
+android {
+  namespace "voltra"
+  defaultConfig {
+    versionCode 1
+    versionName "0.1.0"
+  }
+  lintOptions {
+    abortOnError false
+  }
+  buildFeatures {
+    compose true
+  }
+}
+
+dependencies {
+  // Jetpack Glance - use 'api' instead of 'implementation' to make these available to consuming apps
+  api "androidx.glance:glance:1.2.0-rc01"
+  api "androidx.glance:glance-appwidget:1.2.0-rc01"
+
+  // Compose runtime (required for Glance)
+  api "androidx.compose.runtime:runtime:1.6.8"
+
+  // JSON parsing
+  implementation "com.google.code.gson:gson:2.10.1"
+
+  // Coroutines
+  implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.1"
+
+  // Kotlinx Serialization
+  implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,15 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
+
+    <application>
+        <provider
+            android:name="androidx.core.content.FileProvider"
+            android:authorities="${applicationId}.voltra.fileprovider"
+            android:exported="false"
+            android:grantUriPermissions="true">
+            <meta-data
+                android:name="android.support.FILE_PROVIDER_PATHS"
+                android:resource="@xml/voltra_file_paths" />
+        </provider>
+    </application>
+</manifest>

package/android/src/main/java/voltra/VoltraModule.kt

@@ -0,0 +1,296 @@
+package voltra
+
+import android.util.Log
+import androidx.compose.ui.unit.DpSize
+import androidx.compose.ui.unit.dp
+import androidx.glance.appwidget.GlanceAppWidgetManager
+import expo.modules.kotlin.modules.Module
+import expo.modules.kotlin.modules.ModuleDefinition
+import kotlinx.coroutines.async
+import kotlinx.coroutines.awaitAll
+import kotlinx.coroutines.runBlocking
+import voltra.events.VoltraEventBus
+import voltra.images.VoltraImageManager
+import voltra.widget.VoltraGlanceWidget
+import voltra.widget.VoltraWidgetManager
+
+class VoltraModule : Module() {
+    companion object {
+        private const val TAG = "VoltraModule"
+    }
+
+    private val notificationManager by lazy {
+        VoltraNotificationManager(appContext.reactContext!!)
+    }
+
+    private val widgetManager by lazy {
+        VoltraWidgetManager(appContext.reactContext!!)
+    }
+
+    private val imageManager by lazy {
+        VoltraImageManager(appContext.reactContext!!)
+    }
+
+    private val eventBus by lazy {
+        VoltraEventBus.getInstance(appContext.reactContext!!)
+    }
+
+    private var eventBusUnsubscribe: (() -> Unit)? = null
+
+    override fun definition() =
+        ModuleDefinition {
+            Name("VoltraModule")
+
+            OnStartObserving {
+                Log.d(TAG, "OnStartObserving: Starting event bus subscription")
+
+                // Replay any persisted events from SharedPreferences (cold start)
+                val persistedEvents = eventBus.popAll()
+                Log.d(TAG, "Replaying ${persistedEvents.size} persisted events")
+
+                persistedEvents.forEach { event ->
+                    sendEvent(event.type, event.toMap())
+                }
+
+                // Subscribe to hot event delivery (broadcast receiver)
+                eventBusUnsubscribe =
+                    eventBus.addListener { event ->
+                        Log.d(TAG, "Received hot event: ${event.type}")
+                        sendEvent(event.type, event.toMap())
+                    }
+            }
+
+            OnStopObserving {
+                Log.d(TAG, "OnStopObserving: Unsubscribing from event bus")
+                eventBusUnsubscribe?.invoke()
+                eventBusUnsubscribe = null
+            }
+
+            // Android Live Update APIs
+
+            AsyncFunction("startAndroidLiveUpdate") {
+                payload: String,
+                options: Map<String, Any?>,
+                ->
+
+                Log.d(TAG, "startAndroidLiveUpdate called")
+
+                val updateName = options["updateName"] as? String
+                val channelId = options["channelId"] as? String ?: "voltra_live_updates"
+
+                Log.d(TAG, "updateName=$updateName, channelId=$channelId")
+
+                val result =
+                    runBlocking {
+                        notificationManager.startLiveUpdate(payload, updateName, channelId)
+                    }
+
+                Log.d(TAG, "startAndroidLiveUpdate returning: $result")
+                result
+            }
+
+            AsyncFunction("updateAndroidLiveUpdate") {
+                notificationId: String,
+                payload: String,
+                ->
+
+                Log.d(TAG, "updateAndroidLiveUpdate called with notificationId=$notificationId")
+
+                runBlocking {
+                    notificationManager.updateLiveUpdate(notificationId, payload)
+                }
+
+                Log.d(TAG, "updateAndroidLiveUpdate completed")
+            }
+
+            AsyncFunction("stopAndroidLiveUpdate") { notificationId: String ->
+                Log.d(TAG, "stopAndroidLiveUpdate called with notificationId=$notificationId")
+                notificationManager.stopLiveUpdate(notificationId)
+            }
+
+            Function("isAndroidLiveUpdateActive") { updateName: String ->
+                notificationManager.isLiveUpdateActive(updateName)
+            }
+
+            AsyncFunction("endAllAndroidLiveUpdates") {
+                notificationManager.endAllLiveUpdates()
+            }
+
+            // Android Widget APIs
+
+            AsyncFunction("updateAndroidWidget") {
+                widgetId: String,
+                jsonString: String,
+                options: Map<String, Any?>,
+                ->
+
+                Log.d(TAG, "updateAndroidWidget called with widgetId=$widgetId")
+
+                val deepLinkUrl = options["deepLinkUrl"] as? String
+
+                widgetManager.writeWidgetData(widgetId, jsonString, deepLinkUrl)
+
+                runBlocking {
+                    widgetManager.updateWidget(widgetId)
+                }
+
+                Log.d(TAG, "updateAndroidWidget completed")
+            }
+
+            AsyncFunction("reloadAndroidWidgets") { widgetIds: ArrayList<String>? ->
+                Log.d(TAG, "reloadAndroidWidgets called with widgetIds=$widgetIds")
+
+                runBlocking {
+                    widgetManager.reloadWidgets(widgetIds)
+                }
+
+                Log.d(TAG, "reloadAndroidWidgets completed")
+            }
+
+            AsyncFunction("clearAndroidWidget") { widgetId: String ->
+                Log.d(TAG, "clearAndroidWidget called with widgetId=$widgetId")
+
+                widgetManager.clearWidgetData(widgetId)
+
+                runBlocking {
+                    widgetManager.updateWidget(widgetId)
+                }
+
+                Log.d(TAG, "clearAndroidWidget completed")
+            }
+
+            AsyncFunction("clearAllAndroidWidgets") {
+                Log.d(TAG, "clearAllAndroidWidgets called")
+
+                widgetManager.clearAllWidgetData()
+
+                runBlocking {
+                    widgetManager.reloadAllWidgets()
+                }
+
+                Log.d(TAG, "clearAllAndroidWidgets completed")
+            }
+
+            AsyncFunction("requestPinGlanceAppWidget") {
+                widgetId: String,
+                options: Map<String, Any?>?,
+                ->
+
+                Log.d(TAG, "requestPinGlanceAppWidget called with widgetId=$widgetId")
+
+                val context = appContext.reactContext!!
+
+                // Construct the receiver class name following the convention
+                val receiverClassName = "${context.packageName}.widget.VoltraWidget_${widgetId}Receiver"
+
+                Log.d(TAG, "Looking for receiver: $receiverClassName")
+
+                // Get the receiver class using reflection
+                val receiverClass =
+                    try {
+                        Class.forName(receiverClassName) as Class<out androidx.glance.appwidget.GlanceAppWidgetReceiver>
+                    } catch (e: ClassNotFoundException) {
+                        Log.e(TAG, "Widget receiver class not found: $receiverClassName", e)
+                        throw IllegalArgumentException("Widget receiver not found for id: $widgetId")
+                    }
+
+                // Get GlanceAppWidgetManager and request pin
+                val glanceManager = GlanceAppWidgetManager(context)
+
+                // Parse preview size from options (optional)
+                // See: https://developer.android.com/develop/ui/compose/glance/pin-in-app
+                val previewSize =
+                    if (options != null) {
+                        val width = (options["previewWidth"] as? Number)?.toFloat()
+                        val height = (options["previewHeight"] as? Number)?.toFloat()
+                        if (width != null && height != null) {
+                            DpSize(width.dp, height.dp)
+                        } else {
+                            null
+                        }
+                    } else {
+                        null
+                    }
+
+                val result =
+                    runBlocking {
+                        // requestPinGlanceAppWidget is a suspend function
+                        // See: https://developer.android.com/develop/ui/compose/glance/pin-in-app
+                        if (previewSize != null) {
+                            // Create preview widget with preview dimensions
+                            val previewWidget = VoltraGlanceWidget(widgetId)
+                            glanceManager.requestPinGlanceAppWidget(
+                                receiver = receiverClass,
+                                preview = previewWidget,
+                                previewState = previewSize,
+                            )
+                        } else {
+                            // Basic pin request without preview
+                            glanceManager.requestPinGlanceAppWidget(receiverClass)
+                        }
+                    }
+
+                Log.d(TAG, "requestPinGlanceAppWidget completed with result=$result")
+                result
+            }
+
+            AsyncFunction("preloadImages") { images: List<Map<String, Any>> ->
+                Log.d(TAG, "preloadImages called with ${images.size} images")
+
+                runBlocking {
+                    val results =
+                        images
+                            .map { img ->
+                                async {
+                                    val url = img["url"] as String
+                                    val key = img["key"] as String
+                                    val method = (img["method"] as? String) ?: "GET"
+
+                                    @Suppress("UNCHECKED_CAST")
+                                    val headers = img["headers"] as? Map<String, String>
+
+                                    val resultKey = imageManager.preloadImage(url, key, method, headers)
+                                    if (resultKey != null) {
+                                        Pair(key, null)
+                                    } else {
+                                        Pair(key, "Failed to download image")
+                                    }
+                                }
+                            }.awaitAll()
+
+                    val succeeded = results.filter { it.second == null }.map { it.first }
+                    val failed =
+                        results.filter { it.second != null }.map {
+                            mapOf("key" to it.first, "error" to it.second)
+                        }
+
+                    mapOf(
+                        "succeeded" to succeeded,
+                        "failed" to failed,
+                    )
+                }
+            }
+
+            AsyncFunction("clearPreloadedImages") { keys: List<String>? ->
+                Log.d(TAG, "clearPreloadedImages called with keys=$keys")
+                imageManager.clearPreloadedImages(keys)
+            }
+
+            AsyncFunction("reloadLiveActivities") { activityNames: List<String>? ->
+                // On Android, we don't have "Live Activities" in the same sense as iOS,
+                // but we might want to refresh widgets or notifications.
+                // For now, this is a no-op to match iOS API if called.
+                Log.d(TAG, "reloadLiveActivities called (no-op on Android)")
+            }
+
+            View(VoltraRN::class) {
+                Prop("payload") { view, payload: String ->
+                    view.setPayload(payload)
+                }
+
+                Prop("viewId") { view, viewId: String ->
+                    view.setViewId(viewId)
+                }
+            }
+        }
+}

package/android/src/main/java/voltra/VoltraNotificationManager.kt

@@ -0,0 +1,157 @@
+package voltra
+
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.content.Context
+import android.os.Build
+import android.util.Log
+import androidx.core.app.NotificationCompat
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import voltra.glance.RemoteViewsGenerator
+import voltra.parsing.VoltraPayloadParser
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.atomic.AtomicInteger
+
+class VoltraNotificationManager(
+    private val context: Context,
+) {
+    companion object {
+        private const val TAG = "VoltraNotificationMgr"
+    }
+
+    private val notificationManager =
+        context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+    private val activeNotifications = ConcurrentHashMap<String, Int>()
+    private val idCounter = AtomicInteger(10000)
+
+    suspend fun startLiveUpdate(
+        payload: String,
+        updateName: String?,
+        channelId: String,
+    ): String =
+        withContext(Dispatchers.Default) {
+            Log.d(TAG, "startLiveUpdate called with updateName=$updateName, channelId=$channelId")
+            Log.d(TAG, "Payload (first 200 chars): ${payload.take(200)}")
+
+            val voltraPayload = VoltraPayloadParser.parse(payload)
+            val notificationId = updateName ?: "live-update-${idCounter.getAndIncrement()}"
+            val intId = notificationId.hashCode().and(0x7FFFFFFF) // Ensure positive
+
+            Log.d(TAG, "Parsed payload, notificationId=$notificationId, intId=$intId")
+
+            createNotificationChannel(channelId)
+
+            val collapsedView = RemoteViewsGenerator.generateCollapsed(context, voltraPayload)
+            val expandedView = RemoteViewsGenerator.generateExpanded(context, voltraPayload)
+
+            Log.d(TAG, "Generated views: collapsed=${collapsedView != null}, expanded=${expandedView != null}")
+
+            val notification =
+                NotificationCompat
+                    .Builder(context, channelId)
+                    .setSmallIcon(getSmallIcon(voltraPayload.smallIcon))
+                    .setOngoing(true)
+                    .setPriority(NotificationCompat.PRIORITY_DEFAULT)
+                    .apply {
+                        collapsedView?.let { setCustomContentView(it) }
+                        expandedView?.let { setCustomBigContentView(it) }
+                    }.build()
+
+            notificationManager.notify(intId, notification)
+            activeNotifications[notificationId] = intId
+
+            Log.d(TAG, "Notification posted. Active notifications: ${activeNotifications.keys}")
+
+            notificationId
+        }
+
+    suspend fun updateLiveUpdate(
+        notificationId: String,
+        payload: String,
+    ) = withContext(Dispatchers.Default) {
+        Log.d(TAG, "updateLiveUpdate called with notificationId=$notificationId")
+        Log.d(TAG, "Active notifications: ${activeNotifications.keys}")
+
+        val intId = activeNotifications[notificationId]
+        if (intId == null) {
+            Log.e(TAG, "Notification $notificationId not found in activeNotifications!")
+            return@withContext
+        }
+
+        Log.d(TAG, "Found intId=$intId for notificationId=$notificationId")
+
+        val voltraPayload = VoltraPayloadParser.parse(payload)
+        val channelId = voltraPayload.channelId ?: "voltra_live_updates"
+
+        val collapsedView = RemoteViewsGenerator.generateCollapsed(context, voltraPayload)
+        val expandedView = RemoteViewsGenerator.generateExpanded(context, voltraPayload)
+
+        Log.d(TAG, "Update generated views: collapsed=${collapsedView != null}, expanded=${expandedView != null}")
+
+        val notification =
+            NotificationCompat
+                .Builder(context, channelId)
+                .setSmallIcon(getSmallIcon(voltraPayload.smallIcon))
+                .setOngoing(true)
+                .setOnlyAlertOnce(true) // Don't make sound/vibration on updates
+                .setWhen(System.currentTimeMillis()) // Force timestamp update
+                .setShowWhen(false) // But don't show the time
+                .apply {
+                    collapsedView?.let { setCustomContentView(it) }
+                    expandedView?.let { setCustomBigContentView(it) }
+                }.build()
+
+        // Force notification flags to allow updates
+        notification.flags = notification.flags or android.app.Notification.FLAG_ONGOING_EVENT
+
+        notificationManager.notify(intId, notification)
+        Log.d(TAG, "Notification updated successfully")
+    }
+
+    fun stopLiveUpdate(notificationId: String) {
+        Log.d(TAG, "stopLiveUpdate called with notificationId=$notificationId")
+        activeNotifications.remove(notificationId)?.let { intId ->
+            notificationManager.cancel(intId)
+            Log.d(TAG, "Notification cancelled")
+        }
+    }
+
+    fun isLiveUpdateActive(updateName: String): Boolean = activeNotifications.containsKey(updateName)
+
+    fun endAllLiveUpdates() {
+        Log.d(TAG, "endAllLiveUpdates called")
+        activeNotifications.forEach { (_, intId) ->
+            notificationManager.cancel(intId)
+        }
+        activeNotifications.clear()
+    }
+
+    private fun createNotificationChannel(channelId: String) {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+            val channel =
+                NotificationChannel(
+                    channelId,
+                    "Voltra Live Updates",
+                    NotificationManager.IMPORTANCE_DEFAULT,
+                ).apply {
+                    description = "Live update notifications from Voltra"
+                }
+            notificationManager.createNotificationChannel(channel)
+            Log.d(TAG, "Notification channel created: $channelId")
+        }
+    }
+
+    private fun getSmallIcon(iconName: String?): Int {
+        if (iconName != null) {
+            val resId =
+                context.resources.getIdentifier(
+                    iconName,
+                    "drawable",
+                    context.packageName,
+                )
+            if (resId != 0) return resId
+        }
+        return context.applicationInfo.icon
+    }
+}