Get Started
Documentation

Build with mbui

How the framework is put together, how to write views that are made once and updated by signals, and how to test, film and ship them to six platforms. Every name on this page is taken from the source in libs/mbui.

New here? Start with the quickstart Experimental: APIs change without notice
01

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).

PackageWhat it owns
@viewThe retained window tree: nodes made once, structures (show, pick, each), one-way layout, virtual lists, focus.
@signalsA port of alien-signals: signal, computed, derived_signal, effects and batching.
@motionMotion as data: springs, easings and NodeWay, computed from a cause moment.
@headlessPointer, keyboard and screen-reader behaviour per control kind. Draws nothing, lays out nothing.
@uiThe shared runtime: run_tree, styles (@ui.css), theme, text fields, Tester and FakeHost.
@filmOffscreen pictures and films of a tree: picture, film and bench.
@hostapiThe Host trait. Every host call goes through it, so tests link no platform.
@updaterSigned auto-updates: check_and_fetch a latest.json feed, status, apply.
flex · text · paintLayout and drawing. The flexbox passes Yoga's tests; text segmentation passes Unicode's own.

Three layers, kept apart

  1. Framework@view: what every node needs (tree, layout, motion, virtual lists). Libraries never reimplement it.
  2. Headless@headless: how a control behaves to the hand, the keys and a screen reader. Knows no theme.
  3. Lookssf-ui, liquid-glass: styling over headless controls, and nothing else.
02

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.

///| fn main { let count = @signals.signal(0) @ui.run_tree("Counter", fn(root) { root .grow(@view.Is(1.0)) .pad(@view.Is(24.0)) .box(fn(col) { // bound: re-runs only when count changes col.words(@view.By(fn() { "Pressed \{count.get()} times" })) |> ignore @headless.button( col, fn() { "Increment" }, fn(_) { count.set(count.get() + 1) }, fn(v, _) { v.pad(@view.Is(12.0)).ground(@view.Is(0xEF6334FFL)) |> ignore }, ) |> ignore }) |> ignore }) }
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.
03

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).

// constant: parsed once, from sf-ui's accordion let card : @ui.Style = @ui.css("w=Full bg=Surface border=B0_5 border_color=Line") let head_row : @ui.Style = @ui.css("row w=Full px=S3_5 py=S3 gap=S3 align=AStart") // computed: only where a value is known at run time fn gap_for(dense : Bool) -> @ui.Style { @ui.style(row=true, gap=if dense { S2 } else { S3 }) }
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.
04

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
// a look library wraps the headless button and adds only styling #callsite(autofill(loc)) pub fn primary(parent : @view.View, label : String, act : () -> Unit, loc~ : SourceLoc) -> @view.View { @headless.button(parent, fn() { label }, fn(_) { act() }, fn(v, _) { v.height(@view.Is(Some(40.0))).ground(@view.Is(0x171717FFL)) |> ignore }, made_for=loc) }

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.

05

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.

let press = @motion.NodeWay::new(0.0) let spec = @motion.spring(ratio=0.8, stiffness=400.0) // set off from the cause (a press), never from a frame loop fn on_down(n : @view.View) -> Unit { press.go(n, 1.0, spec) } fn on_up(n : @view.View) -> Unit { press.go(n, 0.0, spec) } // read at draw time: the value at this moment fn pressed(n : @view.View) -> Double { press.shown(n) }
@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.
06

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.

test "pressing increments the count" { let count = @signals.signal(0) let t = @ui.Tester::tree(fn(root) { counter(root, count) }, w=390.0, h=844.0) t.click(Button, label="Increment") t.run_for(300.0) // the moment, declared assert_eq(count.get(), 1) assert_eq(t.audit(), []) // layout rules hold }
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.

07

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.

$ libs/mbui/scripts/mbui init ./my-app --name "Acme Client" --id dev.example.acme --mbui "$PWD/libs/mbui" $ libs/mbui/scripts/mbui check ./my-app/mbui.json --runtime wasm $ libs/mbui/scripts/mbui pack ./my-app/mbui.json --target web,mac --runtime wasm \ --runtime-dir ./runtime --format app,zip --out ./my-app/dist

Two runtimes

--runtime wasm--runtime native
BuildMoonBit to .wasm (or .cwasm with --wasm-aot), injected into a prebuilt mbui-runtime shellMoonBit to C, linked with the platform host sources
Native toolchain per appNone, once the shells are built (--runtime-dir)Xcode, MSVC, GCC + GTK or the Android NDK
Native extensionsStandard mbui/hostapi onlyCustom C, Objective-C or Java FFI
# build the prebuilt runtime shell once per platform $ MBUI_OUT=./mbui-out libs/mbui/scripts/runtime.sh build mac $ libs/mbui/scripts/runtime.sh check # wasm host ABI matches host_native.mbt

Targets and formats

--targetFormatsSigning
macapp zip dmg--sign-identity --keychain --notarize-profile
ios.app .ipa--ios-sdk --sign-identity --ios-profile
androidapk--keystore --key-alias --v3-signing
winportable zip setup--win-cert --win-timestamp
linuxtar.gz deb appimage—
webindex.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.

$ libs/mbui/scripts/mbui publish mbui.json keygen --out ./release-key.pem $ libs/mbui/scripts/mbui publish mbui.json feed --file "./dist/mac/Acme Client-mac.zip" --key ./release-key.pem --out-dir ./rel $ libs/mbui/scripts/mbui publish mbui.json --dir ./rel --provider github --target acme/client --tag v1.0.0

Full reference: libs/mbui/docs/PACKAGING.md