diff --git a/.changeset/orange-ways-invite.md b/.changeset/orange-ways-invite.md
new file mode 100644
index 00000000..f8d62383
--- /dev/null
+++ b/.changeset/orange-ways-invite.md
@@ -0,0 +1,7 @@
+---
+'@use-voltra/android': minor
+'voltra': minor
+'@use-voltra/ios': minor
+---
+
+Add SVG support to image preloading on iOS and Android.
diff --git a/example/screens/android/AndroidImagePreloadingScreen.tsx b/example/screens/android/AndroidImagePreloadingScreen.tsx
index ec7152fc..96d76a10 100644
--- a/example/screens/android/AndroidImagePreloadingScreen.tsx
+++ b/example/screens/android/AndroidImagePreloadingScreen.tsx
@@ -2,7 +2,13 @@ import { useRouter } from 'expo-router'
import React, { useState } from 'react'
import { Alert, ScrollView, StyleSheet, Text, View } from 'react-native'
import { VoltraAndroid } from 'voltra'
-import { clearPreloadedImages, preloadImages, reloadWidgets, updateAndroidWidget } from 'voltra/android/client'
+import {
+ clearPreloadedImages,
+ preloadImages,
+ reloadWidgets,
+ updateAndroidWidget,
+ VoltraWidgetPreview,
+} from 'voltra/android/client'
import { Button } from '~/components/Button'
import { TextInput } from '~/components/TextInput'
@@ -11,12 +17,70 @@ function generateRandomUrl(): string {
return `https://picsum.photos/id/${Math.floor(Math.random() * 200)}/300/200`
}
+const ANDROID_SVG_OPTIONS = {
+ green: {
+ key: 'android-widget-svg-test-green',
+ color: '#34C759',
+ title: 'Show Green SVG in Widget',
+ },
+ purple: {
+ key: 'android-widget-svg-test-purple',
+ color: '#7C3AED',
+ title: 'Show Purple SVG in Widget',
+ },
+} as const
+
+type AndroidSvgOption = (typeof ANDROID_SVG_OPTIONS)[keyof typeof ANDROID_SVG_OPTIONS]
+
+function createAndroidTestSvg(color: string): string {
+ return `
+
+`
+}
+
+function AndroidSvgWidgetContent({ assetKey, color }: { assetKey: string; color: string }) {
+ return (
+
+
+
+
+
+
+
+ SVG preload
+
+
+ {color}
+
+
+
+
+
+ Preloaded SVG asset
+
+
+
+ )
+}
+
export default function AndroidImagePreloadingScreen() {
const router = useRouter()
const [url, setUrl] = useState(generateRandomUrl())
const [isProcessing, setIsProcessing] = useState(false)
const [assetKey] = useState('android-preload-test')
const [updateCount, setUpdateCount] = useState(0)
+ const [isSvgProcessing, setIsSvgProcessing] = useState(false)
+ const [selectedSvgOption, setSelectedSvgOption] = useState(null)
const handleUpdateAndPreload = async () => {
if (!url.trim()) {
@@ -128,6 +192,40 @@ export default function AndroidImagePreloadingScreen() {
}
}
+ const handleShowSvgWidget = async (option: AndroidSvgOption) => {
+ setIsSvgProcessing(true)
+
+ try {
+ const result = await preloadImages([
+ {
+ key: option.key,
+ svg: createAndroidTestSvg(option.color),
+ width: 48,
+ height: 48,
+ },
+ ])
+
+ if (result.failed.length > 0) {
+ throw new Error(result.failed[0].error)
+ }
+
+ await updateAndroidWidget('image_preloading', [
+ {
+ size: { width: 300, height: 200 },
+ content: ,
+ },
+ ])
+ await reloadWidgets(['image_preloading'])
+
+ setSelectedSvgOption(option)
+ Alert.alert('Success', 'SVG preloaded and widget updated!')
+ } catch (error) {
+ Alert.alert('Error', `Failed to update SVG widget: ${error}`)
+ } finally {
+ setIsSvgProcessing(false)
+ }
+ }
+
return (
@@ -165,6 +263,41 @@ export default function AndroidImagePreloadingScreen() {
+
+ SVG Widget Test
+
+ Preload an inline SVG as a PNG asset and update the Android image preloading widget to render it.
+
+
+
+
+
+ {selectedSvgOption ? (
+
+ Preview
+
+
+
+
+ ) : null}
+
+
@@ -216,6 +349,38 @@ const styles = StyleSheet.create({
flexDirection: 'column',
gap: 12,
},
+ section: {
+ marginTop: 24,
+ padding: 16,
+ borderRadius: 16,
+ borderWidth: 1,
+ borderColor: 'rgba(148, 163, 184, 0.2)',
+ backgroundColor: 'rgba(15, 23, 42, 0.8)',
+ },
+ sectionTitle: {
+ fontSize: 20,
+ fontWeight: '700',
+ color: '#FFFFFF',
+ },
+ sectionText: {
+ marginTop: 8,
+ fontSize: 14,
+ lineHeight: 20,
+ color: '#CBD5F5',
+ },
+ greenButtonSelected: {
+ backgroundColor: '#34C759',
+ },
+ purpleButtonSelected: {
+ backgroundColor: '#7C3AED',
+ },
+ previewContainer: {
+ marginTop: 16,
+ },
+ widgetPreview: {
+ borderRadius: 16,
+ overflow: 'hidden',
+ },
footer: {
marginTop: 24,
alignItems: 'center',
diff --git a/example/screens/testing-grounds/ImagePreloadingScreen.tsx b/example/screens/testing-grounds/ImagePreloadingScreen.tsx
index bef9e9ec..df40f0d5 100644
--- a/example/screens/testing-grounds/ImagePreloadingScreen.tsx
+++ b/example/screens/testing-grounds/ImagePreloadingScreen.tsx
@@ -2,7 +2,15 @@ import { Link } from 'expo-router'
import React, { useState } from 'react'
import { Alert, ScrollView, StyleSheet, Text, View } from 'react-native'
import { Voltra } from 'voltra'
-import { clearPreloadedImages, preloadImages, reloadLiveActivities, startLiveActivity } from 'voltra/client'
+import {
+ clearPreloadedImages,
+ preloadImages,
+ reloadLiveActivities,
+ reloadWidgets,
+ startLiveActivity,
+ updateWidget,
+ VoltraWidgetPreview,
+} from 'voltra/client'
import { Button } from '~/components/Button'
import { Card } from '~/components/Card'
@@ -12,10 +20,61 @@ function generateRandomKey(): string {
return `asset-${Math.random().toString(36).substring(2, 15)}`
}
+const SVG_OPTIONS = {
+ green: {
+ key: 'ios-widget-svg-test-green',
+ color: '#34C759',
+ title: 'Show Green SVG in Widget',
+ },
+ purple: {
+ key: 'ios-widget-svg-test-purple',
+ color: '#7C3AED',
+ title: 'Show Purple SVG in Widget',
+ },
+} as const
+
+type SvgOption = (typeof SVG_OPTIONS)[keyof typeof SVG_OPTIONS]
+
+function createTestSvg(color: string): string {
+ return `
+
+`
+}
+
+function SvgWidgetContent({ assetKey, color }: { assetKey: string; color: string }) {
+ return (
+
+
+
+
+
+ SVG preload
+ {color}
+
+
+
+
+
+ Rendered from a preloaded SVG asset
+
+
+ )
+}
+
export default function ImagePreloadingScreen() {
const [url, setUrl] = useState(`https://picsum.photos/id/${Math.floor(Math.random() * 120)}/100/100`)
const [isProcessing, setIsProcessing] = useState(false)
const [currentAssetKey, setCurrentAssetKey] = useState(null)
+ const [isSvgProcessing, setIsSvgProcessing] = useState(false)
+ const [selectedSvgOption, setSelectedSvgOption] = useState(null)
const handleShowAndDownload = async () => {
if (!url.trim()) {
@@ -91,6 +150,42 @@ export default function ImagePreloadingScreen() {
}
}
+ const handleShowSvgWidget = async (option: SvgOption) => {
+ setIsSvgProcessing(true)
+
+ try {
+ const result = await preloadImages([
+ {
+ key: option.key,
+ svg: createTestSvg(option.color),
+ width: 48,
+ height: 48,
+ },
+ ])
+
+ if (result.failed.length > 0) {
+ Alert.alert('SVG preload failed', result.failed.map((failure) => failure.error).join('\n'))
+ return
+ }
+
+ const variants = {
+ systemSmall: ,
+ systemMedium: ,
+ systemLarge: ,
+ }
+
+ await updateWidget('weather', variants)
+ await reloadWidgets(['weather'])
+
+ setSelectedSvgOption(option)
+ Alert.alert('Success', 'SVG preloaded and the Weather widget was updated.')
+ } catch (error) {
+ Alert.alert('Error', `Failed to update SVG widget: ${error}`)
+ } finally {
+ setIsSvgProcessing(false)
+ }
+ }
+
return (
@@ -127,6 +222,39 @@ export default function ImagePreloadingScreen() {
+
+ SVG Widget Test
+
+ Preload an inline SVG as a PNG asset and update the iOS Weather widget to render it with Voltra.Image.
+
+
+
+
+
+ {selectedSvgOption ? (
+
+ Preview
+
+
+
+
+ ) : null}
+
+
@@ -147,6 +275,9 @@ const styles = StyleSheet.create({
paddingHorizontal: 20,
paddingVertical: 24,
},
+ content: {
+ gap: 8,
+ },
heading: {
fontSize: 24,
fontWeight: '700',
@@ -172,6 +303,19 @@ const styles = StyleSheet.create({
flexDirection: 'column',
gap: 12,
},
+ greenButtonSelected: {
+ backgroundColor: '#34C759',
+ },
+ purpleButtonSelected: {
+ backgroundColor: '#7C3AED',
+ },
+ previewContainer: {
+ marginTop: 16,
+ },
+ widgetPreview: {
+ borderRadius: 16,
+ overflow: 'hidden',
+ },
footer: {
marginTop: 24,
alignItems: 'center',
diff --git a/packages/android/src/types.ts b/packages/android/src/types.ts
index 24c90dd9..2369cf20 100644
--- a/packages/android/src/types.ts
+++ b/packages/android/src/types.ts
@@ -4,13 +4,24 @@ export type EventSubscription = {
remove: () => void
}
-export type PreloadImageOptions = {
- url: string
+type PreloadImageBaseOptions = {
key: string
+ width?: number
+ height?: number
+}
+
+export type PreloadImageUrlOptions = PreloadImageBaseOptions & {
+ url: string
method?: 'GET' | 'POST' | 'PUT'
headers?: Record
}
+export type PreloadImageSvgOptions = PreloadImageBaseOptions & {
+ svg: string
+}
+
+export type PreloadImageOptions = PreloadImageUrlOptions | PreloadImageSvgOptions
+
export type PreloadImageFailure = {
key: string
error: string
diff --git a/packages/ios/src/types.ts b/packages/ios/src/types.ts
index c4d08470..6359e6b5 100644
--- a/packages/ios/src/types.ts
+++ b/packages/ios/src/types.ts
@@ -4,13 +4,24 @@ export type EventSubscription = {
remove: () => void
}
-export type PreloadImageOptions = {
- url: string
+type PreloadImageBaseOptions = {
key: string
+ width?: number
+ height?: number
+}
+
+export type PreloadImageUrlOptions = PreloadImageBaseOptions & {
+ url: string
method?: 'GET' | 'POST' | 'PUT'
headers?: Record
}
+export type PreloadImageSvgOptions = PreloadImageBaseOptions & {
+ svg: string
+}
+
+export type PreloadImageOptions = PreloadImageUrlOptions | PreloadImageSvgOptions
+
export type PreloadImageFailure = {
key: string
error: string
diff --git a/packages/voltra/.prettierignore b/packages/voltra/.prettierignore
new file mode 100644
index 00000000..844e091b
--- /dev/null
+++ b/packages/voltra/.prettierignore
@@ -0,0 +1,5 @@
+build
+android/build
+ios/.build
+.expo
+coverage
diff --git a/packages/voltra/android/build.gradle b/packages/voltra/android/build.gradle
index 3fd6edb0..a3dae9ae 100644
--- a/packages/voltra/android/build.gradle
+++ b/packages/voltra/android/build.gradle
@@ -73,6 +73,7 @@ android {
compose true
}
testOptions {
+ unitTests.includeAndroidResources = true
unitTests.all {
testLogging {
events "passed", "failed", "skipped"
@@ -108,6 +109,9 @@ dependencies {
// Kotlinx Serialization
implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.6.3"
+ // SVG rasterization for runtime image preloading
+ implementation "com.caverock:androidsvg-aar:1.4"
+
// Unit tests
testImplementation "junit:junit:4.13.2"
testImplementation "org.jetbrains.kotlinx:kotlinx-coroutines-test:1.8.1"
diff --git a/packages/voltra/android/src/main/java/voltra/VoltraModule.kt b/packages/voltra/android/src/main/java/voltra/VoltraModule.kt
index fb7c1e83..53a00925 100644
--- a/packages/voltra/android/src/main/java/voltra/VoltraModule.kt
+++ b/packages/voltra/android/src/main/java/voltra/VoltraModule.kt
@@ -391,18 +391,30 @@ class VoltraModule : Module() {
images
.map { img ->
async {
- val url = img["url"] as String
val key = img["key"] as String
+ val url = img["url"] as? String
+ val svg = img["svg"] as? String
val method = (img["method"] as? String) ?: "GET"
+ val width = (img["width"] as? Number)?.toInt()
+ val height = (img["height"] as? Number)?.toInt()
@Suppress("UNCHECKED_CAST")
val headers = img["headers"] as? Map
- val resultKey = imageManager.preloadImage(url, key, method, headers)
- if (resultKey != null) {
+ try {
+ imageManager.preloadImage(
+ key = key,
+ url = url,
+ svg = svg,
+ method = method,
+ headers = headers,
+ width = width,
+ height = height,
+ )
Pair(key, null)
- } else {
- Pair(key, "Failed to download image")
+ } catch (error: Exception) {
+ Log.e(TAG, "Error preloading image: $key", error)
+ Pair(key, error.message ?: "Failed to preload image")
}
}
}.awaitAll()
diff --git a/packages/voltra/android/src/main/java/voltra/images/VoltraImageManager.kt b/packages/voltra/android/src/main/java/voltra/images/VoltraImageManager.kt
index e06c6c62..c37e6712 100644
--- a/packages/voltra/android/src/main/java/voltra/images/VoltraImageManager.kt
+++ b/packages/voltra/android/src/main/java/voltra/images/VoltraImageManager.kt
@@ -1,14 +1,20 @@
package voltra.images
import android.content.Context
+import android.graphics.Bitmap
+import android.graphics.Canvas
+import android.graphics.Color
import android.net.Uri
import android.util.Log
import androidx.core.content.FileProvider
+import com.caverock.androidsvg.SVG
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
+import java.io.ByteArrayOutputStream
import java.io.File
import java.net.HttpURLConnection
import java.net.URL
+import kotlin.math.ceil
class VoltraImageManager(
private val context: Context,
@@ -17,72 +23,24 @@ class VoltraImageManager(
private const val TAG = "VoltraImageManager"
private const val PREFS_NAME = "voltra_preload_images"
private const val CACHE_DIR_NAME = "voltra_widget_images"
+ private const val MAX_SVG_SIZE_BYTES = 256 * 1024
}
private val prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
suspend fun preloadImage(
- url: String,
key: String,
+ url: String? = null,
+ svg: String? = null,
method: String = "GET",
headers: Map? = null,
- ): String? =
+ width: Int? = null,
+ height: Int? = null,
+ ): String =
withContext(Dispatchers.IO) {
- try {
- val connection = URL(url).openConnection() as HttpURLConnection
- connection.requestMethod = method
- headers?.forEach { (k, v) -> connection.setRequestProperty(k, v) }
-
- connection.connect()
- if (connection.responseCode !in 200..299) {
- Log.e(TAG, "Failed to download image: ${connection.responseCode}")
- return@withContext null
- }
-
- val cacheDir = File(context.cacheDir, CACHE_DIR_NAME)
- if (!cacheDir.exists()) {
- cacheDir.mkdirs()
- }
-
- // Append timestamp to force refresh
- val filename = "${key}_${System.currentTimeMillis()}.png"
- val file = File(cacheDir, filename)
-
- connection.inputStream.use { input ->
- file.outputStream().use { output ->
- input.copyTo(output)
- }
- }
-
- val uri =
- FileProvider
- .getUriForFile(
- context,
- "${context.packageName}.voltra.fileprovider",
- file,
- ).toString()
-
- // Delete old file if exists
- getUriForKey(key)?.let { oldUriString ->
- try {
- val oldUri = Uri.parse(oldUriString)
- context.contentResolver.delete(oldUri, null, null)
- // Also try to delete the file directly just in case
- val oldFilename = oldUri.lastPathSegment
- if (oldFilename != null) {
- File(cacheDir, oldFilename).delete()
- }
- } catch (e: Exception) {
- Log.w(TAG, "Failed to delete old image file: $oldUriString", e)
- }
- }
-
- prefs.edit().putString(key, uri).apply()
- return@withContext key
- } catch (e: Exception) {
- Log.e(TAG, "Error preloading image: $key", e)
- return@withContext null
- }
+ val data = resolveImageData(key, url, svg, method, headers, width, height)
+ saveImageData(key, data)
+ key
}
fun getUriForKey(key: String): String? = prefs.getString(key, null)
@@ -104,6 +62,157 @@ class VoltraImageManager(
}
}
+ private fun resolveImageData(
+ key: String,
+ url: String?,
+ svg: String?,
+ method: String,
+ headers: Map?,
+ width: Int?,
+ height: Int?,
+ ): ByteArray {
+ val inlineSvg = svg?.trim()
+ if (!inlineSvg.isNullOrEmpty()) {
+ return rasterizeSvg(key, inlineSvg, width, height)
+ }
+
+ val urlString = url?.trim()
+ require(!urlString.isNullOrEmpty()) { "Image '$key' must provide either url or svg" }
+
+ val connection = URL(urlString).openConnection() as HttpURLConnection
+ connection.requestMethod = method
+ headers?.forEach { (k, v) -> connection.setRequestProperty(k, v) }
+
+ try {
+ connection.connect()
+ require(connection.responseCode in 200..299) {
+ "HTTP error while downloading image '$key': ${connection.responseCode}"
+ }
+
+ val data = connection.inputStream.use { input -> input.readBytes() }
+ val contentType = connection.contentType
+
+ return if (isSvgData(data, contentType, urlString)) {
+ require(data.size < MAX_SVG_SIZE_BYTES) {
+ "SVG '$key' is too large: ${data.size} bytes (max $MAX_SVG_SIZE_BYTES bytes)"
+ }
+ val svgString = data.toString(Charsets.UTF_8)
+ rasterizeSvg(key, svgString, width, height)
+ } else {
+ data
+ }
+ } finally {
+ connection.disconnect()
+ }
+ }
+
+ private fun saveImageData(
+ key: String,
+ data: ByteArray,
+ ) {
+ val cacheDir = File(context.cacheDir, CACHE_DIR_NAME)
+ if (!cacheDir.exists()) {
+ cacheDir.mkdirs()
+ }
+
+ // Append timestamp to force refresh
+ val filename = "${key}_${System.currentTimeMillis()}.png"
+ val file = File(cacheDir, filename)
+ file.writeBytes(data)
+
+ val uri =
+ FileProvider
+ .getUriForFile(
+ context,
+ "${context.packageName}.voltra.fileprovider",
+ file,
+ ).toString()
+
+ // Delete old file if exists
+ getUriForKey(key)?.let { oldUriString ->
+ try {
+ val oldUri = Uri.parse(oldUriString)
+ context.contentResolver.delete(oldUri, null, null)
+ // Also try to delete the file directly just in case
+ val oldFilename = oldUri.lastPathSegment
+ if (oldFilename != null) {
+ File(cacheDir, oldFilename).delete()
+ }
+ } catch (e: Exception) {
+ Log.w(TAG, "Failed to delete old image file: $oldUriString", e)
+ }
+ }
+
+ prefs.edit().putString(key, uri).apply()
+ }
+
+ private fun isSvgData(
+ data: ByteArray,
+ contentType: String?,
+ url: String,
+ ): Boolean {
+ if (contentType?.lowercase()?.contains("image/svg+xml") == true) return true
+ if (url.substringBefore("?").lowercase().endsWith(".svg")) return true
+
+ val prefix = data.copyOfRange(0, minOf(data.size, 512)).toString(Charsets.UTF_8).lowercase()
+ return prefix.contains(" 0 && renderHeight > 0) {
+ "SVG '$key' requires positive width and height"
+ }
+
+ val picture = svg.renderToPicture(renderWidth, renderHeight)
+ val bitmap = Bitmap.createBitmap(renderWidth, renderHeight, Bitmap.Config.ARGB_8888)
+ val canvas = Canvas(bitmap)
+ canvas.drawColor(Color.TRANSPARENT)
+ canvas.drawPicture(picture)
+
+ return ByteArrayOutputStream().use { output ->
+ bitmap.compress(Bitmap.CompressFormat.PNG, 100, output)
+ bitmap.recycle()
+ output.toByteArray()
+ }
+ }
+
+ private fun validateSvg(
+ key: String,
+ svgMarkup: String,
+ ) {
+ val lower = svgMarkup.trim().lowercase()
+ require(lower.contains("
+
+
+ """.trimIndent(),
+ width = 24,
+ height = 24,
+ )
+
+ assertEquals("svg_icon", key)
+ val uri = manager.getUriForKey("svg_icon")
+ assertNotNull(uri)
+
+ val bitmap =
+ context.contentResolver.openInputStream(Uri.parse(uri)).use { stream ->
+ BitmapFactory.decodeStream(stream)
+ }
+
+ assertNotNull(bitmap)
+ assertEquals(24, bitmap.width)
+ assertEquals(24, bitmap.height)
+ }
+}
diff --git a/packages/voltra/android/src/test/resources/robolectric.properties b/packages/voltra/android/src/test/resources/robolectric.properties
new file mode 100644
index 00000000..3f67ea5a
--- /dev/null
+++ b/packages/voltra/android/src/test/resources/robolectric.properties
@@ -0,0 +1 @@
+sdk=35
diff --git a/packages/voltra/ios/Voltra.podspec b/packages/voltra/ios/Voltra.podspec
index ea42c7ee..fc7706d1 100644
--- a/packages/voltra/ios/Voltra.podspec
+++ b/packages/voltra/ios/Voltra.podspec
@@ -23,6 +23,7 @@ Pod::Spec.new do |s|
}
s.dependency 'ExpoModulesCore'
+ s.frameworks = 'WebKit'
s.source_files = [
"app/**/*.swift",
diff --git a/packages/voltra/ios/app/VoltraImagePreload.swift b/packages/voltra/ios/app/VoltraImagePreload.swift
index fb3eedd6..f1bce265 100644
--- a/packages/voltra/ios/app/VoltraImagePreload.swift
+++ b/packages/voltra/ios/app/VoltraImagePreload.swift
@@ -2,6 +2,7 @@ import ExpoModulesCore
import Foundation
import os
import UIKit
+import WebKit
// MARK: - Types
@@ -9,7 +10,11 @@ import UIKit
public struct PreloadImageOptions: Record {
/// The URL to download the image from
@Field
- public var url: String
+ public var url: String?
+
+ /// Inline SVG markup to rasterize and preload
+ @Field
+ public var svg: String?
/// The key to use when referencing this image (used as assetName)
@Field
@@ -23,6 +28,14 @@ public struct PreloadImageOptions: Record {
@Field
public var headers: [String: String]?
+ /// Target width in pixels for SVG rasterization
+ @Field
+ public var width: Int?
+
+ /// Target height in pixels for SVG rasterization
+ @Field
+ public var height: Int?
+
public init() {}
}
@@ -63,9 +76,13 @@ public struct PreloadImagesResult: Record {
/// Errors that can occur during image preloading
enum PreloadError: Error, LocalizedError {
case invalidURL(String)
+ case invalidSource(key: String)
case invalidResponse
case httpError(statusCode: Int)
case imageTooLarge(key: String, size: Int)
+ case svgTooLarge(key: String, size: Int)
+ case invalidSvgData(key: String)
+ case invalidSvgDimensions(key: String)
case invalidImageData(key: String)
case appGroupNotConfigured
@@ -73,12 +90,21 @@ enum PreloadError: Error, LocalizedError {
switch self {
case let .invalidURL(url):
return "Invalid URL: \(url)"
+ case let .invalidSource(key):
+ return "Image '\(key)' must provide either url or svg"
case .invalidResponse:
return "Invalid response from server"
case let .httpError(statusCode):
return "HTTP error: \(statusCode)"
case let .imageTooLarge(key, size):
- return "Image '\(key)' is too large: \(size) bytes (max \(VoltraImagePreload.maxImageSizeInBytes) bytes for Live Activities)"
+ return "Image '\(key)' is too large: \(size) bytes " +
+ "(max \(VoltraImagePreload.maxImageSizeInBytes) bytes for Live Activities)"
+ case let .svgTooLarge(key, size):
+ return "SVG '\(key)' is too large: \(size) bytes (max \(VoltraImagePreload.maxSvgSizeInBytes) bytes)"
+ case let .invalidSvgData(key):
+ return "Invalid SVG data for '\(key)'"
+ case let .invalidSvgDimensions(key):
+ return "SVG '\(key)' requires positive width and height"
case let .invalidImageData(key):
return "Invalid image data for '\(key)'"
case .appGroupNotConfigured:
@@ -91,6 +117,7 @@ enum PreloadError: Error, LocalizedError {
enum VoltraImagePreload {
static let maxImageSizeInBytes = 4096
+ static let maxSvgSizeInBytes = 256 * 1024
static func preloadImages(images: [PreloadImageOptions]) async throws -> PreloadImagesResult {
var succeeded: [String] = []
@@ -98,7 +125,7 @@ enum VoltraImagePreload {
for imageOptions in images {
do {
- try await downloadAndSaveImage(imageOptions)
+ try await loadAndSaveImage(imageOptions)
succeeded.append(imageOptions.key)
} catch {
failed.append(PreloadImageFailure(key: imageOptions.key, error: error.localizedDescription))
@@ -120,9 +147,32 @@ enum VoltraImagePreload {
// MARK: - Private
- private static func downloadAndSaveImage(_ options: PreloadImageOptions) async throws {
- guard let url = URL(string: options.url) else {
- throw PreloadError.invalidURL(options.url)
+ private static func loadAndSaveImage(_ options: PreloadImageOptions) async throws {
+ let data = try await resolveImageData(options)
+
+ if data.count >= maxImageSizeInBytes {
+ throw PreloadError.imageTooLarge(key: options.key, size: data.count)
+ }
+
+ guard UIImage(data: data) != nil else {
+ throw PreloadError.invalidImageData(key: options.key)
+ }
+
+ try VoltraImageStore.saveImage(data, key: options.key)
+ VoltraLogger.image.info("Preloaded '\(options.key)' (\(data.count) bytes)")
+ }
+
+ private static func resolveImageData(_ options: PreloadImageOptions) async throws -> Data {
+ if let inlineSvg = options.svg?.trimmingCharacters(in: .whitespacesAndNewlines), !inlineSvg.isEmpty {
+ return try await rasterizeSvg(inlineSvg, key: options.key, width: options.width, height: options.height)
+ }
+
+ guard let urlString = options.url?.trimmingCharacters(in: .whitespacesAndNewlines), !urlString.isEmpty else {
+ throw PreloadError.invalidSource(key: options.key)
+ }
+
+ guard let url = URL(string: urlString) else {
+ throw PreloadError.invalidURL(urlString)
}
var request = URLRequest(url: url)
@@ -144,6 +194,17 @@ enum VoltraImagePreload {
throw PreloadError.httpError(statusCode: httpResponse.statusCode)
}
+ let contentType = httpResponse.value(forHTTPHeaderField: "Content-Type")
+ if isSvgData(data, contentType: contentType, url: url) {
+ guard data.count < maxSvgSizeInBytes else {
+ throw PreloadError.svgTooLarge(key: options.key, size: data.count)
+ }
+ guard let svg = String(data: data, encoding: .utf8) else {
+ throw PreloadError.invalidSvgData(key: options.key)
+ }
+ return try await rasterizeSvg(svg, key: options.key, width: options.width, height: options.height)
+ }
+
if let contentLengthString = httpResponse.value(forHTTPHeaderField: "Content-Length"),
let contentLength = Int(contentLengthString)
{
@@ -156,11 +217,135 @@ enum VoltraImagePreload {
throw PreloadError.imageTooLarge(key: options.key, size: data.count)
}
- guard UIImage(data: data) != nil else {
- throw PreloadError.invalidImageData(key: options.key)
+ return data
+ }
+
+ private static func isSvgData(_ data: Data, contentType: String?, url: URL) -> Bool {
+ if contentType?.lowercased().contains("image/svg+xml") == true {
+ return true
}
- try VoltraImageStore.saveImage(data, key: options.key)
- VoltraLogger.image.info("Preloaded '\(options.key)' (\(data.count) bytes)")
+ if url.pathExtension.lowercased() == "svg" {
+ return true
+ }
+
+ guard let prefix = String(data: data.prefix(512), encoding: .utf8)?.lowercased() else {
+ return false
+ }
+
+ return prefix.contains(" Data {
+ let svgSize = svg.data(using: .utf8)?.count ?? 0
+ guard svgSize < maxSvgSizeInBytes else {
+ throw PreloadError.svgTooLarge(key: key, size: svgSize)
+ }
+
+ try validateSvg(svg, key: key)
+
+ guard let width, let height, width > 0, height > 0 else {
+ throw PreloadError.invalidSvgDimensions(key: key)
+ }
+
+ let size = CGSize(width: width, height: height)
+ let webView = WKWebView(frame: CGRect(origin: .zero, size: size))
+ webView.isOpaque = false
+ webView.backgroundColor = .clear
+ webView.scrollView.backgroundColor = .clear
+ webView.scrollView.isScrollEnabled = false
+
+ let navigationDelegate = SvgNavigationDelegate()
+ webView.navigationDelegate = navigationDelegate
+
+ let html = """
+
+
+
+
+
+
+ \(svg)
+
+ """
+
+ try await withCheckedThrowingContinuation { (continuation: CheckedContinuation) in
+ navigationDelegate.continuation = continuation
+ webView.loadHTMLString(html, baseURL: nil)
+ }
+
+ let configuration = WKSnapshotConfiguration()
+ configuration.rect = CGRect(origin: .zero, size: size)
+ configuration.snapshotWidth = NSNumber(value: width)
+
+ let image: UIImage = try await withCheckedThrowingContinuation { (continuation: CheckedContinuation) in
+ webView.takeSnapshot(with: configuration) { image, error in
+ if let error {
+ continuation.resume(throwing: error)
+ } else if let image {
+ continuation.resume(returning: image)
+ } else {
+ continuation.resume(throwing: PreloadError.invalidSvgData(key: key))
+ }
+ }
+ }
+
+ guard let pngData = image.pngData() else {
+ throw PreloadError.invalidImageData(key: key)
+ }
+
+ return pngData
+ }
+}
+
+private final class SvgNavigationDelegate: NSObject, WKNavigationDelegate {
+ var continuation: CheckedContinuation?
+
+ func webView(_: WKWebView, didFinish _: WKNavigation!) {
+ continuation?.resume()
+ continuation = nil
+ }
+
+ func webView(_: WKWebView, didFail _: WKNavigation!, withError error: Error) {
+ continuation?.resume(throwing: error)
+ continuation = nil
+ }
+
+ func webView(_: WKWebView, didFailProvisionalNavigation _: WKNavigation!, withError error: Error) {
+ continuation?.resume(throwing: error)
+ continuation = nil
}
}
diff --git a/packages/voltra/ios/shared/VoltraWidgetServerFetcher.swift b/packages/voltra/ios/shared/VoltraWidgetServerFetcher.swift
index 6a314f18..ebe006dd 100644
--- a/packages/voltra/ios/shared/VoltraWidgetServerFetcher.swift
+++ b/packages/voltra/ios/shared/VoltraWidgetServerFetcher.swift
@@ -137,7 +137,9 @@ public enum VoltraWidgetServerFetcher {
}
// Add Voltra-specific headers
- let systemVersion = UIDevice.current.systemVersion
+ let systemVersion = await MainActor.run {
+ UIDevice.current.systemVersion
+ }
request.setValue("application/json", forHTTPHeaderField: "Accept")
request.setValue("VoltraWidget/1.0 (iOS/\(systemVersion))", forHTTPHeaderField: "User-Agent")
diff --git a/packages/voltra/src/android/preload.ts b/packages/voltra/src/android/preload.ts
index e68a502a..ff90880d 100644
--- a/packages/voltra/src/android/preload.ts
+++ b/packages/voltra/src/android/preload.ts
@@ -4,8 +4,9 @@ import VoltraModule from '../VoltraModule.js'
/**
* Preload images to Android cache for use in Widgets.
*
- * Downloaded images are stored in the app's cache directory and exposed via FileProvider.
- * Images can then be referenced using the `assetName` property in the Image component.
+ * Downloaded bitmap images and rasterized SVGs are stored in the app's cache
+ * directory and exposed via FileProvider. Images can then be referenced using
+ * the `assetName` property in the Image component.
*
* @param images - Array of images to preload
* @returns Result indicating which images succeeded or failed
@@ -17,6 +18,12 @@ import VoltraModule from '../VoltraModule.js'
* url: 'https://example.com/album-art.jpg',
* key: 'current-album',
* headers: { 'Authorization': 'Bearer token' }
+ * },
+ * {
+ * key: 'status-icon',
+ * svg: '',
+ * width: 24,
+ * height: 24
* }
* ])
*
diff --git a/packages/voltra/src/preload.ts b/packages/voltra/src/preload.ts
index cc598848..1981ce4c 100644
--- a/packages/voltra/src/preload.ts
+++ b/packages/voltra/src/preload.ts
@@ -15,11 +15,11 @@ function assertIOS(name: string): boolean {
/**
* Preload images to App Group storage for use in Live Activities.
*
- * Downloaded images are stored in shared storage accessible by both the app
- * and the Live Activity widget extension. Images can then be referenced using
- * the `assetName` property in the Image component.
+ * Downloaded bitmap images and rasterized SVGs are stored in shared storage
+ * accessible by both the app and the Live Activity widget extension. Images can
+ * then be referenced using the `assetName` property in the Image component.
*
- * Images must be less than 4KB to comply with ActivityKit limits.
+ * Stored images must be less than 4KB to comply with ActivityKit limits.
*
* @param images - Array of images to preload
* @returns Result indicating which images succeeded or failed
@@ -31,6 +31,12 @@ function assertIOS(name: string): boolean {
* url: 'https://example.com/album-art.jpg',
* key: 'current-album',
* headers: { 'Authorization': 'Bearer token' }
+ * },
+ * {
+ * key: 'status-icon',
+ * svg: '',
+ * width: 24,
+ * height: 24
* }
* ])
*
diff --git a/website/docs/android/components/visual.md b/website/docs/android/components/visual.md
index 4ebca048..9e1a46e9 100644
--- a/website/docs/android/components/visual.md
+++ b/website/docs/android/components/visual.md
@@ -15,7 +15,7 @@ Displays text content.
### Image
-Displays bitmap images from the asset catalog or base64 encoded data.
+Displays bitmap images from the asset catalog, preloaded runtime cache, or base64 encoded data. SVGs should be rasterized through the image preloading API and referenced by `assetName`.
**Parameters:**
diff --git a/website/docs/android/development/image-preloading.md b/website/docs/android/development/image-preloading.md
index 7998acad..fe29408e 100644
--- a/website/docs/android/development/image-preloading.md
+++ b/website/docs/android/development/image-preloading.md
@@ -7,8 +7,9 @@ Android widgets have limitations when it comes to displaying remote images direc
The image preloading system on Android works by:
1. Downloading images from URLs to the internal app cache.
-2. Making these images available to Voltra widgets via the `assetName` property.
-3. Providing APIs to reload widgets when new images are ready.
+2. Rasterizing SVG inputs to PNG when needed.
+3. Making these images available to Voltra widgets via the `assetName` property.
+4. Providing APIs to reload widgets when new images are ready.
## API Reference
@@ -18,10 +19,13 @@ Downloads images to the Android cache for use in Widgets.
```typescript
type PreloadImageOptions = {
- url: string // The URL to download the image from
key: string // The assetName to use when referencing this image
+ url?: string // The URL to download the image from
+ svg?: string // Inline SVG markup to rasterize and cache as PNG
method?: 'GET' | 'POST' | 'PUT' // HTTP method (default: 'GET')
headers?: Record // Optional HTTP headers
+ width?: number // Required when rasterizing SVG
+ height?: number // Required when rasterizing SVG
}
type PreloadImagesResult = {
@@ -41,9 +45,15 @@ const result = await preloadImages([
key: 'current-album',
headers: { Authorization: 'Bearer token' },
},
+ {
+ key: 'status-icon-active',
+ svg: '',
+ width: 24,
+ height: 24,
+ },
])
-if (result.succeeded.includes('current-album')) {
+if (result.succeeded.includes('status-icon-active')) {
// Images are ready to be used in widgets
}
```
diff --git a/website/docs/ios/development/image-preloading.md b/website/docs/ios/development/image-preloading.md
index 70834f79..87b9d70d 100644
--- a/website/docs/ios/development/image-preloading.md
+++ b/website/docs/ios/development/image-preloading.md
@@ -17,14 +17,17 @@ The image preloading system works by:
### `preloadImages(images: PreloadImageOptions[]): Promise`
-Downloads images to App Group storage for use in Live Activities.
+Downloads bitmap images to App Group storage or rasterizes SVGs to PNG before storing them for use in Live Activities.
```typescript
type PreloadImageOptions = {
- url: string // The URL to download the image from
key: string // The assetName to use when referencing this image
+ url?: string // The URL to download the image from
+ svg?: string // Inline SVG markup to rasterize and cache as PNG
method?: 'GET' | 'POST' | 'PUT' // HTTP method (default: 'GET')
headers?: Record // Optional HTTP headers
+ width?: number // Required when rasterizing SVG
+ height?: number // Required when rasterizing SVG
}
type PreloadImagesResult = {
@@ -44,6 +47,12 @@ const result = await preloadImages([
key: 'current-song-artwork',
headers: { Authorization: 'Bearer token' },
},
+ {
+ key: 'status-icon-active',
+ svg: '',
+ width: 24,
+ height: 24,
+ },
])
console.log('Succeeded:', result.succeeded)
@@ -111,6 +120,7 @@ ActivityKit enforces a 4KB limit per Live Activity update. Images are validated
- **Content-Length header**: If available, images larger than 4KB are rejected before download
- **Actual size**: After download, the actual data size is validated
+- **SVG rasterization**: SVG inputs are converted to PNG before storage and the generated PNG is size-checked
- **Image validation**: Ensures the downloaded data is a valid image format
Images that exceed 4KB will result in a preload failure with a descriptive error message.
@@ -142,6 +152,8 @@ if (result.succeeded.length === 2) {
- `"Image 'key-name' is too large: 5120 bytes (max 4096 bytes for Live Activities)"` - Image exceeds 4KB limit
- `"Invalid image data for 'key-name'"` - Downloaded data is not a valid image
+- `"Invalid SVG data for 'key-name'"` - SVG markup is malformed or contains unsupported external/script references
+- `"SVG 'key-name' requires positive width and height"` - SVG rasterization needs explicit dimensions
- `"HTTP error: 404"` - Server returned an error status code
- `"App Group not configured"` - Missing App Group configuration in the config plugin
diff --git a/website/docs/ios/development/images.md b/website/docs/ios/development/images.md
index fba0145d..109308e9 100644
--- a/website/docs/ios/development/images.md
+++ b/website/docs/ios/development/images.md
@@ -4,7 +4,7 @@ Live Activities have strict size limits (4KB per update), making image handling
- **Base64 encoding**: Best for small, static images (< 1KB)
- **Build-time asset copying**: Best for medium-sized images that are known at build time
-- **Runtime preloading**: Best for dynamic images from remote URLs
+- **Runtime preloading**: Best for dynamic images from remote URLs or inline SVG data
## Base64 encoding
@@ -48,7 +48,7 @@ You can then reference these images using their assetName:
## Runtime preloading
-For dynamic images from remote URLs, use Voltra's image preloading API to cache images in App Group shared storage.
+For dynamic images from remote URLs or inline SVG markup, use Voltra's image preloading API to cache images in App Group shared storage. SVG inputs are rasterized to PNG before storage.
The image preloading system works by: