ashlar

A lightweight, modern application framework for Rust, powered by egui.

ashlar gives a desktop (and, for its headless core, web) application the parts every app rebuilds: documents with undo and autosave; commands that drive menus, shortcuts, a command palette, a CLI and an MCP server; background jobs; files and settings; native OS features; a component library on egui; and crash safety and telemetry. An idle ashlar app does no work at all.

Status: early (0.1). The API will change between minor versions until 1.0.

Why ashlar

• Everything is a command. Menus, shortcuts, the palette, the CLI, the control port and MCP all go through one registry and one execute chokepoint, so anything a user can do, a script or an AI agent can do too.
• Never crashes. No unwrap, panic! or unsafe outside tests (enforced by lints and a CI gate). Panics in a view, a command or a job are caught; the session survives and unsaved work is recovered on the next launch.
• Zero work when idle. Frames are drawn only when something asks for one: input, a document change, a finished job, a running animation. No polling. A focused text field stops its caret after 10 s, and a settled animation asks for nothing.
• Fast where it matters. It scrolls a 1,000-row list in 0.10 ms of CPU per frame with list::Row, and a virtualized list in 0.035 ms whatever its length. It draws a static 52 KB markdown document in 0.03 ms. Allocations per frame and frame time are gated in CI. The numbers, the method and a comparison with another native Rust UI framework are in docs/benchmarks.md.
• Built for agents. Every app takes --headless --snap out.png --tree tree.json (real pixels, no window). .ui scripts run in process on a virtual clock, and app.clock pauses and steps time. Golden screenshots, named scenes, a motion and jank gate, and record and replay come with it.
• Motion and accessibility. Animations use springs that keep their velocity when retargeted, and follow the OS reduced-motion, accent and contrast settings. Every component reports AccessKit roles and states, and the gallery's accessibility trees are golden-tested.
• Headless core. Documents, commands, jobs and files never touch the UI, so they run in tests, in a CLI, behind MCP and in the browser.
• Small crates. Use the umbrella crate, or pick only the layers you need: each ashlar-* crate works on its own.

Quick start

cargo add ashlar-rs

The package is published as ashlar-rs; the library is still imported as ashlar.

use ashlar::prelude::*;

#[derive(Clone, Default, serde::Serialize, serde::Deserialize)]
struct Doc {
    notes: Vec<String>,
}

fn add(s: &mut Session<Doc>, p: &Value) -> Result<Value, CommandError> {
    let text = p.get("text").and_then(Value::as_str).unwrap_or("New note").to_string();
    s.edit("Add Note", |d| d.notes.push(text)); // one undo step per command
    Ok(json!(s.doc().notes.len()))
}

fn main() -> Result<(), ashlar::app::Error> {
    App::<Doc>::new("jot", env!("CARGO_PKG_VERSION"))
        .format(Format::new("example.jot", "jot 0.1"))
        .commands([cmd!("note.add", "Add Note", ["Edit"], Some("Mod+Shift+N"), [Param::string("text")], always, add)])
        .view(|ui, cx: &mut Cx<'_, Doc>| {
            for n in &cx.doc().notes {
                ui.label(n);
            }
            if ui.button("Add").clicked() {
                cx.dispatch("note.add", json!({}));
            }
        })
        .run() // undo/redo, save/open/autosave, menus, palette, crash guard, control port
}

App::cli() turns the same definition into a -cli binary with commands, exec, run, mcp and serve. --control <port> lets an agent drive the window. Try the examples:

cargo run -p ashlar-example-notes      # a small document app
cargo run -p ashlar-example-gallery    # every UI component

The umbrella crate's features:

cargo add ashlar-rs --features native-menu,telemetry

Binary size: the smallest app (examples/hello) is 13.6 MB stripped in a release build on macOS arm64. cargo build --profile release-small (a profile in this workspace: fat LTO, one codegen unit, opt-level = "s", stripped) brings it to 9.0 MB; copy the profile into your own Cargo.toml. default-features = false saves about 1 MB more, at the cost of accessibility and --headless. cargo xtask bench tracks the number as hello_stripped_bytes.

Crates

Every crate is published on crates.io under the same version, with its API docs at https://docs.rs/<crate>. Depend on a single layer when that's all you need, for example cargo add ashlar-store for documents and undo in a headless tool.

How the crates stack is in docs/architecture.md.

Compatibility

Linux build dependencies (Debian/Ubuntu names):

sudo apt-get install libgtk-3-dev libxdo-dev libxkbcommon-dev libdbus-1-dev

Native features differ by platform. Where one isn't available, the call returns NativeError::Unsupported and nothing panics. Some highlights (the full matrix is in crates/native):

Built on egui, eframe, wgpu, rfd, muda and rustls.

Built with ashlar

• bay and bay-effects by Marl Studio are built on top of ashlar.

Building something with ashlar? Open a pull request to add it here.

Documentation

The guide, developer docs and changelog are at ashlar.himanshuat.com (llms-full.txt for AI agents).

• Architecture: crate ranks, design principles, the performance gate
• Benchmarks: how fast ashlar is, how it is measured, and a head-to-head comparison
• Control protocol: driving an app from scripts and agents
• Debugging UIs with ashlar-debug
• Telemetry: integration, privacy, self-hosting, wire format
• UI: docking, visual regression tests
• API reference on docs.rs

Contributing

Contributions are welcome. Read CONTRIBUTING.md first. Every change must pass cargo xtask ci. Please follow the Code of Conduct, and report security issues privately as described in SECURITY.md.

License

ashlar is licensed under the BSD 3-Clause License. Unless you say otherwise, any contribution you submit for inclusion in ashlar is licensed the same way.