Widget reactivity: support on-device state changes without a server push

[burczu]

Problem

Voltra's current model resolves everything — colors, sizes, content — on the server into a static
JSON snapshot. The native side is a pure interpreter: it receives the snapshot and displays it.
SwiftUI and Glance both have reactive environment systems, but Voltra bypasses them entirely.

This means the following on-device state changes cannot be reflected in widgets without a new
server push:

• System appearance (dark/light mode, high contrast, reduced motion)
• Dynamic Type scale
• iOS widgetRenderingMode (fullColor / accented / vibrant) — required for Liquid Glass and accented rendering
• Android Material You dynamic color tokens
• User-configurable widget parameters (iOS AppIntentConfiguration on iOS 17+; Android Glance config activities)
• Time-based changes

The user-configurable parameter case is the hardest gap: when a user configures a widget in the
gallery, there is no server push — the widget process must render locally with the new parameter.
Today, Voltra has no mechanism for this on either platform.

Goal

Enable Voltra widgets to re-render in response to on-device state changes — primarily
user-configured parameters — without a server push and without an app update, while keeping the
RN-only developer experience (no Swift or Kotlin required from the developer).

Constraints

• Server-driven layout must remain intact where possible — it is Voltra's core value proposition
• Developer API stays in JSX + app.json; config plugin generates all platform-native boilerplate
• iOS-specific: no new linked dependencies in the widget extension (extension memory budget is ~30 MB; JSC is preferred because it is a system framework with zero binary cost)
• Android-specific: reuse Hermes if possible (already linked into every RN-on-Android app — zero added binary cost)

Context

