TermMosaic

Block

Mon, 01 Jan 0001 00:00:00 +0000

A bordered, titled, padded rectangle that other widgets draw inside.

Package widgets/block. API reference: pkg.go.dev/widgets/block.

Block is a bordered region with an optional title. It draws chrome only: it has no content of its own beyond the background and the border.

The zero Block draws no border (Border is BorderNone) with the terminal’s own colours, which is a legal and unremarkable block. It is usable as constructed.

A Block is a plain value in every respect that matters: it is not safe for concurrent use, because SetBounds and Draw race by design — the renderer owns Bounds between frames (ADR 0003).

Text

Mon, 01 Jan 0001 00:00:00 +0000

A single line of styled spans, aligned within its rectangle.

Package widgets/basic. API reference: pkg.go.dev/widgets/basic.

Text renders styled spans on one line.

It is the smallest widget in the catalog and the one most often composed: a label in a form, a value beside it, a status line. It truncates rather than wraps, because wrapping is Paragraph’s job and a widget that both wrapped and did not would be two widgets.

Paragraph

Mon, 01 Jan 0001 00:00:00 +0000

Wrapped, styled prose that reflows to the width it is given.

Package widgets/basic. API reference: pkg.go.dev/widgets/basic.

Paragraph renders wrapped, aligned, styled text over as many lines as fit.

It shows the TOP of its content: there is no scrolling here, because scrolling a block of text is Pager’s job and a Paragraph that scrolled by itself would be a second scroll model. The paragraph that does not fit is the one that gets dropped content, which is ADR 0007’s “information budget” case stated for text: show what fits, clip the rest, never blank.

Split

Mon, 01 Jan 0001 00:00:00 +0000

A container that divides its rectangle among focusable panes.

Package widgets/split. API reference: pkg.go.dev/widgets/split.

Split arranges panes along one axis.

Rendered output

Split rendered by cmd/capture through widgettest.Capture: colour at 3 widths (40, 80, 120 columns), and the exact plain-text cell grid at the widest of them.

MinSize() returns 3 × 1 cells. That is the whole widget including its own chrome, and it is the widget's assertion about itself — below it, Draw clips rather than blanks, and what to do about that is the application's decision.

40 columns × 11 rows

╭ modules ────────────╮ ╭ packages ────╮
│ module size │ │ input  │
│ buffer 8.2 … │ │ layout  │
│ geometry 3.1 … │ │> render █│
│› headless 11.4… │ │ term █│
│ layout 6.7 … │ │ virtual █│
│ render 14.9… │ │ widgets/b…█│
│ virtual 5.0 … │ │ widgets/b…█│
│ │ │ widgets/d… │
│ │ │ widgets/f… │
╰─────────────────────╯ ╰──────────────╯

80 columns × 11 rows

╭ modules ────────────────────────────────────╮ ╭ packages ────────────────────╮
│ module size state │ │ input  │
│ buffer 8.2 kB stable  │ │ layout  │
│ geometry 3.1 kB stable  │ │> render █│
│› headless 11.4 kB beta  │ │ term █│
│ layout 6.7 kB stable  │ │ virtual █│
│ render 14.9 kB beta  │ │ widgets/basic █│
│ virtual 5.0 kB alpha  │ │ widgets/block █│
│ │ │ widgets/data  │
│ │ │ widgets/form  │
╰─────────────────────────────────────────────╯ ╰──────────────────────────────╯

120 columns × 11 rows

╭ modules ────────────────────────────────────────────────────────────╮ ╭ packages ────────────────────────────────────╮
│ module size state │ │ input  │
│ buffer 8.2 kB stable  │ │ layout  │
│ geometry 3.1 kB stable  │ │> render █│
│› headless 11.4 kB beta  │ │ term █│
│ layout 6.7 kB stable  │ │ virtual █│
│ render 14.9 kB beta  │ │ widgets/basic █│
│ virtual 5.0 kB alpha  │ │ widgets/block █│
│ │ │ widgets/data  │
│ │ │ widgets/form  │
╰─────────────────────────────────────────────────────────────────────╯ ╰──────────────────────────────────────────────╯

