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
• widgetRenderingMode (fullColor / accented / vibrant) — required for Liquid Glass and accented rendering
• AppIntentConfiguration user parameters (widget gallery configuration, iOS 17+)
• Time-based changes

The AppIntentConfiguration case is a hard blocker: when a user configures a widget in the gallery,
there is no server push — the extension must render locally with the new parameter. Today, Voltra
has no mechanism for this.

Goal

Enable Voltra widgets to re-render in response to AppIntentConfiguration parameter changes
without a server push and without an app update, while keeping the RN-only developer experience
(no Swift required from the developer).

Constraints

• Server-driven layout must remain intact where possible — it is Voltra's core value proposition
• No new native dependencies in the widget extension (no Hermes linking)
• Developer API stays in JSX + app.json; config plugin generates all Swift boilerplate

Context

The current server-driven JSON model has no mechanism for AppIntent support: when a user
configures a widget in the gallery there is no server push, so the extension has nothing to render
the new parameter value with. Two approaches were evaluated to close this gap:

JSC-in-Extension — a thin JS resolver runs in the extension at render time. Resolves
{{ appIntent.X }} template expressions against current device state, then feeds the resolved
JSON into the existing Swift interpreter. Server retains layout control.

Build-Time Codegen — 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 branch (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.

Related

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

[burczu]

Both 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

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.

Codegen gap vs expo-widgets

The codegen approach reaches approximately 10–15% of expo-widgets feature parity. The gap is
architectural: expo-widgets translates JSX → Swift directly (1:1 primitive mapping), preserving
conditional logic and component composition. The codegen approach goes JSX → Voltra JSON → Swift;
the JSON prerender discards JSX-level structure before the translator ever sees the tree. Closing
this gap would require reimplementing a large portion of expo-widgets' JSX analysis.

Open items before either 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 — out of scope for all tracks. Glance would require a separate effort.