0005 - Toolkit seam
Status: Implemented (2026-11-17)
ADR 0009 fixes the product decision: Auro is the application layer and ships no component toolkit. This spec defines the small seam that makes the decision usable: how an app initializes the toolkit it chose and how it puts that toolkit's root around Auro's view.
Scope
App::setup: a hook that runs after GPUI starts and before any window opens.App::root_with: a way for the app to build the window's root view instead ofV::default().- The default
App::rootstays as theDefault-only sugar. - The config handoff that lets an app apply
app.windows[].themeto its toolkit. - Documentation of one tested integration (
gpui-component 0.5.xwith GPUI 0.2.2).
Out of scope
- Any component toolkit, component implementation, component tests or toolkit compatibility guarantee beyond the documented line.
- Auro-owned themes or a theme system.
- Per-window toolkit theming, dialogs, notifications, focus management: the toolkit owns them.
- Loading a toolkit through a plugin; this is a normal application dependency.
Decisions
D1 - The framework owns no toolkit
auro-ui remains the GPUI seam: re-exports, tokens, and the primitives the scaffold needs. A
toolkit is an app dependency (gpui-component, a private crate, or none). See
ADR 0009.
D2 - Setup runs once, before windows
App::setup registers a closure invoked once per app, in registration order, after the GPUI
application starts and before any configured window opens. It receives the parsed Config so the
app can choose a toolkit theme from the same file that declares the windows.
Setup APIs have no error channel. A panic in setup is an application bug and aborts the process the same way a panic in a view would; Auro does not hide it.
D3 - The app can own the window root
App::root_with takes a builder that returns Entity<V> for the window. It exists because some
toolkits must be the window root (they host dialogs, notifications, sheets and input focus above
the app's view). The builder runs inside the GPUI window callback, after the window is created and
its title is set.
App::root::<V> is sugar for a builder that returns cx.new(|_| V::default()). Both paths share
the same window creation and title handling; a change to one applies to the other.
D4 - Windows keep their existing contract
Every window declared in Auro.toml is opened once, in declaration order, using the root
registered for its label. A window with no matching root logs an error and does not open. Labels
remain unique. Setup does not change the window list.
D5 - Config is the only handoff
The app receives the same Config that declares its windows. app.windows[].theme is parsed and
passed through; the app maps it to its toolkit in setup. auro doctor reports a non-system theme
as toolkit-owned instead of claiming the renderer ignores it.
Per-window themes depend on the toolkit. A toolkit with one global theme (as gpui-component has)
can honor one window's theme, not a different theme per window; the app must decide and document
that. Auro does not pretend otherwise.
D6 - One tested integration, versioned honestly
The documented integration is gpui-component 0.5.x with the pinned gpui = 0.2.2. The current
component line (0.10.x) requires gpui-pre = 0.3.12; using it requires moving the renderer pin and
is not part of this spec. Measured probe (2026-11-17, Linux x86_64, release, stripped,
panic = "abort", one Button + Root): 22.0 MB with the toolkit against 15.5 MB without it, and
spawn→window 147.3 ms against 139.8 ms (median, N=5; not first paint). The app pays the toolkit's
binary size; Auro's minimal app does not.
Interfaces
impl App {
/// Runs after GPUI starts and before any window opens; registration order.
pub fn setup(self, f: impl Fn(&mut gpui::App, &Config) + 'static) -> Self;
/// Builds the window root instead of `V::default()`.
pub fn root_with<V: Render + 'static>(
self,
label: &'static str,
f: impl Fn(&mut Window, &mut gpui::App) -> Entity<V> + 'static,
) -> Self;
/// Unchanged sugar for a `Default` view.
pub fn root<V: Render + Default + 'static>(self, label: &'static str) -> Self;
}
Order inside Application::run:
setups (registration order) -> configured windows, in order:
window created, title set -> root builder -> window mapped
-> on_window_closed -> activate
A toolkit integration looks like this (illustrative, not compiled in this repository):
# app Cargo.toml - not Auro's
[package]
name = "log-viewer"
[dependencies]
auro = { path = "../auro/crates/auro" }
gpui-component = "=0.5.1"
use auro::prelude::*;
use gpui_component::{Root, Theme as KitTheme, ThemeMode};
fn main() {
App::new()
.setup(|cx, config| {
gpui_component::init(cx);
let mode = match config.app.windows[0].theme {
auro::Theme::Dark => ThemeMode::Dark,
auro::Theme::Light => ThemeMode::Light,
auro::Theme::System => ThemeMode::Light, // or follow the system appearance
};
KitTheme::change(mode, None, cx);
})
.root_with::<Root>("main", |window, cx| {
let view = cx.new(|_| LogViewer::default());
cx.new(|cx| Root::new(view, window, cx))
})
.run();
}
The app adds the toolkit, not Auro. If the toolkit does not need a custom root, root::<V> is still
enough and no wrapper is required.
Acceptance
- A setup closure runs once, in registration order, before any root builder; a headless test
records the order (
app::tests::setup_runs_before_roots_and_root_with_uses_the_app_builder). root_withopens every declared window that has a root and uses the app's builder; the same test asserts one window opens and the builder ran.rootkeeps its existing behavior; the window-title and window-options tests cover the shared opener.Configreachingsetupincludes the declared theme;auro doctorreports a non-system theme as toolkit-owned.docs/src/architecture/toolkits.mddocuments choosing a toolkit, the0.5.x/0.10.xsplit, and the measured size caveat;mdbook build docspasses.cargo fmt --all --check,cargo clippy --workspace --all-targets --locked -- -D warnings, andcargo test --workspace --lockedpass.
Open questions
| Question | Where it settles |
|---|---|
Whether to publish an optional auro-gpui-component integration crate | After the next GPUI line migration; ADR 0009 keeps the core toolkit-free meanwhile |
| How per-window themes map onto a toolkit with a global theme | App-level decision documented by the app; Auro passes the config through |
| Whether an optional toolkit integration should provide a shared theme bridge | Phase 3, if more than one toolkit needs it |