Plain text — the exact cell grid, trimmed per line. This is the honest form: Braille and block-element glyphs can take a different advance width in a web font than a terminal gives them, which breaks the alignment they depend on.

# Split — A container that divides its rectangle among focusable panes.
# package: widgets/split
# constructor: split.New(d layout.Direction, panes ...termmosaic.Widget) *split.Split
# 120 columns x 11 rows, rendered through widgettest.Capture

╭ modules ────────────────────────────────────────────────────────────╮ ╭ packages ────────────────────────────────────╮
│ module size state │ │ input │
│ buffer 8.2 kB stable │ │ layout │
│ geometry 3.1 kB stable │ │> render █│
│› headless 11.4 kB beta │ │ term █│
│ layout 6.7 kB stable │ │ virtual █│
│ render 14.9 kB beta │ │ widgets/basic █│
│ virtual 5.0 kB alpha │ │ widgets/block █│
│ │ │ widgets/data │
│ │ │ widgets/form │
╰─────────────────────────────────────────────────────────────────────╯ ╰──────────────────────────────────────────────╯

What you are looking at. This is the cell grid the renderer produced, in a web page. It is not a screenshot of a terminal, and it cannot show interaction, resize or animation — a capture is one settled frame after N frames of settling. Braille and Block Elements can take a different advance width in your browser's font than in a terminal, so if a gauge or a sparkline above looks wrong, the plain-text form below it is the exact output and the colour one is the decoration. The colour frames are at 40, 80, 120 columns; the plain-text frame is at 120. More on this.

TextInput

Mon, 01 Jan 0001 00:00:00 +0000

A single-line editable field with a cursor, a selection and undo.

Package widgets/form. API reference: pkg.go.dev/widgets/form.

TextInput is a single-line editable text field: a caret, an optional selection, word motions, undo, and bracketed paste.

It is the reference implementation of the whole form set, because ADR 0005 §4 was written about it. Three properties are load-bearing and each is pinned by a test:

EventPaste is ONE undoable operation. A 10,000-character paste is one step on the undo stack, so one Ctrl-Z removes the whole of it.
Draw allocates nothing in steady state. The visible runs are rebuilt only when the text, the caret, the styles or the rect change, which is ADR 0007 §3’s rect-keyed adaptation applied to a per-keystroke value.
Draw is total for every rect, including 0×0 and 1×1, and below its MinSize it clips rather than blanking.

Rendered output

TextInput rendered by cmd/capture through widgettest.Capture: colour at 3 widths (40, 80, 120 columns), and the exact plain-text cell grid at the widest of them.

MinSize() returns 1 × 1 cells. That is the whole widget including its own chrome, and it is the widget's assertion about itself — below it, Draw clips rather than blanks, and what to do about that is the application's decision.

40 columns × 3 rows

github.com/serkanalgur/termmosaic

80 columns × 3 rows

github.com/serkanalgur/termmosaic

120 columns × 3 rows

github.com/serkanalgur/termmosaic

# TextInput — A single-line editable field with a cursor, a selection and undo.
# package: widgets/form
# constructor: form.NewTextInput(r buffer.Rect) *form.TextInput
# 120 columns x 3 rows, rendered through widgettest.Capture

github.com/serkanalgur/termmosaic

TextArea

Mon, 01 Jan 0001 00:00:00 +0000

A multi-line editable field with wrapping, selection and undo.

Package widgets/form. API reference: pkg.go.dev/widgets/form.

TextArea is a multi-line editable text region that wraps rather than scrolls horizontally.

The wrapping is buffer’s, not this widget’s: the content is handed to buffer.Wrap and the resulting Wrapped is cached against the rect it was built for. Wrap allocates twice over, so calling it in Draw would add an allocation to every frame — the failure ADR 0008 §4 exists to prevent. The first Draw after a width change wraps; every Draw after that reads the cache.

Select

Mon, 01 Jan 0001 00:00:00 +0000

A single-choice control that expands into a scrollable list.

Package widgets/form. API reference: pkg.go.dev/widgets/form.

Select is a closed list of options with one highlighted, scrollable when the options do not all fit.

