PoC: JS-in-extension AppIntent reactivity (Track 2)

[burczu]

Closes #165

Summary

Proof-of-concept for making Voltra widgets reactive to AppIntentConfiguration parameter changes
without a server push, by running a thin JS resolver inside the widget extension using JavaScriptCore.

The JS layer sits in front of the existing Swift interpreter — it does not replace it. Server-driven
layout is fully preserved; only AppIntent parameter substitution happens on-device.

server push (VoltraNode tree)
    ↓
JS resolver in extension (JSC — resolves {{ appIntent.X }})
    ↓
resolved VoltraNode tree
    ↓
existing Swift interpreter (unchanged)

JavaScriptCore was chosen over Hermes: it is a system framework — zero binary size cost, no new
native dependency, available in widget extensions without any linking changes.

Developer experience

A developer creating a reactive widget writes no Swift. The workflow:

1. Write a JSX component using appIntentParam():

   import { Voltra, appIntentParam } from 'voltra'
   
   export const MyWidget = () => (
     <Voltra.VStack style={{ flex: 1, padding: 16 }}>
       <Voltra.Text style={{ fontSize: 22, color: 'primary' }}>
         {appIntentParam('city')}
       </Voltra.Text>
     </Voltra.VStack>
   )

2. Add an appIntent block to app.json:

   {
     "id": "reactive",
     "appIntent": {
       "parameters": [{ "name": "city", "title": "City", "default": "New York" }]
     }
   }

3. Run expo prebuild — the config plugin generates the full Swift boilerplate and copies
   the resolver bundle into the Xcode Resources phase automatically.

appIntentParam('city') returns {{ appIntent.city }}, which passes through the server renderer
unchanged and is resolved locally at render time.

What was built

Artifact	Location	Purpose
@use-voltra/ios-renderer	packages/ios-renderer/	894 B JS bundle — resolves {{ appIntent.X }}
appIntentParam()	packages/ios/src/app-intent.ts	Developer API
VoltraJSRenderer	packages/voltra/ios/shared/VoltraJSRenderer.swift	JSC evaluation layer — lazy singleton, NSLock thread safety
VoltraReactiveSupport	packages/voltra/ios/shared/VoltraReactiveSupport.swift	Shared Swift helpers for generated widget code
Config plugin extension	packages/expo-plugin/src/ios-widget/files/swift.ts	Generates AppIntent Swift from appIntent config
JS bundle copy	packages/expo-plugin/src/ios-widget/files/index.ts	Copies resolver bundle to extension on prebuild
E2E tests	packages/ios-renderer/src/__tests__/resolve.node.test.ts	10 tests: resolution, passthrough, round-trip

Exit criterion — proved in simulator (2026-05-28)

• AppIntent reactivity: user-configured parameters re-render the widget without a server push ✅
• Zero Swift required from the developer ✅
• Server-driven layout preserved ✅

Not yet proved (requires real device)

• JSC initialisation within the widget extension's ~30 MB memory budget
• Cold-start latency of JSC + bundle evaluation on first render

Implementation gotchas

1. Intent struct must not be private — AppIntents metadata extraction silently skips private
   types at build time. The widget stays permanently in placeholder state with no crash or log.
   Generated struct uses internal access.

2. Shared stylesheet must travel with the family node — The Voltra compact JSON format stores
   the shared style array at the payload root ("s": [...]); individual nodes reference styles by
   index. Extracting only the family-specific subtree drops the "s" array, making all style
   references unresolvable. Fix: copy "s" and "e" from root into the extracted family object,
   mirroring VoltraHomeWidget.reconstructWithSharedData.

Test plan

• npm run test -w @use-voltra/ios-renderer — 10 unit tests pass
• expo prebuild in example/ — Swift generated, bundle copied to Resources
• Build in Xcode — BUILD SUCCEEDED
• Add reactive widget in simulator → configure city → widget re-renders with new value