The current server-driven JSON model has no mechanism for AppIntent / configurable-widget support
on either platform: when a user changes parameters, there is no server push, so the renderer has
nothing to apply the new values to. Each platform has its own architecture, so the approaches
explored on each are different — but the shared underlying claim is the same: some form of
on-device dynamic-value resolution is required, and we want to validate alternatives to natively-
interpreted opcode tuples (#130) and server-round-trip configurable widgets (#147).

Approaches explored — iOS

JSC-in-Extension (Track 2) — a thin JS resolver runs in the widget extension at render time.
Resolves {{ appIntent.X }} template expressions against current AppIntent parameters, then feeds
the resolved JSON into the existing Swift interpreter. Server retains layout control. Uses
JavaScriptCore (system framework — zero binary cost, no new linked dependency).

Build-Time Codegen (Track 3) — the Voltra component is compiled to self-contained SwiftUI at
build time by the config plugin. Full native reactivity, zero runtime overhead. Server can push
data props but not layout changes — an app update is required for structural changes.

A complementary iOS branch (Track 1, poc/widget-reactivity-track-1) addresses rendering
improvements that are independent of AppIntent reactivity: widgetAccentable prop support and
light-dark() CSS Color Level 4 syntax for adaptive text colors. It is a standalone concern that
can be merged separately and is not a prerequisite for either of the above approaches.

Approaches explored — Android

Hermes-in-Process (Track 4) — the same JS-resolver pattern as iOS Track 2, but adapted to
Android's architecture. Unlike iOS widget extensions, Glance widget updates run inside the main
app process via WorkManager — there is no sandboxed extension to slip a JS engine into. Instead,
Voltra instantiates a standalone Hermes runtime via a custom JNI/NDK wrapper, invoked from
VoltraGlanceWidget.provideGlance(). The shared JS bundle (same source as iOS Track 2) resolves
{{ appIntent.X }} placeholders against parameters stored in DataStore, populated by an in-app
UI (the PoC's stand-in for a future Glance configuration activity).

The architectural claim: one JS resolver bundle, two platforms, with strictly more expressiveness
than opcode tuples. PoC scope is narrow — prove engine integration and the reactivity loop. Does
not (yet) replace the native opcode-tuple resolver from #130 or add Glance configuration
activities (analog of #147).

Related

• Apple docs: Making a Configurable Widget
• Apple docs: Optimizing for Accented Rendering Mode and Liquid Glass
• Android docs: Glance — App widget configuration
• PoC branches: poc/widget-reactivity-track-1, poc/widget-reactivity-track-2, poc/widget-reactivity-track-3, poc/widget-reactivity-track-4

[burczu]

iOS findings recap

Note: This recap covers the iOS exploration only (Tracks 1–3). The Android exploration
(Track 4 — Hermes-in-process) is a separate, parallel investigation; findings will follow in a
later comment.

Both iOS approaches proved the primary exit criterion in simulator (2026-05-28):

A user changes an AppIntentConfiguration parameter → widget re-renders correctly,
no server push, no app update.

JSC-in-extension (#167): ✅ proved
Build-time codegen (#168): ✅ proved

---

Key tradeoff (iOS)

JSC-in-extension adds a thin JSC resolver in front of the existing Swift interpreter. The server
retains full control of the layout tree; AppIntent parameter substitution happens in JS on-device.
Server-driven layout is preserved.

Build-time codegen compiles layout to native SwiftUI at build time. Zero runtime overhead, full
native reactivity — but layout is baked into the binary. Structural changes require an app update.

Note on the earlier expo-widgets comparison

An earlier draft of this recap compared Track 3 to expo-widgets and quoted a "10-15% feature
parity" number, assuming expo-widgets translates JSX → Swift at build time. That was wrong:
expo-widgets actually runs JSX in JSC at the widget extension — architecturally closer to
Track 2 than to Track 3. Track 3 (build-time codegen) and expo-widgets are different
architectures, not partial implementations of each other.

Open items before either iOS approach ships

1. Memory budget on real device (JSC-in-extension) — JSC initialises at ~15–20 MB against a
   ~30 MB extension budget. Simulator RSS is meaningless (macOS shared framework mappings). Needs
   measurement on a physical device. A graceful fallback (degrade to static initial state on JSC
   init failure) should be considered.

2. widgetRenderingMode end-to-end example (JSC-in-extension) — payload format and resolver
   are in place, but no concrete per-mode style variants exist in the example yet.

3. light-dark() adaptation on real device (PoC: widgetAccentable prop + light-dark() color support (Track 1) #166) — the iOS simulator does not re-render
   widgets on appearance toggle; native widgets are equally unaffected, confirming this is a
   simulator limitation. LightDarkForeground: ShapeStyle (whose resolve(in:) is called by the
   rendering engine at draw time) is the correct approach and should be verified on a physical
   device running iOS 17+.

4. Android — covered separately in Track 4 (poc/widget-reactivity-track-4).

[burczu]

Android findings recap

Note: This recap covers the Android exploration (Track 4 — Hermes-in-process) only.
For the iOS Tracks 1–3 recap see the earlier comment.

Track 4 (#170) proved the primary exit criterion on Android emulator (2026-06-02):

A user changes a configured parameter → widget re-renders correctly, no server push,
no app update.

Hermes-in-process (branch poc/widget-reactivity-track-4): ✅ proved on emulator (x86_64)

The demo loop: open the Reactive Widget screen, type a city, tap Submit; the writes land in
DataStore and trigger a Glance update; the resolver picks them up and the widget re-renders with
the new value. Widgets without {{ appIntent. placeholders skip Hermes entirely via a fast-path
Kotlin check.

---

Measurements (emulator, x86_64, fresh process)

Stage	Time
Asset read (1,148 chars from APK)	0.53 ms
hermes::makeHermesRuntime() + bundle eval	3.70 ms
First resolve() call (full JNI round-trip)	0.29 ms
Total first reactive render overhead	~4.5 ms

Memory delta (dumpsys meminfo before/after first resolver init) stayed within ~1–2 MB GC noise
on a ~298 MB baseline RN PSS. Since RN already links libhermes.so for its bridge, the standalone
runtime shares the shared library cost — only the VM instance + bundle bytecode is marginal.

---

Architecture mirror of iOS Track 2

Dimension	Track 2 (iOS, JSC)	Track 4 (Android, Hermes)
Engine	JSC system framework	Hermes (already linked via RN)
Where it runs	Sandboxed extension process	Main app process via WorkManager
Memory budget	~30 MB extension cap (tight)	App process budget (much higher)
Engine instantiation	Public JSContext Cocoa API	Custom JNI wrapper required
Native code in repo	None (Cocoa API only)	~200 lines C++/JNI
Native maintenance burden	Negligible	NDK + Hermes ABI tracking

The shared JS bundle source (@use-voltra/android-renderer, ~1.1 KB IIFE) is identical to the iOS
counterpart — same template-substitution logic, same globalThis.VoltraRenderer.resolve API.

---

Open items before Track 4 ships

1. Real-device arm64 numbers. Emulator x86_64 figures are a lower bound, not a substitute
   for production hardware. Cold-start and memory should be re-captured on an arm64 device.

2. Glance configuration activity (Android analog of feat: configurable widgets (iOS 17+) #147). The PoC uses an in-app TextInput
   stand-in for the parameter source. A real shipping feature would add a proper Glance config
   activity that writes to the same DataStore.

3. Package rename if both Tracks 2 and 4 land. @use-voltra/android-renderer and
   @use-voltra/ios-renderer should collapse to a single @use-voltra/widget-renderer at merge
   time (cosmetic chore, deferred from the PoC).

4. Performance comparison vs feat: resolvable dynamic values for widgets #130's opcode-tuple resolver. Resolving {{ appIntent.X }}
   via Hermes (~0.3 ms steady state) vs evaluating opcode tuples natively — worth a head-to-head
   measurement before deciding which approach should win on Android.