Getting started

Three pages, in order. About fifteen minutes in total, and the third one is the one that matters — a TUI is not a library call, it is a loop you own, and the loop is where the design decisions show up.

1. Install — Go 1.23+, CGO_ENABLED=0, and what is and is not released yet.
2. Quickstart — one file, a bordered panel that survives a resize, annotated line by line.
3. Your first app — terminal, renderer, input, and a frame loop, end to end, with the failure modes named.

Before any of it: v1.0.0 is the first TermMosaic release that makes a stability promise — the public API freezes there and Semantic Versioning applies in earnest, with one documented exception: widgets/widgettest, the test harness, is excluded from that promise, because it must evolve with the framework. See Limitations. If you are evaluating it rather than adopting it, that page is the thing to read first — it is short, specific, and lists what does not work.

What you need

• Go 1.23 or newer. Nothing else. No cgo, no C compiler, no Node.
• A terminal. Linux and macOS. Windows compiles but does not run — the Windows backend is a stub that returns a loud error from every console operation.
• Two dependencies, both golang.org/x: golang.org/x/sys and golang.org/x/term.

The examples

go run github.com/serkanalgur/termmosaic/examples/markets@v1.0.0   # live finance dashboard, no API key
go run github.com/serkanalgur/termmosaic/examples/hello@v1.0.0     # bordered panel, focus ring, ? help
go run github.com/serkanalgur/termmosaic/examples/search@v1.0.0    # search + results on real Wikipedia data

markets is the more useful of the first two to read: it is a real screen built out of the catalog, fed by real network data, and Dashboards walks through how. It takes --offline to run on bundled sample data if you have no network.

search is the fourth and newest. It searches real Wikipedia data with no API key and nothing to sign up for, and takes --offline to run on a transcribed capture. It is the first example with a focusable widget in the focus ring — form.TextInput and data.Table both actually hold focus — so it is the one to read if you want to see the widget catalog and the keymap layer meeting under real conditions rather than proving each on its own.

All three are keyboard- and mouse-driven. Press ? in any of them for its key list.

examples/dashboard also still exists and overlaps markets. Whether to keep it or retire it is undecided — start with markets.

Then

• Concepts — the twelve ideas. Start with Renderer and diff and Widgets and focus.
• Widgets — all 24, with a captured frame each.
• Architecture decisions — the ten ADRs, verbatim, if you want the reasoning rather than the how.

Pages in this section

• Install Go 1.23+, CGO off, two dependencies, and what is and is not released.
• Quickstart One file, a bordered panel that survives a resize, annotated line by line.
• Your first app Terminal, renderer, input, focus and the frame loop — end to end, with the failure modes named.