Rendered output

Select rendered by cmd/capture through widgettest.Capture: colour at 3 widths (40, 80, 120 columns), and the exact plain-text cell grid at the widest of them.

40 columns × 9 rows

 alpine
 bookworm
 cachyos
 debian
> endeavouros 
 fedora 
 gentoo 
 nixos 
 void

80 columns × 9 rows

 alpine
 bookworm
 cachyos
 debian
> endeavouros 
 fedora 
 gentoo 
 nixos 
 void

120 columns × 9 rows

 alpine
 bookworm
 cachyos
 debian
> endeavouros 
 fedora 
 gentoo 
 nixos 
 void

# Select — A single-choice control that expands into a scrollable list.
# package: widgets/form
# constructor: form.NewSelect(r buffer.Rect, labels []string) *form.Select
# 120 columns x 9 rows, rendered through widgettest.Capture

 alpine
 bookworm
 cachyos
 debian
> endeavouros
 fedora
 gentoo
 nixos
 void

Checkbox

Mon, 01 Jan 0001 00:00:00 +0000

A tri-state box: unchecked, checked, or indeterminate.

Package widgets/form. API reference: pkg.go.dev/widgets/form.

Checkbox is a toggleable box with an optional label, in one of three states.

Rendered output

Checkbox rendered by cmd/capture through widgettest.Capture: colour at 3 widths (40, 80, 120 columns), and the exact plain-text cell grid at the widest of them.

MinSize() returns 1 × 5 cells. That is the whole widget including its own chrome, and it is the widget's assertion about itself — below it, Draw clips rather than blanks, and what to do about that is the application's decision.

40 columns × 5 rows

[x] widgets (22)
 
[-] visualisation (5)
 
[ ] release (0)

80 columns × 5 rows

[x] widgets (22)
 
[-] visualisation (5)
 
[ ] release (0)

120 columns × 5 rows

[x] widgets (22)
 
[-] visualisation (5)
 
[ ] release (0)

# Checkbox — A tri-state box: unchecked, checked, or indeterminate.
# package: widgets/form
# constructor: form.NewCheckbox(r buffer.Rect, label string) *form.Checkbox
# 120 columns x 5 rows, rendered through widgettest.Capture

[x] widgets (22)

[-] visualisation (5)

[ ] release (0)

Radio

Mon, 01 Jan 0001 00:00:00 +0000

A single-choice group of labels, navigated with the arrow keys.

Package widgets/form. API reference: pkg.go.dev/widgets/form.

Radio is a one-of-N group of options: exactly one is chosen, and the choice is visible without colour.

Rendered output

Radio rendered by cmd/capture through widgettest.Capture: colour at 3 widths (40, 80, 120 columns), and the exact plain-text cell grid at the widest of them.

MinSize() returns 6 × 1 cells. That is the whole widget including its own chrome, and it is the widget's assertion about itself — below it, Draw clips rather than blanks, and what to do about that is the application's decision.

40 columns × 6 rows

 ( ) horizontal
 ( ) vertical
> (o) both

80 columns × 6 rows

 ( ) horizontal
 ( ) vertical
> (o) both

120 columns × 6 rows

 ( ) horizontal
 ( ) vertical
> (o) both

# Radio — A single-choice group of labels, navigated with the arrow keys.
# package: widgets/form
# constructor: form.NewRadio(r buffer.Rect, labels []string) *form.Radio
# 120 columns x 6 rows, rendered through widgettest.Capture

 ( ) horizontal
 ( ) vertical
> (o) both

Backend strategy

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-10-03
Amended: 2026-10-04 — recorded the golang.org/x/term version pin and the verified CGO_ENABLED=0 cross-compilation status, including the fact that the Windows backend is a loud stub.
Amended: 2026-10-05 — bumped the pin to x/term v0.29.0 / x/sys v0.30.0 and recorded the measured floor boundary; the pin itself is unchanged.
Decides: STATUS.md — Core architecture / Backend strategy
Supersedes: the “Option A / B / C” section of the former ARCHITECTURE.md “Decision 1”.

Context

