Duolith docs

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.ts builds every example with duolith build --target native and compares the emitted files with packages/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=1 accepts a change; in CI a missing snapshot fails.
  • Type-checked against the adapter. The same test runs tsc on each build against adapter.d.ts and 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.ts builds examples/minimal and examples/kit with Lynx's own build into main.lynx.bundle.
  • Lynx for Web. scripts/preview.ts bundles a build for Lynx for Web and serves it with Lynx's viewer page; test/native-in-browser.test.ts drives 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 duolith binary or Playwright these tests skip on a contributor's machine and fail when CI is 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

OptionWhy not
Emulators in CINeeds the Android SDK and hardware acceleration; slow and flaky for what it would add now
Only snapshotsA snapshot shows the output did not change, not that it works
Screenshots compared pixel by pixelLynx 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.