0046. The native output is verified without a device, and a checklist covers the rest
- Status: Proposed
- Date: 2026-11-14
- Decided by: native emit domain (internal only), pending Mik's approval
- Planning item: WP10 (native output), WP09 (CI)
Context
CI and the cloud workspaces have no phones, no Android SDK and no Mac. The native output still has to be checked on every change, and what cannot be checked has to be written down rather than assumed.
Decision
- Snapshots.
packages/engine/test/native-output.test.tsbuilds every example withduolith build --target nativeand compares the emitted files withpackages/engine/test/snapshots/<example>.snap(kit parts are kept only in the snapshots of the examples about the kit; the theme's icon drawings are left out).UPDATE_SNAPSHOTS=1accepts a change; in CI a missing snapshot fails. - Type-checked against the adapter. The same test runs
tscon each build againstadapter.d.tsand the runtime's types, and checks the build imports nothing but@duolith/engine,@duolith/client,@duolith/effects(when the app uses effects, decision 0050) and its own files. - A real Lynx bundle.
test/bundle.test.tsbuilds examples/minimal and examples/kit with Lynx's own build intomain.lynx.bundle. - Lynx for Web.
scripts/preview.tsbundles a build for Lynx for Web and serves it with Lynx's viewer page;test/native-in-browser.test.tsdrives examples/control-flow in Chromium (filters, a toggle, adding a todo). It is the same views, adapter and runtime as on a phone, drawn by a different renderer. - Fail, not skip, in CI. Without the
duolithbinary or Playwright these tests skip on a contributor's machine and fail whenCIis set. - **
native/DEVICE-CHECKLIST.md** lists what needs a device: building the shells, every example on both platforms, screen readers, feel, and the known gaps. Nothing on it is claimed done until a person has done it.
Alternatives considered
| Option | Why not |
|---|---|
| Emulators in CI | Needs the Android SDK and hardware acceleration; slow and flaky for what it would add now |
| Only snapshots | A snapshot shows the output did not change, not that it works |
| Screenshots compared pixel by pixel | Lynx for Web's text shaping differs from the phones'; a pixel diff would test the browser |
Consequences
- The snapshots are large (about 740 KB in all) and change with any emitter or kit change; reviewers read their diffs.
- A green CI says the output is well-formed, type-correct and runs in Lynx for Web; it says nothing about a phone.