From 09dbb9df8385caff751f2e05b2ce0580779045ef Mon Sep 17 00:00:00 2001
From: Maciej Lodygowski <maciej.lodygowski@callstack.com>
Date: Wed, 6 May 2026 14:42:56 +0200
Subject: [PATCH] feat: add SVG support to image preloading

---
 .changeset/orange-ways-invite.md              |   7 +
 .../android/AndroidImagePreloadingScreen.tsx  | 167 ++++++++++++-
 .../testing-grounds/ImagePreloadingScreen.tsx | 146 +++++++++++-
 packages/android/src/types.ts                 |  15 +-
 packages/ios/src/types.ts                     |  15 +-
 packages/voltra/.prettierignore               |   5 +
 packages/voltra/android/build.gradle          |   4 +
 .../src/main/java/voltra/VoltraModule.kt      |  22 +-
 .../java/voltra/images/VoltraImageManager.kt  | 223 +++++++++++++-----
 .../voltra/images/VoltraImageManagerTest.kt   |  47 ++++
 .../src/test/resources/robolectric.properties |   1 +
 packages/voltra/ios/Voltra.podspec            |   1 +
 .../voltra/ios/app/VoltraImagePreload.swift   | 205 +++++++++++++++-
 .../shared/VoltraWidgetServerFetcher.swift    |   4 +-
 packages/voltra/src/android/preload.ts        |  11 +-
 packages/voltra/src/preload.ts                |  14 +-
 website/docs/android/components/visual.md     |   2 +-
 .../android/development/image-preloading.md   |  18 +-
 .../docs/ios/development/image-preloading.md  |  16 +-
 website/docs/ios/development/images.md        |   4 +-
 20 files changed, 833 insertions(+), 94 deletions(-)
 create mode 100644 .changeset/orange-ways-invite.md
 create mode 100644 packages/voltra/.prettierignore
 create mode 100644 packages/voltra/android/src/test/java/voltra/images/VoltraImageManagerTest.kt
 create mode 100644 packages/voltra/android/src/test/resources/robolectric.properties

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 `
+<svg viewBox="0 0 48 48" xmlns="http://www.w3.org/2000/svg">
+  <rect width="48" height="48" rx="12" fill="${color}"/>
+  <path d="M15 25.5l6.2 6.2L34 17" stroke="white" stroke-width="5" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
+`
+}
+
+function AndroidSvgWidgetContent({ assetKey, color }: { assetKey: string; color: string }) {
+  return (
+    <VoltraAndroid.Box
+      style={{
+        padding: 14,
+        backgroundColor: '#1E293B',
+        borderRadius: 16,
+        flex: 1,
+      }}
+    >
+      <VoltraAndroid.Column horizontalAlignment="center-horizontally" verticalAlignment="center-vertically">
+        <VoltraAndroid.Image source={{ assetName: assetKey }} style={{ width: 42, height: 42 }} resizeMode="contain" />
+
+        <VoltraAndroid.Spacer style={{ height: 10 }} />
+
+        <VoltraAndroid.Text maxLines={1} style={{ fontSize: 16, fontWeight: 'bold', color: '#FFFFFF' }}>
+          SVG preload
+        </VoltraAndroid.Text>
+        <VoltraAndroid.Text maxLines={1} style={{ fontSize: 12, color: '#CBD5E1' }}>
+          {color}
+        </VoltraAndroid.Text>
+
+        <VoltraAndroid.Spacer style={{ height: 14 }} />
+
+        <VoltraAndroid.Text maxLines={2} style={{ fontSize: 11, color: '#94A3B8', textAlign: 'center' }}>
+          Preloaded SVG asset
+        </VoltraAndroid.Text>
+      </VoltraAndroid.Column>
+    </VoltraAndroid.Box>
+  )
+}
+
 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<AndroidSvgOption | null>(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: <AndroidSvgWidgetContent assetKey={option.key} color={option.color} />,
+        },
+      ])
+      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 (
     <View style={styles.container}>
       <ScrollView style={[styles.scrollView]} contentContainerStyle={styles.content}>
@@ -165,6 +263,41 @@ export default function AndroidImagePreloadingScreen() {
           <Button title="Clear Images" variant="secondary" onPress={handleClearImages} />
         </View>
 
+        <View style={styles.section}>
+          <Text style={styles.sectionTitle}>SVG Widget Test</Text>
+          <Text style={styles.sectionText}>
+            Preload an inline SVG as a PNG asset and update the Android image preloading widget to render it.
+          </Text>
+
+          <View style={styles.buttonRow}>
+            <Button
+              title={isSvgProcessing ? 'Updating...' : ANDROID_SVG_OPTIONS.green.title}
+              variant={selectedSvgOption?.key === ANDROID_SVG_OPTIONS.green.key ? 'primary' : 'secondary'}
+              style={selectedSvgOption?.key === ANDROID_SVG_OPTIONS.green.key ? styles.greenButtonSelected : undefined}
+              onPress={() => handleShowSvgWidget(ANDROID_SVG_OPTIONS.green)}
+              disabled={isSvgProcessing}
+            />
+            <Button
+              title={ANDROID_SVG_OPTIONS.purple.title}
+              variant={selectedSvgOption?.key === ANDROID_SVG_OPTIONS.purple.key ? 'primary' : 'secondary'}
+              style={
+                selectedSvgOption?.key === ANDROID_SVG_OPTIONS.purple.key ? styles.purpleButtonSelected : undefined
+              }
+              onPress={() => handleShowSvgWidget(ANDROID_SVG_OPTIONS.purple)}
+              disabled={isSvgProcessing}
+            />
+          </View>
+
+          {selectedSvgOption ? (
+            <View style={styles.previewContainer}>
+              <Text style={styles.inputLabel}>Preview</Text>
+              <VoltraWidgetPreview key={selectedSvgOption.key} family="mediumWide" style={styles.widgetPreview}>
+                <AndroidSvgWidgetContent assetKey={selectedSvgOption.key} color={selectedSvgOption.color} />
+              </VoltraWidgetPreview>
+            </View>
+          ) : null}
+        </View>
+
         <View style={styles.footer}>
           <Button title="Back to Android Home" variant="ghost" onPress={() => router.push('/android-widgets')} />
         </View>
@@ -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 `
+<svg viewBox="0 0 48 48" xmlns="http://www.w3.org/2000/svg">
+  <rect width="48" height="48" rx="12" fill="${color}"/>
+  <path d="M15 25.5l6.2 6.2L34 17" stroke="white" stroke-width="5" fill="none" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
+`
+}
+
+function SvgWidgetContent({ assetKey, color }: { assetKey: string; color: string }) {
+  return (
+    <Voltra.LinearGradient
+      colors={['#101828', '#1D2939']}
+      start={{ x: 0, y: 0 }}
+      end={{ x: 1, y: 1 }}
+      style={{ flex: 1 }}
+    >
+      <Voltra.VStack style={{ flex: 1, padding: 16 }}>
+        <Voltra.HStack alignment="center" spacing={10}>
+          <Voltra.Image source={{ assetName: assetKey }} resizeMode="contain" style={{ width: 48, height: 48 }} />
+          <Voltra.VStack spacing={3}>
+            <Voltra.Text style={{ color: '#FFFFFF', fontSize: 16, fontWeight: '700' }}>SVG preload</Voltra.Text>
+            <Voltra.Text style={{ color: '#D0D5DD', fontSize: 12 }}>{color}</Voltra.Text>
+          </Voltra.VStack>
+        </Voltra.HStack>
+
+        <Voltra.Spacer />
+
+        <Voltra.Text style={{ color: '#98A2B3', fontSize: 11 }}>Rendered from a preloaded SVG asset</Voltra.Text>
+      </Voltra.VStack>
+    </Voltra.LinearGradient>
+  )
+}
+
 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<string | null>(null)
+  const [isSvgProcessing, setIsSvgProcessing] = useState(false)
+  const [selectedSvgOption, setSelectedSvgOption] = useState<SvgOption | null>(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: <SvgWidgetContent assetKey={option.key} color={option.color} />,
+        systemMedium: <SvgWidgetContent assetKey={option.key} color={option.color} />,
+        systemLarge: <SvgWidgetContent assetKey={option.key} color={option.color} />,
+      }
+
+      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 (
     <ScrollView style={styles.container}>
       <View style={[styles.scrollView, styles.content]}>
@@ -127,6 +222,39 @@ export default function ImagePreloadingScreen() {
           </View>
         </Card>
 
+        <Card>
+          <Card.Title>SVG Widget Test</Card.Title>
+          <Card.Text>
+            Preload an inline SVG as a PNG asset and update the iOS Weather widget to render it with Voltra.Image.
+          </Card.Text>
+
+          <View style={styles.buttonRow}>
+            <Button
+              title={isSvgProcessing ? 'Updating...' : SVG_OPTIONS.green.title}
+              variant={selectedSvgOption?.key === SVG_OPTIONS.green.key ? 'primary' : 'secondary'}
+              style={selectedSvgOption?.key === SVG_OPTIONS.green.key ? styles.greenButtonSelected : undefined}
+              onPress={() => handleShowSvgWidget(SVG_OPTIONS.green)}
+              disabled={isSvgProcessing}
+            />
+            <Button
+              title={SVG_OPTIONS.purple.title}
+              variant={selectedSvgOption?.key === SVG_OPTIONS.purple.key ? 'primary' : 'secondary'}
+              style={selectedSvgOption?.key === SVG_OPTIONS.purple.key ? styles.purpleButtonSelected : undefined}
+              onPress={() => handleShowSvgWidget(SVG_OPTIONS.purple)}
+              disabled={isSvgProcessing}
+            />
+          </View>
+
+          {selectedSvgOption ? (
+            <View style={styles.previewContainer}>
+              <Text style={styles.inputLabel}>Preview</Text>
+              <VoltraWidgetPreview key={selectedSvgOption.key} family="systemMedium" style={styles.widgetPreview}>
+                <SvgWidgetContent assetKey={selectedSvgOption.key} color={selectedSvgOption.color} />
+              </VoltraWidgetPreview>
+            </View>
+          ) : null}
+        </Card>
+
         <View style={styles.footer}>
           <Link href="/testing-grounds" asChild>
             <Button title="Back to Testing Grounds" variant="ghost" />
@@ -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<string, string>
 }
 
+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<string, string>
 }
 
+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<String, String>
 
-                                    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<String, String>? = 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<String, String>?,
+        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("<svg")
+    }
+
+    private fun rasterizeSvg(
+        key: String,
+        svgMarkup: String,
+        width: Int?,
+        height: Int?,
+    ): ByteArray {
+        val svgSize = svgMarkup.toByteArray(Charsets.UTF_8).size
+        require(svgSize < MAX_SVG_SIZE_BYTES) {
+            "SVG '$key' is too large: $svgSize bytes (max $MAX_SVG_SIZE_BYTES bytes)"
+        }
+
+        validateSvg(key, svgMarkup)
+
+        val svg = SVG.getFromString(svgMarkup)
+        val renderWidth = width ?: ceil(svg.documentWidth.toDouble()).toInt()
+        val renderHeight = height ?: ceil(svg.documentHeight.toDouble()).toInt()
+
+        require(renderWidth > 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("<svg")) { "Invalid SVG data for '$key'" }
+        require(
+            !lower.contains("<script") &&
+                !lower.contains("javascript:") &&
+                !lower.contains("<iframe") &&
+                !lower.contains("<object") &&
+                !lower.contains("<embed") &&
+                !lower.contains("href=\"http") &&
+                !lower.contains("href='http") &&
+                !lower.contains("xlink:href=\"http") &&
+                !lower.contains("xlink:href='http"),
+        ) {
+            "Invalid SVG data for '$key'"
+        }
+    }
+
     private fun deleteFileForKey(
         key: String,
         cacheDir: File,
diff --git a/packages/voltra/android/src/test/java/voltra/images/VoltraImageManagerTest.kt b/packages/voltra/android/src/test/java/voltra/images/VoltraImageManagerTest.kt
new file mode 100644
index 00000000..a3b46d68
--- /dev/null
+++ b/packages/voltra/android/src/test/java/voltra/images/VoltraImageManagerTest.kt
@@ -0,0 +1,47 @@
+package voltra.images
+
+import android.graphics.BitmapFactory
+import android.net.Uri
+import kotlinx.coroutines.runBlocking
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.RuntimeEnvironment
+
+@RunWith(RobolectricTestRunner::class)
+class VoltraImageManagerTest {
+    @Test
+    fun preloadsInlineSvgAsPng() =
+        runBlocking {
+            val context = RuntimeEnvironment.getApplication()
+            val manager = VoltraImageManager(context)
+
+            val key =
+                manager.preloadImage(
+                    key = "svg_icon",
+                    svg =
+                        """
+                        <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+                          <rect width="24" height="24" fill="#ff0000"/>
+                        </svg>
+                        """.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("<svg")
+  }
+
+  private static func validateSvg(_ svg: String, key: String) throws {
+    let trimmed = svg.trimmingCharacters(in: .whitespacesAndNewlines)
+    let lowercased = trimmed.lowercased()
+
+    guard lowercased.contains("<svg") else {
+      throw PreloadError.invalidSvgData(key: key)
+    }
+
+    if lowercased.contains("<script") ||
+      lowercased.contains("javascript:") ||
+      lowercased.contains("<iframe") ||
+      lowercased.contains("<object") ||
+      lowercased.contains("<embed") ||
+      lowercased.contains("href=\"http") ||
+      lowercased.contains("href='http") ||
+      lowercased.contains("xlink:href=\"http") ||
+      lowercased.contains("xlink:href='http")
+    {
+      throw PreloadError.invalidSvgData(key: key)
+    }
+  }
+
+  @MainActor
+  private static func rasterizeSvg(_ svg: String, key: String, width: Int?, height: Int?) async throws -> 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 = """
+    <!doctype html>
+    <html>
+      <head>
+        <meta name="viewport" content="width=\(width), height=\(height), initial-scale=1.0">
+        <style>
+          html, body {
+            margin: 0;
+            padding: 0;
+            width: \(width)px;
+            height: \(height)px;
+            overflow: hidden;
+            background: transparent;
+          }
+          svg { display: block; width: \(width)px; height: \(height)px; }
+        </style>
+      </head>
+      <body>\(svg)</body>
+    </html>
+    """
+
+    try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, Error>) 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<UIImage, Error>) 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<Void, Error>?
+
+  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: '<svg viewBox="0 0 24 24">...</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: '<svg viewBox="0 0 24 24">...</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<string, string> // 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: '<svg viewBox="0 0 24 24"><path fill="#34C759" d="..." /></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<PreloadImagesResult>`
 
-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<string, string> // 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: '<svg viewBox="0 0 24 24"><path fill="#34C759" d="..." /></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: