Epic: Alternative Interface Renderers (Swift, Kotlin, React)

[mikewolfd]

Motivation

Formspec's core engine runs in TypeScript/WASM. The web component (<formspec-render>) is one rendering surface, but real-world apps need native and framework-specific renderers. The "Alternative Interface Renderers" initiative creates three such surfaces — iOS/macOS (SwiftUI), Android (Jetpack Compose), and React — so apps can consume formspec definitions without the web component.

Architecture Overview

All three renderers share the same three-layer architecture pattern:

1. Bridge — Connects to formspec-engine (WASM). Swift and Kotlin use a hidden WebView loading a shared HTML bundle with esbuild'd JS + inlined WASM, communicating via typed JSON messages. React imports formspec-engine directly and bridges signals via useSyncExternalStore.
2. State — Reactive state layer native to each platform. Swift uses @Observable, Kotlin uses Compose State/StateFlow, React uses hooks (useField, useForm, etc.).
3. Renderer — Component map pattern: a default set of native UI components that render the LayoutNode tree, overridable by the consumer for "bring your own components."

The shared HTML bundle and EngineCommand/EngineEvent message protocol should be extracted to packages/formspec-bridge/ so Swift and Kotlin reference a single source of truth.

Sub-Tasks

• formspec-swift: SwiftUI renderer for iOS/macOS #5 — formspec-swift: SwiftUI renderer (iOS/macOS)
• formspec-kotlin: Jetpack Compose renderer for Android #6 — formspec-kotlin: Jetpack Compose renderer (Android)
• formspec-react: React hooks + auto-renderer #7 — formspec-react: React hooks + auto-renderer (COMPLETE)
• formspec-adapters: Tailwind CSS adapter reference implementation #8 — formspec-adapters: Tailwind CSS adapter reference implementation

Key Shared Artifacts

Artifact	Location	Consumers
HTML bridge bundle	packages/formspec-bridge/ (to be extracted)	Swift, Kotlin
EngineCommand/EngineEvent protocol	Shared JSON message shapes	Swift, Kotlin
formspec-engine WASM	packages/formspec-engine/	All three (React direct, Swift/Kotlin via WebView)
Component map pattern	Per-renderer	All three

Acceptance Criteria

• All three renderers can load a formspec definition and render a functional form
• Each renderer has its own test suite (unit + integration)
• Swift and Kotlin share the same HTML bridge bundle
• React hooks provide full engine access without the web component
• Component maps are overridable in all three renderers
• Tailwind adapter validates the behavior/adapter split works for utility-first CSS frameworks