TermMosaic needs raw-mode control, alternate screen, resize handling, and input decoding. Three shapes were on the table: wrap a library, own the terminal layer, or define narrow interfaces and adapt at the edges.

Toggle

Mon, 01 Jan 0001 00:00:00 +0000

A two-state switch with an on and an off rendering.

Package widgets/form. API reference: pkg.go.dev/widgets/form.

Toggle is an on/off switch with an optional label.

It is not a Checkbox with a different marker: a toggle means “this is running right now” and a checkbox means “include this in the operation”, and users read them differently. The difference is spelled in the marker — the words “on” and “off” — because a bare “[x]” would be ambiguous between the two.

Cell buffer representation

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-10-03
Amended: 2026-10-04 — the byte-compare soundness condition was stated incompletely (it named padding but not contiguity), and the byte-count figure was an artifact of a single-byte-glyph benchmark scene.
Amended: 2026-10-04 — risk item 1b below asked whether to make RowBytes refuse non-top-level buffers structurally, and deferred the question to v1.0. ADR 0006 settles it now: RowBytes becomes a *Buffer method that panics on a sub-buffer.
Decides: STATUS.md — Core architecture / Cell buffer representation
Depends on: ADR 0001
Supersedes: the “Option AoS / SoA” section of the former ARCHITECTURE.md “Decision 2”, including its stated leaning toward SoA.

Context

The cell buffer is the single most performance-critical structure in the framework. Everything in the widget catalog — a 100k-row virtualized table, a live sparkline, a full-screen pager — reads and writes it every frame.

Install

Mon, 01 Jan 0001 00:00:00 +0000

Install

Requirements


Go	1.23 or newer — matches current stable
cgo	Not used. `CGO_ENABLED=0` builds are verified in CI for `linux/amd64`, `linux/arm64`, `darwin/amd64`, `darwin/arm64`, `windows/amd64`, `windows/arm64`
Dependencies	`golang.org/x/sys` and `golang.org/x/term`. That is all of them.
Terminal library	None. TermMosaic wraps no `tcell`, no Bubble Tea, no Textual. It owns the terminal layer through two small interfaces — see ADR 0001.
Platforms that work	Linux and macOS.

Get it

TermMosaic v1.0.0 is tagged and released, so pin the version:

Tabs

Mon, 01 Jan 0001 00:00:00 +0000

A horizontal strip of labels, one of which is the active pane.

Package widgets/form. API reference: pkg.go.dev/widgets/form.

Tabs is a single row of tab labels with one selected, scrollable when the tabs do not all fit.

Rendered output

Tabs rendered by cmd/capture through widgettest.Capture: colour at 3 widths (40, 80, 120 columns), and the exact plain-text cell grid at the widest of them.

40 columns × 4 rows

 Logs [Metrics] Traces Config

80 columns × 4 rows

 Logs [Metrics] Traces Config

120 columns × 4 rows

 Logs [Metrics] Traces Config

# Tabs — A horizontal strip of labels, one of which is the active pane.
# package: widgets/form
# constructor: form.NewTabs(r buffer.Rect, labels []string) *form.Tabs
# 120 columns x 4 rows, rendered through widgettest.Capture

 Logs [Metrics] Traces Config

Button

Mon, 01 Jan 0001 00:00:00 +0000

A labelled, activatable control with a default and a disabled state.

Package widgets/form. API reference: pkg.go.dev/widgets/form.

Button is a focusable label that activates on Enter, Space or a click.

Rendered output

Button rendered by cmd/capture through widgettest.Capture: colour at 3 widths (40, 80, 120 columns), and the exact plain-text cell grid at the widest of them.

40 columns × 3 rows

    
 [Render]    Save

80 columns × 3 rows

    
 [Render]    Save

120 columns × 3 rows

    
 [Render]    Save

# Button — A labelled, activatable control with a default and a disabled state.
# package: widgets/form
# constructor: form.NewButton(r buffer.Rect, label string) *form.Button
# 120 columns x 3 rows, rendered through widgettest.Capture


 [Render] Save

Quickstart

Mon, 01 Jan 0001 00:00:00 +0000

