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),linkKindandfollowLinks(href, kind). The native router in@duolith/clientkeeps 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 inpackages/engine/src/stack.css, so there is no platform navigation container. A swipe from the leading edge goes back. - Back. The shells send the
duolithBackglobal 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 callsNativeModules.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
anchornames an element id is measured with the engine'sboundingClientRectonce it is laid out. It is then placed byplacement.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
colorby itself, which the build registers withregisterInks. 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: contentsis left out.- In a selector list, the selectors with
:hoveror: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-visibleand:focus-withinselectors warn with E0201. Kit parts do not warn.
- Keys. Lynx reports only a field's return key. It reaches the form's
on:keyasEnter, and then the form is sent. - One script rewrite.
crates/scriptholds 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.tsand 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
Stackprimitive.