Architecture & packages
mbui is one MoonBit core that builds, lays out and paints a tree and draws everything itself on the GPU, plus thin platform hosts that put it on screen and feed it input. The core is split into packages with one job each, and it knows no application: nothing under libs/mbui may name an app (the detlint rule app-word).
| Package | What it owns |
|---|---|
@view | The retained window tree: nodes made once, structures (show, pick, each), one-way layout, virtual lists, focus. |
@signals | A port of alien-signals: signal, computed, derived_signal, effects and batching. |
@motion | Motion as data: springs, easings and NodeWay, computed from a cause moment. |
@headless | Pointer, keyboard and screen-reader behaviour per control kind. Draws nothing, lays out nothing. |
@ui | The shared runtime: run_tree, styles (@ui.css), theme, text fields, Tester and FakeHost. |
@film | Offscreen pictures and films of a tree: picture, film and bench. |
@hostapi | The Host trait. Every host call goes through it, so tests link no platform. |
@updater | Signed auto-updates: check_and_fetch a latest.json feed, status, apply. |
flex · text · paint | Layout and drawing. The flexbox passes Yoga's tests; text segmentation passes Unicode's own. |
Three layers, kept apart
- Framework@view: what every node needs (tree, layout, motion, virtual lists). Libraries never reimplement it.
- Headless@headless: how a control behaves to the hand, the keys and a screen reader. Knows no theme.
- Lookssf-ui, liquid-glass: styling over headless controls, and nothing else.
Retained views & fine-grained signals
A node is made once, when it first shows, and kept until it leaves. Properties that change are bound to signals with By(fn); constant ones are given with Is(v). When a signal changes, only the bindings that read it run again: nothing is rebuilt and nothing is diffed.
View::show · pick · each- Structures for dynamic children. each takes items, a key and a maker; keeps parks off-screen keys at rest instead of dropping them.
View::by_room- Structure that depends on the room given. Layout flows strictly one way: compute inside by_room, never read layout back from outside the tree.
View::scrolls_window- The virtual list. It owns slots, reading anchors, head and foot, multi-block bands and reused blocks; frame cost stays flat from 30 to 15,000 keys.
@signals.signal · computed- Values require T : Eq, so a recomputation that yields an equal value stops propagating. Use derived_signal for a writable derivation.
Styling, layout & tokens
Styles are flexbox boxes described by tokens. Write constant, top-level styles as @ui.css strings; keep @ui.style(...) for values computed at run time or inside functions, because a top-level @ui.style call generates a large amount of startup C (the detlint rule style-text).
Flexbox- row, w, h, p/px/py, gap, align, justify, radius, border and shadow, with dark, hovered, pressed, focused and narrow patches on the same style.
View::concentric_radius- A nested corner is derived from the container lent to it (corner_scope, corner_inset, concentric_end_pad), so it follows when the outer corner changes.
@ui.font_scale- The system text size, read live. Tests sweep it with Tester::set_font_scale so layouts hold at large text.
View::fits- Rows that run out of room hide optional children first, then shorten cut text down to 4 em, and only then shrink further.
Headless controls & look libraries
A headless control owns behaviour: focus, keys, pointer, presses and what a screen reader hears. Its caller hands it a look, a function that styles the node from the control's state. Bring your own design system by writing looks; never reimplement behaviour.
- button
- toggle
- toggle_group
- choice
- radio_group
- tabs
- slider
- disclosure
- accordion
- split
- table
- listbox
- combobox
- cmdk
- menu
- context_menu
- submenu
- dialog
- popover
- tooltip
- hover_reveal
- overlay
- anchor
- toaster
- text_field
- progress
- shortcut
sf-ui MIT
A production design system shipped as its own module (stillfail/sf). It imports only mbui and MoonBit's core, holds only general parts and design atoms, and a public part takes at most 8 arguments; larger ones become compound parts with slots.
liquid-glass Apache-2.0
A 1:1 port of Kyant0/AndroidLiquidGlass's catalog to mbui's tree. Every number comes from the catalog's source; behaviour is the headless button, toggle, slider, radio_group and dialog underneath.
Closed-form motion
Motion is data: a start, an end, a curve and the moment of its cause. Whatever is drawn at a given moment is computed from that data, so a run looks identical at 60, 120, 24 or 7 fps, or in one jump. There are no per-frame loops and no comparisons with the previous frame's geometry.
@motion.spring- A spring Spec from ratio and stiffness; motion_spring(duration, bounce=) describes the same by its duration and bounce.
@motion.NodeWay- One animated value on a node: go, go_from, go_ms and put set it off; shown reads it at the current moment.
View::at_moment- Runs a step at a declared moment. One scheduled in the past fires at the moment it was asked for, not late.
View::comes- The framework's one entry, exit and resize motion along a column. Children added by each or show join one group that starts and lands together; first answers settle at once.
Deterministic testing & offscreen film
A test drives the tree step by step, declares the exact moment it reads, and asserts. Time is declared, never waited for: no sleeps, no retries, no waiting for things to settle. The Tester installs FakeHost, so tests link no platform and run on Linux CI.
Tester::run_for- Advances to a declared moment, skipping idle time. Every test also runs at 60, 120, 24 and 7 fps (MBUI_TEST_FPS) and must match exactly.
Tester::audit- Checks layout rules on the current screen and names each fault's callsite.
sources_at · sources_of- Under a Tester, nodes record where they were made. Ask which lines drew a point or a phrase to trace a fault to its caller.
@film.picture · @film.film- Draw a tree offscreen to an image at a declared moment, or to a film from a script at a fixed fps. Apple and Linux film natively; other hosts link a stub.
Pictures are compared from the Tester's draw list and per-host offscreen renders, never from screenshots of devices, simulators or desktop windows.
Six-platform packaging & distribution
One CLI, libs/mbui/scripts/mbui (written in MoonBit under tools/pack), scaffolds, validates, packs, signs and publishes. mbui.json at your repository's root is the single source of truth; variants deep-merge on top of it and CLI flags win over both.
Two runtimes
--runtime wasm | --runtime native | |
|---|---|---|
| Build | MoonBit to .wasm (or .cwasm with --wasm-aot), injected into a prebuilt mbui-runtime shell | MoonBit to C, linked with the platform host sources |
| Native toolchain per app | None, once the shells are built (--runtime-dir) | Xcode, MSVC, GCC + GTK or the Android NDK |
| Native extensions | Standard mbui/hostapi only | Custom C, Objective-C or Java FFI |
Targets and formats
| --target | Formats | Signing |
|---|---|---|
mac | app zip dmg | --sign-identity --keychain --notarize-profile |
ios | .app .ipa | --ios-sdk --sign-identity --ios-profile |
android | apk | --keystore --key-alias --v3-signing |
win | portable zip setup | --win-cert --win-timestamp |
linux | tar.gz deb appimage | — |
web | index.html host.js .gz/.br PWA | — |
Updates and releases
mbui publish signs a latest.json feed with an Ed25519 key, can make binary deltas from earlier releases, verifies the feed and uploads artifacts before the feed (providers: dir, github, s3). In the app, @updater.check_and_fetch reads the feed and @updater.apply installs once the status is Ready. mbui repack rebrands an existing APK for a variant without recompiling.