gru

README

Gru

Version: 0.7.0

Gru (GRU) is a Go-first UI toolkit (retained-mode, Raylib-backed) for building desktop applications.

License: Mozilla Public License 2.0
Third-party notices: NOTICE
Copyright: Shawn Londono and LedoCorp
Publisher: LedoCorp · Maintainer: Shawn Londono

---

What’s included

• Full ui/ platform — widgets, layout, text, inspector
• Curated demo app (-tags grudemo) — widget / composition demos, Tab to switch, F12 Inspector
• Optional WebView2 demos (-tags webview2) on Windows
• cmd/gru — scaffold, build, and package apps (gru new, gru build, gru package)
• Sample apps — cmd/hello (native) and cmd/webviewhello (FillClient WebView shell)

What’s not in this repository

• Gru Notepad / Gru Notes (private for now)
• Prism (paused / private)
• Full Studio testing harness and private catalog
• Foundry R&D (internal)

Commercial dual-licensing may come later; it is not part of this release.

---

Module

go get github.com/ledocorp/gru@v0.7.0

import "github.com/ledocorp/gru/ui"

Use @latest once you are comfortable tracking the newest tag.

Quick start (Windows)

From the repository root (folder with go.mod, assets/, pages/):

go run ./cmd/hello
go run -tags webview2 ./cmd/webviewhello
go run -tags grudemo .
go run -tags "grudemo,webview2" .

Scaffold a new app:

go run ./cmd/gru new myapp
go run ./cmd/gru new myapp --webview

Guide	Path
Docs home	docs/README.md
Getting started	docs/GETTING_STARTED.md
CLI	docs/CLI.md
Composition	docs/COMPOSITION.md
WebView	docs/WEBVIEW.md
Architecture	docs/architecture/README.md
Widgets	docs/widgets/README.md
API	docs/api/README.md
Demo index	docs/DEMO_INDEX.md
Build & smoke	docs/BUILD.md

Key	Action
Tab	Next demo scene
F12	Inspector
F11	Perf overlay (optional)

Pull requests are not accepted on this repository — see CONTRIBUTING.md.

Primary target today: Windows.

---

Open-source credits

Gru depends on these projects. Please respect their licenses. Full texts and notices: NOTICE.

Project	Role	License (summary)	Link
Raylib (via raylib-go)	Windowing & rendering	Zlib	https://www.raylib.com/
Remix Icon	Icon font / atlas	Remix Icon License v1.0	https://github.com/Remix-Design/RemixIcon
Inter, Poppins, Fira Code, DM Mono	Bundled UI / mono fonts	SIL OFL 1.1	See assets/fonts/*/OFL.txt
go-text/typesetting	Text shaping	BSD-3-Clause (+ MIT HarfBuzz subtree)	https://github.com/go-text/typesetting
goldmark	Markdown	MIT	https://github.com/yuin/goldmark
chroma	Syntax highlighting	MIT	https://github.com/alecthomas/chroma
go-latex	LaTeX helpers	BSD-3-Clause	https://codeberg.org/go-latex/latex
gospell	Spell-check	MIT	https://github.com/client9/gospell
gg / sbinet/gg	Imaging helpers	MIT	—
fsnotify	File watching	BSD-3-Clause	https://github.com/fsnotify/fsnotify
zenity	Native dialogs	MIT	https://github.com/ncruces/zenity
modernc.org/sqlite (+ libc/memory/mathutil)	SQLite	BSD-3-Clause	https://gitlab.com/cznic/sqlite
golang.org/x/image / x/net / x/sys / x/text	Go extended libs	BSD-3-Clause	https://pkg.go.dev
golang/freetype	Font raster (via x/image stack)	BSD-style	https://github.com/golang/freetype
go-webview2 (vendored)	Windows WebView host	MIT / ISC (loader)	Vendored under internal/go-webview2
Microsoft Edge WebView2	Embedded web runtime (Windows)	Microsoft redistribution terms	https://developer.microsoft.com/microsoft-edge/webview2

---

Contributing

See CONTRIBUTING.md.

Security

Report security issues per SECURITY.md.

---

Gru (GRU) — Copyright Shawn Londono and LedoCorp — MPL 2.0

Documentation

Overview

Caret debugger — press F5 in the demo to toggle stderr tracing for:

• space / char input (focus, cursor, buffer)
• caret draw color and lifecycle phase
• idle FPS blockers (needsRedraw, dirty nodes, wake)

F6 benchmark · F7 resize FPS · F10 draw-dirty · F11 perf overlay

Draw-dirty debugger — press F10 to toggle per-frame dirty-node tracing.

When enabled, logs the first dirty nodes whenever a full SSAA redraw runs without an interactive wake (mouse/keyboard/resize). Use with F6 benchmark lines to correlate redraw=60 with the widgets still marking the tree dirty.

Idle guard — warns when hands-off frames cannot reach cleanForIdle (NeedsRedraw pinned).

Enable with GRU_IDLE_GUARD=1 (GORY_IDLE_GUARD alias) or toggle with F7 (resize FPS debug). See docs/IDLE_INVARIANTS.md.

Resize propagation debugger for the page shell → viewport → grid chain.

Go excludes files named *_test.go from normal builds (go run / go build), so this lives as debug_resize.go. Press F8 in the demo to print bounds.

Resize FPS debugger — press F7 in the demo to toggle detailed stderr logging.

Logs every target-FPS transition with a full snapshot of resize hold, idle policy inputs, and frame timing. While enabled, also emits throttled lines during active resize (~4/sec) so you can correlate actual FPS with hold state.

F6 = benchmark summary (1 line/sec). F7 = this trace. F8 = layout propagation.

WebView flash debugger — GRU_WEBVIEW_DEBUG=1 (GORY_WEBVIEW_DEBUG alias) or Shift+F11 while running.

Logs passthrough, visibility, and present skips when the embedded panel blanks.

Package main is the Gru demo launcher.

Press Tab (or the on-screen button) to cycle through the available demo scenes. Each scene is built by a function in the examples/ package.

Platform helpers for desktop vs Android (raylib NativeActivity).

This file is compiled on every GOOS; branches use isAndroidApp() so desktop keeps MSAA, custom chrome, and default window size. Android-only entry is main_android_init.go (build tag). See docs/ANDROID_CODE.md.