Learn from runnable examples

Language: English | 简体中文

The examples form one executable learning path. Run them from a repository checkout, then read the neighboring test to see the public behavior each slice guarantees.

Run and test the catalog

Run one command from the repository root, where go.work connects current modules:

go run ./examples/hello

Test every command from the example module:

cd examples
go test ./...

Start with the first group when the runtime contract is new. Jump to a later group when you already understand its prerequisites.

Learn the runtime contract

These examples introduce drawing, input ownership, key sequences, and headless fields:

Example	Run	Controls	Focus
hello	go run ./examples/hello	Any key counts; q or Ctrl+C quits	program.Component, Config.Root, grid.View
keys	go run ./examples/keys	g moves after a deadline; gg jumps; q quits	Named actions, exact-prefix sequences, caller-owned timeout
form	go run ./examples/form	Tab changes field; arrows choose; Enter submits	Controlled fields, validation, grid and spoken rendering
state	go run ./examples/state	Type in four fields; Tab advances; Enter submits	Local state, exact binding, normalization, and rejection through one Accessor seam

Pipe the form to exercise the same headless fields without a terminal:

go run ./examples/form | cat

Read Build your first interface before modifying these commands.

Compose headless behavior

These examples combine reusable behavior while the application keeps product layout and meaning:

Example	Run	Controls	Focus
picker	go run ./examples/picker	Type to filter; arrows move; Enter picks	Text field, fuzzy ranking, list, highlighted matches
composer	go run ./examples/composer	Type @; arrows choose; Enter submits	Completion, draft history, atomic paste elements
files	go run ./examples/files .	Tab changes pane; arrows navigate; q quits	Focus, tree identity, viewport, pointer routing
dashboard	go run ./examples/dashboard	Press 1–3, sort headers, adjust sliders	Caller-owned tabs and slider, tables, passive charts, bounded samples, animation lifetime

The library does not add a second Picker or FileBrowser API. Each product interaction is a composition over the same controllers.

Read Compose a themeable picker for the ownership and appearance seams used in this group.

Render optional content

These examples prove that each content module works independently before composition:

Example	Run	Controls	Focus
markdown	go run ./examples/markdown	q quits	Finished blocks, measurement, width-dependent layout
mermaid	go run ./examples/mermaid	r replaces, q quits	Worker diagram preparation, stale results, image upload and release
latex	go run ./examples/latex	q quits	Standalone formula, two-dimensional text layout
content	go run ./examples/content	1/2/3 selects format; q quits	Shared registry for top-level content and Markdown extensions

Read Render Markdown, code, and mathematics to use the three natural entry points and their consumer-owned composition seam.

Publish streamed output

These examples add background work, incremental transforms, inline publication, and application policy:

Example	Run	Controls	Focus
run	go run ./examples/run -- go test ./core/...	Ctrl+E edits; Ctrl+Z suspends; Ctrl+C quits	ANSI decoding, subprocess output, terminal handover
read	go run ./examples/read	Ctrl+C quits after the answer	Incremental Markdown, extensions, stable blocks, open tail
streaming	go run ./examples/streaming	Enter approves; Ctrl+X cancels	Controlled dialog, bounded ingress, transcript, failure, resize
agent	go run ./examples/agent	Enter sends; /help lists commands	Plan, completion, tool review, diff, bounded history

streaming is the canonical library integration. agent adds product policy without moving model names, tool grammar, or workspace effects into the framework. Neither command performs network requests or changes files.

Read Build bounded streaming output before the canonical integration, then Build a bounded agent interface for the advanced boundary.

Review tests and visual goldens

Each main_test.go starts the command through programtest.Host, sends events, and asserts visible behavior. The streaming example also tests terminal scrollback and idle output on a real pseudoterminal (PTY).

The agent command stores narrow and wide text goldens. Regenerate them only when the new geometry is intended:

cd examples
go test -update ./agent

Review every changed golden beside the code change. Ordinary go test ./... never rewrites fixtures.