gelm

README

gelm

A pure-Go (no cgo) widget toolkit for Wayland, built as a feature-complete counterpart of relm4: a component framework with typed messages, a retained widget tree with GTK4/libadwaita-class widgets, xdg-shell and layer-shell windows, a GTK-flavored CSS engine over a typed palette, the desktop's portals and protocols, and an event loop that idles at 0% CPU.

Status

gelm runs on sway and Hyprland, and both are required CI gates: the compositor-in-the-loop suite runs against a private headless sway (just headless) and against Hyprland in a private NixOS VM (just hyprland-vm). docs/completeness.md maps every capability against relm4, GTK4 and libadwaita.

Install

go get github.com/stubbedev/gelm@latest

Packages

Apps import the public packages; everything under internal/ is implementation.

Package	Contents
component	the component framework: components, controllers, factories, workers, commands
component/componenttest	a loop that runs components in tests without a compositor
ui	typed view builders, one per widget
app	the session, windows and layer surfaces, the loop, dialogs, popovers, desktop services
widget	the widget tree, theme, CSS, actions, bindings
widget/css	libadwaita's style classes and named colors as constants
render	the premultiplied canvas, shaped text, icons
anim	tweens, easing, springs and timelines
appearance	the desktop's color scheme, accent and contrast preferences
i18n	gettext catalogs (.mo, .po)
highlight	syntax highlighters for the code view
media	video and sound playback
pdf	PDF writing
transfer	the shared shape of clipboard and drag-and-drop content
dmabuf	dma-buf frame descriptions
capture	screen and window capture
vinput	virtual pointer and keyboard injection
wlr	generated Wayland protocol bindings

A minimal app

package main

import (
	"log"
	"strconv"

	"github.com/stubbedev/gelm/app"
	"github.com/stubbedev/gelm/component"
	"github.com/stubbedev/gelm/ui"
	"github.com/stubbedev/gelm/widget"
)

type Msg int

const (
	Increment Msg = iota
	Decrement
)

type Counter struct {
	env ui.Env
	n   int
}

func (c *Counter) Init(cx *component.Context[Msg, int]) widget.Widget {
	return ui.Mount(cx, c.env, ui.Row(
		ui.Button(ui.Label("-"), 8, 6).OnClick(func() { cx.Input(Decrement) }),
		ui.Expand(ui.Label("").WatchText(func() string { return strconv.Itoa(c.n) })),
		ui.Button(ui.Label("+"), 8, 6).OnClick(func() { cx.Input(Increment) }),
	).Spacing(6))
}

func (c *Counter) Update(cx *component.Context[Msg, int], msg Msg) {
	switch msg {
	case Increment:
		c.n++
	case Decrement:
		c.n--
	}
	cx.Output(c.n)
}

func main() {
	err := component.Run(app.WindowConfig{Title: "counter", AppID: "dev.example.counter"},
		func(a *app.Application) (*Counter, error) {
			face, err := app.Font("sans-serif", 15)
			if err != nil {
				return nil, err
			}
			if err := a.AddAccel("Escape", widget.NewAction("quit", a.Quit)); err != nil {
				return nil, err
			}
			return &Counter{env: ui.Env{Face: face, Size: 15}}, nil
		})
	if err != nil {
		log.Fatal(err)
	}
}

This program is kept compiling as ExampleRun in component/example_test.go. docs/components.md walks through components, the typed builders, factories, workers and actions. app.NewApplication and NewWindow are the lower-level path for apps that want the widget tree without components (ExampleApplication in app/example_test.go).

Development

devenv shell       # pinned Go, gopls, golangci-lint, just, sway; CGO_ENABLED=0
just demo          # the gelm-hello showcase

The gates, all required in CI:

just check         # go vet, golangci-lint, go test, build
just fmt-check     # gofumpt and gci formatting
just headless      # the compositor-in-the-loop suite on a private headless sway
just hyprland-vm   # the same suite against Hyprland in a private NixOS VM (needs KVM)
just atspi         # the AT-SPI bridge on a private accessibility bus
just atspi-verify  # the bridge against real at-spi2-core

just bench runs the benchmarks; CI archives the numbers without gating on them (bench/baseline.md holds the method and the allocation budgets the tests enforce). just goldens regenerates the golden-image snapshots after a deliberate visual change.

nix build .#gelm builds the module and every demo with the pinned toolchain. Pushing a v* tag releases gelm-hello, gelm-bar and gelm-panel (linux/amd64 and arm64) through goreleaser.

Documentation

