Duolith docs

0049. A native build honours each feature or stops with an error, and says how a style opts out of a phone

  • Status: Proposed
  • Date: 2026-11-14
  • Decided by: native emit domain (internal only), pending Mik's approval
  • Planning item: WP10 (native output), review of PR #22 and its re-review
  • Amends: 0047 (its CSS fallbacks and its E0200/E0201 warnings)

Context

Decision 0047 made up for some of the CSS that Lynx drops, and warned about hover: and :hover in a project's own files. The kit was exempt. The review of PR #22 found that this left many features quietly broken on a phone:

  • the kit TabBarItem's [aria-current] colour;
  • Badge's color-mix(in oklab, …);
  • [data-state='open'] with single quotes;
  • display: contents with no ; after it;
  • the properties Lynx's encoder strips (backdrop-filter, user-select, outline-offset, text-underline-offset and others);
  • href on text, icons and images;
  • on:key on a plain view;
  • on:focus on a button;
  • an image's zoomable and on:dismiss;
  • a sheet's detent drag.

A warning nobody reads does not stop such a build from shipping.

To see what Lynx drops, probe CSS was bundled through @lynx-js/rspeedy and its log was read:

  • Properties. The encoder drops the properties now listed in crates/emit-native/src/css_support.rs.
  • Selectors it drops: :focus-visible, :focus-within, :visited, :required, :invalid, :placeholder-shown, :target, :is(), :where(), :has() and ::marker.
  • Selectors it keeps: :hover, :active, ::before, :nth-child(), attribute selectors and :root. Lynx never matches :hover on a phone. It also keeps, without matching them, :disabled, :checked, :empty, :focus, ::selection and the ~ combinator.
  • At-rules. Lynx keeps @keyframes and drops every other at-rule block without a word: @media, @supports, @layer, @container, @font-face. The re-review of PR #22 found that the kit's hover and web-only blocks, and any project's width queries, were lost this way, and that nested rules came out as CSS Lynx cannot read.

