Voltra

Voltra

Use this as the single Voltra skill entrypoint. Keep all product-wide ground truth here and load references from references/ as needed.

Voltra-Wide Ground Truth

• Never generate native platform UI code for Voltra tasks. Use Voltra JSX and Voltra JS APIs.
• Do not generate Swift, Kotlin, Java, Objective-C, or platform XML unless the user explicitly asks to edit an existing Voltra-supported Android widget preview XML file.
• Always solve Voltra tasks through Voltra JavaScript or TypeScript APIs, JSX components, and the Expo config plugin first.
• If a task appears to require native code, first check whether Voltra already exposes a JS API or config option. Prefer that path.
• Do not scaffold native extension code manually. Voltra's config plugin owns native target setup.
• Do not use plain React Native primitives inside Voltra-rendered trees. Avoid View, Text, Pressable, TouchableOpacity, and similar RN UI primitives for Live Activity or Android widget content.
• For iOS app code, import Voltra and runtime APIs from @use-voltra/ios-client.
• For Android app code, import VoltraAndroid and runtime APIs from @use-voltra/android-client.
• Keep iOS and Android authoring paths separate unless the user explicitly asks for a shared abstraction.
• Update config before writing registration-dependent UI code.
• Treat images as a Voltra concern, not a native-code concern. Prefer Voltra image props, Voltra asset directories, and Voltra preloading APIs.
• When guidance conflicts, prefer this skill's internal references first, then hosted docs on use-voltra.dev.
• Use hosted docs on https://use-voltra.dev when deeper documentation is needed.

Reference Routing

Read only the references needed for the current task:

• Setup, install, Expo Dev Client, expo prebuild: references/setup.md
• app.json, app.config.*, plugin keys, widget registration, groupIdentifier, enablePushNotifications: references/app-config.md
• Exact plugin fields and widget registration schema: references/plugin-schema.md
• iOS Live Activities, Dynamic Island, lock screen variants, supplemental activity families: references/ios-live-activities.md
• Exact Live Activity variant shapes: references/variant-shapes.md
• iOS Home Screen widgets, accessory widgets, scheduled widgets, widget timelines, widget families, VoltraWidgetPreview, updateWidget, scheduleWidget, reloadWidgets, getActiveWidgets: references/ios-widgets.md
• Exact iOS widget families and fallback behavior: references/widget-families.md
• Charts for iOS widgets, Live Activities, and Android widgets: references/charts.md
• Android widgets, Android widget previews, pre-rendering, widget updates: references/android-widgets.md
• Server-driven widgets, serverUpdate, widget polling flows, createWidgetUpdateHandler, setWidgetServerCredentials, clearWidgetServerCredentials: references/server-driven-widgets.md
• Android component choices and widget API checklist: references/component-mapping.md, references/runtime-api-checklist.md
• APNS, push tokens, push-to-start, channel IDs, server-rendered Live Activity payloads: references/ios-server-updates.md and usually references/ios-live-activities.md
• Exact APNS flow details: references/push-flow.md
• Image handling for Voltra surfaces: references/images.md plus the target surface reference

Working Style

1. Identify the target platform and surface first. 2. Confirm the correct Voltra namespace and JS entrypoint. 3. If the task involves charts, verify the public JSX props and platform behavior before writing code or docs. 4. Update config before writing registration-dependent UI code. 5. Read only the domain references needed for the task. 6. Use Voltra APIs that already exist in the repo before inventing new abstractions. 7. Keep answers scoped to the requested platform.

Reference Index

• references/source-of-truth.md
• references/images.md
• references/setup.md
• references/app-config.md
• references/plugin-schema.md
• references/ios-live-activities.md
• references/variant-shapes.md
• references/ios-widgets.md
• references/widget-families.md
• references/charts.md
• references/android-widgets.md
• references/server-driven-widgets.md
• references/component-mapping.md
• references/runtime-api-checklist.md
• references/ios-server-updates.md
• references/push-flow.md

Android Widgets

Use this reference for Android Voltra widget UI or Android widget runtime APIs.

Domain Rules

