Duolith docs

0047. On native, the engine plays screen transitions and places anchored overlays, and the build makes up for CSS that Lynx drops

  • Status: Proposed
  • Date: 2026-11-14
  • Decided by: native emit domain (internal only), pending Mik's approval
  • Planning item: WP10 (native output)

Context

The first native output (decision 0045) swapped screens with no movement, did not hear Android's back button, placed menus and popovers at a fixed spot, drew every list as plain views, and stroked icons in the ink colour. Lynx also drops CSS the kit relies on: color-mix(), :hover, :focus-visible, :focus-within, attribute selectors such as [data-state="open"], and display: contents. Without a device, Lynx for Web in Chromium is the check (decision 0046).

Decision

  • A stack in the engine. The adapter gains Stack (front, leaving, kind), linkKind and followLinks(href, kind). The native router in @duolith/client keeps the leaving screen until the engine says the movement is over. A link inside a page pushes; a link in a layout, such as a tab, switches. Push and pop slide, while switch and replace fade. These are CSS keyframes in packages/engine/src/stack.css, so there is no platform navigation container. A swipe from the leading edge goes back.
  • Back. The shells send the duolithBack global event for the system back button. The engine gives it to the newest back handler: an open overlay that can be dismissed, then the stack. When nothing takes it, the engine calls NativeModules.DuolithShell.leave(), which the Android shell implements.
  • Lists that recycle. A <list> that is a screen's own child turns the screen into Lynx's <list>. The screen's other children become full-span items, and each row becomes an item. A list anywhere else stays plain views inside the scrolling around it, because a nested <list> has no height of its own.
  • Anchored overlays. A popover, menu, list box or tooltip whose anchor names an element id is measured with the engine's boundingClientRect once it is laid out. It is then placed by placement.ts, which follows the web's rules (flip, shift, cap the height). It stays hidden until it has been placed.
  • Icons take the text colour. View, Button and Text pass their text colour to what they hold. That colour comes from their look, or from a style-block class that sets color by itself, which the build registers with registerInks. An icon strokes its SVG in its own colour if it has one, otherwise in that passed colour, otherwise in the ink token.
  • CSS fallbacks at build time (crates/emit-native/src/css.rs):
    • color-mix() of theme or hex colours is mixed in sRGB for light and for dark into --mix-* custom properties on .duolith-app.
    • [data-name="value"] becomes .st-name-value, which the engine sets (st-state-open, st-detent-*).
    • display: contents is left out.
    • In a selector list, the selectors with :hover or :focus-* are left out, so Lynx keeps the rest of the rule instead of dropping it whole.
    • A project's own hover: utilities warn with E0200. Its own :hover, :focus-visible and :focus-within selectors warn with E0201. Kit parts do not warn.
  • Keys. Lynx reports only a field's return key. It reaches the form's on:key as Enter, and then the form is sent.
  • One script rewrite. crates/script holds the setup-script rewrite and type stripping that emit-web and emit-native both use.

Consequences

  • All of this is checked in Chromium through Lynx for Web (packages/engine/test/native-in-browser.test.ts, test/placement.test.ts and the css.rs tests). Feel, frame rate, the hardware back button and predictive back still need a device (native/DEVICE-CHECKLIST.md).
  • An icon does not get a colour set by a descendant selector (.destructive .item-icon). The Menu's Delete icon is muted on native.
  • Screens animate in the engine rather than in UINavigationController or a Fragment back stack. If a device shows this is not good enough, a later decision can move the stack to the platform behind the same Stack primitive.