UI internals¶
How the web UI and the egui desktop app are put together.
Schema-driven UI¶
The UI draws whatever the daemon's UiSchema describes (GET /api/ui-schema; defined in crates/fleet-api/src/ui.rs). Components hold no status, column or action names. Add or change what the board shows in the schema first; touch React only for a new kind of thing.
Layers¶
| Layer | Where | Job |
|---|---|---|
| Schema logic | web/src/api/schema.ts |
evalCondition, columnFor, visibleActions, actionRequest, fieldValue, formatDuration. Pure functions, no React. |
| State | web/src/api/board.ts, events.ts, hooks.ts |
boardReducer applies events; subscribe and useFleet feed it from SSE. |
| Primitives | web/src/ui/ |
Button, Badge, Tabs, Field. The only place a raw <button> or a badge <span> is written. |
| Components | web/src/components/ |
Board → Column → Card, plus RepoFilter, SpawnForm, PreviewPane. They compose primitives and read the schema. |
| Styles | web/src/styles.css |
The only stylesheet. Colours are variables on :root (with a dark-mode override); tone and variant come from data-tone, data-variant and aria-pressed attributes. |
Rules¶
- A new card field is a
FieldDefin the schema.Fielddraws it by kind (text,badge,duration,mono) and renders a list value as one element per entry. - A new button action is an
ActionDefin the schema.client.runexecutes it; no component names an action. - A new column is a
ColumnDef.Boardrenders it withColumn. fieldValuederives exactly two keys from the workspaces:reposandbranch. A contract test infleet-apirejects any other card field that is not anAgentfield.- Use
ButtonandBadge, never a raw<button>or a.badgespan. Style a new look as adata-variantinstyles.css, not as a new class. - No inline
style=props and no per-component stylesheets. - Inputs, selects and textareas are plain elements styled by element selectors in
styles.css; they have no behaviour of their own to share.
Tests¶
pnpm --dir web test. Component tests query by role and title, never by class, so a restyle does not break them. The default schema the tests use is web/src/api/generated/default-ui-schema.json, written by cargo test -p fleet-api, so the UI is always tested against the daemon's real default.
egui client (crates/fleet-gui)¶
- The window is a drawer (left,
drawer.rs) and the content (right). The app (app.rs) owns the drawer (brand row, New task, nav, live status), the content footer and the selected agent; a view owns the content header, its main area and whether the detail panel (the selected agent's preview) shows. The selection outlives a view that hides it. - The drawer header and the content header are both exactly
theme::layout::HEADERtall, the drawer footer and the content footer exactlylayout::FOOTER, so the border under the headers and the border over the footers each run unbroken across the window. Every row's border is its panel's own separator line.tests/shell_layout.rschecks this from measured rects and painted pixels; keep it passing. views/holds one module per view (kanban.rs,tasks.rs,releases.rs,management/,settings/). A new view is aViewvariant, a module inviews/with its header and main, and a nav entry (drawer::VIEWS). The app always opens on Kanban.- A view that needs tabs puts
widgets::tab_bar(a full-width strip with a bottom border) at the top of its main area, directly under the header. Settings does, with General, Daemon and Log; its tab is kept while the app runs. - Settings → General applies Theme, Font, Mono font, Closing the window, Footer and Motion at once (saved to
gui.toml; see Theme, fonts and motion). Its Tasks folder and Personas folder each need their own Save, because Save writestasks_rootorpersonas_dirinto the daemon'sconfig.toml(config::set_tasks_root/config::set_personas_dir, which keep the user's other keys and comments and write atomically) and restarts the daemon: the daemon reads both only at startup. A new personas folder is not created by the GUI (the daemon makes it with its own modes), and existing personas' folders, with their Claude and GitHub logins, are not moved; the note under the field says so. Settings → Daemon shows the address, who started the daemon, the state directory, the config file and the PID (whendaemon.pidexists), with Restart daemon. - A Save's restart shows its progress inline, in place of the note under the field that was saved (under both for Restart daemon, and in Settings → Daemon), not in the footer; the footer gets only the outcome (
Daemon restarted, or the error). This departs from the app-shell spec on purpose: the progress stays next to the field that caused it. - Both restarts go through
FleetApp::start_restart: one background thread writes the config (a Save only), thenshell::restart_daemon(stop, then ensure). The app gets them fromshell::DaemonCtl, whichRootbuilds from its ownensure/stopwhen the board starts; an app without one (tests, embedding) leaves those settings out. Save and Restart daemon are disabled, with the reason as a tooltip, while an agent is Queued or a spawn, add-repo or grant is in flight (the daemon's startup reconcile would break them), and each Save also for its current folder. A pending repo request asks first (Restart anyway/Cancel). After a restart the window owns the daemon:take_restarted()letsRoottell itsCloseFlow. - Settings → Log (
views/settings/log.rs) lists the app's and the daemon's lines in one list. The files aregui.loganddaemon.login the daemon's state directory (DaemonCtl.state_dir; an app without one lists only what it logged itself). The source switch is App, Daemon or Both (default), merged by time with the app's line first on a tie; error, warning, info and debug toggles (debug off by default; trace goes with debug) leave stray lines such as a panic visible; the search is a case-insensitive substring of the whole rendered line, fields included. Opening the tab reads at most the lastTAIL(1 MiB) of each file from a line start on a background thread; a missing file saysNo daemon log at <path>orNo app log at <path>. The app's lines then come fromFleetApp::log_entries(); file lines are listed only when older than the first live entry, so none appears twice. The daemon's file is re-read from its last offset once a second, only while the tab is drawn (request_repaint_after(1 s)only then, no file IO per frame), holding back a half-written last line and starting over when the file shrinks. The merged list is rebuilt only when its inputs change. - The content footer (
components/footer.rs, state inmessages.rs) shows one message line at a time from a queue: success, info and warning for 4 s, error for 8 s, in arrival order. With Settings → General → Footer on (the default,sticky_alertsingui.toml) an error or warning loops back into the queue until the user clicks it away; a click on any other message skips it. When the queue empties the last message stays, dimmed. The line is one row with the full text as its tooltip; theHistorybutton lists the last 10 (time in UTC) and ends inOpen log →, which opens Settings → Log. - To tell the user something, log an event with a
notifyfield oferror,warning,successorinfofrom anywhere in the GUI:tracing::error!(notify = "error", agent_id = %id, "{e}"). The message is the footer text and ids go in fields. Only events whose target starts withfleet_count, so a dependency'snotifyfield never reaches the user.FleetAppcollects every such event fromfleet-logand feeds the queue; there is no per-view error state. A form that has its own error line (the New task dialog) keeps it and logs nothing extra. - The window stays idle while the footer is on screen: it asks for a repaint only at the next turn of the queue (
Messages::next_change), and not at all when a looping message is alone. - The app's name as a person reads it is
theme::APP_NAME("Fleet Manager"); ids, paths and binaries stayfleet-manager. theme.rsis the only place for colours, type sizes, corner radii and fonts. Light and dark come from one token set; the rest of the crate reads tokens and never writes a literal colour.- Spacing (margins, gaps, padding) is not tokenised: each component sets its own, next to the layout it belongs to.
widgets/is the only place buttons, badges, tabs, chips, icons, dots and nav entries are drawn. A new look is a variant of a primitive there, not a styled one-off in a component.- egui's stock widgets (
ComboBox,checkbox,TextEdit,ScrollArea, tooltips) are not redrawn inwidgets/: they pick up the tokens through theVisualsthattheme::applyinstalls, and components call them directly. - Components in
components/compose those primitives and read the schema. They never write a colour or a font size. components/folder_picker.rsis the one folder and repo picker: aBrowse…button whose modal lists folders (and a repo's checkouts) fromfleet-fson background threads. Every text box that takes a folder or repo reuses it; its rows are thelist_rowprimitive.- The fonts (IBM Plex Sans and IBM Plex Mono by default; Space Grotesk, JetBrains Mono and Atkinson Hyperlegible to pick in Settings › General) are vendored under
crates/fleet-gui/assets/fonts/with their SIL OFL licences and compiled in withinclude_bytes!, so the binary runs air-gapped. - The window must stay idle: no repaint loop beyond the 15 s refresh, events and background results. Motion goes only through
theme::animate(ctx)(withtheme::pulse,visor,spinandsweepbuilt on it): it is true only while the window has focus and the Animations setting is on, and then frames are throttled to about 100 ms (theme::ANIMATION_FRAME), or 40 ms (theme::SWEEP_FRAME) for fast movers. It is false while the window is unfocused and in every test (egui_kittest'sHarness::run()panics on continuous repaints). - Tests (
cargo test -p fleet-gui) find widgets by role and label, so a restyle does not break them; keep visible labels unchanged.
Theme, fonts and motion¶
Every choice on Settings → General except the two folders applies at once and is saved at once:
FleetApp::apply_general applies it to the egui context, then SettingsWriter re-reads gui.toml, changes that one
key and writes it on a background thread (the home can be on NFS). A failed write is reported in the footer and the
choice still holds for this run.
gui.toml is in the config folder (~/.config/fleet-manager on Linux, %USERPROFILE%\AppData\Roaming\fleet-manager
on Windows) (GuiSettings in crates/fleet-client/src/config.rs). The keys
these settings write:
| Setting | Key | Values | Default |
|---|---|---|---|
| Theme | theme |
system, light, dark |
system |
| Font | ui_font |
plex (IBM Plex Sans), space_grotesk, atkinson (Atkinson Hyperlegible Next) |
plex |
| Mono font | mono_font |
plex (IBM Plex Mono), jetbrains (JetBrains Mono), atkinson (Atkinson Hyperlegible Mono) |
plex |
| Motion → Animations | animations |
true, false |
true |
A missing or unreadable file is the defaults. An unknown theme or font name, from a hand edit, reads as the default and keeps the rest of the file.
Theme¶
theme.rs holds one built-in theme, BUILTIN: a dark and a light Palette of the same shape, each a set of
Tokens (surfaces, text, accent) and Tones (status colours). theme::apply installs the visuals for both halves
once (set_visuals_of for Theme::Dark and Theme::Light); the Theme setting only sets egui's
ThemePreference, and egui picks the half. main sets the saved preference before the first frame, so a saved
Light or Dark never flashes the system theme first. Widgets read theme::tokens(ui.visuals().dark_mode), so they
follow the switch without being told.
Fonts¶
The font is the face for everything but code; the mono font is the face for code, terminal output and labels. They are chosen independently, so any pair works.
All nine files in crates/fleet-gui/assets/fonts/ are compiled in (FONT_FILES, include_bytes!), so the
binary needs no network or system fonts. Each UI font is a Regular and a Medium file; each mono font one Regular.
The files are static instances, because egui draws a variable font only at its default instance; their sources and
licences are in assets/fonts/README.md.
font_definitions(fonts) builds egui's font families:
Proportionalstarts with the chosen UI font's Regular,Monospacewith the chosen mono font.ui-medium(theme::MEDIUM_FAMILY) holds the chosen UI font's Medium. egui has no font weights, sotheme::sans(ui, size, Weight::Medium)and theHeadingtext style use this family.- One family per font (
ui:<key>,mono:<key>) holding only that face, so Settings draws each choice's name in its own face whatever is active. - egui's own fonts follow ours in every family, for the glyphs the bundled faces lack (emoji, symbols, CJK). A glyph
no font has draws as a box (
MissingGlyphPolicy::Tofu) instead of stopping the window.
theme::apply installs the defaults (IBM Plex Sans and IBM Plex Mono) and the text styles at their theme::size
values; FleetApp::with_settings then installs the saved pair with theme::set_fonts, and a change in Settings
calls it again. egui lays the text out again from the next frame.
Motion¶
The Animations setting turns off all motion: the edge of a Working card that is not paused (a band sweeping along it), the edge of a
card that needs you (a slow pulse), the radar in the drawer, and egui's own transitions such as hover fades
(animation_time is theme::ANIMATION_TIME, 0.12 s, while animating and 0 otherwise).
theme::set_animations stores the setting in the egui context's temporary data; theme::animate reads it there.
Every animation asks animate before it asks for a repaint, so with the setting off, or the window unfocused, the
window repaints only on events. A scripted demo run (FLEET_GUI_CUES, see Demo media) forces
animation on with theme::force_animation, over the setting and focus: under Xvfb the window never reports focus.