• Use VoltraAndroid for Android Voltra UI.
• For Android app code, import VoltraAndroid and runtime APIs from @use-voltra/android-client.
• Do not use Voltra.VStack, Voltra.HStack, or plain React Native primitives inside Android Voltra widget trees.
• Do not claim APNS or undocumented FCM server-update support for Android.
• If the task includes widget registration, picker previews, or initial state files, also read app-config.md.
• If the task includes serverUpdate, WorkManager-driven refreshes, widget auth credentials, or createWidgetUpdateHandler, also read server-driven-widgets.md.
• For images, use VoltraAndroid.Image with build-time assetNames or preloaded keys. Use preloadImages, reloadWidgets, and clearPreloadedImages from @use-voltra/android-client.

Preferred APIs

• updateAndroidWidget
• reloadAndroidWidgets
• clearAndroidWidget
• clearAllAndroidWidgets
• requestPinAndroidWidget
• getActiveWidgets
• VoltraWidgetPreview
• VoltraView
• preloadImages
• reloadWidgets
• clearPreloadedImages
• setWidgetServerCredentials
• clearWidgetServerCredentials

Sources

• component-mapping.md
• runtime-api-checklist.md
• server-driven-widgets.md

App Config

Use this reference for Voltra plugin configuration.

Domain Rules

• Update app.json or app.config.* before writing widget code that depends on registration, previews, or initial state files.
• For iOS push updates, require enablePushNotifications: true.
• For Android widgets, define them under android.widgets in the Voltra plugin config.
• For server-driven widgets, configure serverUpdate on the widget entry itself and rebuild after config changes.
• Only mention preview XML when the user is explicitly editing an existing Android widget preview layout supported by Voltra.
• Do not invent unsupported plugin keys.
• If the task is about iOS image preloading, check whether groupIdentifier is needed for the intended Voltra surface and storage flow.
• If the task is about authenticated iOS server-driven widgets, check whether keychainGroup is needed for shared credentials.

Working Rules

• iOS-oriented plugin keys live at the top level of the Voltra plugin config.
• Android widget registration lives under android.widgets.
• Use groupIdentifier when the app needs extension data sharing or forwarded interactions.
• Use keychainGroup when iOS widgets need authenticated server-driven updates and the default derived group is not sufficient.
• If the task includes iOS widget UI or supportedFamilies, also read ios-widgets.md.
• If the task includes Android widget UI, also read android-widgets.md.
• If the task includes iOS server updates, also read ios-server-updates.md.
• If the task includes serverUpdate, widget polling, or widget auth credentials, also read server-driven-widgets.md.

Sources

• plugin-schema.md

Charts

Use this reference for Voltra chart UI, chart docs, or chart API questions.

Domain Rules

• Verify chart behavior against the public JSX props and the platform renderer before changing docs or examples.
• Keep chart guidance user-facing. Explain when to use a mark or prop, not how the native renderer works, unless the constraint changes what users can do.
• Mark components must be direct children of Chart.
• Use Voltra.Chart from @use-voltra/ios-client for iOS chart UI.
• Use VoltraAndroid.Chart from @use-voltra/android-client for Android chart UI.
• If the task involves widget or Live Activity layout around a chart, also read the relevant platform widget reference.

iOS Support

• Available in iOS widgets and Live Activities.
• SectorMark requires iOS 17+.
• Chart supports:
• xAxisVisibility
• yAxisVisibility
• xAxisGridStyle
• yAxisGridStyle
• legendVisibility
• foregroundStyleScale
• BarMark supports grouped bars with stacking="grouped".
• LineMark and AreaMark support interpolation.
• LineMark and PointMark support symbols.
• Do not document chartScrollableAxes as a supported user-facing prop for iOS charts unless the implementation is restored.

Android Support

• Available in Android widgets.
• Charts are rendered to a bitmap and shown in the widget.
• Chart supports:
• xAxisVisibility
• yAxisVisibility
• xAxisGridStyle with visibility-only behavior
• yAxisGridStyle with visibility-only behavior
• foregroundStyleScale
• Do not document legendVisibility as supported on Android charts.
• LineMark and AreaMark support interpolation.
• PointMark renders circular markers on Android.
• SectorMark supports ratio-based radii and fixed radii values greater than 1.
• Grouped bars are supported with stacking="grouped". Do not claim other stacking modes unless the renderer supports them.

Verification Targets