Quickstart

Here is the smallest complete TermMosaic program. It opens the terminal, draws a bordered panel with a frame counter and the negotiated colour depth, survives a resize, and exits on q, Escape or Ctrl-C.

It is also, near enough, examples/hello — so if a line here does not match what you see in the repository, the repository is the source of truth:

go run github.com/serkanalgur/termmosaic/examples/hello@v1.0.0

The program

package main

import (
	"fmt"
	"os"
	"sync"
	"time"

	"github.com/serkanalgur/termmosaic"
	"github.com/serkanalgur/termmosaic/buffer"
	"github.com/serkanalgur/termmosaic/input"
	"github.com/serkanalgur/termmosaic/layout"
	"github.com/serkanalgur/termmosaic/render"
	"github.com/serkanalgur/termmosaic/term"
	"github.com/serkanalgur/termmosaic/widgets/block"
)

const (
	blockW = 46
	blockH = 9
)

func main() {
	if err := run(); err != nil {
		fmt.Fprintln(os.Stderr, "hello:", err)
		os.Exit(1)
	}
}

func run() error {
	t, err := term.Open(os.Stdin, os.Stdout, os.Getenv)
	if err != nil {
		return err
	}
	// Restoring the terminal is not optional on any exit path: a program that
	// leaves a terminal in raw mode has broken the user's shell.
	defer t.Close()

	w, h := t.Size()
	caps := t.Capabilities()

	r := render.New(term.NewSink(os.Stdout), render.Config{
		Width: w,
		Height: h,
		Caps: caps,
		NoColor: render.NoColorFromEnv(os.Getenv),
	})
	// This program has no text input, so a cursor blinking in the last cell drawn
	// would look like a bug. It is managed-but-hidden.
	r.SetCursor(render.Cursor{Valid: true, Visible: false})

	root := newPanel(rootBounds(w, h), caps.ColourDepth())
	r.SetRoot(root)

	if err := t.EnterRawMode(); err != nil {
		return err
	}
	if err := t.EnterAltScreen(); err != nil {
		_ = t.LeaveRawMode()
		return err
	}
	if err := r.Reset(); err != nil {
		return err
	}

	// Both the input loop and the heartbeat below may want to stop the program,
	// and closing a channel twice panics, so the close goes through sync.Once.
	quit := make(chan struct{})
	var quitOnce sync.Once
	stop := func() { quitOnce.Do(func() { close(quit) }) }

	// The input Source is built AFTER raw mode: the kitty keyboard query it sends
	// is answered on the input stream and is meaningless without raw mode.
	sink := term.NewSink(os.Stdout)
	src := input.NewSource(t, withProbe(input.DefaultConfig(), sink))

	// The panel shows a counter that changes when a frame is drawn, so it needs a
	// heartbeat to stay alive. A real application is invalidated by whatever it is
	// displaying, and should not have this goroutine at all.
	stopBeat := make(chan struct{})
	go func() {
		ticker := time.NewTicker(time.Second)
		defer ticker.Stop()
		for {
			select {
			case <-stopBeat:
				return
			case <-quit:
				return
			case <-ticker.C:
				r.InvalidateAll()
			}
		}
	}()

	// Keys and resizes arrive on ONE ordered channel, so a resize can never be
	// delivered between the bytes of a half-read escape sequence.
	go func() {
		for {
			select {
			case <-quit:
				return
			case ev, ok := <-src.Events():
				if !ok {
					stop() // the terminal reached EOF
					return
				}
				switch ev.Kind {
				case termmosaic.EventKey:
					if isQuitKey(ev) {
						stop()
						return
					}
				case termmosaic.EventResize:
					// ADR 0007 §5's order, with nothing between the two steps:
					// recompute the root's rectangle, then resize the renderer.
					// Renderer.Resize never draws, so the whole interval is
					// available to recompute bounds, and Resize already forces a
					// full repaint.
					w, h = ev.Size.W, ev.Size.H
					root.bounds = rootBounds(w, h)
					r.Resize(w, h)
				}
			}
		}
	}()

	pacer := render.NewPacer(r)
	frameErr := make(chan error, 1)
	go func() { frameErr <- pacer.Run(quit) }()

	err = <-frameErr
	close(stopBeat)
	_ = src.Close()
	_ = r.LeaveAltScreen()
	_ = t.LeaveRawMode()
	return err
}

