GUI Layer
How the WeftOS GUI is built today - the egui shell, the canon primitive vocabulary, TOML surface descriptions, the substrate RPCs, and the VS Code panel.
GUI Layer
The WeftOS GUI is one egui/eframe application, clawft-gui-egui. It runs as a native
binary and as a WASM bundle hosted inside VS Code and Cursor. The earlier React + Tauri
GUI (gui/, gui/src-tauri, clawft-ui/src-tauri) was never released and was removed
from the tree on 2026-10-18; CHANGELOG 0.8.4-rc.15 records "The Tauri desktop shells.
egui is the native GUI." ADR-005, ADR-007, ADR-013 and ADR-038 are superseded by the
egui shell and are kept as history only (docs/adr/adr-038-tauri-desktop-shell.md,
status line and "Superseded note"). See K8 GUI for the short form.
Source: crates/clawft-gui-egui/ (shell, apps), crates/clawft-canon/ (primitives),
crates/clawft-surface/ (surface descriptions), extensions/vscode-weft-panel/ (editor host)
Surfaces
| Surface | How it ships | Build |
|---|---|---|
| Native desktop | the weft-gui-egui binary, a cargo-dist app (crates/clawft-gui-egui/Cargo.toml, [package.metadata.dist]) | scripts/build.sh gui-egui |
| Editor panel | the same crate compiled to wasm32-unknown-unknown, loaded by extensions/vscode-weft-panel/ through weft_start("weft-canvas") | extension README |
| Web dashboard | clawft-ui/, a separate Vite + React 19 SPA for the agent gateway; it is not the kernel GUI | clawft-ui/README.md |
clawft-gui-egui/src/lib.rs states the split: native entry is run() (the
weft-gui-egui binary), the WASM entry is weft_start(canvas_id).
How the shell talks to the kernel
The shell is a client of the node daemon. crates/clawft-gui-egui/src/live.rs publishes one
Snapshot from two transports behind the same Arc<Live>:
- Native: a background thread with its own tokio runtime calls the daemon IPC socket
through
clawft_rpc::DaemonClient. - WASM: inside the webview there is no Unix socket, so the panel posts JSON-RPC-shaped
messages through
acquireVsCodeApi()and the extension host proxies them to the daemon.
The substrate RPCs (read, subscribe, publish, notify) come from the
clawft-substrate crate (CHANGELOG 0.6.19, "M1.5 App Layer Trilogy"). Apps bind to
substrate paths; the shell does not call kernel internals directly.
Desktop shell and apps
shell/desktop.rs is the compositor: a wallpaper grid, floating windows and a tray of
status chips (kernel, mesh, ExoChain). The sidebar targets are the variants of
SidebarTarget in shell/sidebar.rs: Files, Processes, Services, Network (mesh, Wi-Fi,
Bluetooth), Settings, Scheduler, Monitor, Logs, Terminal, Chat, Admin, Explorer,
Workspace and Apps. Most have a module under crates/clawft-gui-egui/src/apps/.
The apps/mod.rs header says the first cut of these apps shipped as stubs that render a
heading plus an empty, loading or offline state against their substrate paths, to be
filled in by follow-up tickets. Read an app's module to see how far it has gone; this
page does not claim feature parity per app.
The canon vocabulary
Renderers speak one fixed vocabulary of 21 primitives, defined in crates/clawft-canon/
(lib.rs: "Primitive canon - the 21-item vocabulary every renderer speaks"). The modules
are canvas, chip, dock, field, gauge, grid, media, modal, plot, pressable, select, sheet,
slider, stack, stream_view, strip, table, tabs, thread_dock, toggle and tree. Each
primitive implements CanonWidget and returns a CanonResponse.
The blocks/ module in the egui crate is an older 12-block demo gallery
(text, table, tree, tabs, oscilloscope and others). Its header marks it as the theming
test bed and showroom, with a planned retirement in favour of canon primitives. New UI
should be built from canon primitives.
Surface descriptions
crates/clawft-surface/ turns a declarative surface description into canon primitives.
Descriptions are TOML (fixtures in crates/clawft-surface/fixtures/, for example
weftos-admin-desktop.toml and the per-chip surfaces) or built with a Rust builder. A
binding expression evaluator drives values from substrate data; the supported combinators
at the time of writing are count, filter, sort, len, first and last plus the
fmt_* and exists helpers. Ternary ?: and nested lambdas are rejected by the parser
(crates/clawft-surface/src/lib.rs, "M1.5 scope reductions"). Compose-time governance
filters which affordances a surface may show (ComposeGovernance).
This replaces the JSON block-descriptor format of ADR-013, which is superseded.
Theming
crates/clawft-gui-egui/src/theming.rs defines the base style tokens: dark surfaces, thin
strokes, and one warm accent used only to mark active, focused or selected state. The
four --weftos-* CSS themes described in older versions of this page belonged to the
removed React app.
Console
The Terminal and Chat apps and the Explorer live in the egui shell. The kernel command
dispatcher behind service.method strings is ShellAdapter in
crates/clawft-kernel/src/service.rs; see Console Commands
for what is and is not verified about it.
Development
scripts/build.sh gui-egui # native weft-gui-egui binary
scripts/build.sh check # compile check for the workspaceFor the WASM panel, see extensions/vscode-weft-panel/README.md and SMOKE.md.
See Also
- K8 GUI - one-page summary and history
- ECC - the knowledge graph the Explorer visualizes
- Governance - the engine that gates actions
- Mesh Networking - mesh topology shown in the Network app