• Public JSX props:
• src/jsx/Chart.tsx
• src/android/jsx/Chart.tsx
• src/jsx/BarMark.tsx
• src/jsx/LineMark.tsx
• src/jsx/AreaMark.tsx
• src/jsx/PointMark.tsx
• src/jsx/RuleMark.tsx
• src/jsx/SectorMark.tsx
• src/android/jsx/BarMark.tsx
• src/android/jsx/LineMark.tsx
• src/android/jsx/AreaMark.tsx
• src/android/jsx/PointMark.tsx
• src/android/jsx/RuleMark.tsx
• src/android/jsx/SectorMark.tsx
• Native implementations:
• ios/ui/Views/VoltraChart.swift
• android/src/main/java/voltra/glance/renderers/ChartRenderers.kt
• android/src/main/java/voltra/glance/renderers/ChartBitmapRenderer.kt

Component Mapping

Prefer these Android Voltra primitives over iOS or React Native UI primitives:

• VoltraAndroid.Column instead of Voltra.VStack
• VoltraAndroid.Row instead of Voltra.HStack
• VoltraAndroid.Box instead of layered RN View trees
• VoltraAndroid.Text instead of RN Text
• VoltraAndroid.Image instead of RN Image
• VoltraAndroid.Scaffold for top-level Android widget layouts
• VoltraAndroid.Spacer for spacing
• Android-specific controls when needed:
• Button
• FilledButton
• OutlineButton
• CircleIconButton
• SquareIconButton
• Switch
• CheckBox
• RadioButton

Avoid these in Android Voltra UI:

• Voltra.VStack
• Voltra.HStack
• RN View
• RN Text
• RN Pressable
• Native Glance/Kotlin implementations

Hosted docs: see source-of-truth.md.

Images

Voltra supports three image paths:

• build-time assets
• runtime preloading
• base64 for very small generated images

Build-Time Assets

Use build-time assets when the image is known at build time.

• iOS: place files under assets/voltra/
• Android: place files under assets/voltra-android/

Reference bundled assets with assetName.

Examples:

• iOS: <Voltra.Image source={{ assetName: 'logo.png' }} />
• Android: <VoltraAndroid.Image source={{ assetName: 'logo' }} />

Android notes:

• Android resource names are sanitized to lowercase underscore names.
• Do not include the file extension in Android assetName.

Runtime Preloading

Use preloading when the image comes from a remote URL or runtime data.

• iOS preloading API: preloadImages, reloadLiveActivities, clearPreloadedImages from @use-voltra/ios-client
• Android preloading API: preloadImages, reloadWidgets, clearPreloadedImages from @use-voltra/android-client

After preloading, reference the image with the same key via assetName.

Platform Rules

• iOS Live Activities and iOS widgets use Voltra.Image.
• Android widgets and Android live updates use VoltraAndroid.Image.
• iOS image preloading depends on App Group-backed shared storage, so config tasks may also need groupIdentifier.
• Android image preloading uses app cache plus Voltra's local delivery path; do not invent a native image pipeline.

Base64

Use base64 only for very small inline images. Prefer build-time assets or preloading for anything non-trivial.

Sources

• source-of-truth.md

iOS Live Activities

Use this reference for iOS Live Activity UI or lifecycle APIs.

Domain Rules

• Use Voltra and runtime APIs such as useLiveActivity, startLiveActivity, updateLiveActivity, stopLiveActivity, and addVoltraListener from @use-voltra/ios-client.
• Do not use VoltraAndroid or Android widget primitives in iOS Live Activity code.
• Use valid iOS variant keys: lockScreen, island, and supplementalActivityFamilies.
• For images, use Voltra.Image with either a bundled assetName or a preloaded image key. Use preloadImages and reloadLiveActivities from @use-voltra/ios-client for runtime images.
• If the task involves APNS, push tokens, push-to-start, channel IDs, or backend-driven updates, also read ios-server-updates.md.

Preferred APIs

• useLiveActivity
• startLiveActivity
• updateLiveActivity
• stopLiveActivity
• endAllLiveActivities
• addVoltraListener
• VoltraView
• VoltraLiveActivityPreview

Sources

• variant-shapes.md

iOS Server Updates

Use this reference for APNS-driven Live Activity updates only.

Domain Rules

