FC GPUI

A GPU-accelerated UI framework for Rust, forked from Zed's GPUI. fc-gpui extends the original framework with daemon-mode capabilities, system tray integration, global hotkeys, native notifications, and more — making it suitable for background apps, menu bar utilities, and overlay tools.

Getting Started

fc-gpui 0.12.0 is published on crates.io. The unrelated adabraka-gpui registry crate is the upstream Augani crate at 0.5.1 and does not carry this fork's releases. Depend on the crates.io package:

fc-gpui = "0.12.0"

Building requires the toolchain pinned in rust-toolchain.toml: Rust 1.97.1 with edition 2024.

To keep the build small, disable default features and opt into only the image formats you need:

fc-gpui = { version = "0.12.0", default-features = false, features = [
    "font-kit",
    "wayland",
    "x11",
    "image-format-png",
    "image-format-jpeg",
    "image-format-webp",
] }

image-format-* features map to the underlying image crate decoder features. image-rayon re-enables parallel decoding. SVG support is handled separately through resvg.

Note that keyring (Linux Secret Service credentials storage) and accessibility are also default features; add "keyring" back to the list above if your app calls write_credentials / read_credentials / delete_credentials.

Import Naming

The published package is fc-gpui, but the library target keeps the upstream gpui namespace, so a plain dependency imports as gpui and Zed-derived code compiles unchanged:

use gpui::*;

Renaming the dependency is also supported — the GPUI macros (derives, register_action!, #[gpui::test]) follow the dependency key:

[dependencies]
gpui = { package = "fc-gpui", version = "0.12.0" }

The utility crates (fc-gpui-util, fc-gpui-http-client, …) import under their matching fc_gpui_* library names.

Upgrading from 0.11.3

The 0.12.0 release renames ScrollWheelEvent to ScrollEvent, adds the required Platform::platform_info() method, and changes Modifiers::secondary / secondary_key to receive the current &App. macOS also adds the optional write_credentials_if_not_exists API. See the downstream migration notes before upgrading.

Macro Dependency Override

Macro paths are resolved automatically for normal fc-gpui dependencies and ordinary Cargo aliases. If one package directly lists both fc-gpui and fc-gpui-core, or uses an alias that is indistinguishable from the normalized package name, select the intended crate once in the consuming package's Cargo.toml:

[package.metadata.gpui-macros]
crate = "core_ui"

The value must be the Rust dependency identifier visible to that package. It applies consistently to derive macros, register_action!, and #[gpui::test]. An ambiguous direct dependency graph without this override fails with an actionable macro error instead of guessing a crate.

Platform Support

Rendering Backends

Linux X11 and Wayland use the internal wgpu renderer ported from Zed's current GPUI backend. Blade is no longer part of the crate. The default macOS renderer is Metal and Windows uses DirectX.

Downstream applications continue to use only fc-gpui; the renderer package is an internal implementation dependency and does not change the Application::new() entry point. See the WGPU migration notes for details.

Accessibility

fc-gpui exposes AccessKit-backed roles, labels, values, focus, and action handlers on elements. Native adapters connect the generated accessibility tree to macOS Accessibility, Linux AT-SPI, and Windows UI Automation.

Native adapters are enabled by the default accessibility feature. Disable default features to exclude their platform dependencies; the core accessibility API remains available but inactive.

cargo run -p fc-gpui --example a11y

See examples/a11y.rs for focus navigation, accessible actions, numeric values, switches, and list metadata.

Wayland Layer Shell

Create a layer-shell surface with WindowKind::LayerShell. The Wayland backend requires wlr-layer-shell; opening the window fails with LayerShellNotSupportedError when the selected backend or compositor does not support that protocol. Compositors older than wlr-layer-shell version 5 cannot select exclusive_edge, so that option is ignored with a warning. A width or height of zero is passed through to let the compositor choose that dimension.

Applications upgrading from 0.6.x should follow the layer-shell migration and implementation provenance guide.

use gpui::{
    Bounds, WindowBounds, WindowKind, WindowOptions,
    layer_shell::{Anchor, KeyboardInteractivity, LayerShellOptions}, point, px, size,
};

let popup_bounds = Bounds::new(point(px(1520.0), px(820.0)), size(px(320.0), px(220.0)));

let options = WindowOptions {
    window_bounds: Some(WindowBounds::Windowed(popup_bounds)),
    kind: WindowKind::LayerShell(LayerShellOptions {
        namespace: "gpui-popup".to_string(),
        anchor: Anchor::TOP | Anchor::RIGHT,
        margin: Some((px(24.0), px(24.0), px(0.0), px(0.0))),
        keyboard_interactivity: KeyboardInteractivity::None,
        ..Default::default()
    }),
    ..WindowOptions::default()
};

The layer-shell regression tests avoid requiring a real compositor. They cover configure sizing and protocol enum mapping:

cargo test -p fc-gpui-core --lib --features test-support layer_shell
cargo check -p fc-gpui --example layer_shell --features wayland

Features

Core UI Framework (inherited from GPUI)

• Hybrid immediate/retained mode rendering
• GPU-accelerated with Metal, Vulkan, OpenGL, and DirectX backends
• Tailwind-style layout and styling API
• Entity-based state management
• Declarative views with the Render trait
• Low-level Element API for custom rendering
• Async executor integrated with the platform event loop
• Action system for keyboard shortcuts
• AccessKit accessibility tree and native platform adapters
• Test framework with #[gpui::test]

Daemon & Background App Support (new in fc-gpui)

• System tray — icon, tooltip, and nested menus with action callbacks
• Global hotkeys — register system-wide keyboard shortcuts
• Native notifications — OS-level notifications on all platforms
• Overlay windows — always-on-top transparent windows
• Click-through windows — mouse events pass through to windows below
• Window show/hide — programmatic visibility control
• Auto-launch — register your app to start at login
• Single instance — prevent multiple copies with activation signaling
• Keep alive without windows — apps stay alive with no visible windows via QuitMode::Explicit, set through Application::with_quit_mode or App::set_quit_mode
• Focused window info — query which window the user is focused on
• Permission status — check accessibility and microphone permissions
• In-app toast notifications — stackable, auto-dismissing toast component (deprecated; use the fc-ui toast component instead)

Quick Example

use gpui::{App, Application, TrayMenuItem};

fn main() {
    Application::new().run(|cx: &mut App| {
        cx.set_quit_mode(gpui::QuitMode::Explicit);
        cx.set_tray_tooltip("My App");

        cx.set_tray_menu(vec![
            TrayMenuItem::Action {
                label: "Settings".into(),
                id: "settings".into(),
            },
            TrayMenuItem::Separator,
            TrayMenuItem::Action {
                label: "Quit".into(),
                id: "quit".into(),
            },
        ]);

        cx.on_tray_menu_action(|id, cx| match id.as_ref() {
            "quit" => cx.quit(),
            _ => {}
        });
    });
}

Dependencies

macOS

• Xcode with macOS components
• Xcode command line tools: xcode-select --install

Linux

• Standard development packages for your distro
• For X11: libxcb, libxkbcommon
• For Wayland: libwayland-client, libxkbcommon
• GPU backend: wgpu with Vulkan/OpenGL support
• D-Bus (for system tray via StatusNotifierItem)

Windows

• Visual Studio Build Tools with C++ workload
• Windows SDK

License

Apache-2.0