quadraui

One Rust UI codebase that runs in a terminal and as a native desktop window.

quadraui is a widget toolkit with four rendering backends: TUI (via ratatui), GTK4 (Cairo + Pango), macOS (Core Graphics + Core Text) and Windows (Direct2D + DirectWrite). You write your app once, and the same code runs over SSH in a terminal or as a native window, with only the one-line runner call in main changing.

use quadraui::prelude::*;

struct Hello { keys_pressed: u32 }

impl Hello {
    fn config() -> ShellConfig {
        ShellConfig::new("Hello", Vec::new())
            .with_status_bar()
            // No panels, so no activity-bar column to pick one with.
            .with_activity_bar_width(0.0)
    }
}

impl ShellApp for Hello {
    fn render_content(&self, backend: &mut dyn Backend, layout: &AppShellLayout) {
        // The shell already computed where the status bar goes —
        // no viewport arithmetic here. Describe the UI as plain data;
        // the backend rasterises it natively.
        let Some(rect) = layout.status_bar_bounds else { return };
        let bar = StatusBar {
            id: WidgetId::new("status:bar"),
            left_segments: vec![StatusBarSegment {
                text: format!(" Hello, quadraui! (keys: {}) ", self.keys_pressed),
                fg: Color::rgb(255, 255, 255),
                bg: Color::rgb(40, 80, 120),
                bold: true,
                action_id: None,
            }],
            right_segments: vec![],
        };
        let mut frame = ScreenLayout::new();
        frame.push(Surface::StatusBar { rect, bar, hovered: None, pressed: None });
        frame.draw(backend);
    }

    fn handle(&mut self, event: UiEvent, _backend: &mut dyn Backend, _ctx: &ShellContext) -> Reaction {
        match event {
            UiEvent::KeyPressed { key: Key::Char('q'), .. } => Reaction::Exit,
            UiEvent::KeyPressed { .. } => { self.keys_pressed += 1; Reaction::Redraw }
            _ => Reaction::Continue,
        }
    }
}

fn main() {
    quadraui::tui::shell_runner::run_with_shell(Hello { keys_pressed: 0 }, Hello::config());
    // quadraui::gtk::shell_runner::run_with_shell(...), quadraui::macos::... or
    // quadraui::win::... for a native window: same `Hello`.
}

The full version is quadraui/examples/hello.rs: cargo run --example hello --features tui.

Why it is different

• Terminal and native from one codebase. Ratatui and Textual have no native backend; egui, iced and Slint have no terminal backend. quadraui has both, behind one trait.
• Paint and click share one layout. Every primitive exposes a layout(...) that the rasteriser paints from and the host hit-tests against. Mouse clicks cannot drift from what is on screen, because both read the same computed rectangles.
• Small, and idle when idle. A macOS release binary measured 0.7–2.0 MB in the 2026-09-26 audit. The runtime is event-driven: an app with nothing to do renders nothing.
• Declarative, serialisable widgets. Primitives are plain data (Serialize), events are plain data routed by WidgetId, and no closures cross the API. That is what makes scripting practical (vimcode lets Lua extensions declare quadraui views), and later, language bindings.
• Honest about capabilities. BackendCaps tells an app what the current backend can do. Where a terminal cannot do something (a tray icon, a native dialog) the backend degrades and says so, rather than silently doing nothing.
• Heavily tested. Around 5,900 tests, including headless paint-then-click round trips on all four backends, an end-to-end TuiDriver that drives real example apps through the event loop, and benchmarks for 100k-row tables and trees and a 4k-line editor.

Who it is for

A good fit: keyboard-driven developer, ops and data tools (editors, dashboards, log viewers, database and HTTP clients) that should run in a terminal over SSH and as a native window, written in Rust, by people comfortable with a pre-1.0 API.

Not a fit, today:

• Accessibility. There is no assistive-technology support: no AccessKit, AT-SPI, UI Automation or NSAccessibility. A screen reader sees nothing. That rules quadraui out wherever a Section 508, EN 301 549 or WCAG obligation applies. Tracked in quadraui#1309.
• CJK and other IME input. No backend implements an input-method protocol, so composed input (CJK, and dead-key accents) does not work. The design is quadraui/docs/IME_INPUT_PROPOSAL.md; the backend work is quadraui#900.
• Right-to-left text. East-Asian character width is handled; RTL, bidi and complex shaping are not, and are out of scope.
• Multiple windows (quadraui#1120), and languages other than Rust (bindings are a later phase, quadraui#1096).

Status

0.6.x — pre-1.0, published on crates.io. Breaking changes are grouped into scheduled minor releases and recorded in CHANGELOG.md. What a 0.x release may change is D-019 in quadraui/docs/decisions/DECISIONS.md; the release order and the 1.0 bar are in ROADMAP.md.

The real consumers are vimcode, a Vim-compatible editor that runs on all four backends, and coord-tui, a terminal dashboard. Both are by the same author, so quadraui has not yet been tried by an outside team. If you build something on it, please open an issue; that feedback is the most useful thing the project can get right now.

How it was built

quadraui is developed almost entirely by AI coding agents. Of its first 1,314 commits (April to October 2026), 1,107 are co-authored by Claude. The agents are coordinated by code-coordinator, which dispatches each issue to a worker on one of several machines and gates every merge on tests and on an adversarial review by a separate agent with no shared context. That pipeline, not a person reading every diff, is what holds the agents to the repository's rules.

You do not have to take that on trust. An independent audit of the framework, commissioned and published unedited, is at quadraui/docs/audits/FRAMEWORK_AUDIT_2026-09-26.md. It covers code quality, the alternatives, and what has to be true before 1.0. Its recommendations are tracked as epics on this repository's issue tracker.

Getting started

[dependencies]
quadraui = { version = "0.6", features = ["tui", "gtk"] }

Feature flags, the system packages each backend needs, and every platform combination CI verifies are in quadraui/docs/INSTALL.md. To track unreleased work instead of the last crates.io release, pin a git revision rather than following develop's tip — both real consumers do this today: quadraui = { git = "https://github.com/JDonaghy/quadraui", rev = "<commit-sha>", features = [...] }. For sibling-checkout development, use quadraui = { path = "../quadraui/quadraui", features = [...] }.

Then:

• Run hello (the ShellApp path above), then tui_demo / gtk_demo, which use the same AppLogic body under two runners.
• Or start a new app from the templates/app starter — cargo generate --git https://github.com/JDonaghy/quadraui templates/app — which already has the hello/main.rs shape above wired to all four backend features and a TuiDriver test, with no edits needed to build and run --features tui.
• Read quadraui/docs/GUIDE.md for the app model and quadraui/docs/APP_ARCHITECTURE.md for how a larger app is put together.
• Browse quadraui/examples/. Most examples come in tui_* / gtk_* pairs (some also macos_* / win_*), so you can compare backends.

Features

Pick the backends you ship; terminal is independent of them.

• terminal — PTY + vt100 + scrollback engine (quadraui::terminal_engine) for embedding a terminal. No rasteriser; pairs with any backend below.
• tui — terminal backend (quadraui::tui), via ratatui.
• gtk — GTK4 backend (quadraui::gtk), via gtk4-rs + Cairo + Pango.
• macos — macOS backend (quadraui::macos), via Core Graphics + Core Text. Compiles only on target_os = "macos".
• win — Windows backend (quadraui::win), via Direct2D + DirectWrite (windows-rs). Compiles on every host; only the WinAPI calls are cfg(target_os = "windows").
• layout — optional flex/grid layout module (quadraui::flex), via Taffy. Unit-agnostic (plain f32 in, plain f32 out); pairs with any backend above, or none.
• a11y — optional accessibility conversions (From<A11yRole> for accesskit::Role and friends) in quadraui::a11y, via AccessKit. The A11yRole/ A11yInfo data model itself is always compiled; pairs with any backend above, or none.

What's in the box

49 primitives, one module each under quadraui/src/primitives/: a declarative description and a shared layout, each with a rasteriser per backend — except DatePicker, which currently ships layout/hit-test logic only and has no backend rasteriser yet (it is a seam, exercised headlessly via quadraui/tests/date_picker_driver.rs). Among them:

• Content: TreeView, ListView, DataTable, Form, Editor, TextDisplay, MessageList, DiffView, Chart, Board, Terminal, Minimap, DatePicker (layout/hit-test only — no rasteriser yet), Canvas (app-defined drawing, painted through the public PaintSurface seam).
• Chrome: TabBar, StatusBar, MenuBar, ActivityBar, Toolbar, CommandCenter, Scrollbar.
• Containers: Split, SplitTree, Panel, MultiSectionView.
• Overlays: Dialog, Palette, ContextMenu, Tooltip, Float (anchored overlay above the main layout, stacked via ModalStack with focus vs. non-focus floats), Completions, FindReplace, Toast, plus ProgressBar and Spinner.

Compose controllers in quadraui::compose own the interaction state machines, so an app matches on semantic events (MenuEvent::Activated, SidebarEvent::RowSelected) instead of raw mouse coordinates:

Also in compose: a Markdown-to-StyledText adapter, and notify_or_toast, which sends a system notification where the platform has one and shows a toast where it does not.

See quadraui/docs/COMPOSE.md for what each controller owns, the events it emits, the smallest wiring snippet, and which example file demonstrates it.

Platform services: clipboard, file open/save and folder dialogs, message dialogs, notifications, open_url, reveal-in-file-manager, move to trash, secret storage, OS file drop, window control and a tray icon. Each is reported through BackendCaps, and degrades honestly on the terminal.

Testing

• Paint-then-click round trips. Paint a primitive into a headless surface, find the painted glyphs, click those exact coordinates, and assert paint and click identify the same widget.
• Conformance matrix. quadraui/tests/conformance.rs runs the same scenarios against every backend and reports a per-primitive matrix.
• End-to-end drivers. quadraui::tui::testing::TuiDriver runs a real AppLogic through the event → handle → render path against an in-memory terminal, with scripted keys, clicks and drags. See quadraui/docs/TESTING.md.
• Real terminals. A pty tier spawns example binaries in a real pseudo-terminal and checks the bytes they emit. Its results generate the table below.

Terminal compatibility

Generated from quadraui/tests/tui_pty_smoke.rs's pty tier, not hand-written. ✅ is verified by the named pty fixture, 🚫 is a cited known limitation, ❔ is untested. See quadraui/tests/terminal_matrix.rs for how to regenerate it.

Workspace

Design documents

• quadraui/docs/UI_CRATE_DESIGN.md — goals, non-goals and the core invariants.
• quadraui/docs/COMPOSE.md — every compose controller: what it owns, the events it emits, the smallest wiring example, and which example file shows it.
• quadraui/docs/PRIMITIVE_RULES.md — the rules every primitive follows, including the public-API lifecycle.
• quadraui/docs/decisions/DECISIONS.md — architectural decision log.
• quadraui/docs/NATIVE_GUI_LESSONS.md — pitfalls found building the native backends.
• quadraui/docs/CLIPBOARD.md — how terminal copy reaches the system clipboard, including tmux setup.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.

Third-party assets

quadraui/assets/codicon.ttf bundles Microsoft's codicon icon font, Copyright (c) Microsoft Corporation, used by every GUI backend (GTK, macOS, Windows) to paint built-in chrome glyphs — tree chevrons, tab dirty/close marks, the context-menu submenu arrow, data-table sort arrows — without requiring the host to have a Nerd Font installed. Licensed separately from the dual license above, under Creative Commons Attribution 4.0 International (CC-BY-4.0); the full license text ships at quadraui/assets/CODICON_LICENSE.