• This flow is iOS-only.
• This reference is for Live Activities, not Home Screen widgets using serverUpdate.
• Require enablePushNotifications: true in the Voltra plugin config.
• Use Voltra event APIs from @use-voltra/ios-client to collect tokens.
• Use @use-voltra/ios-server to render Live Activity payloads.
• Use Voltra-generated UI JSON in APNS payloads.
• Do not extrapolate this APNS flow to Android unless Voltra provides a documented JS API and guide for that exact use case.
• If the task is about widget polling, createWidgetUpdateHandler, or setWidgetServerCredentials, read server-driven-widgets.md instead.
• If the task also defines or changes Live Activity UI, also read ios-live-activities.md.

Preferred APIs

• addVoltraListener
• startLiveActivity
• useLiveActivity
• renderLiveActivityToString
• Voltra from @use-voltra/ios-server

Sources

• push-flow.md

iOS Widgets

Use this reference for iOS widget UI, scheduled widgets, widget families, or iOS widget runtime APIs.

Domain Rules

• Use Voltra and widget APIs such as updateWidget, scheduleWidget, reloadWidgets, clearWidget, clearAllWidgets, getActiveWidgets, and VoltraWidgetPreview from @use-voltra/ios-client.
• Do not use VoltraAndroid or Android widget primitives in iOS widget code.
• Widget registration lives in the Voltra plugin config. If the task includes widgets, supportedFamilies, or initialStatePath, also read app-config.md.
• If the task includes serverUpdate, widget polling intervals, widget auth credentials, or createWidgetUpdateHandler, also read server-driven-widgets.md.
• VoltraWidgetPreview is a React Native preview component for app screens, not a Voltra widget primitive to nest inside widget JSX.
• Use scheduleWidget for timeline-based or scheduled widget updates instead of inventing background schedulers or native WidgetKit code.
• Use serverUpdate plus a Voltra server handler for remote widget content instead of inventing custom WidgetKit networking or native extension code.
• For images, use Voltra.Image with bundled assetNames or preloaded keys. If shared image resources change, use reloadWidgets.

Preferred APIs

• VoltraWidgetPreview
• updateWidget
• scheduleWidget
• reloadWidgets
• clearWidget
• clearAllWidgets
• getActiveWidgets
• WidgetFamily
• setWidgetServerCredentials
• clearWidgetServerCredentials

Sources

• widget-families.md

Plugin Schema

Voltra plugin config lives under expo.plugins.

Common Top-Level Keys

• groupIdentifier
• enablePushNotifications
• liveActivity
• widgets
• fonts
• android
• deploymentTarget
• targetName

iOS Widget Schema

Use top-level widgets for iOS widget gallery registration.

• id: unique identifier, use alphanumeric and underscores only
• displayName (string or per-locale map)
• description (string or per-locale map)
• supportedFamilies: array of iOS families such as systemSmall, systemMedium, systemLarge
• initialStatePath (string or per-locale map of paths for localized pre-render)
• serverUpdate.url: widget endpoint, Voltra appends widgetId, platform=ios, and family
• serverUpdate.intervalMinutes: polling interval, default 15, subject to WidgetKit throttling

Other important Apple-side keys:

• groupIdentifier: needed for shared storage, forwarded interactions, and image preloading
• enablePushNotifications: required for APNS-driven Live Activity updates
• deploymentTarget: widget extension deployment target
• targetName: custom Apple widget extension target name
• keychainGroup: shared credential group for authenticated server-driven widgets; auto-derived when omitted and iOS widgets use serverUpdate

Android Widget Schema

Use android.widgets for Android widget registration.

• id: unique identifier, use alphanumeric and underscores only
• displayName (string or per-locale map)
• description (string or per-locale map)
• targetCellWidth
• targetCellHeight
• minCellWidth
• minCellHeight
• minWidth
• minHeight
• resizeMode
• widgetCategory
• initialStatePath (string or per-locale map of paths)
• serverUpdate.url: widget endpoint, Voltra appends widgetId and platform=android
• serverUpdate.intervalMinutes: polling interval; use at least 15 minutes
• previewImage
• previewLayout

Decision Rules

