gelm

gelm

A retained-mode widget kit for Wayland, written in pure Go (no cgo). Logical-coordinate widget space, damage-tracked repaint, a parked event loop that idles at 0% CPU, and a renderer built on premultiplied-alpha ARGB — designed to carry a future Go wayle; see stubbedev/wayle#19 for the full plan and the completeness ladder.

Status

The toolkit core works end to end on real compositors (verified on Hyprland and headless sway): toplevel and layer-shell windows, the full widget set below, keyboard and pointer input with a defined input model, the clipboard, drag and drop, IME composition, fractional scaling with live rescale, and an animation clock. Theming is a composable palette value (widget.SetTheme, widget.DarkTheme().WithAccentHex("#a6e3a1").WithPadding(8)-style chaining, dark and light presets); state shades derive from the palette, and a GTK-flavored CSS subset layers on top as an override — widget.LoadStylesheetFile("theme.css") with element/class/id/state selectors, hot reload on file change, and classes/ids per widget (b.AddClass("destructive"), b.SetID("save-button")); see docs/css.md. The system's dark/light preference is available as a signal, not an automatic switch: internal/appearance watches xdg-desktop-portal's color-scheme (pure Go, no cgo) and the app wires it to SetTheme — see docs/appearance.md.

The compositor-in-the-loop gate runs the same input suite on both compositors: sway is the primary required gate (just headless), and Hyprland runs the identical suite inside a private NixOS VM with its own DRM node (just hyprland-vm, tests/hyprland-vm.nix) — currently allow-failure while stability settles, promoted to blocking once it has been green for a sustained window. Verified per compositor: the full synthetic-seat suite (clicks, keys, drag, tooltip dwell, list multi-select, dialog modality, window states, clipboard roundtrip, compositor-kill disconnect) runs unchanged on both; only the pinning recipe differs (sway for_window rules vs Hyprland windowrules).

Feature matrix

A capability-by-capability audit against relm4/GTK — including the deliberate non-goals and the honest, deferred gaps — lives in docs/completeness.md.

Widgets

Protocols and input

Engine

The rules that keep all of this correct — the parked loop, the resize-before-acquire ordering, buffer staleness, the shared line height, the implicit-grab input model — are written down with file pointers in docs/architecture.md.

Quickstart

devenv shell  # pinned go 1.27, gopls, golangci-lint, gofumpt, delve, just, sway; CGO_ENABLED=0
just demo     # the gelm-hello showcase: widgets, drag, tooltips, menu, Tab focus
just panel    # the gelm-panel layer-shell demo

Other recipes: just bar (layer-shell bar), just multi (many windows on one loop), just check (the release gates: vet, lint, test, build), just fmt (gofumpt in place; just fmt-check is the gate CI runs), just bench (benchmarks, see below). For headless runs without a desktop: just test-env starts a private sway on wlroots' headless backend, and just demo-headless, move, click, sweep, axis drive the demo through the synthetic wlpointer client.

Packaging and releases

The flake exposes the module and the demo binaries as packages, built with the same pinned Go toolchain the dev shell uses (no cgo, no network at build time — modules are vendored via buildGoModule with vendorHash pinning go.sum):

nix build .#gelm-hello   # the widget showcase binary
nix build .#gelm-bar     # the layer-shell bar
nix build .#gelm-panel   # the layer-shell panel
nix build .#gelm         # the whole module: every demo binary + wlpointer

packages.gelm.goModules carries the vendored dependency tree for other nix Go builds. Plain Go consumers don't go through nix: the toolkit ships as an ordinary Go module, and apps pin a version by semver tag — go get github.com/stubbedev/gelm@v0.1.0.

Releases are tag-driven: pushing v* runs .github/workflows/release.yml, which builds the three demo binaries (linux/amd64 + arm64, CGO off) with goreleaser and attaches archives to the GitHub release. goreleaser was chosen over a nix-based release path because release artifacts must be usable without nix, while the flake remains the primary build path; the two share the same source and the same CGO-off constraint.

Benchmarks

widget/benchmark_test.go benchmarks the three frame passes on the showcase tree: BenchmarkShowcaseMeasure (cold measure, cache defeated by alternating constraints), BenchmarkStaticTreeMeasure (warm measure: zero recursion), BenchmarkShowcaseArrange (steady layout walk), BenchmarkShowcasePaint (full-window repaint), plus the damage-tracker benchmarks BenchmarkProgressOnlyFrame / BenchmarkProgressOnlyFrames (incremental repaint). Fixed sizes, no time-dependent content. just bench runs them; CI archives the numbers as workflow artifacts for trend watching — deliberately not a gate, shared runners are too noisy.

The minimal app

gelm's session plumbing is internal/, so an app is a command inside the module (all the demos are). Add cmd/hello/main.go:

package main

import (
	"errors"
	"fmt"
	"log"

	"github.com/stubbedev/gelm/app"
	"github.com/stubbedev/gelm/internal/sysfont"
	"github.com/stubbedev/gelm/internal/window"
	"github.com/stubbedev/gelm/internal/wlsession"
	"github.com/stubbedev/gelm/widget"
)

func main() {
	sess := must(wlsession.Connect())
	defer sess.Close()
	tf := must(sysfont.Sans())
	surf := must(sess.Compositor().CreateSurface())
	win := must(window.New(sess.WmBase(), surf, window.Config{
		Title: "hello", AppID: "dev.stubbe.gelm.hello", Width: 320, Height: 120,
	}))
	die(surf.Commit())
	for range 20 { // complete the xdg configure handshake
		if win.EnsureUsable() == nil {
			break
		}
		die(sess.Roundtrip())
	}

	clicks := 0
	count := widget.NewLabel(tf, 15, "clicked 0 times", widget.Current().Text)
	button := widget.NewButton(count, 10, 8)
	button.OnClick = func() {
		clicks++
		count.SetText(fmt.Sprintf("clicked %d times", clicks))
	}
	sess.OnWmBasePing = win.Pong

	err := app.Run(app.Config{Session: sess, Host: win, Root: button, Background: widget.Current().Bg})
	if err != nil && !errors.Is(err, app.ErrClosed) {
		log.Fatal(err)
	}
}

// must unwraps a (value, error) pair or dies; die checks an error.
func must[T any](v T, err error) T {
	if err != nil {
		log.Fatal(err)
	}
	return v
}

func die(err error) {
	if err != nil {
		log.Fatal(err)
	}
}

go run ./cmd/hello maps the window; the compositor's close button ends the loop. This exact program is kept compiling (and honest) as ExampleRun in app/example_test.go, and the widget-level examples — ExampleEntry, ExampleTextArea, ExampleMenu — run under go test ./... with their output checked.

Documentation

Demos

Roadmap

Milestones from the plan: M1 paint, M2 widgets, M3 theming (palette plus the CSS override layer), and M4 input are in; M5 apps (bar, OSD, launcher, lock screen, settings) is where the demos point. Long term: GTK-class completeness, tiers T1-T4 in the issue.

Dependencies

All pure Go, no cgo:

• neurlang/wayland — Wayland client, event loop, and protocol scanner
• godbus/dbus/v5 — session-bus access for internal/appearance (the system dark/light preference; #53 sanctions this one, the a11y decision does not apply)
• go-text/typesetting — Harfbuzz-grade shaping and glyph outlines
• golang.org/x/image — vector rasterization (and embedded test fonts)
• srwiley/oksvg + srwiley/rasterx — SVG icons
• unxed/xkb-go — the compositor's xkb keymap, self-contained (no system xkb data at runtime)

License

MIT