0001 - Foundation
Status: Implemented (Phase 0 closed 2026-11-17)
Phase 0 exists to answer one question: does an Auro app feel like a native app, and is the loop fast enough to live in? This spec defines the smallest set of contracts that makes the vertical slice real, and nothing beyond it.
Scope
- A Cargo workspace with the crates needed for the slice, and only those.
Auro.toml: the configuration surface an app author edits (fields in 0002).auro new,auro dev,auro build,auro doctor.- A typed command contract:
#[auro::command],generate_handler!,AuroError. - Application state, reachable from commands and views (app-wide events arrive with the Phase 1 lifecycle work).
- The GPUI seam: how Auro owns the main thread and hands the renderer a view.
- The generated project skeleton.
Out of scope
- Plugins, capabilities enforcement, bundling output, updater, signing - later phases, later specs.
- Hot reload. Phase 0 relaunches the process; the
< 500 mstarget and mechanism are tracked in spec 0004. - A component kit. Phase 0 ships the primitives the slice needs, styled by tokens.
- App-wide events and lifecycle management. Both arrive in Phase 1 with the window manager.
- Embedded config, embedded assets,
$schemageneration and build-script codegen. Config loads at runtime until the bundler lands. - Mobile.
Decisions
D1 - Six crates now, eleven in the full graph
Phase 0 materialises auro (facade), auro-core, auro-ui, auro-ipc, auro-macros,
auro-cli. auro-bundle joins in Phase 2 (spec 0010); auro-perms, auro-plugins,
auro-update, auro-sign arrive with the phase that needs them.
Rejected: creating all nine empty crates now. Empty crates invite speculative APIs and make the
workspace look finished when it is not. Rejected: folding IPC into auro-core. The command
boundary is the thing the project is built around; it gets its own crate from day one.
| Crate | Kind | Depends on | Responsibility |
|---|---|---|---|
auro | lib | core, ui, ipc, macros | App builder, window attachment, prelude; the only crate an app depends on |
auro-core | lib | ipc | config loading, state store; re-exports the IPC runtime; no renderer types (lifecycle and events in Phase 1) |
auro-ipc | lib | - | CommandArg, IpcResponse, Invoke, registry, AuroError, tokio runtime bridge |
auro-macros | proc-macro | - | #[command], generate_handler! |
auro-ui | lib | core | the only crate that names gpui; primitives, tokens, Render re-export; themes are toolkit-owned (ADR 0009) |
auro-cli | bin | core | new, dev, build, doctor; no runtime logic |
Rules: no cycles; auro-ui holds no policy (no filesystem, no config reads); gpui is a
dependency of exactly one crate (auro-ui), and app-level tests enable its test-support feature
through a dev-dependency; auro-core never names a renderer type. The builder lives in the facade
because it is the one place that must know both the app model and the renderer.
Rejected: the builder in auro-core. It would force gpui into core's manifest or a
renderer-abstraction trait layer that buys nothing in Phase 0.
D2 - GPUI is pinned exactly
gpui = "=0.2.2" # in auro-ui only
Edition 2024, resolver 3, workspace MSRV 1.90 (the floor tauri-bundler 2.10 declares).
Exact pins, not ranges: GPUI is pre-1.0 and breaks on minor bumps. Upgrading is a deliberate
change with a changelog entry, not something cargo update does behind our back.
Rejected: a git dependency on Zed's main. It turns every cargo build into a lottery and is
how a compat layer becomes a fork.
D3 - Two executors, one bridge
GPUI ships its own executors (smol-based). Context::spawn polls on the main thread; nothing in
GPUI runs a tokio reactor. A command body calling tokio::fs from GPUI's executor panics with
"no reactor running".
Therefore #[auro::command] is a code transform, not metadata: it wraps the body in
auro_ipc::runtime::run(async move { /* body */ }) (re-exported as auro_core::runtime) and awaits
the task, so the body always runs on Auro's multi-threaded tokio runtime no matter who awaits it. A
sync command runs through runtime::run_blocking. The runtime is a process-global LazyLock
created on first use, so tests and first-party call sites work without App::run.
The other rules:
- Views, entities and window state are
!Sendand never cross threads. - Command arguments and return values are
Send + 'static; results come back throughEntity::update/AsyncApp::update, thencx.notify()schedules the repaint. - Any
awaitinside a command must not hold an entity borrow.
Rejected: one thread per command. Unbounded, untraceable, hostile to cancellation. Rejected:
running commands on GPUI's executor. tokio APIs would panic, and blocking work would stall the
window.
D4 - Commands are Rust functions with an attribute
#![allow(unused)] fn main() { #[auro::command] async fn save_document(path: PathBuf, body: String) -> Result<Saved, AuroError> { /* ... */ } }
- Attribute options:
name = "...",rename_all = "snake_case" | "camelCase"(defaultsnake_case). Async is detected from theasync fnitself. A plainfnis allowed: it is emitted as anasync fnand its body runs on the blocking pool, so a first-party call site always awaits an off-thread result. - Arguments:
serde::Deserialize + Send + 'static, orState<T>. The Phase 1 command registry addsschemars::JsonSchemafor schema derivation; Phase 0 has no schema consumer. - Result:
Result<T, AuroError>withT: Serialize + Send + 'static. generate_handler![save_document, load_document]builds aCommandHandlerthat maps a command name to a typed dispatch. In Phase 0 it exists and is tested; it is not wired intoApp. Wiring arrives with plugins, when something other than first-party Rust calls it.- The first-party call site is a plain function call (
api::save_document(...)); the handler is the boundary for the future plugin and webview paths. AuroErroris#[non_exhaustive]withFrom<std::io::Error>andFrom<serde_json::Error>.
Rejected: reusing tauri-macros with root = "::auro". The macro also pulls
tauri_utils::acl::read_allowed_commands at expansion time, so reuse buys a proc-macro dependency
on a crate that is about to jump to 3.0.
D5 - State is owned, never borrowed across threads
App::manage(value)storesT: Send + Sync + 'staticbehind anArc.State<T>is a cheap owned handle (Arc<T>,Deref<Target = T>), notState<'_, T>: a borrowing handle cannot be captured by theSend + 'staticcommand future. The macro resolvesStatearguments before hopping to tokio, so the body receives the owned handle.- Views read state through the app handle; one owner per piece of state.
- App-wide notifications are a typed enum in
auro-core, emitted through the app handle; that contract lands with the Phase 1 lifecycle work. Window events stay GPUI events. No untyped broadcast payloads.
Rejected: a global EventBus with string topics. It is the failure mode the project exists to
avoid. Rejected: State<'_, T> copied from Tauri. Tauri's commands can borrow because its
invocation runs on a different boundary; ours cannot.
D6 - Configuration
Auro.toml next to the app's Cargo.toml; TOML; sections [app], [dev], [bundle]; platform
overrides in Auro.<platform>.toml merged key by key. Full field table,
defaults and validation rules: 0002.
- Config is authoritative for identity and windows.
app.identifier,app.product-name,app.versionand the window list come from the file. The builder attaches root views to windows by label:App::new().root::<Editor>("main").run(). - Discovery, in order:
AURO_CONFIG(a path), thenAuro.tomlin the current directory, then in the directory of the running executable. A missing file is an error with exit code 2 that names both places searched. - CLI overrides travel to the child process as
AURO_CONFIG_OVERRIDES, a JSON Merge Patch. There is no other CLI-to-app channel. app.versionversusCargo.tomlis checked byauro buildandauro dev(which have the manifest), not by the running app.App::run(self)prints theAuroErrordiagnostic (configuration, platform or instance) and exits 2;App::try_run(self) -> Result<(), AuroError>is the non-exiting entry point (tests drive views through GPUI'sTestAppContextinstead). On Linux,try_runrejects a Wayland compositor that does not advertise the globals GPUI 0.2.2 binds, so a minimal compositor gets a typed error instead of a panic.
Loaded at runtime in Phase 0. Embedded at bundle time in Phase 2, when there is a bundler to embed it into.
Rejected: the Rust builder owning identity and window geometry. It makes Auro.toml decorative
and splits one truth across two files.
D7 - The dev loop relaunches
auro dev = load config, cargo build, spawn the binary with AURO_CONFIG_OVERRIDES, watch
src/** and Auro.toml, kill, rebuild, relaunch. Ctrl-C stops the child and exits 0. No dev
server, no frontend directory, no static file serving.
Rejected: starting with hot reload before the app model was proven. A relaunch loop proves the app model without risking the schedule; the hot-reload mechanism is tracked in spec 0004.
D8 - Bundling is delegated
Phase 2 wraps tauri-bundler (2.10.x, pinned) behind auro-bundle, mapping our [bundle]
section into its Settings. It is the one Tauri crate we depend on. Its own docs warn that minor
releases may change the API, so an upgrade is a change that must run the three-OS CI.
Rejected: writing a bundler. .dmg + codesign/notarize + WiX + NSIS + AppImage + deb + rpm is
months of edge cases that are not the product.
D9 - Window keys are honored where GPUI can express them
GPUI 0.2.2 has no max-size, no always-on-top, no per-window theme setter, and its decorations
switch is platform-specific. Phase 0 maps size, position policy (center), minimum size,
resizability, visibility, fullscreen, transparency and decorations onto WindowOptions. theme
is parsed and handed to the app through App::setup; the chosen toolkit applies it
(ADR 0009). The remaining keys are parsed,
validated, and reported by auro doctor as "accepted, not honored on this platform". A config
key that silently does nothing is worse than one that says so.
Rejected: implementing platform-specific window code in Phase 0. It is a Phase 2 item, and it
belongs in auro-ui with the rest of the renderer.
Interfaces
CLI
| Command | Behaviour |
|---|---|
auro new <path> | scaffold the tree below; refuse a non-empty directory |
auro dev | build, spawn, watch, relaunch |
auro build | cargo build --release; no packaging until Phase 2 |
auro doctor | toolchain, GPUI pin, config parse result, platform, Linux dependencies, and config keys the platform cannot honor |
auro --version | the workspace version |
Generated project
The scaffold is the four-crate workspace from
ADR 0022; types is framework-free, data owns
the hot boundary, ui owns the view, and the bin wires them.
demo/
Auro.toml
Cargo.toml # auro in-repo path or published version; workspace members and profiles
Dioxus.toml # `dx serve` name for hot mode
icons/icon.png # 512x512 placeholder; replace before release
src/
main.rs # demo_ui::run(demo_data::view_data)
ui/
Cargo.toml # depends on auro and types, never on data
src/lib.rs # Render, window, element tree
src/services.rs # command functions, the `api` module the UI calls
data/
Cargo.toml # depends on types only
src/lib.rs # the hot boundary
types/
Cargo.toml # no dependencies
src/lib.rs # ViewData and the fixed HotData frame
The bundler slice extends the scaffold with the placeholder icon and [bundle] icon; apps replace
it with their own asset. auro new does not create empty asset directories.
The slice, as the author writes it
use auro::prelude::*;
#[auro::command]
async fn save_document(path: PathBuf, body: String) -> Result<Saved, AuroError> {
tokio::fs::write(&path, body).await?;
Ok(Saved { path, bytes: body.len() })
}
impl Render for Editor {
fn render(&mut self, _window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
div()
.flex()
.flex_col()
.gap_2()
.child(Button::new("save", "Save").on_click(cx.listener(
|this, _, _window, cx| {
let doc = this.document.clone();
cx.spawn(async move |this, cx| {
let saved = api::save_document(doc.path, doc.body).await?;
this.update(cx, |this, cx| {
this.status = format!("Saved {} bytes", saved.bytes);
cx.notify();
})
})
.detach();
},
)))
.child(self.status.clone())
}
}
fn main() {
auro::App::new()
.root::<Editor>("main")
.run();
}
The window comes from Auro.toml; main names it by label. This is the current GPUI 0.2 API:
render receives &mut Window, listener closures take (this, event, window, cx), spawn
yields (WeakEntity<T>, &mut AsyncApp), and WeakEntity::update takes any AppContext. The
sample in README.md is corrected from this spec.
Acceptance
Runnables, in order, on a clean checkout:
cargo build --workspace --lockedsucceeds on Linux, macOS and Windows.cargo run -p auro-cli -- new /tmp/democreates the tree;cargo checkinside it passes.cargo run -p auro-cli -- devinside/tmp/demoopens the window declared inAuro.toml; the button dispatches an async command and the rendered text changes; closing the window exits 0.- Ctrl-C during
auro devleaves no child process behind. cargo fmt --all --check,cargo clippy --workspace --all-targets --locked -- -D warnings,cargo test --workspace --lockedpass.- Unit tests cover: config parse, platform merge, unknown-key rejection,
Stateextraction, sync and async dispatch throughCommandHandler,AuroErrorconversion, andauro newrefusing a non-empty directory. - One headless test in the app crate: start Auro's runtime, render the root view through
TestAppContext, await the command task, assert the view'sstatusfield, and assert the rendered tree contains that text viadebug_bounds. GPUI has no text accessor, so the field is the contract and the tree check is structural. - Save-to-window time is measured once and recorded here. No target is claimed until measured.
Status (2026-11-15, closed 2026-11-17)
Phase 0 accepted on 2026-11-17: all eight items below are met. The closing audit fixed
auro build's manifest parse (it failed on every app), wired the version check into auro dev,
added the executable-directory config fallback, validated [bundle] targets against the host, made
auro doctor report the resolved GPUI pin, and added the config round-trip and AuroError
conversion tests the specs required.
- 1: met in CI. CI is green on macOS, Windows,
ubuntu-latestandubuntu-22.04(latest: runs44004201364/44004201288forff96535; earlier run43776830848for5a5d389remained the first green after addinglibxkbcommon-x11-dev). Local gates are green on the closing commit. - 2: met locally (
/tmp/auro-demobuilds) and on Windows 11 (auro newthencargo buildin 274 s in the guest), after fixing two scaffold defects found there: a backslashpaththat TOML rejected as a unicode escape, and a missing[workspace]that let a parent manifest capture the app. - 3: met. Window opens and the rebuild/relaunch cycle work locally; a headless
GPUI test clicks the button, dispatches the async
#[auro::command]and asserts the view update (aurointegration testclicking_button_dispatches_async_command_and_updates_view). Closing the last window now quits the app and was verified to exit 0 on a local niri/Wayland session (/tmp/auro-demobinary); closing throughauro devalso exits 0 (measured 2026-11-16: warmauro dev→ window in 2 s, close →DEV_EXIT=0). Automated process-level window-close coverage is the only test debt; the acceptance item is a manual runnable, verified as described. The window-title gap observed on 2026-11-16 (niri/Wayland reported(unset)althoughAuro.tomlset one, whileapp_idwas correct) was diagnosed and fixed the same day: GPUI 0.2.2 appliesWindowOptions::titlebar.titleon X11, Windows and macOS but not on Wayland, soAppnow callsWindow::set_window_titlewhen opening each window. Verified on niri (title: "auro-demo"fromniri msg --json windows) and covered by the headless unit testapp::tests::opens_window_with_the_configured_title. - 4: met locally (Ctrl-C exits 0, no orphan).
- 5: met locally (fmt, clippy
-D warnings, tests). - 6: met (config parse/merge/unknown-key refusal,
Stateextraction, sync and async dispatch, rename/unknown-command handling,AuroErrorconversion via?forioandjson,auro newrefusing a non-empty directory). - 7: met.
auro-uiintegration testroot_view_renders_status_and_boundsrenders a root view throughTestAppContext, assertsstatus == "Ready"and a non-empty rendered tree viadebug_bounds. - 8: met (measurement recorded). A saved source change to a visible relaunch measured ~60 s on
the development machine (relink dominates; the watcher itself reacts once per edit). This is the gap
hot reload must close, not an acceptable steady state. Re-measured 2026-11-16 on the scaffold
demo with the traced dev loop (debug, warm dependency cache, incremental relink): save→build
2380 ms, save→repaint-requested 2730 ms (medians over three saves;
niri msg windowsby app id, 50 ms poll resolution). A cold build of the demo (dependencies included) takes minutes, so the number is only meaningful with a warm cache. Details and the trace format: spec 0004, D6. Phase 0 required a recorded measurement; the< 500 mstarget is spec 0004's and is not a Phase 0 exit condition.
Open questions
| Question | Where it settles |
|---|---|
Component kit: own primitives vs gpui-component | Resolved: Auro ships no toolkit; the app chooses one (ADR 0009, spec 0005) |
| Hot reload mechanism and its measurability | Spec 0004 |
| Plugin isolation: out-of-process first or in-process | Phase 3 RFC |
Does release embed config or ship Auro.toml next to the binary | Phase 2 spec |
| Windows/Linux input, IME and a11y parity | Phase 2 audit |