• If the task asks for Apple widget gallery registration or supportedFamilies, stay in config first and then read ios-widgets.md.
• If the task asks for Android widget picker metadata, stay in config first and then read android-widgets.md.
• If the task asks for pre-rendered initial widget content, add initialStatePath and then move to the target widget reference.
• If the task asks for APNS-driven Live Activity updates, ensure enablePushNotifications is present and then move to ios-server-updates.md.
• If the task asks for iOS image preloading or shared extension images, check groupIdentifier before moving on to UI code.
• If the task asks for widget polling, widget SSR endpoints, or widget auth credentials, configure serverUpdate first and then move to server-driven-widgets.md.

Hosted Docs

Consult source-of-truth.md for the canonical hosted doc list.

Push Flow

Use this flow for iOS Live Activity server-driven updates:

1. Enable enablePushNotifications: true in the Voltra plugin config. 2. Start the Live Activity or subscribe to token events in the app. 3. Capture Voltra push tokens with addVoltraListener from @use-voltra/ios-client. 4. Send the token or channel identifier to your backend. 5. Render the Live Activity UI payload with renderLiveActivityToString from @use-voltra/ios-server. 6. Send the APNS request with the Voltra-generated UI JSON in the payload.

Important concepts:

• Update token: update an existing Live Activity.
• Push-to-start token: start a Live Activity remotely.
• channelId: subscribe to broadcast updates on supported iOS versions.
• APNS headers must match Live Activity requirements.
• Keep payloads small.

Use these sources first:

• source-of-truth.md
• https://use-voltra.dev/ios/development/server-side-updates
• https://use-voltra.dev/ios/development/events
• https://use-voltra.dev/ios/api/configuration

Do not extend this flow to Android unless new repo docs and APIs clearly support it.

Runtime API Checklist

Use Android-specific Voltra widget APIs when possible.

Widget runtime entrypoint:

• @use-voltra/android-client

Use these for widgets:

• updateAndroidWidget
• reloadAndroidWidgets
• clearAndroidWidget
• clearAllAndroidWidgets
• requestPinAndroidWidget
• getActiveWidgets
• VoltraWidgetPreview
• VoltraView
• preloadImages
• reloadWidgets
• clearPreloadedImages

Do not claim a full Android server-push architecture unless the task is directly supported by current Voltra JS APIs and docs.

Server-driven Widgets

Use this reference for Voltra widgets that fetch content from your server on a schedule.

Domain Rules

• This flow is for Home Screen widgets, not APNS Live Activity updates.
• Configure serverUpdate in the Voltra plugin config before writing widget server code.
• Rebuild native apps after adding or changing serverUpdate, keychainGroup, or widget registration.
• iOS: createIOSWidgetUpdateNodeHandler from @use-voltra/ios-server. Android: createAndroidWidgetUpdateNodeHandler from @use-voltra/android-server. Cross-platform HTTP: @use-voltra/server.
• Use setWidgetServerCredentials after login and clearWidgetServerCredentials on logout when the endpoint requires auth.
• If the endpoint is public, skip credential storage entirely.
• Keep render paths platform-specific: renderIos returns iOS WidgetVariants; renderAndroid returns Android size variants.
• Keep a meaningful initialStatePath so the widget has placeholder content before the first successful fetch.

Request and Response Rules

• Voltra appends widgetId and platform to every request.
• iOS requests also include family.
• WidgetRenderRequest includes widgetId, platform, family, token, and headers.
• If validateToken is provided, missing or invalid bearer tokens should reject with 401.
• Return null from the platform render function to produce 404 for unsupported widget IDs or unavailable content.

Platform Notes

• iOS widgets are polled by WidgetKit. Treat intervals below about 15 minutes as advisory because the OS may throttle them.
• Android widgets are scheduled through WorkManager. Use at least 15 minutes and set the interval explicitly.
• On iOS, authenticated server-driven widgets may need keychainGroup so the widget extension can read credentials. If omitted, Voltra auto-derives a default when any iOS widget uses serverUpdate.
• On Android emulators, local servers usually need 10.0.2.2 instead of localhost.

Preferred APIs

• createWidgetUpdateHandler
• createWidgetUpdateNodeHandler
• createWidgetUpdateExpressHandler
• setWidgetServerCredentials
• clearWidgetServerCredentials
• reloadWidgets

Sources

• ios-widgets.md
• android-widgets.md
• app-config.md
• plugin-schema.md

Setup

Use this reference when the task is about bootstrapping or installation.

