clawft

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

SurfaceHow it shipsBuild
Native desktopthe weft-gui-egui binary, a cargo-dist app (crates/clawft-gui-egui/Cargo.toml, [package.metadata.dist])scripts/build.sh gui-egui
Editor panelthe same crate compiled to wasm32-unknown-unknown, loaded by extensions/vscode-weft-panel/ through weft_start("weft-canvas")extension README
Web dashboardclawft-ui/, a separate Vite + React 19 SPA for the agent gateway; it is not the kernel GUIclawft-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 workspace

For 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

On this page