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) are opt-in. The wasm32 / browser entry point is the separate unpublished oxiui-web copy-template, not a facade feature.

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.2"

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

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

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

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 the unpublished oxiui-web copy-template in 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

The facade itself does not mount a browser canvas. On wasm32, App::run returns Err(UiError::Unsupported) directing you to oxiui_web::mount(canvas_id). That entry point lives in the unpublished oxiui-web crate (publish = false), which is provided as a copy-template for your own wasm app rather than a crates.io dependency. See its README for the browser API and build steps.

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

Note: there is no web feature. The wasm32 browser entry point lives in the unpublished oxiui-web crate (publish = false), used as a copy-template — see Web (wasm32) entry point above.

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)