0045. Native output is ReactLynx, written against an engine adapter
- Status: Proposed
- Date: 2026-11-14
- Decided by: native emit domain (internal only), pending Mik's approval
- Planning item: WP10 (native output)
Context
duolith build --target native has to turn the same Screen IR the web emitter reads into code a phone runs. The plan names Lynx as the engine. Lynx offers ReactLynx (React components over Lynx elements, run on its background thread with a first render on its main thread) and a lower level element API. Whatever the choice, the compiled views must not tie the language to it: decision 0004 confines an engine to one package, so it can be swapped without touching the compiler's output format more than it must.
Decision
- The engine is Lynx, through ReactLynx. The emitter writes TSX that ReactLynx's build (rspeedy with
pluginReactLynx) bundles intomain.lynx.bundle, the file the iOS and Android shells load. - Views see only the adapter.
packages/engine/adapter.d.tsis the contract: one primitive per element (Screen, View, Text, Button, Image, Input, TextArea, List, Scroll, Form, Toggle, Checkbox, Slider, Progress, Icon, Overlay, Group), their props, the theme and the look types. The package's JSX runtime declares no intrinsic elements, so the emitted code type-checks only if it uses the adapter;packages/engine/srcimplements it on Lynx elements and is the only code that imports@lynx-js/*(tools/boundaries.yaml). - What one source file becomes. A page, layout or component turns into
<module>.setup.js(its script and expression functions, the same rewrite the web emitter does, types stripped), a.setup.d.ts, and<module>.tsx(a function component that runs setup once per instance withuseSetupand draws withx.view(() => ...)). Kit parts the app uses are compiled the same way intosrc/kit/.src/routes.ts,src/theme.ts,src/theme.css,src/index.tsx, atsconfig.jsonandduolith-native.jsoncomplete the build. - The runtime is shared. Signals, effects, the router's matching and guards come from
@duolith/client; itsnativeentry adds the instance (useSetup,pass,slot,track,rows) and a router that keeps a stack of screens in a state cell instead of the browser's history. - Styles become looks. Each style table entry becomes a list of rules, weakest first: the conditions it needs (interaction states,
dark, a minimum window width, a rank for state rules) and its declarations with every token resolved, for light mode and, where a token differs, for dark. The theme's colour scheme is applied at build time (always light drops dark rules, always dark resolves to dark values). Logical sides become physical ones and the web's line-clamp recipe becomes onelineClamp. The adapter picks the rules that hold on each draw; nothing is matched by selector on the device. - Base looks are classes. Each primitive's own look (a button centres its content, an input has a border) is a
st-<element>class in the generatedtheme.css, imported first, so a utility's inline style always wins over it, as the web's:where()base styles lose to utilities.<style>blocks compile to scoped classes as on the web. - **Dark mode is the
colorSchemeglobal prop.** The shells passlightordark; the adapter setsduolith-darkon the app's root and chooses dark values for looks.
Alternatives considered
| Option | Why not |
|---|---|
| Lynx's element API directly | Every element, update and list would be hand-written in the emitter; ReactLynx already diffs and schedules |
Emit Lynx elements (<view>, <text>) in the views | Ties the output to Lynx; the adapter would be documentation, not a boundary |
| Resolve looks to CSS classes, as on the web | Lynx's CSS subset drops :focus-visible, :hover, :not and color-mix(); state and dark rules would need selectors it does not have |
| Share the script rewrite with the web emitter now | Moving it into a shared crate touches crates/emit-web, outside this work; it was duplicated in emit-native until it moved to crates/script (decision 0047) |
| React Native | Not the plan's engine, and its runtime is larger than the language needs |
Consequences
- The native emitter and the web emitter must be kept in step by hand until the rewrite moves to a shared crate.
- A change to
adapter.d.tsis a change to the compiler's output contract: every snapshot inpackages/engine/test/snapshots/is re-type-checked against it. - Swapping the engine means a new
packages/engine/src, not a new emitter.