GPUI Forge
GPUI Forge is an integrated ecosystem of tools designed to bring visual prototyping and rapid UI development to the GPUI framework.
The goal of this project is to bridge the gap between high-level design and low-level Rust implementation, allowing developers to visually compose complex, high-performance user interfaces that can be seamlessly compiled into standalone, production-ready GPUI applications.
📦 Current Status
What ships today:
forge-spec — the YAML document model, saphyr loader (anchors, aliases,
merge keys, source spans), canonical + preserving writers, catalog manifests,
and validation. Shipped documents round-trip byte-for-byte.gpui-forge-runtime — renders any document through ForgeView on the
gpui-kit base: ~60 catalog elements, state/binding ({{ path }}), on <event>
hook dispatch, dialogs, themes, drag & drop, element picking.forge-studio — a self-hosted visual builder (its own UI is a Forge
document): palette click-to-place and drag-and-drop insertion, outline and
inspector panels, two-way source pane, undo/redo, reparent/delete mutations,
file open/save with a disk-watch reload, and a Preferences dialog.forge CLI — forge check|validate, forge fmt, forge new
(project scaffold with forge.toml), forge convert (YAML ↔ JSON),
forge schema (JSON Schema from the serde model), forge build
(embeds the document + catalogs + all themes into a native app;
--codegen compiles the document to Rust), forge package (AppDir /
.app / NSIS scaffolding), forge preview (build + launch).forge-web — a Svelte editor/playground at site/ backed by the
forge-web-canvas WASM runtime: palette drag-and-drop, outline,
inspector, undo/redo, localStorage persistence, JSON/.forge
import-export, and schema-generated TypeScript types.
Still on the roadmap: per-base adapters, the #[forge_hook] bridge,
and Studio packaging.
🚀 The Vision
Traditional GPUI development requires writing imperative Rust code for every layout and element. GPUI Forge introduces a declarative workflow: design your interface visually in a desktop or web-based editor, define logic via hooks, and compile the result into a high-performance native binary.
🛠 The Ecosystem
The project is comprised of six core pillars that work in tandem:
1. The Forge Schema (forge-spec)
A multi-format specification for defining GPUI element trees. To ensure interoperability, we support:
- Forge YAML: Plain YAML with a JSON Schema: human-readable, one fact per line for clean Git diffs, and editable with existing YAML tooling.
- JSON: the machine interchange format between the Web Builder and the Rust Engine (YAML is a JSON superset, so conversion is a serialize, not a translate).
See the draft Forge YAML format and document model. Writing a Forge adapter covers integrating third-party GPUI component libraries (the forge-lib-ely pattern).
2. The Forge Converter (forge-cli)
A powerful command-line utility used to transform interface definitions between all supported formats (e.g., converting a JSON blob from the web editor into a .forge file for the desktop editor).
3. The Forge Runtime (gpui-forge-runtime)
The core Rust library that powers everything else. It is responsible for:
- Parsing Forge definition files at runtime.
- Mapping declarative elements (Buttons, Containers, Text) to native components from the project's base component system (gpui-kit by default).
- The Hook System: A reactive bridge that allows developers to inject custom Rust logic and event handlers into the visually defined UI structure.
4. The Forge Studio (forge-studio)
The flagship desktop application built natively using GPUI. Inspired by Workbench, it provides a professional IDE experience:
- A visual canvas for dragging and dropping components.
- Property inspectors for layout, styling, and padding.
- Real-time preview of the UI logic. Studio itself is built with gpui-kit; projects on other bases are rendered by a separate preview process for that base (
forge-preview-<base>), which Studio controls over IPC.
5. The Forge Compiler (forge-compiler)
A build tool that takes a .forge definition and a set of Rust "hooks" and bundles them into a standalone, optimized GPUI application. This allows you to ship "demos" or "prototypes" as complete, single-binary executables.
6. Forge Web (forge-web)
A lightweight, Svelte-based web application that brings the power of visual design to the browser. The Svelte shell hosts a canvas that renders the real components of the project's base via gpui-forge-runtime compiled to WebAssembly (one canvas bundle per WASM-capable base), so web and native output match. It serves as a collaborative design tool, allowing designers to iterate on UI layouts and export JSON definitions that can be immediately pulled into the Rust workflow.
🧩 Base Component Systems
A Rust app links exactly one gpui, so components built on different GPUI versions or forks can't be mixed in one window. Each Forge project therefore picks a base when it is created (base: in forge.toml). The base fixes the GPUI build, and Forge only offers libraries that are compatible with it. Within a base you can mix and match libraries freely.
| Base | GPUI build | Base library | Compatible add-ons | Web/WASM |
|---|
| gpui-kit (default) | gpui-pre =0.3.9 | gpui-kit | Ely GPUI Component, gpui-video-player, zorite widgets (GPL-3.0, opt-in), HIG for GPUI (after bump) | yes |
| Bezel | bezel-gpui 0.3.x (fork) | Bezel | Bezel ecosystem (chart, editor, canvas, markdown, terminal, icons, motion, …) | yes |
| adabraka-ui | adabraka-gpui 0.5 (fork) | adabraka-ui | none known | no (nightly Rust) |
| Vanilla GPUI 0.2 | crates.io gpui 0.2.2 | guise | ferrum-flow, gpui-symbols, rhythm-gpui, gpui-video-player, … | no |
- Each library ships a catalog manifest declaring the bases it supports; validation rejects incompatible libraries.
- The runtime is compiled once per base, and the compiler emits a
Cargo.toml + rust-toolchain for the chosen base.
- Changing base later is a migration (
forge migrate --base).
- Libraries pinned to raw Zed git revisions fit no base and are tracked for porting (#83).
Non-GPUI bases (planned)
Bases are not limited to GPUI builds. The document model, Forge YAML loader, catalogs and
validation are toolkit-agnostic, so the same files drive other UI frameworks. What each
non-GPUI base needs is a catalog, a runtime adapter, its own style profile (the style &
layout keys map to GPUI Styled methods) and a preview host (forge-preview-<base>,
#97).
| Base | Kind | Event model | Web/WASM | Tracking |
|---|
| ratatui | Terminal UI; immediate-mode, drawn from state each frame | on <event> fires while the node is focused (key/mouse are polled) | via a terminal-emulator backend (e.g. ratzilla) | #112 |
| iced | Elm-style GUI on winit/wgpu — not a TUI | on <event> maps to a Message in update() | experimental | #113 |
📐 Architecture Overview
graph TD
subgraph "Design Phase"
A[Forge Web - Svelte] -->|Export JSON| B(Forge Schema)
C[Forge Studio - GPUI] -->|Edit/Save .forge| B
end
subgraph "Development Phase"
B --> D[forge-cli]
D -->|Convert to JSON| E[External Tools]
F[Rust Logic & Hooks] --> G[gpui-forge-runtime]
B --> G
end
subgraph "Deployment Phase"
G --> H[forge-compiler]
F --> H
H --> I[Standalone GPUI App]
end
🛠 Tech Stack
- Language: Rust (Core engine, Runtime, Studio, Compiler)
- UI Framework: GPUI
- Components: a per-project base component system: gpui-kit (default), Bezel, adabraka-ui or Vanilla GPUI 0.2
- Web Frontend: Svelte shell + the base's canvas compiled to WebAssembly
- Serialization:
saphyr (YAML), serde (JSON)
🗺 Roadmap
🧑💻 Development
The docs site, with live gpui-kit previews, a playground and an editor, lives in site/ and deploys to GitHub Pages on every merge to main.
The Cargo workspace lives under crates/ (forge-spec, gpui-forge-runtime, forge-cli, forge-studio, forge-compiler).
cargo test --workspace # default base: gpui-kit
cargo run -p forge-studio # opens the Studio window
cargo run -p forge-cli # the `forge` binary
On Linux, install GPUI's system dependencies first (Ubuntu 24.04):
sudo apt install gcc g++ clang libfontconfig-dev libwayland-dev libwebkit2gtk-4.1-dev \
libxkbcommon-x11-dev libx11-xcb-dev libssl-dev libzstd-dev libasound2-dev \
vulkan-validationlayers libvulkan1
gpui-forge-runtime is built for one base at a time via mutually exclusive base-* features (base-gpui-kit is the default; base-bezel, base-adabraka, base-gpui02, base-ratatui and base-iced are reserved until their bases land). forge-spec must stay GPUI-free; CI enforces this.
🤝 Contributing
This is an experimental project at the intersection of systems programming and creative tooling. Contributions are welcome, especially regarding the specification design and the runtime performance of the hook system.
Implementation Note: Hooks
The most difficult part of this architecture will be Point 3.1 (Hooks). To make this work, you cannot simply "inject" code at runtime in Rust. You will likely need to implement a Trait-based Registry or an Event Dispatcher where the visual builder defines string_ids for events, and your Rust application maps those IDs to actual function pointers or closures during the initialization phase of the gpui-forge-runtime.
