oxiui — The COOLJAPAN Pure-Rust GUI facade

oxiui is the top-level façade crate for OxiUI — the COOLJAPAN Pure-Rust UI layer with no GTK (C), no Qt (C++), no SDL (C), no system widgets, and no raw AppKit / Win32 / Cocoa bindings. It wraps the immediate-mode widget API from oxiui-core, selects a render + framework backend through Cargo features, and re-exports everything an application needs behind one builder: App. By default it boots an egui application rendered via wgpu; alternative backends (iced, Slint, Dioxus, software, web/WASM) are opt-in.

The facade is the only crate most applications depend on. It owns the application life-cycle: window configuration (AppConfig), the event loop (App::run), headless rendering for CI (App::run_headless_once, App::screenshot), and cross-cutting features — plugins (Plugin), global hotkeys (HotkeyRegistry), a fuzzy-searchable command palette (CommandPalette), and a toast NotificationQueue. GPU drivers (Vulkan/Metal/DX12/WebGPU) are OS-provided at runtime and do not appear in cargo tree --edges normal, keeping the build Pure Rust.

Default-features note (GOVERNANCE §6): default = ["gpu", "egui"]. A zero-feature facade build must select at least one Pure adapter (ADAPTER_PATTERN §3 rule 4), mirroring precedents such as oxicrypto's default = ["pure"] and oxitls's default = ["pure", "webpki-roots"]. For a strictly minimal / ffi-audit build use --no-default-features --features software.

Installation

[dependencies]
# Default: egui + wgpu native app
oxiui = "0.1.0"

# Headless / ffi-audit: CPU softbuffer framebuffer, no GPU stack at build time
oxiui = { version = "0.1.0", default-features = false, features = ["software"] }

# iced retained-mode backend
oxiui = { version = "0.1.0", features = ["iced"] }

# Everything: tables, accessibility, web, plus the iced backend
oxiui = { version = "0.1.0", features = ["iced", "table", "a11y", "web"] }

Quick Start

egui backend (default)

use oxiui::{App, AppConfig};

App::new(AppConfig::new().title("Hello OxiUI"))
    .theme(oxiui::theme::cooljapan_default())
    .content(|ui| {
        ui.heading("Hello, world!");
        if ui.button("Quit").clicked { /* exit logic */ }
    })
    .run()
    .expect("UI error");

iced backend

use oxiui::{App, AppConfig, Backend};

App::new(AppConfig::new().title("Hello OxiUI (iced)"))
    .theme(oxiui::theme::cooljapan_default())
    .backend(Backend::Iced)
    .content(|ui| {
        ui.heading("Hello from iced!");
        if ui.button("Quit").clicked { std::process::exit(0); }
    })
    .run()
    .expect("UI error");

Headless (CI-friendly, no display)

use oxiui::{App, AppConfig};

let exit = App::new(AppConfig::new().title("smoke"))
    .content(|ui| { ui.heading("h"); })
    .run_headless_once()?;
assert_eq!(exit, oxiui::AppExit::Ok);
# Ok::<(), oxiui::UiError>(())

Backend Selection

The active backend is chosen with App::backend and the Backend enum. The default is Backend::Egui. Each non-default variant is gated behind its own Cargo feature; the variant is only present when its feature is enabled.

The egui-on-wasm32 path is not driven through App::run (which returns UiError::Unsupported on wasm32); instead use oxiui::web::mount from a browser binary.

API Overview

Application builder

App builder methods

Cross-cutting feature types

Pluggable runner infrastructure (oxiui::runner)

Note: EguiRunner / IcedRunner are stable public types but currently wiring stubs — the live render paths remain inside App::run. Full delegation lands in M6.

Re-exported modules

Crate-root re-exports

From oxiui-core at the crate root: ButtonResponse, Color, FontSpec, Palette, Theme, UiCtx, UiError. From runner: BackendRunner, LifecycleConfig (always), plus EguiRunner (egui) and IcedRunner (iced). From theme_picker: theme_by_name, theme_picker, BUILTIN_THEMES.

Web (wasm32) entry point

With --features web, oxiui::web::mount(canvas_id) boots an OxiUI app on a <canvas> (wasm32 only; returns Err on native). See oxiui-web for the full browser API.

Feature Flags

Features fall into two groups: render backends (how pixels reach the screen) and framework backends (which widget framework drives the frame), plus optional capability modules.

Render backends

Framework backends

Capability modules

Errors

App methods return Result<_, oxiui_core::UiError>. UiError is #[non_exhaustive].

A separate HotkeyConflict error (its own std::error::Error type) is returned by App::try_hotkey / HotkeyRegistry::register on a duplicate (Modifiers, Key) binding.

Examples

The crate ships runnable examples (see examples/):

cargo run --example hello                              # egui (default)
cargo run --example hello_iced   --features iced       # iced backend
cargo run --example hello_table  --features table      # table widget
cargo run --example hello_slint  --features slint      # Slint adapter
cargo run --example hello_dioxus --features dioxus     # Dioxus adapter

Related Crates

License

Apache-2.0 — COOLJAPAN OU (Team Kitasan)