Domain Rules

• Voltra is not supported in Expo Go. Use Expo Dev Client or a native build.
• Install @use-voltra/ios-client and/or @use-voltra/android-client, then configure the matching Expo plugins and run expo prebuild.
• If setup also requires widget registration or push settings, also read app-config.md.

Setup Flow

1. Install @use-voltra/ios-client and/or @use-voltra/android-client. 2. Add @use-voltra/ios-client and/or @use-voltra/android-client to app.json or app.config.*. 3. For iOS, ensure the deployment target meets Voltra's minimum supported version. 4. Run expo prebuild for the target platform. 5. Continue with the relevant platform reference.

Sources

• source-of-truth.md
• https://use-voltra.dev/ios/setup
• https://use-voltra.dev/android/setup

Source Of Truth

Use this file as the compact local source of truth for Voltra behavior. For deeper documentation, use hosted docs on use-voltra.dev.

Hosted docs to use for guidance:

• https://use-voltra.dev/ios/setup
• https://use-voltra.dev/android/setup
• https://use-voltra.dev/ios/development/developing-live-activities
• https://use-voltra.dev/ios/development/developing-widgets
• https://use-voltra.dev/ios/development/images
• https://use-voltra.dev/ios/development/image-preloading
• https://use-voltra.dev/ios/development/server-side-updates
• https://use-voltra.dev/android/development/developing-widgets
• https://use-voltra.dev/android/development/images
• https://use-voltra.dev/android/development/image-preloading
• https://use-voltra.dev/android/api/plugin-configuration

Core facts:

• iOS app install: @use-voltra/ios-client (re-exports Voltra and runtime APIs)
• Android app install: @use-voltra/android-client (re-exports VoltraAndroid and runtime APIs)
• iOS server rendering entrypoint: @use-voltra/ios-server
• Android server rendering entrypoint: @use-voltra/android-server
• Cross-platform widget HTTP handlers: @use-voltra/server
• iOS Expo plugin: @use-voltra/ios-client
• Android Expo plugin: @use-voltra/android-client

Default rule:

• Install only the @use-voltra/* client packages you need for app runtime code.
• Widget initialStatePath modules run in Node during prebuild: import from @use-voltra/ios or @use-voltra/android, not the -client packages.
• Use use-voltra.dev for documentation lookups.

Variant Shapes

Use these iOS Live Activity shapes.

Minimal lock screen only

const variants = {
  lockScreen: <Voltra.Text>Hello</Voltra.Text>,
}

Dynamic Island shape

const variants = {
  island: {
    minimal: <Voltra.Text>M</Voltra.Text>,
    compact: {
      leading: <Voltra.Text>L</Voltra.Text>,
      trailing: <Voltra.Text>T</Voltra.Text>,
    },
    expanded: {
      leading: <Voltra.Text>L</Voltra.Text>,
      trailing: <Voltra.Text>T</Voltra.Text>,
      center: <Voltra.Text>C</Voltra.Text>,
      bottom: <Voltra.Text>B</Voltra.Text>,
    },
  },
}

Supplemental families

const variants = {
  supplementalActivityFamilies: {
    small: <Voltra.Text>ETA 12 min</Voltra.Text>,
  },
}

Hosted docs: see source-of-truth.md.

Widget Families

Use these iOS widget families when defining WidgetVariants:

• systemSmall
• systemMedium
• systemLarge
• systemExtraLarge
• accessoryCircular
• accessoryRectangular
• accessoryInline

Working rules:

• Build widget content with Voltra.* components.
• Use VoltraWidgetPreview from @use-voltra/ios-client to preview widget content in React Native screens.
• Use updateWidget for immediate updates.
• Use scheduleWidget for timeline-based or scheduled widget updates. This is the correct Voltra API for predictable future widget content changes on iOS.
• Use Voltra.Image for widget images. Bundled assets and preloaded image keys are both referenced through assetName.
• Use reloadWidgets after changing shared resources such as preloaded images.
• Use getActiveWidgets to inspect installed widget instances.

Plugin reminder:

• iOS widget registration is configured in the Voltra plugin under widgets.
• supportedFamilies controls the sizes exposed in the widget gallery.
• If registration or family support changes are part of the task, also read app-config.md.

Hosted docs: see source-of-truth.md.