feat: server-driven Dynamic Widgets

[V3RON]

Implements ADR 0002. Stacked on #266, which adds the ADR; review and merge that first, and this retargets to main. Closes #176.

What is this?

A widget that wants fresh data without the app running has had one option: serverUpdate on a payload-driven widget, where the server runs Voltra's JSX renderer and returns a full UI payload. That rules out any backend not written in Node, the fetch is GET-only, and the URL is frozen at build time with no way to tell the server which account or range the widget wants.

Giving a widget both entry and serverUpdate now makes it a server-driven Dynamic Widget: the device fetches a plain JSON object from the configured URL and passes it to the bundled JS as props. Rendering stays on the device and the server never sees a component tree, so a hand-written PHP script is enough.

serverUpdate in app.json also becomes a set of defaults rather than the final word. setWidgetServerUpdate lets an app change the URL, interval, method, query, headers and body at runtime — per widget or for all of them, for both render engines — and turn fetching off entirely to drive a widget itself.

How does it work?

entry decides how a widget renders and serverUpdate decides where its data comes from, so the two keys together select one of four providers on iOS and receivers on Android. That choice is made once, when the native project is generated; no runtime code asks whether a widget is server-driven.

Both engines read their settings through one resolver per platform, composed of four layers stacked in a fixed order — app.json config, the deprecated credentials, global runtime settings, per-widget runtime settings. headers and query merge per key; everything else takes the value from the most specific layer that sets it. That rule lives in the resolver and nowhere else, and the same code builds every request, which is what gives payload widgets runtime URLs and non-GET methods too. Everything per widget is keyed by a WidgetScope rather than a bare id, so per-instance fetches can be added later without changing callers.

Every fetch is fetch, parse, trial-render, commit. Props are rendered once off screen before they are committed, so a response the widget cannot draw leaves the last good one on screen rather than blanking the widget. A body that is not a JSON object is rejected, and one shaped like a Voltra payload is rejected by name, since pointing a widget with an entry at a payload endpoint is the mistake sharing the config key invites. ETag, Cache-Control: max-age and Retry-After are honoured, clamped to what each platform can schedule.

Widgets see the outcome on env.serverUpdate — status, fetchedAt, error, httpStatus — so they can show "updated 3 min ago", dim when the data is stale, or hide the freshness line while the app has taken them over. That is the only change to the existing Dynamic render path: an environment seam the plain engine leaves empty.

On Android the work runs in the app process through WorkManager and never pushes RemoteViews; drawing stays in VoltraClientGlanceWidget. On iOS the new timeline provider wraps the existing one, keeping placeholder and getSnapshot off the network.

Why is this useful?

Any backend can drive a widget now, in any language, by returning the data it already has instead of learning Voltra's renderer. Per-tenant deployments can ship a widget with no URL at all and supply one after login. An app can point a widget at a different endpoint, add an auth header, or take the widget over entirely without a rebuild.

Payload widgets get the same runtime settings, ETag revalidation and locale parameter without any config change, and keep their existing request and schedule when no runtime settings are set.

[Angelk90]

@V3RON :

if I have:

a)

// app.json
{
  "url": "https://api.example.com/portfolio",
  "intervalMinutes": 30
}

b)

setWidgetServerUpdate(
  {
    url: "https://customer.example.com/portfolio",
    intervalMinutes: 60
  },
  { widgetId: "portfolio" }
)

Who has the highest priority?

Scenario:

1. I open an app and then close it, so it should have a higher priority of b)

2. I restart the smartphone, so it should have a higher priority of a), because I haven't opened any apps, so it should remain the default value.

Am I wrong?

[V3RON]

@V3RON :

if I have:

a)

// app.json
{
  "url": "https://api.example.com/portfolio",
  "intervalMinutes": 30
}

b)

setWidgetServerUpdate(
  {
    url: "https://customer.example.com/portfolio",
    intervalMinutes: 60
  },
  { widgetId: "portfolio" }
)

Who has the highest priority?

Scenario:

1. I open an app and then close it, so it should have a higher priority of b)
2. I restart the smartphone, so it should have a higher priority of a), because I haven't opened any apps, so it should remain the default value.

Am I wrong?

The in-app overwrite is locally persisted and has greater priority than the defaults set in app.json.