// withProbe wires the input Source's enable sequences and kitty query to the same
// sink the renderer writes frames through, so the two cannot interleave badly.
func withProbe(cfg input.Config, sink termmosaic.Sink) input.Config {
	cfg.WriteProbe = func(p []byte) error {
		if _, err := sink.Write(p); err != nil {
			return err
		}
		return sink.Flush()
	}
	return cfg
}

// isQuitKey reports whether ev should end the program. These are keys a person
// reaches for, expressed in the decoder's vocabulary rather than as raw bytes:
// Ctrl-C arrives as Ctrl+'c' rather than as 0x03, and Escape arrives as KeyEscape
// only after the decoder has waited out its ambiguity delay.
func isQuitKey(ev termmosaic.Event) bool {
	switch {
	case ev.Key == termmosaic.KeyEscape:
		return true
	case ev.Rune == 'q' || ev.Rune == 'Q':
		return ev.Mod == 0
	case ev.Rune == 'c':
		return ev.Mod == termmosaic.ModCtrl
	}
	return false
}

The four-method termmosaic.Widget interface is the whole contract. Here is a complete widget — a Block for the chrome and a body that changes each frame.

Renderer mode

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-10-03
Amended: 2026-10-04 — ADR 0007 considered three ways to make Widget express adaptive content and changed none of the four methods; the amendment tightens the Bounds()/Draw ordering contract and adds one sibling optional interface (Minimizable) beside Focusable.
Decides: STATUS.md — Core architecture / Renderer mode
Depends on: ADR 0001, ADR 0002
Supersedes: the “immediate / retained / hybrid” section of the former ARCHITECTURE.md “Decision 3”.

Context

The framework must pick how a frame gets described:

KeyHint

Mon, 01 Jan 0001 00:00:00 +0000

A one-line bar of key names and their meanings.

Package widgets/form. API reference: pkg.go.dev/widgets/form.

KeyHint renders the keys available right now: the discoverability half of the form catalog.

It is a widget rather than a string helper because a hint is the one piece of a form that changes whenever the state changes — a Select with no options has nothing to activate, so its hint goes away — and because it must obey the same repaint and clipping rules as everything else. Drawing it by hand at each call site is how a form ends up with three different hint styles.

Layout engine

Mon, 01 Jan 0001 00:00:00 +0000

Status: Accepted
Date: 2026-10-03
Amended: 2026-10-04 — the “Fill is order-sensitive” sharp edge was false for this implementation; order-insensitivity is now documented as a deliberate, tested guarantee that diverges from tmux.
Decides: STATUS.md — Core architecture / Layout engine
Depends on: ADR 0003
Supersedes: the “constraint / flexbox” section of the former ARCHITECTURE.md “Decision 4”.

Context

Terminal layouts are small, fixed, and mostly rectangular: a header, a sidebar, a main pane, a status bar. Two models compete:

Your first app

Mon, 01 Jan 0001 00:00:00 +0000

Your first app

The quickstart gave you a panel and a loop. This page adds the two things a real application needs and the quickstart deliberately omits: a widget that takes keys, and a layout with more than one thing in it.

Everything here is written against v1.0.0, the first release that makes a stability promise. The limitations page applies in full.

The shape of a TermMosaic program

There is no framework object, no App.Run() and no message algebra. Five pieces, each owned by you:

TermMosaic

Block

Text

Paragraph

Split

Rendered output

TextInput

Rendered output

TextArea

Select

Rendered output

Checkbox

Rendered output

Radio

Rendered output

Backend strategy

Context

Toggle

Cell buffer representation

Context

Install

Install

Requirements

Get it

Tabs

Rendered output

Button

Rendered output

Quickstart

Quickstart

The program

The widget

Renderer mode

Context

KeyHint

Layout engine

Context

Your first app

Your first app

The shape of a TermMosaic program