Decision

  • Honour it or stop. Every feature the native build cannot honour is an error, for the kit as much as for a project. No feature fails without a word. packages/engine/test/bundle.test.ts bundles minimal, kit and gallery and fails if Lynx logs any "Unsupported property" or "Unsupported selector".
  • Errors.
    • E0200: a hover: utility with no pressed: utility on the same element. A class: directive's utility (class:hover:bg-raised={on}) counts as the element's own, for hover: and for pressed:.
    • E0201: a :hover selector with no :active twin (the same selector with :active in place of :hover) in its selector list. Each :hover selector needs its own twin.
    • E0205: a selector Lynx cannot match. The check is an allow-list: classes, ids, element names, *, the descendant, > and + combinators, :active, :not() (its arguments checked the same way), :first-child, :last-child, :nth-child(), ::before, ::after and ::placeholder, and the states and attributes the engine stands in for (below). Anything else is an error, ~ included.
    • E0206: a property Lynx drops, which the build cannot write again and the engine does not draw.
    • E0207: on:key on a view that touch cannot reach another way, or on:focus or on:blur on anything but a field. A spin button is not a composite: its arrow keys change its value, which touch never sends, so its on:key is heard only with buttons in its own group that move what its keys change both ways (a stepper's − and +). A button counts when it is beside the spin button, or wrapped one level down beside it, and has on:press (a placed component, onPress). The buttons pair with it when their handlers between them move state the on:key handler writes both up and down (one handler both ways, or one each way; directly, or through the file's own functions it calls, with what it calls them with), or when one's controls names the spin button's id. A handler that sets the state to a value (a Reset, v = 0) moves it neither way. Where the build cannot tell the way (a step whose sign is a prop's, a value written as text, a handler that calls an imported function or a prop's callback), the pair is written with controls; the kit's Stepper and TimePicker do so. slider is not a role (E0124); the <slider> element is drawn by the engine and needs no keys.
    • E0208: a color-mix() the build cannot work out.
    • E0204: two source files written to one output module. The root layout and pages/index/_layout now have output paths of their own, because output paths mirror source paths. Modules are compared without their extension and without case, so foo.duo beside foo.setup.duo, and About.duo beside about.duo, are errors too.
    • E0209: an at-rule the build cannot answer for a phone (below): @container, a media feature the engine does not know (prefers-contrast, resolution…), a length in vw or another unit than px, em and rem, @supports font-tech(), and @font-face, @import, @page and the like.
    • E0210: a declaration inside a @supports block that never holds on a phone, of a property its condition does not name. Such a block is left out, so the declaration would be lost with it.
    • E0213: a focus: utility, or a :focus or :focus-visible selector, on anything but a field. Lynx gives only inputs and textareas the focus, and the engine sets st-focus on them alone, so the style would never apply. A selector is on a field when it names input or textarea, or a class the file puts only on fields, or names nothing but the focus, as .wrap > :focus or .box :focus-visible do: on a phone these become .wrap > .st-focus, which matches exactly the fields they reach, so they apply as on the web. :not(:focus) is not asking for the focus: on what never has it, it always holds, so it is allowed. :focus-within is not checked: a view carries st-focus-within while a field inside it has the focus. Lynx reports no focus for views or buttons, so the engine cannot honour focus there.
  • How a style opts out of a phone. Each of these is said once, in the source, and the native build then leaves the style out without a word:
    • **pressed: covers hover:.** An element with both shows the pressed look on a phone and the hover look under a pointer.
    • **An :active twin covers :hover.** In .row:hover, .row:active the build keeps .row:active and leaves out .row:hover. In .a:hover, .b:hover, .a:active, .b:hover is still an error.
    • **pressed: covers focus:.** An element with both shows the pressed look under a finger, and the focus look under a keyboard on the web.
    • **@supports selector(:focus-visible) keeps focus rules for browsers.** Asking whether :focus or :focus-visible is supported never holds on a phone, so the block is left out. A rule in it whose every selector needs :focus or :focus-visible (outside a :not() or a :has(), and in an :is() or :where() only when each of its branches needs it) is for browsers, and goes without a word. Any other rule in it, such as .tile { padding: 40px }, a :hover with no twin, .btn:active, .btn:is(.a, .btn:focus-visible) (which matches .btn.a without the focus) or .btn:has(:focus), would be lost on a phone, so it is checked as if it were outside the block (E0201, E0205, E0213) and each of its declarations the condition does not ask about is E0210. A condition in brackets of its own, @supports (selector(:focus-visible)), is the same block. The same holds when the selector condition is joined with others by and: the properties they name may stay. Every browser the web target supports has :focus-visible, so the web keeps the rules as they are. The kit keeps its focus rings this way (Link, Breadcrumbs, TabBarItem, Menu, Select).
    • Pointer media queries are for pointers only. A rule inside @media (hover: hover) or (pointer: fine) is for pointers only, and is left out. The query is parsed, not searched: not (hover: hover) and (hover: none) always hold on a phone, and (hover: hover) or (min-width: 600px) is the width query alone.
    • **@supports asks about a property.** A @supports (property: value) block is kept if Lynx keeps that property and left out if it does not. To keep a declaration such as outline-offset on the web only, put it in @supports (outline-offset: 2px) { … }. A condition may join properties with and, or and not; a left-out block may hold only the properties its condition names (E0210). The kit's parts keep their web-only touches this way, NavHeader's blur asking for (backdrop-filter: …) or (-webkit-backdrop-filter: …).
  • Conditional at-rules are answered by the build. No at-rule but @keyframes reaches Lynx. Each condition is worked out as an either-or of all-of answers (css_condition.rs):
    • @layer always holds: its rules are written plainly. (The web's layer order is not kept; rules come in source order.)
    • @supports is answered from what Lynx keeps, and selector() from the selector check.
    • A media query is answered for a phone where it can be: hover, any-hover, pointer, any-pointer, forced-colors, scripting and the media types (screen and all hold, print does not).
    • Where the answer depends on the phone, the rules are written under classes the engine puts on the app's root view, as .duolith-app.st-mq-w-ge-768 .card { … }: duolith-dark and duolith-light for prefers-color-scheme, st-reduce-motion and st-full-motion for prefers-reduced-motion (the shells pass it as the reducedMotion global prop), st-mq-portrait and st-mq-landscape, and a class for each width or height comparison the sheets use, in px, em or rem (registered with registerWindowQueries and kept current as the window changes size).
    • packages/engine/test/bundle.test.ts bundles a page with each kind of block and checks the bundle differs from the page without it.
  • Nesting and keyframes. Nested rules are flattened (& stands for the parent; a nested selector without one is a descendant of it), and a nested @media or @supports adds to the conditions around it. Each @keyframes step is checked and written again like a rule, so its declarations get the same rewrites and errors.
  • What the build and the engine make up for.
    • State selectors become classes.
      • :focus-visible and :focus become .st-focus, which a field carries while it has the focus.
      • :disabled becomes .st-disabled and :enabled :not(.st-disabled); :empty becomes .st-empty. Text, View and Button set them from disabled and from having no children.
      • :focus-within becomes .st-focus-within, which the build registers (registerFocusWithin) and a view carries while a field inside it has the focus.
      • [aria-current] becomes .st-current and [aria-selected] becomes .st-selected. Text, View and Button set these from the element's state.
      • [data-state=open], [data-detent=…] and [data-side=…] become .st-state-open, .st-detent-… and .st-side-…, with or without quotes. The engine's overlays set them.
    • Mixes are worked out at build time. color-mix() is mixed for light and for dark, in srgb or oklab. It can mix theme colours, hex colours, named colours and transparent.
    • Properties are written again in a form Lynx keeps:
      • inset;
      • the *-inline and *-block properties;
      • place-*;
      • logical sizes;
      • text-decoration-line;
      • rotate, scale and translate, when the rule sets no transform.
    • Other values Lynx would lose:
      • env(safe-area-inset-*) becomes 0px, because the shells already lay the app out inside the safe area;
      • display: contents is left out, with or without its ;.
    • **The engine draws text-transform and object-fit** when a plain class's rule sets them. The build registers them with registerClassStyles, and Text, Button and Image apply them.
  • Events and media the engine now honours.
    • Text, icons and images follow href.
    • An image with zoomable pinches, double-taps to 2.5×, pans, and calls on:dismiss when dragged down 96 px.
    • A sheet drags between its detents, calls on:detent, and is dismissed when dragged below its smallest detent.
    • on:key is allowed on a field, on an element with a composite role (tab list, list box, menu, radio group, grid, tree…), next to on:press or href, and on a spin button whose own buttons move what its keys change both ways (E0207), because touch reaches all of these.
    • The toast region, open over the bottom of the window, lets presses through to the screen beneath it, as on the web; only its toasts take them.
  • Accessibility on native. Lynx has a trait for a selected element, a value (iOS's accessibility value, Android's state description), a role description (Android), custom actions and a way to move the screen reader's focus (requestAccessibilityFocus). The engine says selected with the trait and in the value, current, invalid and value-now in the value (after value-text, which wins over value-now), a toggle's on or off and a checkbox's checked or not checked first in it, and the roles alert, status, dialog, alert-dialog and navigation as a role description. Lynx has no relations and no live regions, so the engine makes them up at run time (packages/engine/src/relations.ts); none is dropped:
    • **labelled-by and described-by.** Each element drawn with an id says its text (the text of its children and of the elements in them) and its name. An element whose labelled-by names ids takes their text as its name where it has no label; one whose described-by does says their text last in its value, which a screen reader reads after the name, as the web reads a description. Both follow the named text as it changes (a field's hint becoming its error). When several elements are drawn with one id, the first of those still drawn says the text, so one going leaves the other naming the field. This is done at run time rather than at build time because the kit's ids are made when a part is placed (duolith-field-…).
    • **value-min and value-max** follow the value: "2, minimum 1, maximum 8".
    • **controls** becomes a custom action, "Go to" and the controlled element's name, that moves the screen reader to it.
    • Live announcements. An element with role alert or status says its text through the shell's DuolithShell.announce(words, urgent) when it appears and each time its text changes: an alert at once, a status after what is being said (iOS queues it with accessibilitySpeechQueueAnnouncement; Android's announceForAccessibility queues both). The toast region is a polite live region on the web, so on native each text that comes into it is said as a status. One drawn with its screen (or, outside a screen, with the app) is silent until its text changes, as a live region already on the page is on the web. The same words asked for twice in one drawing, such as a text inside an alert that appear together, are said once, at once if either is an alert; different words are each said, even when one holds the other.
  • Motion, boundaries and islands (decisions 0055 to 0059). Each is honoured through the engine, or stops the build:
    • Motion presets and the default motion. A show's sides are drawn in the engine's Presence, and a list's rows by the List primitive and the screen's recycled list. What comes plays in, and what goes stays drawn while it plays out, each element at the top by its own motion= preset (or the list's, for its rows) or the default settle, as Lynx CSS animations (packages/engine/src/motion.css). motion="none" goes at once.
    • **The closest motion= wins.** A row's top element's own preset wins over its list's, as on the web, so rows of a list with motion="none" still play their own. A row with nothing to play (its top sets none, or nothing in a list with motion="none") goes at once, its row and the gap above it with it, as on the web: the list hears the preset each element at a row's top plays.
    • What leaves goes, whatever redraws. Each Presence and list schedules its next step for when the first movement still playing ends, so a screen that redraws every few milliseconds does not keep what leaves on it. A key that comes back while it leaves comes in again.
    • What leaves cannot be used. While it plays out it takes no touch (user-interaction-enabled, and pointer-events: none where Lynx for Web draws), no press and no focus, and assistive technology no longer reaches it (accessibility-elements-hidden).
    • Rows that move glide. The list works out where each row was and is from the rows' laid-out heights, the gap and their order, then draws each moved row where it was and moves it to its place.
    • Reduced motion. The shells pass reducedMotion. Every preset becomes a 120ms fade, rows do not glide, and screen movements are a short fade.
    • **<boundary> and <fallback>.** The Boundary primitive catches what its content throws while it is built or drawn again (its content is drawn in its own tracked part). It shows the fallback, given the failure and retry(), or a sentence and a Try again button. While loading holds, its content is drawn as pulsing blocks that cannot be pressed, at least as tall as it last was under remember. On native the boundary is a column view of its own.
    • Islands. A component placed with load= is built at once: the bundle on the phone already holds every component's code, so there is nothing to load later.
    • Edge-swipe back was already the engine's own (stack.tsx), from the trailing edge's opposite in a right-to-left display.
    • **morph is E0212.** The engine's screen movements move whole screens; carrying an element between them needs both screens' places and a copy that moves above them, which is not built yet. examples/motion therefore does not build for native; a copy of it without its morphs does, and the tests build it.

Consequences

  • The kit's parts move their hover looks into @media (hover: hover) and their web-only declarations into @supports. Their look on the web does not change.
  • :hover and the vendor pseudo-elements (::-webkit-*, ::-moz-*) never match on a phone; a selector with one is left out without a word, and so are its declarations' checks when every selector of a rule is left out.
  • Which pseudo-classes Lynx matches was read from its build's log and its documentation, not from a device; native/DEVICE-CHECKLIST.md asks for the allow-list to be confirmed there.
  • Badge mixes each tone explicitly.
  • The gallery gains a pressed: look and an on:press beside its key pad.
  • examples/effects and examples/production still do not build for native. That is on purpose (decision 0048 and E0203).
  • The opt-outs are what a project writes to keep a style for the web only. Nothing else in the source switches a check off.
  • What only a device can confirm is listed in native/DEVICE-CHECKLIST.md:
    • how the gestures feel (sheet drag, image zoom);
    • that a field's st-focus follows the keyboard;
    • that recycling actually reuses rows;
    • what VoiceOver and TalkBack say for the relations, the custom action and the announcements. The iOS DuolithShellModule is new and, like the rest of the Swift, was not compiled here.

Update: what wave 5 made a phone honour

  • Morph (E0212) and the production adapters (E0203) build for native now (decisions 0056 and 0053); neither code is reported any more.
  • Fonts. A @font-face at the top of a style block is a font the app ships, so E0209 no longer covers it (one inside a conditional block still is). The build copies its file from public/ to assets/fonts/ with a list (fonts.json); the Android shell gives each to Lynx's typeface cache and the iOS shell registers it with Core Text before the first screen draws, so font-family and the theme's font.family find it. What a phone cannot ship is an error: no TrueType or OpenType source (E0450), no family or a source that is not a root-relative file of public/ (E0451), a file missing from public/ (E0452). Android keeps one face per family for each of normal, bold, italic and bold italic, and iOS finds a font by the family inside the file; both are device checks.
  • Rung 0 on native. A file whose script folds to tables (decision 0075) is written as a table on native too, when that is smaller, and duolith build --target native --report writes build-report.ios.json and build-report.android.json with each file's rung.
  • Source maps. Each setup module ends with a map back to its .duo file, the bundle carries them through, and the bundle step keeps the bundle's own maps in dist/maps/ so a native crash's frames map back to the page line (packages/engine/scripts/map-frames.ts).
  • Keys other than Enter stay E0207. Lynx 4.2 has key events (bindkeydown, bindkeyup) only in its desktop builds and Lynx for Web, never on iOS or Android, and a field reports one key, Enter, as its confirm event. The gap closes when Lynx gives phones key events.
  • Inset logical properties. inset-inline, inset-block and their sides, which Lynx drops, are written again in ones it keeps.