Features and where to see them
Every feature of Duolith, the example that shows it, and a screenshot of it. The audit went through:
- the guides in
docs/guide/, - the elements, attributes, events and flow in
spec/language/elements.yaml, - the exports of
@duolith/client, - the kit's parts,
- the styling prefixes and utility families in
spec/styling/utilities.yaml, - the CLI's commands.
The screenshots are not in the repository. The script node tools/screenshots/gallery.ts makes them (see its header). It saves them to tools/screenshots/out/, which git ignores, or to the folder given with --out. The script fails if it does not make every file named here. Each gallery screenshot also has a 1280x800 version with -wide added to its name, such as gallery-home-wide.png.
Run any example with cargo run -p duolith-cli -- dev examples/<folder>. The data example also needs its mock server, node examples/data/server/server.ts.
Language: elements
| Feature | Example | Screenshot |
|---|---|---|
<screen> with a title | every page; gallery pages/index.duo | gallery-home.png |
<view> | gallery pages/styling.duo | gallery-styling.png |
<text> | gallery pages/styling.duo (Type) | gallery-styling-type.png |
<button> | minimal pages/index.duo | minimal-pressed.png |
<image> (alt, decorative, placeholder, lazy) | gallery pages/language.duo (Elements) | gallery-language-elements.png |
<input> | gallery pages/language.duo (Two-way binding) | gallery-language-binding.png |
<textarea> | gallery pages/language.duo (Two-way binding) | gallery-language-binding.png |
<list> with each, as, key and index | gallery pages/language.duo (Keyed list) | gallery-language-list.png |
<scroll> | gallery pages/language.duo (Elements) | gallery-language-elements.png |
<form> | gallery pages/language.duo (A form) | gallery-language-form.png |
<toggle> | gallery pages/language.duo (Two-way binding); components pages/index.duo | gallery-language-binding.png |
<checkbox> | gallery pages/language.duo (Two-way binding) | gallery-language-binding.png |
<slider> | gallery pages/language.duo (Two-way binding) | gallery-language-binding.png |
<progress> (determinate and indeterminate) | gallery pages/language.duo (Elements) | gallery-language-elements.png |
<icon> | gallery pages/language.duo (Elements) | gallery-language-elements.png |
<overlay> (kind, anchor, open) | gallery pages/overlays.duo (The overlay element) | gallery-overlays-element.png |
Language: flow, components and reactivity
| Feature | Example | Screenshot |
|---|---|---|
<show> and <otherwise> | gallery pages/language.duo; control-flow | gallery-language.png |
<match> and <case>, exhaustive at build time | data pages/typed.duo (over feed.state.status) | data-typed.png |
Components with props() | gallery components/Panel.duo, components/Rating.duo | gallery-language-components.png |
bindable() props and bind: on a component | gallery components/Rating.duo | gallery-language-components.png |
<slot>, named slots | gallery components/Panel.duo; components components/Card.duo | gallery-language-components.png |
<piece> (leading and trailing content) | kit pages/lists.duo | kit-lists.png |
Scoped <style> blocks | gallery pages/styling.duo (A page style block) | gallery-styling-dark.png |
class:name={condition} | gallery pages/language.duo (Conditional classes) | gallery-language-effects.png |
state() | minimal pages/index.duo | minimal-pressed.png |
derived() | gallery pages/language.duo (Derived values) | gallery-language-list.png |
effect(), onDispose(), untracked() | gallery pages/language.duo (effect, onDispose and untracked) | gallery-language-effects.png |
bind:value, bind:checked | gallery pages/language.duo (Two-way binding) | gallery-language-binding.png |
Language: events
| Feature | Example | Screenshot |
|---|---|---|
on:press | gallery pages/language.duo (Events) | gallery-language-events.png |
on:longpress | gallery pages/language.duo (Events); control-flow | gallery-language-events.png, control-flow-longpress.png |
on:key | gallery pages/language.duo (Events), components/Rating.duo | gallery-language-events.png |
on:focus, on:blur | gallery pages/language.duo (Events) | gallery-language-events.png |
on:change | gallery pages/language.duo (Events) | gallery-language-events.png |
on:input | data pages/signup.duo | data-signup-errors.png |
on:submit | gallery pages/language.duo (A form) | gallery-language-form.png |
on:load, on:error on <image> | gallery pages/language.duo (Elements) | gallery-language-elements.png |
on:dismiss on <overlay> | gallery pages/overlays.duo (The overlay element) | gallery-overlays-element.png |
Language: attributes and accessibility
| Feature | Example | Screenshot |
|---|---|---|
label, id | gallery pages/language.duo (A form, Accessibility attributes) | gallery-language-accessibility.png |
described-by | gallery pages/language.duo (A form) | gallery-language-form.png |
labelled-by, controls | gallery pages/language.duo (Accessibility attributes) | gallery-language-accessibility.png |
role, selected, tab-stop | gallery components/Rating.duo | gallery-language-components.png |
value-now, value-min, value-max, value-text | gallery pages/language.duo (Accessibility attributes) | gallery-language-accessibility.png |
href | gallery pages/navigation/index.duo | gallery-navigation.png |
current | gallery pages/navigation/item/[id].duo (hand-built section links, styled from [aria-current]) | gallery-navigation-item.png |
Styling and themes
| Feature | Example | Screenshot |
|---|---|---|
| Layout utilities (row, grow, items, justify, gap, grid) | gallery pages/styling.duo (Layout); styling pages/layout.duo | gallery-styling.png, styling-layout.png |
| Spacing utilities | styling pages/spacing.duo; gallery pages/styling.duo | styling-spacing.png |
| Sizing utilities | gallery pages/styling.duo (Sizing) | gallery-styling-sizing.png |
| Position utilities | gallery pages/styling.duo (Position) | gallery-styling-sizing.png |
| Colour utilities | gallery pages/styling.duo (Colour); styling pages/color.duo | gallery-styling-colour.png, styling-color.png |
| Type utilities | gallery pages/styling.duo (Type) | gallery-styling-type.png |
| Borders and radius | styling pages/borders.duo; gallery pages/styling.duo | styling-borders.png |
| Shadows and opacity | gallery pages/styling.duo (Shadows and opacity) | gallery-styling-shadows.png |
pressed:, hover:, focus:, disabled: | gallery pages/styling.duo (State prefixes); styling pages/states.duo | gallery-styling-prefixes.png, styling-states.png |
md:, lg: | gallery pages/_layout.duo (rail), pages/styling.duo | gallery-home-wide.png, gallery-styling-dark-wide.png |
dark: | gallery pages/styling.duo (Window and scheme prefixes) | gallery-styling-dark.png |
| Dark mode from the system | gallery | gallery-home-dark.png |
A light/dark switch, colorScheme | gallery pages/index.duo, pages/appearance.duo | gallery-appearance-dark.png |
A theme of your own (theme.yaml) | theming | theming-light.png, theming-dark.png |
look: platform, web-look: the kit as iOS and as Material | theming theme.yaml | theming-ios.png, theming-material.png |
duration, easing, shape, control tokens; parts: overrides of tokens, variants and slots | theming theme.yaml (Button, Card) | theming-light.png |
A font of your own: @font-face from public/fonts/ as the theme's font.family (Caladea, SIL Open Font License) | theming pages/index.duo, theme.yaml | theming-light.png |
The gallery has no switch between whole themes, because the theme is fixed when the app is built. The Appearance tab says so and points at examples/theming.
Navigation
| Feature | Example | Screenshot |
|---|---|---|
File routes and [param] routes | gallery pages/navigation/item/[id].duo | gallery-navigation-item.png |
[...rest] routes | gallery pages/navigation/docs/[...topic].duo | gallery-navigation-rest.png |
route() (params and query) | gallery pages/navigation/item/[id].duo | gallery-navigation-item.png |
navigate(), with replace | gallery pages/navigation/index.duo | gallery-navigation-item.png |
back(), canGoBack(), backTitle() | gallery pages/navigation/item/[id].duo | gallery-navigation-item.png |
| Transitions (push slides, replace and tabs crossfade) | gallery pages/navigation/index.duo | gallery-navigation-transition.png |
Layouts (_layout.duo), nested | gallery pages/_layout.duo; navigation pages/profile/_layout.duo | gallery-home.png, navigation-settings.png |
guard() | gallery pages/navigation/vault.duo | gallery-navigation-guarded.png, gallery-navigation-vault.png |
Shared state, state(x, { shared }) | gallery pages/navigation/index.duo, pages/_layout.duo | gallery-navigation-shared.png |
_not-found.duo | gallery pages/_not-found.duo | gallery-navigation-not-found.png |
| Screen titles | gallery pages/navigation/item/[id].duo | gallery-navigation-item.png |
public/ files | gallery public/images/; inputs-and-media public/photos/ | gallery-inputs-and-media-images.png |
Data
| Feature | Example | Screenshot |
|---|---|---|
state.load() | gallery pages/data.duo (state.load) | gallery-data.png |
| A load keyed by state | gallery pages/data.duo | gallery-data-keyed.png |
action() with an optimistic change, rolled back | gallery pages/data.duo | gallery-data-rollback.png |
describeError() | gallery pages/data.duo (Optimistic action) | gallery-data-rollback.png |
Offline queue, network | gallery pages/data.duo (Offline queue); data pages/offline.duo | gallery-data-offline.png, data-offline-queued.png |
pagedList() | gallery pages/data.duo; data pages/catalogue.duo | gallery-data-paging.png, data-catalogue-more.png |
listView(), byText, byNumber, containsText | gallery pages/data.duo, pages/search.duo | gallery-data-paging.png, gallery-search-query.png |
filterItems(), sortItems() | gallery pages/data.duo | gallery-data-functions.png |
form(), field(), required, minLength, maxLength, email, matches, custom | gallery pages/data.duo (Form validation) | gallery-data-validation.png |
environment() | gallery pages/data.duo (Settings per build) | gallery-data-functions.png |
duolith.env, duolith.<mode>.env, typed environment() | data duolith.env, pages/typed.duo | data-typed.png |
typedApi() from an OpenAPI description (api/*.openapi.yaml) | data api/posts.openapi.yaml, pages/typed.duo | data-typed.png |
state.load().state, one union | data pages/typed.duo | data-typed.png |
autocomplete on fields, TextField's autocomplete | data pages/signup.duo; effects pages/sign-in.duo | data-signup-errors.png |
api(), the typed client | data pages/posts.duo | data-posts.png, data-posts-liked.png |
Retries, ApiError | data pages/retry.duo | data-retry.png |
stream() | data pages/live.duo | data-live.png |
Kit: core parts
| Feature | Example | Screenshot |
|---|---|---|
| Button, IconButton | gallery pages/kit-core.duo; kit pages/buttons.duo | gallery-kit-core.png, kit-buttons.png |
| ListRow, Section | gallery pages/kit-core.duo; kit pages/lists.duo | gallery-kit-core.png, kit-lists.png |
| Card, Avatar, Badge, Divider | gallery pages/kit-core.duo | gallery-kit-core-cards.png |
| TextField, TextArea | gallery pages/kit-core.duo; kit pages/inputs.duo | gallery-kit-core-fields.png, kit-inputs.png |
| ToggleRow, Checkbox, RadioGroup | gallery pages/kit-core.duo; kit pages/selection.duo | gallery-kit-core-selection.png, kit-selection.png |
| SegmentedControl, Slider | gallery pages/kit-core.duo | gallery-kit-core-controls.png |
| Spinner, ProgressBar | gallery pages/kit-core.duo | gallery-kit-core-controls.png |
| EmptyState, ErrorState | gallery pages/kit-core.duo; kit pages/feedback.duo | gallery-kit-core-feedback.png, kit-feedback.png |
Kit: overlays
| Feature | Example | Screenshot |
|---|---|---|
| Sheet with detents | gallery pages/overlays.duo | gallery-overlays-sheet.png |
| Dialog | gallery pages/overlays.duo | gallery-overlays-dialog.png |
| AlertDialog | gallery pages/overlays.duo | gallery-overlays-alert.png |
| Menu | gallery pages/overlays.duo | gallery-overlays-menu.png |
| Popover | gallery pages/overlays.duo | gallery-overlays-popover.png |
| Tooltip | overlays pages/index.duo; gallery pages/overlays.duo | overlays-tooltip.png |
Toast, toast(), visibleToasts(), dismissToast() | gallery pages/overlays.duo | gallery-overlays-toast.png |
| Select | gallery pages/overlays.duo | gallery-overlays-select.png |
Kit: inputs and media
| Feature | Example | Screenshot |
|---|---|---|
| DatePicker | gallery pages/inputs-and-media.duo | gallery-inputs-and-media.png |
| TimePicker, Stepper | gallery pages/inputs-and-media.duo; inputs-and-media pages/pickers.duo | inputs-and-media-pickers.png |
| SearchField, ChipGroup, Chip | gallery pages/inputs-and-media.duo | gallery-inputs-and-media-chips.png |
| Tabs | gallery pages/inputs-and-media.duo | gallery-inputs-and-media-tabs.png |
| Image (placeholder, fade, fallback) | gallery pages/inputs-and-media.duo; inputs-and-media pages/media.duo | gallery-inputs-and-media-images.png, inputs-and-media-media-fallback.png |
| ImageViewer and zoom | gallery pages/inputs-and-media.duo | gallery-inputs-and-media-viewer.png |
| Skeleton | gallery pages/inputs-and-media.duo | gallery-inputs-and-media-skeleton.png |
Kit: more parts
| Feature | Example | Screenshot |
|---|---|---|
Accordion (expanded), Banner, Pager, Pagination, Rating, ProgressRing | kit pages/more.duo | kit-more.png |
Combobox (a WAI-ARIA combobox over a listbox), ChipInput, DataTable (a table with sorted, aria-sort), FileInput, ActionSheet, Fab | kit pages/more.duo | kit-more.png |
on:swipe; Pager paging on a swipe; SwipeRow, PullToRefresh, Drawer (decision 0121) | kit pages/more.duo | kit-more.png |
| DateRangePicker (a start, then an end, the days between marked) | kit pages/more.duo | kit-more.png |
Kit: navigation parts
| Feature | Example | Screenshot |
|---|---|---|
| TabBar, TabBarItem (badge, rail on wide windows) | gallery pages/_layout.duo, pages/navigation-parts.duo | gallery-navigation-parts.png, gallery-home-wide.png |
| NavHeader (large title, up, trailing actions) | gallery pages/index.duo, components/AreaScreen.duo | gallery-home.png, gallery-navigation-parts.png |
| Toolbar | gallery pages/navigation-parts.duo | gallery-navigation-parts-toolbar.png |
| Breadcrumbs | gallery pages/navigation/docs/[...topic].duo | gallery-navigation-rest.png |
| Link | gallery pages/navigation-parts.duo | gallery-navigation-parts.png |
Native output
duolith build <example> --target native writes ReactLynx through @duolith/engine's adapter. Every example builds and is checked against a snapshot in packages/engine/test/snapshots/. To run one in Lynx for Web, use node packages/engine/scripts/preview.ts <example>/dist-native --port 4300. The screenshot script does not take these screenshots, so the Check column names the test that drives each feature in Chromium instead. Checks that need a device are in native/DEVICE-CHECKLIST.md.
| Feature | Example | Check |
|---|---|---|
| Native build of every example, gallery included | every example | packages/engine/test/native-output.test.ts |
| Push and pop transitions, a back button with the previous title, the system back event | navigation (feed, then a post) | packages/engine/test/native-in-browser.test.ts |
A list straight inside a screen, recycled through Lynx's <list> | navigation pages/(tabs)/index.duo | packages/engine/test/native-in-browser.test.ts |
| A menu, popover or tooltip anchored to the element that opened it | overlays (Menu, popover and tooltip) | packages/engine/test/native-in-browser.test.ts |
| Icons in the surrounding text colour | overlays (the icon in the Open sheet button) | packages/engine/test/native-in-browser.test.ts |
color-mix() of theme, hex and named colours in srgb or oklab, mixed at build time | gallery (badges, alerts) | crates/emit-native/src/css.rs and css_colour.rs tests |
Errors for what a phone cannot honour (E0200, E0201, E0204 to E0210), the kit included, with the pressed:, :active, @media (hover: hover) and @supports opt-outs | gallery (hover: with pressed:, Rating), kit parts | crates/emit-native/src/portability.rs tests, packages/engine/test/bundle.test.ts |
@media width, orientation, colour-scheme and reduced-motion queries, @supports and @layer answered for a phone; nested rules flattened | kit parts (NavHeader, SearchField) | crates/emit-native/src/css_condition.rs and css.rs tests, packages/engine/test/bundle.test.ts |
Motion presets and the default motion of shows and lists, rows that glide, reduced motion; <boundary> with a skeleton, <fallback> and retry | engine fixture native-motion | packages/engine/test/native-motion-in-browser.test.ts, native-output.test.ts |
morph on native: a FLIP copy flies from the feed's thumbnail to the post's picture and back, nothing with reduced motion | motion pages/index.duo to pages/post/[id].duo | packages/engine/test/native-morph-in-browser.test.ts |
Islands on native: idle, interaction (a "Load" skeleton) and visible (Lynx's exposure events), with a boundary skeleton until then | motion pages/islands.duo | packages/engine/test/native-morph-in-browser.test.ts |
| Remembered skeleton shapes kept per app through the storage effect, drawn at that height on the next launch | motion pages/islands.duo | packages/engine/test/native-morph-in-browser.test.ts |
Production adapters on native: t() from the bundled catalogues in the phone's language, consent kept in the shell's storage, crash reports from the shell's uncaught handler (also those kept from the last run), an outbox for httpTransport, a compact Intl where the engine has none | production | packages/engine/test/native-production-in-browser.test.ts, packages/adapters/test/intl-fallback.test.ts, outbox.test.ts |
Native source maps: a thrown error's frames map back to the page line (scripts/map-frames.ts) | production pages/index.duo ("Report a test error") | packages/engine/test/native-production-in-browser.test.ts, crates/emit-native/src/lib.rs tests |
Rung 0 tables on native, and --report writing build-report.ios.json and build-report.android.json | any example, --target native --report | crates/cli/tests/build_command.rs |
Fonts of your own: @font-face from public/ shipped in the app and registered by the shells, the theme's font.family using it (E0450 to E0452) | theming pages/index.duo, theme.yaml, public/fonts/ | crates/emit-native/src/fonts.rs tests, native-output.test.ts |
| Page scripts run once; one screen per tab; a deep-linked screen let go when a tab is pressed; the screen beneath kept as it was left | engine fixture native-app | packages/engine/test/native-app-in-browser.test.ts |
href on text, icons and images; the kit TabBarItem's current colour; an anchored menu following the scroll | engine fixture native-app | packages/engine/test/native-app-in-browser.test.ts |
The app manifest in duolith.yaml (name, id, version and build, icon at every density, launch screen, orientation, oldest systems, link domains and URL scheme), checked with E0470 to E0477 and written into the Android and iOS projects (decision 0140) | field-notes duolith.yaml; dist-native/native/ after a build | crates/cli/src/manifest/tests.rs; the CI Android job, which builds it into the shell's APK |
Links that open the app (App Links, universal links, the app's scheme) routed to their screen; onLink and lastLink from @duolith/client/native (decision 0141) | field-notes (/notes/[id]); engine fixture native-shell | packages/engine/test/native-shell-in-browser.test.ts, packages/client/test/native-links.test.ts |
An href to another site opened by the system (openUrl on the DuolithShell module); DUOLITH_PUBLIC_* values as environment() on a phone | field-notes pages/index.duo | packages/engine/test/native-shell-in-browser.test.ts |
duolith dev --target android|ios [--host]: the bundle served and reloaded on each change, a QR code for the preview app (native/preview-app) | field-notes | crates/cli/src/dev_native/serve.rs tests (a headless WebSocket client) |
duolith ship android|ios [--upload]: a signed store release, refused before building without its manifest, signing, Mac or store credentials (E0478 to E0483) | field-notes | crates/cli/tests/ship_command.rs (the Play upload against a stand-in server) |
Motion and islands
| Feature | Example | Screenshot |
|---|---|---|
| Automatic motion: rows and show sides play in and out, moved rows glide (FLIP), reduced motion respected | motion pages/index.duo (Add, Shuffle, Remove) | motion-feed.png |
Motion presets: motion="fade|scale|slide-up|slide-down|slide-left|slide-right|spring|none" | motion pages/index.duo (Presets) | motion-presets.png |
morph: an element carried between screens (View Transitions, or a FLIP copy) | motion pages/index.duo to pages/post/[id].duo | motion-post.png |
Edge-swipe back on touch (from the right edge under dir="rtl"), the screens following the finger | motion pages/post/[id].duo | motion-post.png |
Islands: load="visible|idle|interaction" on a placed component, its code loaded only then | motion pages/islands.duo (Islands) | motion-islands.png |
<boundary> with <fallback as="failure"> and failure.retry() | motion pages/islands.duo | motion-islands.png |
Skeletons: derived from the layout with loading={...}, remembered with remember="name" | motion pages/islands.duo | motion-skeleton.png |
Each movement, held at fixed points, is checked against baselines by pnpm test:screenshots --suite motion, and dropped frames by pnpm bench:frames.
Production: consent, analytics, crashes and translation
| Feature | Example | Screenshot |
|---|---|---|
Consent by category, remembered on the device, with Global Privacy Control (startConsent, consent()) | production pages/_layout.duo, components/ConsentBanner.duo, pages/settings.duo | production-consent-banner.png, production-settings.png |
Analytics: automatic screen views, typed track(), batches sent by beacon on hide (startAnalytics) | production pages/_layout.duo, pages/index.duo | production-home.png |
Crash reports with the screen, breadcrumbs and source-mapped frames (startCrashReporting, captureError) | production pages/index.duo ("Report a test error"), pages/reports.duo | production-reports.png |
Translation: t() with ICU plurals and selects, locales/*.json checked at build (E0280 to E0283) | production locales/en.json, locales/ar.json | production-home.png, production-settings-ar.png |
Locale detection, setLocale(), right-to-left dir, number, date and relative-time formatting | production pages/settings.duo (Language) | production-settings-ar.png |
App-store privacy declarations (privacy/PrivacyInfo.xcprivacy, privacy/data-safety.json) | production, written to dist/privacy/ by duolith build | none: build output, shown under CLI |
duolith scan: a verdict per npm dependency for web, iOS and Android (E0285 to E0289) | production package.json (vendor/tiny-ordinal, vendor/dom-tooltip) | none: shown under CLI |
Decisions 0070 to 0074 and docs/guide/production.md describe these.
Platform effects
The effects example uses a mock sign-in backend and a mock store, so it needs no accounts: cargo run -p duolith-cli -- dev examples/effects. The gallery script does not visit it yet, so this section names the screen instead of a screenshot.
| Feature | Example | Screenshot |
|---|---|---|
| Sign-in: email and password, magic link, Apple and Google with PKCE, a mock backend | effects pages/sign-in.duo, pages/_layout.duo, pages/mock-provider.duo, pages/callback.duo | the Sign in screen |
A screen guarded by the session (guard(signIn.required(...))) | effects pages/account.duo | the Account screen |
| Secure storage (WebCrypto AES-GCM, key in IndexedDB) | effects pages/storage.duo | the Storage screen |
| Key-value storage, typed and reactive across windows | effects pages/storage.duo | the Storage screen |
| Push: permission with an explainer, local notifications that open a screen, web push with a VAPID key | effects pages/push.duo, components/Explainer.duo | the Push screen |
| Permissions with an explainer, and the Info.plist and Android manifest declarations a build writes | effects components/Explainer.duo; dist/native/ after a build | the Push and Camera screens |
| Purchases: "not available" on the web, a mock store for the flow | effects pages/purchases.duo | the Purchases screen |
| Share with a copy fallback, haptics | effects pages/share.duo | the Share screen |
| Camera capture | effects pages/camera.duo | the Camera screen |
| Lifecycle (foreground, background, online, offline) and the minimum-version check | effects pages/device.duo | the Device screen |
| Every effect on iOS and Android: sign-in (Apple's sheet, Credential Manager, browser sheets with PKCE), push (APNs, FCM), purchases (StoreKit 2, Play Billing, signature-checked), camera (decision 0110) | packages/engine/test/fixtures/native-effects, built with --target native and run in Lynx for Web | none (needs a device) |
| A magic link that opens the app signs in, for the screen it was sent from; a native build refuses it until the shells deliver links (E0402) | effects pages/sign-in.duo; packages/effects/test/native-account-and-device.test.ts | none (a build error on native) |
| Push's Firebase configuration, checked by the build (E0400, E0401) | effects google-services.json | none (a build error) |
| A photo from the library, through the picker with no permission | effects pages/camera.duo | the Camera screen |
Device effects
Every device effect, on the web, Android and iOS (decisions 0101 and 0102): cargo run -p duolith-cli -- dev examples/device-effects. Its pages import no mock, so it builds for native, where a mock is refused with E0432; the effects' tests put each on its mock. The gallery script does not visit it yet, so this section names the screen instead of a screenshot.
| Feature | Example | Screen |
|---|---|---|
| Location: one position and a watch, asked for with its permission | device-effects pages/location.duo | the Where you are screen |
| Sensors: the compass heading and the accelerometer | device-effects pages/location.duo | the Where you are screen |
| Device information: model, version, locale, time zone, safe area, text size, dark mode | device-effects pages/phone.duo | the This device screen |
| The connection: online, type, metered | device-effects pages/phone.duo | the This device screen |
| The keyboard: visible, height, dismiss | device-effects pages/phone.duo | the This device screen |
| The display: keep awake, orientation lock, brightness, "unavailable" where the platform lacks one | device-effects pages/phone.duo | the This device screen |
| Contacts: the system picker, for a phone number or an email address, with no permission | device-effects pages/people.duo | the People and things screen |
| The calendar: add an event through the calendar's own editor ("added", "cancelled" on iOS 17, or "handed-off" on Android and as an .ics on the web) | device-effects pages/people.duo | the People and things screen |
| The clipboard: copy and paste text, read only right after a press | device-effects pages/people.duo | the People and things screen |
| The media and file picker: photos, videos and documents | device-effects pages/people.duo | the People and things screen |
| The browser: in-app (Custom Tabs, SFSafariViewController) or the system's; E0420 for an address that is not http or https | device-effects pages/people.duo | the People and things screen |
| Biometrics with the device credential as a fallback | device-effects pages/trust.duo | the Trust screen |
| App Tracking Transparency, "not-needed" off iOS | device-effects pages/trust.duo | the Trust screen |
| Store reviews, "unavailable" on the web | device-effects pages/trust.duo | the Trust screen |
| The app badge, "unavailable" on Android | device-effects pages/trust.duo | the Trust screen |
| Recording and playback | device-effects pages/sound.duo | the Sound and codes screen |
| Speech: speaking, and listening with what was heard so far | device-effects pages/sound.duo | the Sound and codes screen |
| The barcode scanner, failing loudly with E0425 where unsupported | device-effects pages/sound.duo | the Sound and codes screen |
Every effect's mock, put in place with use, in tests | packages/effects/test/device-effects.test.ts | (no screen: E0432 refuses a mock in a native build) |
| A permission asked for by name is declared, or the build fails with E0431 | packages/engine/test/fixtures/native-effects (permissions.yaml declares the camera it asks for) | (no screen) |
Types and compile-time checks
These fail the build, so they are shown as duolith check output (below, under CLI) rather than screenshots. Each typed position has a failing and a clean project in tests/typed-markup/; docs/explanation/types.md has the full matrix.
| Feature | Example | Shown by |
|---|---|---|
| A misspelt field in markup (E0341) | typed-errors pages/index.duo (recipe.titel) | duolith check examples/typed-errors |
| A word an attribute does not take (E0340) | typed-errors pages/index.duo (type="serach") | the same |
| A binding whose state has the wrong type, both directions (E0340) | typed-errors pages/index.duo (the slider) | the same |
Props checked against props<...>() (E0340) | typed-errors pages/index.duo (minutes="20", level="expert") | the same |
| Data read before it loaded (E0343) | typed-errors pages/index.duo (recipes.data.length) | the same |
| A switch that misses a case (E0346) | typed-errors pages/index.duo (label) | the same |
| Strict options: reads by position, query keys, implicit any (E0343 to E0345) | tests/typed-markup/data-layer, route-query, implicit-any | their tests |
| A link to a page that does not exist, a missing public image (E0353, E0354) | crates/cli/src/links.rs tests | duolith check |
Every way a route is named: href={"/x"}, navigate under any name or through the namespace, guard redirects, signIn.required (E0353) | crates/script-view/src/route_paths.rs tests, crates/cli/src/typecheck/tests.rs | duolith check |
A quoted value an attribute cannot take, disabled="false", min="abc" (E0355) | crates/analyzer/src/quoted_values.rs tests | duolith check |
A project's own .ts file checked in its own lines; a value imported from one (E0356) | crates/cli/src/typecheck/tests.rs, packages/checker/test | duolith check |
@ts-ignore and the like in any case, /// <reference>, any, Function, eval, !, as unknown as, declare, and imports from outside the project, refused (E0356 to E0359) | crates/analyzer/src/escape_hatches.rs tests, crates/cli/src/typecheck/tests.rs | duolith check |
| Columns in characters on CRLF and multi-byte lines, the same in the editor | tests/typed-markup/unicode-and-crlf | their tests |
Kit parts' props typed (ChipGroup's values for several choices) | gallery pages/inputs-and-media.duo (Chips) | gallery-inputs-and-media-chips.png |
Execution ladder
The ladder's features show in the build report, so this section points at duolith build --report output (captured under CLI below) rather than at screenshots. The rust-module example's own screenshots were taken by hand, in /mnt/project-files/demo/ (rust-module-start, rust-module-called, rust-module-about-rung0).
| Feature | Example | Check |
|---|---|---|
| Rung 0 tables: files whose expressions are all constants build as a template and a table of constants, with none of their script (decision 0075) | styling (5 of 6 pages), rust-module pages/about.duo, social pages/about.duo, navigation-kit library and settings/about, the kit and inputs-and-media index pages | duolith build examples/styling --report |
| Rung 1, and the closed bytecode and rung 2 gates (decision 0076) | every example | "script" and "bytecode" in any build-report.json |
| Keyed lists move only the rows that changed order, in TypeScript, measured against Rust built to WebAssembly (decision 0077) | gallery pages/language.duo (Keyed list, Reverse) | pnpm bench --budgets |
| Rust modules: a page calls Rust, built to WebAssembly, with types; Swift and Kotlin bindings from UniFFI (decision 0078) | rust-module pages/index.duo, modules/maths | duolith dev examples/rust-module; pnpm --filter @duolith/modules bindings:native examples/rust-module/modules/maths |
The build report, validated against spec/schemas/build-report.schema.json for every example (decision 0079) | every example | duolith build <example> --report |
Security, contracts and test suites
| Feature | Example | Check |
|---|---|---|
A strict Content-Security-Policy on every web build: a <meta> tag with the hashes of the build's own inline scripts, and a _headers file that adds frame-ancestors 'none'; sources added, replaced or turned off in duolith.yaml (decision 0150, E0550) | every example; examples/data/duolith.yaml adds its mock API to connect-src | duolith build examples/data, then the <meta http-equiv="Content-Security-Policy"> in index.html and _headers; the web screenshot suite fails on any violation |
Addresses of other sites a page writes as text (an image's src, api(), stream(), httpTransport(), fetch, new WebSocket, new EventSource, a stylesheet's url()) checked against the policy when building, E0551 for one it blocks; a written-out policy keeps the shell's scripts and styles; E0550 for every setting a browser would misread | examples/typed-errors/duolith.yaml allows its api("https://example.com"); tests/typed-markup/data-layer/*/duolith.yaml | cargo test -p duolith-cli -- origins security csp_sources; duolith build examples/typed-errors shows only its type errors |
duolith test keeps the build's policy on: a function mock is compiled before the page loads, and a violation fails the test | examples/data/pages/posts.test.ts ("a mock written as a function") | duolith test examples/data |
Screenshot suites draw with fonts kept in the repository, so baselines match on any machine; --target web runs every suite | tools/screenshots/fonts/ | pnpm test:screenshots --target web |
The Screen IR and style table schemas, the runtime API (packages/client/api.d.ts) and the syntax tree API, each checked against the code | spec/ir/ | pnpm spec:validate; node tools/check-generated.ts |
| 46 conformance fixtures: a source with its expected IR, web and native output, or diagnostics | spec/conformance/ | pnpm spec:generate --check |
| Screenshot suites: the first screen of every example, and every kit page light and dark, beside the motion suite | tools/screenshots/baselines/web, kit, motion | pnpm test:screenshots --suite web (or kit, motion) |
| Web benchmarks: first-screen bundle, startup and a 2,000-row list's scroll, with recorded numbers | tests/benchmarks/ | pnpm bench:web |
| End-to-end flows across the social, data and navigation examples | tests/e2e/ | pnpm test:e2e |
| The native spike's screens, measured in Lynx for Web (the phone columns need devices) | spike/ | pnpm --dir spike measure |
Shown elsewhere, without a screenshot of its own
on:detentand the overlaydetentattribute: inside the Sheet part. The gallery binds its detent withbind:detent(gallery-overlays-sheet.png).zoomableandon:dismisson<image>: inside the ImageViewer part (gallery-inputs-and-media-viewer.png).pressToastAction(): the Toast part calls it for a toast's action button ("With undo" in gallery-overlays-toast.png).- Highlighting of page files outside VS Code (tree-sitter for Neovim, Helix and Zed; Shiki, highlight.js and Prism for docs; Rouge for GitLab; the GitHub and GitLab
.gitattributesfallbacks): every page inexamples/is coloured by each in the tests ofeditors/grammars/, and a sample page is in/mnt/project-files/demo/highlighting/(one screenshot per highlighter, seeeditors/grammars/README.md).
Not shown in an example
QueuedWriteGivenUp: a queued write gives up only after about eight minutes with no server.packages/client/testcovers it.dataCore,useDataHost,browserHost: hooks for tests and other hosts, not for pages.StateCell,DerivedCell: the classes behindstate()andderived().duolith build, optimized by default (minified, hashed names, import map,_headers;--no-optimizeleaves it out):crates/cli/tests/optimize_command.rsandpackages/kit/test/optimized-in-browser.test.tsbuild and load it.duolith api generate: every build runs it forapi/;crates/cli/tests/api_command.rsruns the command itself.- The 409 answer on the data example's sign-up page (
taken@example.com): the browser logs the refused request as a console error, and the screenshot script fails on console errors.
CLI
The CLI's output is text, so this section shows the real output instead of screenshots. It was captured with target/debug/duolith from a small project (cli-demo) that has one page with an unknown class.
duolith version
$ duolith version
duolith 0.0.0
duolith build and a diagnostic
$ duolith build cli-demo
pages/index.duo:6:20: error[E0103]: glow is not a utility, and no style block in this page defines .glow
6 | <view class="p-4 glow">
| ^^^^
help: Check the spelling against the utility reference, or define .glow in a <style> block.
more: duolith explain E0103
build failed: 1 error(s)
Every command accepts --json:
$ duolith build cli-demo --json
{"diagnostics":[{"code":"E0103","column":20,"file":"pages/index.duo","help":"Check the spelling against the utility reference, or define .glow in a <style> block.","line":6,"message":"glow is not a utility, and no style block in this page defines .glow","severity":"error"}],"ok":false}
With the class fixed:
$ duolith build cli-demo
built 51 files into cli-demo/dist
$ duolith build examples/gallery
built 149 files into examples/gallery/dist
duolith check
Every check duolith build makes, structure and then types, without writing anything (decision 0096). duolith build and duolith dev run the same type check. The first two of examples/typed-errors' eight errors:
$ duolith check examples/typed-errors
pages/index.duo:12:31: error[E0346]: Function lacks ending return statement and return type does not include 'undefined'. (TS2366)
12 | function label(level: Level): string {
| ^^^^^^
help: Some path through this code does not end the way the rest does, such as a switch that misses a case. Handle every case, or end with a return.
more: duolith explain E0346
pages/index.duo:24:16: error[E0340]: Argument of type '"serach"' is not assignable to parameter of type '"number" | "text" | "email" | "password" | "phone" | "search" | undefined'. (TS2345)
24 | <input type="serach" placeholder="Search" bind:value={search} />
| ^^^^^^
help: The value has a type this place does not accept, so it would show or do the wrong thing when the page runs. Change the value, or the type it is declared with.
more: duolith explain E0340
...
check failed: 8 error(s)
$ duolith check examples/minimal
1 page file(s) checked: no errors
duolith explain
$ duolith explain E0103
Unknown class
Classes are either utilities from the theme or classes defined in the page's own style block.
Fix: Check the spelling against the utility reference, or define .{class} in a <style> block.
Docs: https://docs.example.invalid/errors/E0103.html
$ duolith explain E0142
Routes match the same paths
A parameter matches any one segment, so pages/post/[id].duo and pages/post/[slug].duo would both serve /post/7, and neither could be chosen.
Fix: Keep one parameter name for this place in the path, or give one route a fixed segment.
Docs: https://docs.example.invalid/errors/E0142.html
duolith fmt
$ duolith fmt --check cli-demo
not formatted: cli-demo/pages/index.duo
1 page file(s) checked, 1 not formatted before
$ duolith fmt cli-demo
formatted cli-demo/pages/index.duo
1 page file(s) checked, 1 not formatted before
$ printf '<screen>\n<text>Hi</text>\n</screen>\n' | duolith fmt --stdin
<screen>
<text>Hi</text>
</screen>
fmt --check exits with 1 when a file is not formatted. It also fails when a named path does not exist or when it found no page file to check, and warns about a named file that is not a page file. CI runs duolith fmt --check examples/*/.
duolith lint (decision 0080)
Thirteen lint rules (W0001-W0061), set per project in duolith.yaml; docs/guide/lint.md lists them. CI runs duolith lint --deny-warnings on every example except lint-showcase, which trips every rule on purpose.
| Feature | Example | Output |
|---|---|---|
duolith lint with thirteen rules (W0001-W0061) | duolith lint examples/lint-showcase | pages/index.duo:32:4: warning[W0001]: <view> has on:press, but a keyboard cannot reach it and a screen reader does not say it can be pressed … pages/index.duo:45:6: warning[W0003]: text-muted on bg-border has a contrast of 4.0:1 in light mode; this text needs 4.5:1 … pages/index.duo:51:6: warning[W0004]: <button> can be pressed, but it is inside another element that can be pressed … pages/index.duo:79:16: warning[W0060]: p-2 has no effect: p-4 after it sets the same … components/Tag.duo:5:14: warning[W0041]: the prop tone is never used / lint: 0 error(s), 14 warning(s) (6 can be fixed with --fix) |
duolith lint --fix | duolith lint examples/lint-showcase --fix (on a copy), then duolith fmt --check on it | lint: fixed 6; 0 error(s), 8 warning(s): the input got label="Search todos", p-2, the <otherwise> and forgotten were removed, and #4b5bdc and #e2dfd8 became var(--color-primary) and var(--color-border); the view stays a view (making it a button changes the layout, so that fix is editor-only); then 2 page file(s) checked, 0 not formatted before |
--fix writes only what builds | crates/cli/src/lint.rs tests ("a fix that breaks the build is left out and named...", "fixing stops after the last pass...") | lint: did not apply "Remove a" (W0040) in pages/index.duo: the project did not build with it: ...; at most 10 passes |
duolith lint --json | duolith lint examples/minimal --json | {"configWarnings":[],"diagnostics":[],"fixed":0,"notApplied":[],"ok":true,"stoppedEarly":false}; --json | head does not panic (crates/cli/tests/lint_command.rs) |
Rule levels in duolith.yaml (off, warning, error) | examples/lint-showcase/duolith.yaml | a misspelt rule: error: duolith.yaml: lint.list-witout-key: not a lint rule; did you mean list-without-key? (exit 1); not UTF-8: error: duolith.yaml: it is not UTF-8 text (exit 1); a rule set twice: warning: duolith.yaml: lint.list-without-key: W0020 is the same rule and is set too; the later entry wins |
duolith explain by rule name | duolith explain list-without-key | List without a key … Lint rule list-without-key: set it to off, warning or error under lint: in duolith.yaml. |
| Lint warnings and quick fixes in editors | packages/language-server/test/server.test.ts ("a lint warning is shown and offers its fix") | W0002 on the feed's input, quick fix Label it "Share something" inserting label="Share something" |
A broken duolith.yaml in editors | packages/language-server/test/server.test.ts ("a duolith.yaml that is broken or not UTF-8...") | W0099 at the top of the page: duolith.yaml: it is not UTF-8 text, or duolith.yaml: lint.list-witout-key: not a lint rule; did you mean list-without-key? |
| Every other example lints clean | CI step "Every example lints clean"; crates/cli/src/lint.rs test | lint: nothing to report for each of the 14 other examples |
| The showcase runs: lint warnings never stop a build | duolith dev examples/lint-showcase | demo/lint-showcase-initial.png, demo/lint-showcase-pressed.png (no console errors) |
duolith scan
$ duolith scan examples/production
scanned 2 package(s) for web, iOS and Android
dom-tooltip 0.4.2 (MIT) web only
document [E0287] in tooltip.js:4 (2 use(s)); more: duolith explain E0287
window [E0287] in tooltip.js:7 (1 use(s)); more: duolith explain E0287
tiny-ordinal 1.0.0 (MIT) works everywhere
With --json, each package is a module manifest (spec/schemas/module.schema.json), with targets and what its browser field replaced. The command fails when a direct dependency is not supported or not installed.
Privacy declarations from duolith build
$ duolith build examples/production
built 88 files into examples/production/dist
$ grep -o 'NSPrivacy[A-Za-z]*' examples/production/dist/privacy/PrivacyInfo.xcprivacy | sort -u
NSPrivacyAccessedAPICategoryUserDefaults
NSPrivacyAccessedAPIType
NSPrivacyAccessedAPITypeReasons
NSPrivacyAccessedAPITypes
NSPrivacyCollectedDataType
NSPrivacyCollectedDataTypeCrashData
NSPrivacyCollectedDataTypeLinked
NSPrivacyCollectedDataTypeOtherDiagnosticData
NSPrivacyCollectedDataTypeProductInteraction
NSPrivacyCollectedDataTypePurposeAnalytics
NSPrivacyCollectedDataTypePurposeAppFunctionality
NSPrivacyCollectedDataTypePurposes
NSPrivacyCollectedDataTypeTracking
NSPrivacyCollectedDataTypes
NSPrivacyTracking
NSPrivacyTrackingDomains
dist/privacy/data-safety.json holds the same data types in Google Play's words (App interactions, Crash logs, Diagnostics), each optional because the example passes consent.
duolith dev
$ duolith dev examples/gallery --port 4460
duolith dev: http://localhost:4460/ (watching examples/gallery)
rebuilt
duolith doctor
$ duolith doctor
ok Rust compiler rustc 1.97.0 (2d8144b78 2026-07-07)
ok Cargo cargo 1.97.0 (c980f4866 2026-06-30)
ok Node.js v22.23.4
ok pnpm 10.28.0
absent Xcode needed for native targets: Install Xcode from the Mac App Store (macOS only)
absent Android Debug Bridge needed for native targets: Install Android Studio, or the Android SDK platform tools
ok Java openjdk version "21.0.12.1" 2026-08-18
duolith build --report
Across every example (pnpm bench --budgets): 11 of 234 files on rung 0, 30,852 of 1,016,535 module bytes saved; none of the gallery's 64 files, the effects example's 27 or the production example's 15, which all run scripts.
$ duolith build examples/styling --report
rung bytes saved bindings events file
0 5827 2481 0 0 pages/index.duo /
0 11687 4523 0 0 pages/borders.duo /borders
0 15526 6931 0 0 pages/color.duo /color
0 17981 7877 0 0 pages/layout.duo /layout
0 13927 6931 0 0 pages/spacing.duo /spacing
1 10128 - 2 2 pages/states.duo /states
6 files: 5 on rung 0 (tables), 1 on rung 1; 75076 bytes of modules, 28743 saved by tables; runtime 183457 bytes
$ duolith build examples/rust-module --report
rung bytes saved bindings events file
1 4904 - 4 2 pages/index.duo /
0 2200 199 4 0 pages/about.duo /about
module maths (rung 3): 26123 bytes of WebAssembly, 7542 of loader, used by pages/index.duo
2 files: 1 on rung 0 (tables), 1 on rung 1; 7104 bytes of modules, 199 saved by tables; runtime 183457 bytes
The first screen and the module in rust-module's build-report.json:
{
"version": 1,
"target": "web",
"bytecode": {
"isOpen": false,
"waitingFor": "spike/RESULTS.md: one function timed as bytecode, compiled TypeScript and Rust on a mid-range Android phone and an iPhone"
},
"screens": [
{
"kind": "page",
"source": "pages/index.duo",
"route": "/",
"module": "_duolith/pages/index.js",
"rung": 1,
"script": "source",
"reason": "it imports ../modules/maths, which runs when the screen opens",
"bytes": 4904,
"savedBytes": 0,
"bindings": 4,
"events": 2,
"effects": [],
"modules": ["maths"],
"warnings": []
}
],
"modules": [
{ "name": "maths", "rung": 3, "wasmBytes": 26123, "glueBytes": 7542, "usedBy": ["pages/index.duo"] }
]
}
$ pnpm --filter @duolith/modules bindings:native examples/rust-module/modules/maths
generated maths's bindings:
swift/maths.swift
swift/mathsFFI.h
swift/mathsFFI.modulemap
kotlin/uniffi/maths/maths.kt
The editor support in docs/guide/editors.md (the language server) runs inside an editor and has no screen in an example.
CLI and agent
The agent surface's output is text too, so this section shows real output. The create templates' screens were checked in Chromium through the tool server's screenshot_route; they are not part of the gallery run.
| Feature | Example | Screenshot |
|---|---|---|
Agent reference: llms.txt and one full file per topic in llms/, generated from spec/ and docs/ (decision 0060) | pnpm generate; node tools/check-generated.ts | none: output below |
New app from a template (blank, tabs, data), with AGENTS.md, CLAUDE.md and llms/; the skills come from Duolith's packs | packages/create/templates/ | none: output below |
| Tool server (MCP over stdio) with seventeen tools: the eight below, and run_tests, lint_project, scan_packages, check_project, upgrade_project, build_native, build_report, lookup_effect and lookup_theme_token; screenshot_route taps, types and navigates first and returns the console log (decision 0149) | packages/mcp-server; test/project-tools.test.ts | none: output below |
| 17 contributor skills and Duolith's 21 topic packs (rules and skills, decision 0160), with 39 evaluations (decision 0062); device and release skills check what can be checked here and list what needs a person | skills/contrib/, skills/packs/ | none: output below |
| Duolith's packs: every diagnostic code in exactly one rule, and 346 bad and good examples compiled to report what they say | duolith packs check --builtin; duolith packs test --builtin | Duolith's packs: 0 problem(s) / packs test: 346 examples, 0 failed |
| Grading an agent's own attempt at a skill's task | pnpm skills:eval --skill <name> --workspace <folder> | none: output below |
pnpm generate
$ pnpm generate && node tools/check-generated.ts
generated editors/grammars/duolith.tmLanguage.json
generated editors/others/sublime/Duolith/Duolith.tmLanguage
generated editors/grammars/tree-sitter-duolith/queries/highlights.scm
generated editors/grammars/highlighters/highlightjs/duolith.js
generated editors/grammars/highlighters/prism/duolith.js
generated editors/grammars/rouge/lib/rouge/lexers/duolith.rb
generated editors/others/helix/runtime/queries/duolith/highlights.scm
generated editors/others/helix/runtime/queries/duolith/injections.scm
generated editors/others/zed/languages/duolith/highlights.scm
generated editors/others/zed/languages/duolith/injections.scm
generated editors/others/neovim/queries/duolith/highlights.scm
generated editors/others/neovim/queries/duolith/injections.scm
generated editors/others/neovim/queries/duolith/locals.scm
generated editors/others/neovim/queries/duolith/folds.scm
generated editors/others/neovim/queries/duolith/indents.scm
generated docs/reference/README.md
generated docs/reference/elements.md
generated docs/reference/attributes.md
generated docs/reference/events.md
generated docs/reference/kit.md
generated docs/reference/diagnostics.md
generated docs/reference/utilities.md
generated docs/reference/cli.md
generated llms.txt
generated llms/language.md
generated llms/elements.md
generated llms/kit.md
generated llms/diagnostics.md
generated llms/styling.md
generated llms/data.md
generated llms/navigation.md
generated llms/production.md
generated llms/cli.md
generated llms/lint.md
generated llms/agents.md
check-generated: ok
Making an app
$ node packages/create/src/main.ts my-app --template tabs
made my-app
next:
cd my-app
duolith dev
$ ls -A my-app
.gitignore AGENTS.md CLAUDE.md README.md llms llms.txt pages skills
The tool server
The tools the SDK's client lists, then two calls:
explain_diagnostic, check_page, format_page, list_kit_parts, list_routes, build_project, lookup_docs, screenshot_route
== check_page {"project":"examples/minimal","page":"pages/index.duo","source":"<screen>\n <widget />\n</screen>\n"}
{ "ok": false, "diagnostics": [ { "code": "E0101", "column": 4, "file": "pages/index.duo", "line": 2,
"message": "<widget> is not an element", "severity": "error", "help": "Use one of: button, checkbox, … " } ] }
== lookup_docs {"name":"pressed:bg-raised"}
{ "kind": "utility", "name": "pressed:bg-raised", "pattern": "bg-{color}", "section": "color",
"description": "Background colour.", "declarations": { "background-color": "{color}" },
"prefixes": [ { "name": "pressed:", "kind": "state", "strength": 3, "description": "While the element is being pressed." } ] }
Skill evaluations
Each check runs on a fresh workspace (it must find the task undone) and after the reference solution (it must find nothing wrong):
$ pnpm skills:eval
ok skills/contrib/add-diagnostic/eval (undone: 1 problem(s); solved: 0)
ok skills/contrib/add-kit-part/eval (undone: 1 problem(s); solved: 0)
ok skills/contrib/add-platform-effect/eval (undone: 5 problem(s); solved: 0)
ok skills/contrib/add-server-feature/eval (undone: 1 problem(s); solved: 0)
ok skills/contrib/change-the-language/eval (undone: 1 problem(s); solved: 0)
ok skills/contrib/device-verification/eval (undone: 1 problem(s); solved: 0)
ok skills/contrib/motion-and-interactions/eval (undone: 4 problem(s); solved: 0)
ok skills/contrib/parallel-work/eval (undone: 1 problem(s); solved: 0)
ok skills/contrib/record-a-decision/eval (undone: 1 problem(s); solved: 0)
ok skills/contrib/release/eval (undone: 1 problem(s); solved: 0)
ok skills/contrib/repo-orientation/eval (undone: 1 problem(s); solved: 0)
ok skills/contrib/state-and-data/eval (undone: 1 problem(s); solved: 0)
ok skills/contrib/vscode-extension/eval (undone: 1 problem(s); solved: 0)
ok skills/contrib/write-a-brief/eval (undone: 1 problem(s); solved: 0)
ok skills/contrib/write-conformance-fixture/eval (undone: 3 problem(s); solved: 0)
ok skills/contrib/write-docs/eval (undone: 1 problem(s); solved: 0)
ok skills/contrib/write-rust-module/eval (undone: 1 problem(s); solved: 0)
ok skills/packs/accessibility/eval/make-it-accessible (undone: 1 problem(s); solved: 0)
ok skills/packs/assets/eval/add-images (undone: 1 problem(s); solved: 0)
ok skills/packs/components/eval/make-a-component (undone: 1 problem(s); solved: 0)
ok skills/packs/data/eval/load-and-show-data (undone: 1 problem(s); solved: 0)
ok skills/packs/data/eval/stream-live-data (undone: 1 problem(s); solved: 0)
ok skills/packs/data/eval/work-offline (undone: 1 problem(s); solved: 0)
ok skills/packs/effects/eval/use-effects (undone: 1 problem(s); solved: 0)
ok skills/packs/forms/eval/build-a-form (undone: 1 problem(s); solved: 0)
ok skills/packs/i18n/eval/translate-the-app (undone: 7 problem(s); solved: 0)
ok skills/packs/kit/eval/show-a-list (undone: 1 problem(s); solved: 0)
ok skills/packs/kit/eval/use-overlays (undone: 7 problem(s); solved: 0)
ok skills/packs/language/eval/build-a-screen (undone: 1 problem(s); solved: 0)
ok skills/packs/native/eval/build-for-native (undone: 3 problem(s); solved: 0)
ok skills/packs/navigation/eval/add-navigation (undone: 1 problem(s); solved: 0)
ok skills/packs/navigation/eval/guard-a-screen (undone: 2 problem(s); solved: 0)
ok skills/packs/packs/eval/make-a-pack (undone: 2 problem(s); solved: 0)
ok skills/packs/project/eval/fix-a-diagnostic (undone: 2 problem(s); solved: 0)
ok skills/packs/rust-modules/eval/add-a-rust-module (undone: 1 problem(s); solved: 0)
ok skills/packs/styling/eval/style-a-screen (undone: 1 problem(s); solved: 0)
ok skills/packs/styling/eval/theme-the-app (undone: 1 problem(s); solved: 0)
ok skills/packs/testing/eval/check-a-screen (undone: 2 problem(s); solved: 0)
ok skills/packs/testing/eval/write-tests (undone: 1 problem(s); solved: 0)
skills:eval: ok (39 evaluations)
Grading an attempt
$ pnpm skills:eval --skill add-navigation --workspace my-app
skills/packs/navigation/eval/add-navigation: 1 problem(s)
- pages/item/[id].duo does not exist
Toolchain
Testing, upgrading, the generated reference, debugging and the editor features (decisions 0065 to 0069). The output was captured from real runs. The two screenshots were taken through @duolith/testing.
| Feature | Demo | Captured output |
|---|---|---|
duolith test and @duolith/testing (decision 0065) | duolith test examples/control-flow (also examples/data with mocked loaded state and actions, examples/components with components rendered alone) | ✓ todos › adding a todo shows it in the list and counts it (466 ms) … ✓ todos › holding a todo stars it (1.1 s) / 4 passed, 0 failed, 0 skipped (2.8 s); screenshots taken through the API: demo/toolchain-test-initial.png, demo/toolchain-test-after-add.png |
duolith test --json (spec/schemas/cli/test.schema.json) | duolith test examples/data --json | {"files":[{"file":"pages/posts.test.ts","tests":[{"durationMs":436,"name":"the posts that load are shown","outcome":"passed"},…]}],"ok":true,"project":"examples/data","summary":{"durationMs":2361,"failed":0,"passed":5,"skipped":0}}; packages/testing/test/duolith-test.test.ts validates every run against the schema, including a failing fixture (1 passed, 2 failed, 1 skipped, exit 1) |
duolith test survives tests that misbehave | DUOLITH_TEST_TIMEOUT_MS=3000 duolith test packages/testing/test/fixtures/misbehaving (and fixtures/stuck with DUOLITH_TEST_DEADLINE_SECONDS=5) | ✗ forgets to await a check "1 check(s) were still waiting when the test returned: write await expect(...) so the test waits for each check."; ✗ leaves a rejection nothing handles "Nobody caught this"; ✗ times out, then tries to render "did not finish within 3 s"; ✓ runs after a test that timed out; ✓ loads a key named constructor for real; ✓ mocks a load with a method in shorthand; ✓ renders a component whose file name has a dash / 4 passed, 3 failed, 0 skipped (7.8 s), ending in 8.7 s with an open setInterval. The stuck project: {"error":"the tests did not finish within 5 s, so they were stopped","ok":false}, exit 1, scratch folder removed. --filter matching nothing: No test's name contains "…", so no test ran., exit 1 |
duolith upgrade with editions and migrations (decision 0067) | duolith upgrade examples/upgrade/edition-0.1 --dry-run; the upgraded app is examples/upgrade | -export let count = state(start); / +let count = state(start); … -export function visitAgain() { / +function visitAgain() { / edition 0.2: would change 2 file(s) |
duolith upgrade parses the script and reports what it cannot move | packages/testing/test/duolith-upgrade.test.ts; duolith upgrade <copy> --dry-run on a page with a template string, export default function shown(), export { shown as again } and export default { help } | the template string's export const not = 1; is untouched; -export default function shown() { / +function shown() {; -export { shown as again };; then "error: pages/index.duo: line 9: export default of a value with no name cannot be kept; give it a name (const shown = ...) or remove the export default" / "error: 1 statement(s) could not be moved to edition 0.2; fix them by hand and run duolith upgrade again", exit 1 (quoted without the message's backticks). The upgraded page of the first test builds with duolith build |
Reference docs generated from spec/ (decision 0068) | pnpm generate; pnpm check:repo fails when stale | generated docs/reference/elements.md … generated docs/reference/cli.md: 8 pages, 2,705 lines, 44 kit parts and 54 diagnostic sections |
Source maps in duolith dev, debugging recipe (decision 0069) | docs/guide/debugging.md; packages/testing/test/debugging.test.ts | sources: ["/pages/index.duo"] / pages/index.duo line 25 -> index.js line 32:2 -> back to line 25 (const title = draft.value.trim();); a CDP breakpoint set by that .duo line stops when Add is pressed |
| Editor structure: symbols, folding, selection, links, workspace symbols (decision 0066) | packages/language-server/test/features.test.ts on test/outline-fixture/ | workspace/symbol "pid": ["/post/[id]","route"]; the href="/post/7" value links to pages/post/[id].duo |
| Editor insight: semantic tokens, inlay hints, highlights, call hierarchy | same | inlay hints [{"line":11,"character":24},"→ post/[id].duo"], [{"line":12,"character":25},"→ no page"]; call hierarchy on Card: in [["index",3]], out ["Avatar"] |
Editor refactoring: wrap in <view>, extract to component, linked editing | same | code actions on <view class="p-2">: ["refactor.extract","Extract to component Extracted"], ["refactor.rewrite","Wrap in <view>"]; linked editing on <show>: [{"line":16,"character":3},{"line":18,"character":4}] |
| Extract to component with props | packages/language-server/test/features.test.ts; on the todo row of examples/control-flow | on the row <view> inside <list each={visible} as="todo" index="i">: type Todo = { id: number; title: string; done: boolean; starred: boolean }; / let { update, todo, i, remove } = props<{ update: (todo: Todo, change: Partial<Todo>) => any; todo: any; i: number; remove: (todo: Todo) => any }>();, placed as <Extracted update={update} todo={todo} i={i} remove={remove} />; the new component has no diagnostics. On <button on:press={() => (isOpen = !isOpen)}>: disabled, "It assigns isOpen, which would need a bindable prop." |
| Extract to component carries the page's style rules, and builds | packages/language-server/test/features.test.ts and test/page-styles.test.ts | extracting <text class="note">{i + 1}. {greeting}, {person.name}</text> gives a component ending <style> / .note { / color: var(--color-ink); / } / </style>, and a copy of the fixture with the edit applied passes duolith build; a class in .list .row gives "The style rule .list .row (in backticks) also needs .list, which is outside the markup." |
Duolith debug adapter (DAP), the VS Code duolith debug type (decision 0069) | F5 in VS Code with the extension; packages/debug-adapter/test/adapter.test.ts on examples/control-flow | setBreakpoints on pages/index.duo line 25: {"id":1,"line":25,"verified":false,"message":"Not loaded yet: the page has not opened this file."}, then breakpoint event {"id":1,"line":25,"verified":true}; after pressing Add, stopped {"reason":"breakpoint"}, top frame {"name":"add","source":"examples/control-flow/pages/index.duo","line":25,"column":17}; evaluate draft gives "Debug me" (the signal's value); after next: line 26, Local: add shows title = "Debug me" |
Docs site and release
The docs site is not an example app: pnpm docs:build writes it to docs/site/out/ from the guides, the specification, the catalogue and these examples (decision 0090). Open docs/site/out/index.html, or serve the folder. Its screenshots are made by node tools/release/site/screenshots.ts (see its header), not by the gallery script: the home page, a guide, an error page and search, at 1280x800 and 390x844, light and dark.
| Feature | Example | Screenshot |
|---|---|---|
| Docs site: home, guides, reference, one page per E-code and W-code, search, light and dark | pnpm docs:build, then docs/site/out/index.html | made by tools/release/site/screenshots.ts |
| Release dry run: next version, changelog section, npm packs and .vsix under placeholder names, CLI archives | pnpm release:dry; .github/workflows/release.yml (manual, dry run) | text output, no screenshot |
Editors
Editors have no screen in an example. Each one runs the same language server on any example's pages, such as examples/minimal/pages/index.duo. The Check column is the automated check. A check marked headless starts the editor itself (pnpm --filter duolith-editors-others test:headless). The other checks are part of pnpm check.
| Editor | Where | Highlighting | Check |
|---|---|---|---|
| VS Code | editors/vscode | TextMate grammar | pnpm --filter duolith-vscode test |
| JetBrains IDEs | editors/jetbrains (LSP4IJ) | TextMate grammar, through the TextMate bundle | plugin.xml, bundle and build agree (test/plugin.test.ts); pnpm --filter duolith-jetbrains plugin builds it, runs the Plugin Verifier and the headless IntelliJ tests, in which the real server answers hover and reports E0103 |
| Neovim 0.9+ | editors/others/neovim | Duolith tree-sitter grammar once its parser is installed, otherwise the Vim syntax file; plus semantic tokens | Lua parses; headless: the E0103 diagnostic, hover and semantic tokens arrive; with the parser built, tree-sitter starts and colours a page |
| Helix | editors/others/helix | Duolith tree-sitter grammar and its queries | languages.toml parses and names the grammar; the queries are the grammar's; indents.scm compiles against it |
| Zed | editors/others/zed | Duolith tree-sitter grammar and its queries | the TOML files parse and agree; the queries are the grammar's; indents.scm compiles against it (cargo test of the extension crate, which also starts the debug adapter, is run by hand) |
| Sublime Text 4 | editors/others/sublime | TextMate grammar, as a property list | the grammar is current and reads back rule for rule |
| Emacs 29+ | editors/others/emacs (eglot) | duolith-ts-mode on the Duolith tree-sitter grammar, or duolith-mode on html-mode without it | headless: both byte-compile; the diagnostic arrives through flymake, and hover answers; with the grammars built, every capture gets its face, TypeScript and CSS are embedded, imenu lists components, and indentation gives back the page |
Developer tools (wave 5, decisions 0145 to 0149)
Each row's check runs in pnpm check unless it says headless (pnpm --filter duolith-editors-others test:headless) or Rust (cargo test --workspace).
| Feature | Example | Check |
|---|---|---|
| An installed Duolith works outside the repository: the checker, test runner and templates ship beside the binary (decision 0145) | node crates/cli/install/stage.ts --binary target/debug/duolith --out <prefix>; docs/guide/projects.md | Rust: crates/cli/tests/installed_cli.rs makes, checks, builds and tests an app, and builds and tests a copy of examples/control-flow, in a temporary folder |
duolith create with the tabs-auth, effects, native, themed and tested templates | duolith create my-app --template tabs-auth | packages/create/test/create.test.ts: each builds, lints clean with --deny-warnings, is formatted and passes its tests; native builds for native |
duolith add for an effect, a kit part or an npm package, refused and restored when it cannot ship (decision 0146): the package files are put back and reinstalled, a project without package.json gets one, a copied part is formatted with its lint findings listed, and each refusal has a code (E0532 to E0539) | duolith add camera, duolith add Badge, duolith add ./vendor/tiny-ordinal in a copy of examples/production | Rust: crates/cli/src/add.rs, crates/cli/tests/add_command.rs; packages/testing/test/cli-json.test.ts |
duolith locales check and duolith locales extract [--rewrite] (decision 0148): text around values is one message, keys never collide (E0530), and --rewrite adds startTranslation() to the root layout when nothing calls it | duolith locales extract examples/control-flow --rewrite on a copy: it builds, is formatted and every locale has every key | Rust: crates/cli/src/locales_extract.rs, crates/cli/tests/locales_command.rs; cli-json.test.ts |
A --json schema for every command, each output checked against it | spec/schemas/cli/, commands.yaml names each | packages/testing/test/cli-json.test.ts |
Effect mocks for every export in effects.yaml, with recorded calls and effectError (decision 0147) | examples/effects/pages/share.test.ts | duolith test examples/effects |
Visual baselines with a tolerance, --update-snapshots, --watch, --file | packages/testing/test/fixtures/snapshots | packages/testing/test/duolith-test.test.ts |
Scan: the react-native field, server-only exports conditions, and a regular expression after if (...) (decision 0073) | docs/guide/production.md | Rust: crates/cli/src/scan/ |
| Language server: references and rename across unopened pages, signature help, type definition, theme colour swatches, code lenses for tests and preview | packages/language-server/test/xref-fixture/ | packages/language-server/test/server.test.ts, features.test.ts, held to checklist.yaml |
VS Code: commands, duolith tasks with a problem matcher, a test explorer, schemas for duolith.yaml, permissions.yaml, kit and module files | editors/vscode; open examples/control-flow and run Duolith: Run Tests | editors/vscode/test/workbench.test.ts runs each command and a test file through the explorer with the real binary |
| Debugging in nvim-dap, Helix, Zed and JetBrains (LSP4IJ) | docs/guide/debugging.md; editors/others/neovim/lua/duolith/dap.lua, helix/languages.toml, zed/src/lib.rs, editors/jetbrains/dap/duolith/ | headless: editors/others/test/headless/debuggers.test.ts launches each configuration's adapter for a copy of examples/minimal |