The original

Voltra · React Native (Expo)

A Callstack-incubated open-source library. JSX → JSON → SwiftUI/Glance.
~32,500 LoC across 7 packages, an Expo config plugin, and native modules.

The pipeline (unchanged)

// JS side
<Voltra.VStack>
  <Voltra.Text>Order #42</Voltra.Text>
</Voltra.VStack>
    ↓
renderLiveActivityToString()
    ↓
'{"type":"VStack","children":[…]}'
    ↓  // crosses bridge
// Native side (Swift/Kotlin)
VoltraParser.parse(json) → SwiftUI.View

This is the key insight. The bridge is small. Almost everything else is shared.

Why it works

Voltra's components only use createElement and hooks: never ReactDOM, never platform-specific APIs.

renderLiveActivityToString() walks the React element tree and serializes nodes to JSON. The element tree is the same shape no matter which createElement produced it.

What it unlocks

100% Layer 0 reuse via plain npm. No fork, no wrapper, no shim.

// In a Lynx .tsx file:
import { Voltra } from '@use-voltra/ios'

<Voltra.VStack style={{ padding: '16px' }}>
  <Voltra.Text>Order #42</Voltra.Text>
</Voltra.VStack>
// → traverses, serializes, native parses → SwiftUI ✨

The component

// Lynx-side
<voltra-preview
  width="170"
  height="170"
  payload={renderWidgetToString(jsx)}
/>

The native registration

LynxUIRegister.register(
  "voltra-preview",
  VoltraPreviewHostView.self
)

What it does

Renders Voltra SwiftUI inline inside the Lynx app, not on the home screen, not in the lock screen. Makes the Testing Grounds screens show actual SwiftUI output instead of JSON dumps.

Wraps a UIHostingController on iOS / ComposeView on Android, subscribes to width prop changes from Lynx, re-renders SwiftUI on payload mutations.

9 testing-ground screens converted live SwiftUI in-app

The 4 PRDs

Why it works

A user story is a cache-friendly unit of agent work, small enough to fit in one context window, with explicit acceptance criteria the agent can self-verify against.

The (US-XXX) commit suffix becomes a permanent audit trail: run git log --oneline | grep US-053 and you find the Positioning Screen conversion in one line.

Cost of context drift drops to zero, each story is a fresh start with the PRD as ground truth.

$ git log --oneline | grep 'US-0' | wc -l
       61

The principles

+ Translation tables

| Expo Pattern | Lynx Equivalent |
| AsyncFunction(...)
        → @LynxMethod fun(... callback: Callback)
| requireNativeModule<T>
        → createModuleAdapter<T>(NativeModules…)
| sendEvent(name)
        → lynxContext.sendGlobalEvent("voltra:" + name)
| Platform.OS → __PLATFORM__ build constant

The compounding effect

When a new agent dispatches on a fresh story, it doesn't have to discover how the bridge works. It reads three things, CLAUDE.md, LYNX_PORT.md, the relevant PRD section, and produces code that matches the architecture.

Personal CLAUDE.md additionally captures lessons from past mistakes:

The hand-off file

.claude/ralph-loop.local.md

---
active: true
iteration: 6
max_iterations: 0     # unbounded
started_at: "2026-04-26T13:19:56Z"
---

Implement the Voltra Lynx Android port following the
PRD at tasks/prd-voltra-lynx-android.md.
The JS bridge layer is already complete.
Scaffold Android host app with Sparkling,
implement VoltraLynxModule.kt, verify all 5 Android
demos work end-to-end. Follow LYNX_PORT.md
architectural principles strictly.

What Ralph contributed

Why it works here

The architectural seam was already proven on iOS. Android is the same problem with a different vocabulary, exactly the kind of predictable, parallel work loop-style agents excel at.

Pattern: stand up a strong harness on platform A by hand, let the loop port to platform B.

This very deck, agents used

The economics

Anthropic's prompt cache has a 5-minute TTL. Sleeping past 300s on the main thread means reading the full context uncached, slow and expensive.

Sub-agents don't share that cache, so dispatching them costs nothing extra, and the main thread keeps moving while they work.

Rule of thumb: if 2+ tasks are independent (no shared state, no sequential dependency), they should run in parallel.

// Single message · 3 tool calls
<Agent description="loc audit" />
<Agent description="narrative" />
<Bash command="find ..." />

skills/voltra/ · 17 reference docs

The agent loads SKILL.md on relevant triggers and pulls deeper references on demand. Tribal knowledge → committed file → reusable.

~/.claude/projects/.../memory/

Per-project memory directory with typed entries: user, feedback, project, reference.

When a session learns something durable, “the iOS host uses CocoaPods Lynx 3.7.0, not the internal template”, it writes a memory. The next session reads it on boot.

The result: a session in week 4 inherits the breakthroughs of week 1 without paying for them again.

memory/
├── MEMORY.md                # index
├── lynx-host-setup.md       # project
├── css-gotchas.md           # reference
└── react-alias-pattern.md   # reference

Principle 1

说不清解决什么问题的改动，就不该做

If you can't name a specific, reproducible bug, don't change it. “More robust” and “more standard” are not reasons.

Born from: vue-lynx migration, a “cleaner” path-resolve refactor that introduced a new pnpm-symlink bug.

Principle 2

Don't mechanically port upstream patterns.

Ask: what does this pattern depend on? Does my environment satisfy that premise?

Born from: lynx-stack vs vue-lynx, same pattern, different architecture; the pattern didn't transfer.

Principle 3

Don't intuit “pre-existing” errors.

git stash first. If the error reproduces on the parent commit, it's pre-existing. Otherwise: you caused it.

Born from: a build error blamed on the upstream, that was actually introduced by the very change being verified.

Principle 4

Compile ≠ works. Test the user path.

pnpm build green + pnpm test green ≠ shippable. Run the example end-to-end. Pack the npm package. Open the app.

Born from: a migration where unit tests passed but the example app build broke at runtime.