Document	Contents
docs/completeness.md	the capability map against relm4/GTK/libadwaita, and the known gaps
docs/architecture.md	the layers, the invariants that keep them correct, theming, non-goals
docs/application-model.md	windows, layer surfaces, disconnects, single instance, file dialogs, data transfer, chrome
docs/components.md	the component framework: components, typed view builders, tracking, controllers, children, testing
docs/threading.md	the loop goroutine, Invoke/Every, the off-loop guard, the typed messaging layer
docs/input-model.md	routing, implicit grab, click/drag, drag and drop, keyboard, IME, touch, tablets
docs/css.md	the CSS layer: selectors, values, properties, cascade, lifecycle
docs/appearance.md	following the desktop's color scheme, accent and contrast
docs/icons.md	icon-theme lookup and symbolic recoloring
docs/a11y.md	semantic roles, the keyboard-first guarantee, the AT-SPI bridge
docs/inspector.md	the live widget inspector, tree dump, and doctor block

Demos

Command	What it shows
cmd/gelm-hello	the showcase as a component: core widgets, a context menu on typed actions, tooltips, Tab focus, drag-to-move
cmd/gelm-bar	a layer-shell top bar repainting only what changed each second
cmd/gelm-panel	a right-anchored layer-shell panel with live widgets
cmd/gelm-launcher	a launcher: a keyboard-exclusive overlay, a filtered app grid, live toplevel thumbnails through capture
cmd/gelm-osd	an OSD: a transient layer-shell volume/brightness popup over the overlay layer
cmd/gelm-lock	a lock screen: one ext-session-lock surface per output with an auth entry
cmd/gelm-multi	one loop: per-output layer bars, on-demand windows, close-request veto
cmd/gelm-invoke	a lifetime-bound spawned command and Every feeding a component
cmd/gelm-messages	the typed messaging layer and single-instance forwarding
cmd/gelm-settings	a settings app: PreferencesView rows, the adaptive shell, typed persisted settings
cmd/gelm-columns	ten thousand sorted, filtered rows; the tree view; drag-to-reorder
cmd/gelm-dialogs	every dialog constructor: message, prompt, color, font, calendar, file, adaptive, about
cmd/gelm-dnd	cross-window drag-and-drop: swatches that drag and drop between two toplevels
cmd/gelm-draw	custom painting: a DrawingArea animating straight onto the Canvas
cmd/gelm-ime	IME composition: preedit and commit mirrored from an entry and a text area
cmd/gelm-a11y	a labeled form served over AT-SPI; builds with -tags atspi to force the bridge on
cmd/gelm-capture	the capture consumer: list, screenshot, and monitor outputs and windows to PNG
cmd/gelm-gpu	a GPUArea paced by its own frame callbacks, with gelm drawing over it
cmd/gelm-video	a video with its controls: a file through ffmpeg, or a generated clip decoded in pure Go
cmd/gelm-i18n	a gettext .po catalog (plurals included) localizing built-in and app strings
cmd/gelm-states	the window-state client the headless suite drives: xdg state chords, mirrored from what the compositor confirms
cmd/gelm-multilist	the multi-select client the headless suite drives: a multiple-selection list with keyboard and rubber-band selection
cmd/gelm-popover	the popover client the headless suite drives: popup grabs, live repaints, nested menus
cmd/wlpointer, cmd/zz-vpclick	synthetic input for the headless suite

Dependencies

All pure Go: neurlang/wayland (patched copy in third_party/), godbus/dbus, go-text/typesetting, rivo/uniseg, golang.org/x/image, golang.org/x/text, golang.org/x/sys, srwiley/oksvg + rasterx, kettek/apng, yalue/native_endian, unxed/xkb-go, and jfreymuth/pulse (the PulseAudio protocol, which pipewire-pulse also serves). media.OpenFile runs ffmpeg and ffprobe from PATH when an app plays a file; nothing else needs them.

License

MIT

Documentation

Overview

Package gelm is a pure-Go (no cgo) widget toolkit for Wayland and a counterpart of relm4: a component framework with typed messages, a retained widget tree with GTK4/libadwaita-class widgets, xdg-shell windows and layer-shell surfaces, a CSS engine over a typed palette, the desktop's portals and protocols, and one event loop that idles at 0% CPU.

Applications import the public packages:

component  the component framework: components, controllers,
           factories, workers, commands (headless tests in
           component/componenttest)
ui         typed view builders, one per widget
app        the session, windows and layer surfaces, the loop,
           dialogs, popovers, desktop services
widget     the widget tree, theme, CSS, actions, bindings
           (libadwaita style classes in widget/css)
render     the premultiplied canvas, shaped text, icons
anim       tweens, easing, springs and timelines
appearance the desktop's color scheme, accent and contrast
i18n       gettext catalogs
highlight  syntax highlighters for the code view
media      video and sound playback
pdf        PDF writing
transfer   clipboard and drag-and-drop content
dmabuf     dma-buf frame descriptions
capture    screen and window capture
vinput     virtual pointer and keyboard injection
wlr        generated Wayland protocol bindings

Everything under internal/ is implementation. The docs/ directory holds the reference: architecture, components, the application, input and threading models, CSS, appearance, icons, accessibility, the inspector, and the capability map in docs/completeness.md.