Tuimark

Tuimark is a view language for terminals. UI is authored as text — structure in .tui (XML), style in .tcss (a reduced CSS), data as JSON, behavior as named actions (on:select="open") — and a Go runtime interprets those files: it lays out an integer cell grid, paints Unicode, and dumps a machine-readable snapshot.

agent edits app.tui + theme.tcss + sample.json
        ↓
tuimark dump --format json --cols 80
        ↓
grid + node geometry
        ↓
agent edits again

Website: tuimark.dev

• Getting started, the guides, and the reference for the language, the CLI, the Go API, and the TypeScript client
• Examples: every app in examples/, pictured from tuimark play output, with animated demos
• Kit components: every component of the kit, pictured in both themes, with its markup
• Blog (RSS)
• For agents: every page as Markdown (its URL plus .md), llms.txt, and llms-full.txt

Release history is in the Changelog.

The Tuimark specification (the SPEC) is the source of truth for the language and the runtime. It is maintained by the author outside this repository; "SPEC §N" references in code and docs point to it. This file is the map of what's in the repo and how to drive it.

What Tuimark is not

Rules the runtime holds to (SPEC §1):

• Not a compiler. .tui is interpreted at runtime; nothing generates Go.
• Not Bubble Tea, Lipgloss, tview, Textual, Ink, or Ratatui — none of those are used as the authoring surface or the public API.
• Not pixels. One unit is one terminal cell; there is no px/em/vh.
• Not an open vocabulary. Tags and CSS properties are a closed catalog; an unknown one is a diagnostic (V001/V003), not a new widget.
• Not a place for logic. No expressions, filters, function calls, or Go in markup — only literal values, {path} interpolation, each, and if.

Installation

Homebrew (macOS and Linux)

brew install --cask abdul-hamid-achik/tap/tuimark
tuimark version

The tap is added automatically; you do not need to run brew tap first.

npm (Node and Bun)

npm i -g @thelacanians/tuimark
tuimark version

Or run it once without installing: npx @thelacanians/tuimark version.

@thelacanians/tuimark is the CLI and the TypeScript client in one package (sdk/ts in this repository). Its tuimark command is a small launcher (plain JavaScript for Node 18 or later and Bun, no dependencies, no postinstall script) that runs the Go binary of the release with the same version: it downloads tuimark_<version>_<os>_<arch> from the GitHub release once, checks its SHA-256 against a table built into the package, and caches it. TUIMARK_BINARY points it at a binary you installed yourself. See TypeScript client for the library side.

Go

go install github.com/abdul-hamid-achik/tuimark/cmd/tuimark@latest

This puts tuimark in $(go env GOPATH)/bin (make sure that directory is on your PATH). It needs Go 1.22 or newer.

Release archives

Each GitHub release has prebuilt binaries for macOS, Linux, and Windows on amd64 and arm64: tuimark_<version>_<Os>_<arch>.tar.gz (.zip on Windows), each holding the tuimark binary, this README, the changelog, and the license. Check the download against checksums.txt, unpack it, and put tuimark on your PATH:

shasum -a 256 -c checksums.txt --ignore-missing   # or: sha256sum -c --ignore-missing checksums.txt
tar -xzf tuimark_*_Linux_x86_64.tar.gz tuimark
sudo install tuimark /usr/local/bin/

Go library

The runtime is also a Go package (see Public Go API):

go get github.com/abdul-hamid-achik/tuimark@latest

import "github.com/abdul-hamid-achik/tuimark"

It has no CGO and needs Go 1.22 or newer. On current macOS, a program built with Go 1.22 that links the net package (such as examples/agent) fails to start with dyld: missing LC_UUID load command; build it with Go 1.23 or newer there.

TypeScript client

The same npm package drives a view from a Bun program over the host protocol: spawnHost starts tuimark host with your document, and your program writes data and answers the actions the document fires.

bunx @thelacanians/tuimark new my-app --ts   # a project with a Bun parent
npm i @thelacanians/tuimark                  # or add it to your own

import { spawnHost } from "@thelacanians/tuimark";

const ui = await spawnHost("app.tui", { data: "sample.json" });
ui.on("open", async (ev) => {
  await ui.set("detail", await load(ev.keys.item));
});

The client needs Bun 1.4.2 or later. See the TypeScript client guide and examples/host-ts.

From source

git clone https://github.com/abdul-hamid-achik/tuimark.git
cd tuimark
go build -o bin/tuimark ./cmd/tuimark

task build (below) builds the CLI and every example host into bin/.

Requirements (development)

• Go 1.22+, no CGO (internal/layout and internal/paint are the only layout/paint engines involved; there is no C dependency to build).
• go-task — optional, for the task verify / task build / task glyph shortcuts in Taskfile.yml. Each task is a short shell command; without task, use the equivalent commands shown under Testing (for example the five go build lines), since a couple of tasks use Taskfile template variables (like {{.AGENT_DIR}}) that a plain shell won't expand.
• Glyphrun (the glyph CLI) — optional, only needed to run the terminal end-to-end specs under specs/glyphrun/. go install github.com/abdul-hamid-achik/glyphrun/cmd/glyph@latest (it needs Go 1.26; CI pins @v0.23.0), then run glyph docs for its own documentation.

Quickstart

go build -o bin/tuimark ./cmd/tuimark
./bin/tuimark validate examples/spike/inbox.tui
./bin/tuimark dump examples/spike/inbox.tui --cols 80 --rows 24
./bin/tuimark dump examples/spike/inbox.tui --cols 80 --rows 24 --format json
./bin/tuimark preview examples/spike/inbox.tui --cols 80 --rows 24

dump prints one frame: the text dump by default, or --format json for the machine-readable shape (grid + nodes + errors). preview writes the same text dump, plus an ANSI-painted grid first when stdout is a TTY. Bind a JSON file as the data store with --data:

./bin/tuimark dump examples/inbox/app.tui --data examples/inbox/sample.json --cols 80 --rows 24

To use the document live in the terminal, with no host program, run it: every action it fires shows in an event strip (F12, or --strip from the start), and saving the file reloads it in place.

./bin/tuimark run examples/inbox/app.tui --data examples/inbox/sample.json --strip

Or use it as a library:

ui, err := tuimark.Load("app.tui")
if err != nil { return err }
_ = ui.Bind("tickets", tickets)
ui.On("open", handleOpen)
ui.On("quit", func(tuimark.Event) error { return tuimark.ErrQuit })
return ui.Run(os.Stdout)

Language tour

A minimal complete app: one list bound to an array, one detail pane bound to the selected item, and a media query that stacks them on a narrow terminal. Three files:

app.tui:

<tui theme="dark">
  <style src="theme.tcss"/>
  <keymap>
    <bind keys="q,ctrl+c" action="quit"/>
  </keymap>
  <screen id="main" focus="#items">
    <col id="root">
      <row id="header">
        <text>{title}</text>
      </row>
      <row id="body">
        <list id="items" each="tickets as t" key="t.id" bind="selected" on:select="open">
          <item>
            <text>{t.title}</text>
          </item>
        </list>
        <box id="detail" if="selected_ticket">
          <text>{selected_ticket.title}</text>
        </box>
        <box id="empty" if="!selected_ticket">
          <text>no selection</text>
        </box>
      </row>
    </col>
  </screen>
</tui>

theme.tcss:

#header { height: 1; }
#body { layout: row; gap: 1; }
#items { width: 30%; border: single; }
#detail, #empty { width: 1fr; border: single; }

@media (max-cols: 60) {
  #body { layout: column; }
  #items { width: 100%; height: 8; }
}

sample.json:

{
  "title": "tickets",
  "selected": "t-1",
  "selected_ticket": { "id": "t-1", "title": "fix the login loop" },
  "tickets": [
    { "id": "t-1", "title": "fix the login loop" },
    { "id": "t-2", "title": "cannot deploy" }
  ]
}

./bin/tuimark validate app.tui --data sample.json
./bin/tuimark dump app.tui --data sample.json --cols 80 --rows 24
./bin/tuimark dump app.tui --data sample.json --cols 60 --rows 24

validate reports ok, and the two dumps show the same layout side by side at 80 columns and stacked at 60 (the @media (max-cols: 60) block takes over), proving the loop end to end. This one example touches:

• Layout units (SPEC §9): N (height: 1, height: 8), N% (width: 30%), Nfr (width: 1fr, the implicit 1fr on col/row), and auto (the default for text).
• TCSS selectors/@media (SPEC §10): #id and a comma-list of ids as selectors, and one feature per @media block (max-cols).
• Bindings (SPEC §7): {path} in <text> bodies, each="tickets as t" on <list>, and if="selected_ticket" / if="!selected_ticket".
• Keymap and actions (SPEC §8): a global <bind> for quit, and on:select="open" as a named action the host would register with On.

Document versions

A <tui> needs no version: without one it is the current language, with everything this section describes plus the 0.4b and 0.4c additions in the Language notes below (composition, props and the slot, and a few defaults and key rules). It is not version="3": a document that writes version="1", "2", or "3" is pinned to the meaning it had in 0.4.1, defaults included, and its dumps do not change; new vocabulary in a pinned document is a diagnostic that ends (requires a <tui> without version). There is no version="4" (it is V003). A version="1" document keeps the vocabulary and meaning it has always had, and its dumps stay byte-identical. version="2" adds the 0.2b vocabulary (SPEC §5.1), and version="3" the 0.3 one. This build implements all of it:

• The version gate. In a version="1" document each 0.2b tag is V001, each 0.2b attribute V002, and each 0.2b value, property, pseudo-class, media feature, or built-in action V003, with a message that ends in (requires version="2"). A .tcss file is checked against the version of the document that loads it, so one stylesheet can serve both. Any other version is V003, and the document is read as version="1". Removing the attribute lifts the gate.

• class:NAME="path" (or !path) on any rendered element adds the class NAME while the guard is truthy, evaluated every frame in the element's scope (a missing path is B002 and counts as null, as for if: class:x="path" adds nothing, class:x="!path" adds x). NAME is lowercase, [a-z_][a-z0-9_-]* (V015 otherwise; an uppercase letter is V002). The JSON dump of a version="2" document lists each node's classes: its class names, then its truthy guards, without repeats (a name that is already there, from class or a guard, is not added again, so class="a b a" gives a b).

• theme="auto". Run() asks the terminal for its background color (OSC 11, waiting at most 250 ms, so the first frame is already in the right theme), falls back to COLORFGBG, then to dark. Every command and Dump()/Validate() treat auto as dark, and validate checks an auto document under both themes.

• @media (theme: dark) / @media (theme: light) hold per-theme rules and :root palettes. Tokens apply in document order, so a light block goes after the base :root it refines:

  :root { --brand: #e0443e; }
  @media (theme: light) { :root { --brand: #c8102e; --bg: #fbfaf8; } }
  #title { color: $brand; }
  

• :focus-within matches the focused node and each ancestor up to the screen (through a modal); nothing while nothing is focused. matches a list or table row whose key is in the widget's array. Both count +10, like the other pseudo-classes.

version="3": clipping warnings (0.3)

A version="3" document is a version="2" document with two extra layout warnings. They name content that a dump shows as gone but that no error mentioned:

• L008: a text loses content without saying so. Either a nowrap line is wider than its box, with no ellipsis, or its lines outnumber its box's rows.
• L009: a node cuts a child on an axis it does not scroll, for example a fixed-height grid whose second row does not fit.

Both show up in validate (at 40, 80, and 120 columns) and in a dump's errors. The dump also marks the node with "clipped": "text" or "children", and the text dump ends its line with clipped. When a cut is what you want, say so in the stylesheet and the warning goes away: wrap: nowrap on the text or an ancestor for a wide line, and overflow: hidden on the node that cuts. Nothing else changes: for a document that clips nothing, version="3" dumps are byte-identical to version="2" ones. A document without version gets them too. The warnings stay out of version="1" and version="2" documents, so existing hosts whose tests expect an empty Validate() keep passing.

CLI reference

tuimark dump     FILE [--cols 80] [--rows 24] [--format text|json] [--data FILE.json]
                      [--cells] [--styles] [--strict] [--theme dark|light]
tuimark validate FILE [--json] [--strict] [--catalog FILE] [--data FILE.json] [--theme dark|light]
tuimark preview  FILE [--cols 80] [--rows 24] [--data FILE.json] [--watch] [--theme dark|light]
                      [--color truecolor|256|16|none]
tuimark play     FILE [--cols 80] [--rows 24] [--data FILE.json] [--theme dark|light]
                      [--input STEPS | --script FILE.ndjson]
                      [--format text|json] [--cells] [--styles] [--frames] [--strict]
tuimark fmt      FILE [--write] [--check]
tuimark ir       FILE
tuimark agents   [--repo | --project]
tuimark catalog
tuimark new      NAME [--go | --ts]
tuimark test     [DIR] [--update] [--allow-breaking]
tuimark inspect  FILE (--at X,Y | --id ID) [--cols 80] [--rows 24] [--data FILE.json]
                      [--theme dark|light] [--strict] [--json]
tuimark run      FILE [--data FILE.json] [--theme dark|light] [--events FILE.ndjson]
                      [--mock FILE.json] [--strip] [--screen ID]
tuimark host     FILE [--data FILE.json] [--theme dark|light] [--reply-timeout 5s] [--screen ID] [--inline]
tuimark mcp
tuimark lsp
tuimark version

• dump renders one frame: the text dump (grid + node geometry + diagnostics) by default, or --format json for the machine-readable shape agents parse (SPEC §13.2). --data FILE.json binds the file as the JSON store first. --cells (JSON only) adds per-cell {x,y,ch,id} ownership; --strict upgrades missing bind paths (B003) to errors; --theme/--styles are below. Exits 2 when the dump has an error-severity diagnostic.
• validate prints diagnostics (or, with --json, the full shape including the action catalog) without laying out a frame for its own sake — it still renders internally at 40/80/120×24 to catch layout/bind problems (under both themes, dark first, for a theme="auto" document without --theme). Without --data, bind-dependent checks (B001–B003, the 0.2b B008–B010, the 0.4b B011 and B012, and the 0.4d B013) are skipped, since every path would otherwise read as "missing", and the text output ends with ok (bindings not checked: no --data) instead of ok (0.4a); with --data the line stays ok. --json has the members actions, data (the --data argument as given, or null), diagnostics, file, and ok. --catalog FILE (a JSON list of action names, or {"actions":[...]}) turns unresolved actions into B004 warnings.
• preview writes the text dump to stdout, and also paints an ANSI frame first when stdout is a TTY, in the color profile from --color, else TUIMARK_COLOR, else detection (the same order and detection rule Run() uses; see "Environment variables" below) — resolved once per preview, including across --watch reloads. --watch re-renders whenever the document, its stylesheets, or --data change (polled every 150ms).
• play replays input against a document with no TTY and prints the resulting dump plus the actions it fired (below).
• fmt is the canonical formatter (below).
• ir prints the source IR as JSON (SPEC §13.1): a document's parsed shape from the stylesheet cascade (SPEC §18's "parse .tui → source IR" step, ahead of "apply stylesheet + media") — a node's map holds only its own presentation attributes and , not rules matched from a sheet. It exits like every other command ( on any diagnostic with error severity, including stylesheet-only errors). A document (and the spike) gives , valid against ; a document gives , valid against , which adds the six new kinds, , and the keymap's / ( attributes stay in under their full names). Its are resolved for the document's theme with as ; a rule inside counts only for that theme.

--theme and dump --styles

--theme dark|light (on dump, validate, preview, play, and inspect) overrides the document's own theme attribute for that one render — the same override Run()'s TUIMARK_THEME environment variable applies for a live session (SPEC §26.4). Any other value the flag is explicitly given — including auto (no tool probes the terminal) and "" — is a usage error that exits 1 before anything is rendered; only leaving --theme off entirely keeps the document's own theme, and a document's theme="auto" is dark in every tool. The golden manifest's theme field (below) follows the same rule.

The host's theme, Set("@theme", "dark"|"light"|"auto") (a reserved path, in both document versions), beats both the document's theme and --theme; in Run(), TUIMARK_THEME beats it, and auto resolves from the terminal's background. Whatever Run() probed never reaches Dump() or Validate().

Environment variables (Run() and preview --color)

Run() reads three environment variables before it touches the terminal (SPEC §26.10); an invalid value is a usage error and Run returns before entering raw mode. Values are exact and case-sensitive; an empty value counts as unset.

Variable	Values	Meaning
TUIMARK_COLOR	truecolor, 256, 16, none	forces the color profile (SPEC §26.3), instead of detecting it from TERM/COLORTERM/NO_COLOR/WT_SESSION
TUIMARK_THEME	dark, light	overrides the document's theme, same as --theme (SPEC §26.4)
TUIMARK_SYNC	0, 1	forces synchronized-output framing off or on, instead of probing the terminal (SPEC §26.6)
TUIMARK_LOG	a file path	writes an NDJSON log of the session (below); a path that cannot be opened, or that names a terminal, makes Run return an error before touching the terminal
COLORFGBG	set by some terminals	the fallback for theme="auto" when the terminal does not answer the background query: its last ; field, 0–6 and 8 dark, 7 and 9–15 light

TUIMARK_LOG=FILE (SPEC §26.12) makes Run() write one JSON object per line to FILE — created with mode 0600, or, when it is an existing regular file (or a symlink to one), truncated and narrowed to 0600 — so diagnostics never land on the terminal Run() owns. Anything else that is not a terminal (/dev/null, a FIFO, a shell's >(jq …) pipe) is written as it is, never truncated and never chmod-ed; a terminal is refused with an error. A Run() that fails before its session starts (stdin is not a terminal) leaves the file with no records. Each record starts with ev and t (milliseconds since Run() started): start (version and size), caps (whether the probe ran, the color profile, synchronized output, grapheme mode, and the effective theme with where it came from), then one record per key (by token), paste (its normalized length), mouse (kind press, release, wheel-up, or wheel-down, and the 0-based cell; only while the mouse is on), mode (each mouse mode change written), action (the §8.2 payload), frame (microseconds and bytes written), and resize, and finally end with its reason (quit, eof, signal, or error). While an enabled secret input has focus, key and paste records are just {"ev", "t", "redacted": true}, and that input's events are logged without their value. A write error stops the logging, never the app.

preview also reads TUIMARK_COLOR — but only when stdout is a TTY (so a plain, redirected preview never depends on the environment), and only as a fallback: --color on the command line wins first. An invalid TUIMARK_COLOR makes preview exit 1 before writing anything, the same way it makes Run() return an error. dump, validate, play, ir, fmt, test, Dump(), and Validate() never read any TUIMARK_* variable, so their output never depends on the environment.

dump --styles (also play --styles; JSON output only) adds two fields to the dump: "theme", the effective theme, and "styles", one array of spans per row. Each span ({"x", "w", "fg", "bg", "a"}) is a maximal run of adjacent columns sharing a foreground, background, and attribute set; every row's spans are contiguous and cover every column. Colors are canonical — "#rrggbb" (lowercase), an ANSI name such as "bright-cyan", or "default" for an unset color — and are never downsampled (downsampling is only a Run()/preview terminal-output concern). "a" lists whichever of bold, dim, italic, underline, reverse are on, in that order, and is omitted when none are. This is how a test asserts :focus, :selected, and reverse-selection styling by diffing JSON instead of reading preview's ANSI output by eye.

tuimark play

tuimark play app.tui --data sample.json \
  --input "text:log tab down" --format json

play loads a fresh app from FILE (--data binds the store root, as for dump) and replays a session against it with no TTY: the same primitives Run()'s event loop uses (key/paste decoding and coalescing, event dispatch, the lifecycle-event settle loop), just never touching a real terminal. Built-in actions (quit, focus) run; a host action registered with On does not exist here, so it is only ever recorded, never executed — play checks what the document would dispatch, not a Go handler's own logic (simulate a handler's effect with a set: step, or test the Go side with go test or Glyphrun).

Steps come from --input "STEP STEP ..." (space-separated; a run of spaces is one separator) or --script FILE.ndjson (one JSON object per line, for steps whose payload needs an embedded space or explicit JSON), never both. With neither, the session is just the first frame (step 0).

--input step	Meaning
KEY	one key: a named key (enter esc tab backspace space up down left right home end pgup pgdn shift+tab; in a document without version also delete, f1..f12, shift+enter, ctrl+enter, alt+enter, alt+backspace, and alt+ a letter or a digit), ctrl+a..ctrl+z, or any other single printable ASCII character but , (write /, not slash — there are no aliases). In a document without version it is delivered as the bytes a terminal sends for the key and read by the same decoder Run() uses: Kitty's CSI-u form by default (shift+enter is CSI 13 ; 2 u), the legacy bytes with --keyboard legacy (alt+x is ESC x; a key a legacy terminal cannot send is a usage error)
text:STR	STR's bytes, decoded like real terminal input: a run of printable characters going to a focused input is one edit and one on:change (the same coalescing Run() does for fast typing or an unbracketed paste); characters that go elsewhere reach the keymap one by one. In a version="2" document each key or paste of the step sees the frame the previous one left, as in Run(), so text:ab\r and text:ab enter fire the same events
paste:STR	one bracketed paste. Normalized (CRLF/CR/LF/TAB → space, ANSI/control bytes stripped) and delivered as one edit/on:change when an enabled input has focus; discarded — never reaching the keymap or a built-in — otherwise, so a paste containing q can never quit
set:PATH=JSON	Set(PATH, json.Unmarshal(JSON)); PATH may be empty (the store root) or the reserved @focus/@screen/@theme (set:@theme="light")
append:PATH=JSON	Append(PATH, json.Unmarshal(JSON)) (0.4d): concatenates a string to the string at PATH, or adds the value as one element at the end of the array there. A failing append is a usage error with the reason

The equivalent --script line for each: {"key":"..."}, {"text":"..."}, {"paste":"..."}, {"set":{"path":"...","value":...}}, {"append":{"path":"...","value":...}}, {"focus":"#..."}, {"resize":[COLS,ROWS]}. {"theme":"light"} ("dark", "light", or "auto") is Set("@theme", value), like set:@theme="light"; since play never probes the terminal, auto is dark. {"click":[X,Y]} is click:X,Y, and {"wheel":"up","at":[X,Y]} (or "down") is wheel-up:X,Y/wheel-down:X,Y — the one step object with two members, exactly those two.

A quit (a keymap quit, or ctrl+c with nothing else claiming it) ends the session early: later steps are never applied. --format json prints the final dump (with --cells/--styles as for dump) plus "events" — every dispatched action, in order, each {"step", "action", "source", "keys", "value"} — always present, [] when nothing fired. --frames adds "frames", one {"step", "input", "events", "dump"} per applied step (step 0 included). --format text appends an === events === section (STEP ACTION SOURCE KEYS VALUE, or the single line none) after the text dump, with one such section per step when --frames is given.

Exit codes: 0 the final dump is ok; 2 it has an error-severity diagnostic; 1 a usage or I/O error (an unparseable step, a mouse step outside the grid, a Set error such as a bad path or an unknown screen) — nothing is printed to stdout in that case, only tuimark: play: step N (INPUT): REASON to stderr.

Exit codes, uniform across every command: 0 ok, 1 usage, I/O, or crash, 2 validation errors (or, for fmt --check / test, "not formatted" / "golden mismatch"). On the CLI, --cols/--rows must be between 1 and 1000 (the underlying Go Dump itself accepts 0, giving an empty grid).

tuimark fmt

Canonical formatting, built on the lossless XML tree so it survives comments and works on any well-formed document regardless of catalog or binding errors (only not-well-formed XML, V005, is refused):

• 2-space indentation, one element per line.
• Attributes reordered to id, class, the class:NAME guards in source order, then the rest in source order.
• Elements with no children and no text self-close (<box id="a"/>).
• <text>/<button> bodies (and a version="2" <column>'s cell template) that fit on one line stay inline (<text>hi</text>); multi-line bodies are indented one level, one output line per text line.
• Inline <style> bodies are re-indented one level and re-escaped (&, <, ]]>; CDATA is not preserved); relative indentation within the body is kept.
• Comments are preserved in place.
• < > & are escaped in text, " & < in attribute values.
• Output always ends with exactly one newline.

Default prints the formatted document to stdout; --write rewrites the file in place; --check prints the file name and exits 2 if it is not already formatted (no write). Both examples/spike/inbox.tui and examples/inbox/app.tui already pass fmt --check.

tuimark inspect

tuimark inspect app.tui --data sample.json --at 12,3 --json
tuimark inspect app.tui --data sample.json --id inbox

inspect renders one frame exactly as dump does with the same flags (it is deterministic, like dump) and explains one node of it: "why does this cell look like this?" --at X,Y (0-based, as in the dump) picks the node the cell belongs to — the node whose id owns the cell in the --cells map, then down through its anonymous children that contain the cell (a list row, a text); --id ID picks the first laid-out node with that id. Exactly one of the two is required.

--json prints cols, rows, ok, the node (as in the dump), its layout path (/screen#main/col#app/list#inbox/item[3]/text), the cell (with --at), the pseudo-classes that match it, one entry per class it could have ({"name", "from", "guard", "active", "used"}: from is class or class:NAME; used tells whether any selector of the loaded stylesheets or of the built-in sheet names it), and one style entry per TCSS property, in a fixed order: its computed value, its origin (ua, attribute, author, inline, inherited, or initial), the winning rule (file, line, column, selector as written — the whole list for a, b, with the specificity of its highest matching selector — or the attribute as written, or style="" — specificity, and @media condition), and the declarations it overridden, highest priority first (a declaration of a selector list counts once, never against itself). The text form (the default) shows the same, one line per property that is not initial.

For a <tui> without version, a cell that a run of a <text runs> painted also adds run: {"index", "text", "classes", "style"}, the run's index in its array (0 for a string), its text, its classes, and the style entries of the seven properties its span styles (a property no rule sets on the span has the text's value and the origin inherited). A cell after the text, on an ellipsis, or selected with --id has none.

A cell outside the grid, an id no laid-out node has, or a malformed value exits 1 with nothing on stdout; a frame with an error-severity diagnostic exits 2 and still prints the report.

tuimark test and the golden manifest

testdata/golden/manifest.json is a JSON array:

[
  {
    "name": "spike",
    "file": "examples/spike/inbox.tui",
    "sizes": ["40x24", "80x24", "120x24"],
    "json": ["80x24"],
    "frozen": true
  }
]

data is optional. For every size in sizes, tuimark test compares the text dump against DIR/<name>/<size>.txt; for sizes also listed in json, it compares the JSON dump against DIR/<name>/<size>.json. DIR defaults to testdata/golden. One PASS/FAIL line is printed per golden, with a short diff hint on failure; the command exits 2 on any mismatch, 1 on an I/O error (a document or golden file that can't be read). --update (re)writes the goldens for every entry whose frozen is not true — spike's goldens are frozen and must never be regenerated; inbox, stacked, unicode, and the SPEC literal fixtures under specs/fixtures/ are not: table (§6.9.5, at 30x5), tabs (§6.10.5, the strip at 8, 12, 20, 30, and 40 columns), hints and hints-filter (§6.12, the second after the play step focus:#filter), and grid (§11.7, at 20 and 30 columns). Adding another fixture just needs another row in the manifest and a golden directory; nothing else in the runner is fixture-specific.

An entry also takes these optional fields:

Field	Meaning
theme	"dark" or "light", as --theme
input	play steps (--input's grammar, above); the goldens for this entry are then play output (an === events ===/"events" section too) instead of plain dump output
script	a play script path (--script's grammar), exclusive with input
styles	true to have the JSON goldens include "theme" and "styles"
cells	true to have the JSON goldens include "cells" (0.2b)

--update's superset check. For a non-frozen entry and a size where a JSON golden already exists, --update refuses to overwrite it unless the newly rendered JSON is a superset of the one on disk: every scalar that was there keeps its exact value, every array keeps its exact length (element by element a superset too), and an object may only gain new members. When it is not — a value changed, an array grew or shrank, a member disappeared — neither the .json nor the paired .txt golden is written for that size; tuimark test instead prints FAIL NAME SIZE (json): update removes or changes POINTER (an RFC 6901 JSON Pointer to the first offending location) and exits 2. This catches an accidental regression at update time instead of only at the next git diff. --allow-breaking skips the check for one run, for a reviewed, deliberate change (a moved node from an auto-fit change, for example) — say why in the commit that updates the goldens.

Public Go API

The public surface is deliberately small (package tuimark, SPEC §18): eighteen entry points.

func Load(path string) (*App, error)
func LoadFS(fsys fs.FS, name string) (*App, error)            // 0.3
func Parse(r io.Reader) (*App, error)

func (a *App) Bind(path string, v any) error
func (a *App) Set(path string, v any) error
func (a *App) Get(path string) (any, bool)                     // 0.3
func (a *App) Batch(fn func(b *Batch) error) error              // 0.3
func (a *App) On(action string, h Handler)
func (a *App) Catalog() []ActionSpec
func (a *App) Dump(cols, rows int) (*Dump, error)
func (a *App) Validate() []Diagnostic
func (a *App) Play(opts PlayOptions, steps ...string) (*PlayResult, error) // 0.3
func (a *App) Run(w io.Writer) error
func (a *App) RunContext(ctx context.Context, w io.Writer) error                // 0.4
func (a *App) RunWith(ctx context.Context, w io.Writer, opts RunOptions) error  // 0.4
func (a *App) Quit()                                                            // 0.4
func (a *App) Every(d time.Duration, fn func(b *Batch) error) (stop func())    // 0.4
func (a *App) Derive(path string, fn func(get func(path string) (any, bool)) (any, error)) error // 0.4

type RunOptions struct {                                        // 0.4
    OnError func(ev *Event, err error) error
}

internal/layout and internal/paint are not importable from outside this module; the only supported entry points are the functions above.

• Load/Parse never fail on diagnostics in the document — a bad .tui loads fine; read Validate() or Dump() to see the problems. Only I/O (Load) or a read error (Parse) returns an error here.
• Bind/Set coerce v to JSON-shaped data (null | bool | number | string | array | object) at the boundary; NaN/±Inf are rejected, as are values with no JSON shape (channels, funcs). Set additionally schedules a redraw and is safe from any goroutine. Three paths are reserved for hosts, not markup: Set("@focus", "#id") moves focus, Set("@screen", "id") switches the active screen — the SPEC says only "the host switches by id" without naming an API, and these paths are how this runtime exposes it without growing the public surface — and Set("@theme", "dark"|"light"|"auto") sets the host's theme (any other value is an error and changes nothing), for Run() and for Dump()/Validate() alike.
• Event is the payload a handler receives: Action (the name), Source (the firing node's id), Keys (a snapshot of the selected item's each aliases, e.g. {"item": "t-12"}), and Value (the input's text for events from a focused input, such as on:change/on:submit or a keymap row; the selected item's id or index for a static, non-each list; the new checked array for a list's on:change; nil otherwise).
• ErrQuit, returned by a handler, stops Run cleanly.
• Dump is a side-effect-free snapshot: it never moves focus, queues events, or mutates scroll/list/input state, so dumping the same app at several sizes never depends on call order. A negative cols/rows is an error; 0 gives an empty grid. Validate has the same no-side-effects property.
• Run drives the app in the terminal (raw mode) until quit. SIGTERM, SIGHUP, and SIGINT also stop it (Unix; on other platforms only os.Interrupt): the terminal is restored first (cooked mode, main screen, visible cursor), and returns a non-nil error naming the signal, so the process can exit with a failure status instead of exiting clean — even when a handler had already returned as the signal arrived.

Examples

Every example below is pictured on tuimark.dev/examples, rendered from tuimark play (or, for the ones that move on their own, from the app's -demo mode).

• examples/spike/inbox.tui — the phase-0 fixture (5 tags: app col row box text). Its goldens in testdata/golden/spike/ are frozen: they are never regenerated, by design — a geometry mismatch there is a runtime regression, not a fixture update.

  ./bin/tuimark dump examples/spike/inbox.tui --cols 80 --rows 24
  

• examples/inbox/{app.tui,theme.tcss,sample.json} — the SPEC §17 fixture (keymap, focus, input, list, binding, each/if, scroll, spacer, media queries; see examples/dashboard below for button/modal/progress/ rule). These three files are kept byte-identical to the SPEC's fixture text; examples/inbox/main.go is an interactive host wiring open/search/quit.

  go build -o bin/inbox ./examples/inbox
  ./bin/inbox
  

• examples/dashboard — a multi-screen host (app.tui, theme.tcss, sample.json, actions.json) exercising screen switching and a confirm-style modal; driven by specs/glyphrun/dashboard_*.yml.

  go build -o bin/dashboard ./examples/dashboard
  ./bin/dashboard
  ./bin/dashboard -dump 80x24   # print the JSON dump instead of running
  

• examples/agent — an interactive host around a scripted or Ollama-backed chat provider (agent.tui, engine.go, provider.go, tools.go, its own README.md); driven by specs/glyphrun/agent_*.yml and has its own Go tests (go test ./examples/agent). The whole view is .tui/.tcss; Go only supplies data and named actions through the public API above.

  go build -o bin/tuimark ./cmd/tuimark
  go build -o bin/agent ./examples/agent
  
  # scripted provider (default), interactive, seeds a demo workspace
  # (--demo-workspace deletes and recreates the given directory)
  ./bin/agent --demo-workspace ./demo-workspace
  
  # headless, machine-readable, one shot
  ./bin/agent --headless --json --demo-workspace ./demo-workspace -p "list"
  
  # headless, then print the resulting UI's own JSON dump instead
  ./bin/agent --headless --dump 120x30 --demo-workspace ./demo-workspace -p "list"
  
  # the in-process loopback fixture: exercises the real HTTP streaming
  # client end to end with no model
  ./bin/agent --fixture --demo-workspace ./demo-workspace
  
  # a real local Ollama model
  ./bin/agent --provider ollama --model qwen3.5:0.8b --demo-workspace ./demo-workspace
  

Testing

• go test ./... — the Go test suite: parser/CSS/layout/IR unit tests, the SPEC §21 conformance tests (conformance_test.go for tests 1-9, phase_test.go for tests 10-14, and the 0.2b literal fixtures and gates through the public API in conformance_v02b_test.go, conformance_p2_test.go, conformance_p3_test.go, conformance_p4_test.go, and the examples/monitor acceptance checks in conformance_p5_test.go), the formatter's idempotence/semantics-preservation tests, the IR-vs-schema test, the AGENTS.md-does-not-drift test, and the CLI's own exit-code/output tests. It also runs tuimark test testdata/golden itself (cmd/tuimark/main_test.go's TestTestCommandPasses), so a golden mismatch fails go test ./... (and task verify) same as any other test. go test -race ./... runs the same suite with the race detector.
• go test -run xxx -bench BenchmarkFrame ./internal/host/ — SPEC §21 test 73 (recorded, not a gate): one 200×60 frame of a 1000-row, 7-column table, with a warm row cache (only the cursor moved), the same with every row checked and the cursor in the last rows, and a cold one (the rows resolved again, as after a Set of the array).
• tuimark test — the golden dump runner described above, runnable on its own (./bin/tuimark test) for a faster loop while iterating; --update regenerates the non-frozen goldens for a human to review and commit. The spike goldens under testdata/golden/spike/ are frozen and never touched by --update.
• glyph run specs/glyphrun/*.yml — terminal end-to-end specs driven by Glyphrun (the glyph CLI) against the real interactive hosts (examples/inbox, examples/dashboard, examples/monitor, examples/agent, and the help modal of every example that writes no version) and the tuimark CLI itself. Every binary the specs run must exist under bin/ first — task build builds bin/tuimark and all the example apps:

  task build
  

  The host_ts* specs also need examples/host-ts's dependencies, which include @thelacanians/tuimark copied from sdk/ts. Reinstall them from scratch so a stale copy never hides an SDK change:

  (cd examples/host-ts && rm -rf node_modules && bun install --frozen-lockfile)
  

  builds and then runs every spec; runs fmt, vet, test, build, golden, and glyph in order — the full local gate. See and for the spec format.

CI (.github/workflows/ci.yml) runs the same gate on every push and pull request to main: gofmt, go vet, go test -race, the builds, and the goldens on Linux (Go 1.22, the module's minimum, and Go 1.26) and macOS (Go 1.26), then every Glyphrun spec on Linux and macOS through .github/scripts/glyph-specs.sh, which runs all the specs and reports every failure instead of stopping at the first. Every spec runs offline: the agent specs use the scripted provider or the in-process loopback fixture.

Architecture

The pipeline a document goes through, from source to screen (SPEC §18):

parse .tui → source IR
apply stylesheet + media(cols, rows, theme)
inflate bindings + each + if
layout measure / allocate
focus + hit-test
paint buffer
diff previous frame → ANSI   # Run() only

Each frame is built in the order SPEC §18 fixes for 0.2b: (1) inflate the active screen and its open modals (if, hidden, text, class guards; a tabs' tab nodes but not their content), (2) cascade and drop display: none, (3) activate one tab per tabs, (4) resolve focus, repeating 1–4 while focus or an active tab changes (at most three rounds), (5) build the items of each hints, (6) measure and allocate, (7) generate the visible rows of each table, (8) paint. A table resolves every row in stage 1 (keys, guards, cell texts, the columns' measures) and gets its rows in stage 7, once layout knows its body height and offset. Stage 3 inflates only the active tab's content, so inactive tabs cost nothing; stage 5 runs the key dispatch without side effects to decide which hints apply; layout then picks the tab label tier and drops the hint items that do not fit.

Package map:

Package	Role
internal/ir	node, scalar, diagnostic, binding-grammar, and key-token types shared by the other packages
internal/parse	the XML tokenizer (xml.go), the IR builder (build.go), the canonical formatter (format.go), and source-IR-as-JSON (irjson.go)
internal/css	the TCSS parser, selectors, cascade, themes/tokens, and @media
internal/layout	the integer flex engine (SPEC §11): box model, measure, allocate; layout: grid, the tab strip, and the hint items (widgets.go); the table (table.go)
internal/paint	the cell grid, borders, titles, widgets, and the ANSI frame diff
internal/dump	the text and JSON frame dump (SPEC §13)
internal/host	the JSON store, bind/each/if inflation, cascade application, focus, the key dispatch of SPEC §8.6 with the built-in actions (dispatch.go, shared by Run, play, and the hints), tabs (tabs.go), hints and sparklines (hints.go), tables (table.go), event dispatch, and the Run loop
internal/agentsdoc	generates AGENTS.md from the catalogs the packages above expose

cmd/tuimark is the CLI built on top of these packages; the root package tuimark (this module's public API, in tuimark.go) is a thin wrapper around internal/host.

Language notes (clarifications of the SPEC)

The SPEC is the source of truth and is not edited here. These are points where its text is loose or silent about behavior the runtime actually has; the generated AGENTS.md carries the same points, more tersely, in its ### Notes section. The full design-decision record (parser edge cases, TCSS cascade details, layout arithmetic, focus/signal handling, the CLI) is kept with the maintainer's project notes, outside this repository.

• <text>/<button> body normalization (SPEC §6.3, §12). Each line of the body is trimmed of XML whitespace (space, tab, CR) and leading/trailing blank lines are dropped; interior spaces are kept, so <text>mail {folder}</text> keeps its two-space gap. Width (§11.5) and paint (§12) both see the already-trimmed content — <text> sync</text> measures 4 cells and paints sync, not sync. There is no XML-level way to force a leading or trailing space into the body (CDATA is trimmed the same way, and numeric character references are rejected outright); use gap, padding, or margin on a parent for spacing, or a non-XML space such as U+00A0 (NBSP) if you need it as literal content. Both points hold for the default wrap: nowrap (and the truncate* values) only: with wrap: wrap, a line is cut into words at every Unicode space (§11.5), so a run of spaces becomes one, and an NBSP is a break point painted as a plain space, not literal content.

• Numbers in the store are float64 (SPEC §7, §18). The store holds JSON values, so Bind, Set, Batch, --data, and the host protocol's set/batch keep every number as a double: an integer beyond ±2^53 (a snowflake or database ID, say) is rounded, and {path} and Get show the rounded value. Pass such values as strings.

• Modal visibility: open vs bind (SPEC §6.5, §7). A <modal>'s open attribute takes true, false, a bare path, or !path — never {path} (that gives V003); truthiness follows the §7 table. bind on a modal is shorthand for the same thing: a path whose truthiness opens it. Reading internal/host/frame.go's inflate for modal, the two are not merged or OR'd: if the open attribute is present at all, it alone decides visibility and bind is ignored outright, even when open's path is falsy and bind's path is truthy. bind is only consulted when open is absent. In practice, set exactly one of the two on a given modal.

• Cross-axis stretch inside a modal (SPEC §11.2, §11.3 pass 4, §6.5). / default to on axes, and by default children stretch to fill the cross axis (). A modal in a document that writes defaults to 80%×80% of the screen when unsized (in a without it is as big as its content, and the row below grows only to a the modal writes), so a of buttons placed after other content inside it — the common confirm-dialog shape — inherits all of the modal's leftover height on the main axis, and its buttons then stretch to match on the cross axis. This is easy to miss in a dump's text grid (a button's label still reads as one line) but is very visible once a focused button has , which paints its rect: a tall reversed block instead of a one-line button. Give the action row an explicit or — alone shrinks the buttons but leaves the row itself still filling the height. For example:

Status per phase (SPEC §4)

• Phase 0 (spike) — done: app col row box text, goldens frozen and green.
• Phase 1 (style) — done: TCSS parser, tokens/themes, one-feature @media, preview --watch.
• Phase 2 (interaction) — done: JSON store, {path}/each/if, list item input button scroll spacer, focus/tab, named actions.
• Phase 3 (chrome) — done: keymap bind progress rule modal, screen focus, validate --strict --catalog, Run().
• Phase 4 (agent polish) — done: fmt, ir, test, agents, dump --cells, the examples/agent harness, this README.
• Phase 5 (v0.2a: runtime, terminal, and tools) — grapheme-cluster width (segmentation by github.com/rivo/uniseg) and the wide/--cells dump fields; auto-fit scroll/list sizing with the L006 diagnostic; Run()'s capability probe, color profiles, theme selection, bracketed paste, and input decoder (SPEC §26); and the headless tools this delivery added — tuimark play, dump --styles, --theme on dump/validate/preview/play, the tuimark test --update superset check, and schema/ir.v0.2.json/schema/dump.v0.2.json. No 0.2a document changes version (tuimark ir still emits "version": "0.1"); <tui version="2"> and the rest of the new vocabulary are 0.2b.
• Phase 6 (v0.2b) — implemented; the SPEC §24 trial with a fresh agent (§21 test 74) is still to be run and recorded. Done: the version="2" gate for the whole 0.2b vocabulary (with the (requires version="2") hint in version="1" documents), IR 0.2 and the 0.2b schemas, class:NAME and the dump's classes, the SPEC §18 frame order, theme="auto" (OSC 11, COLORFGBG), @media (theme), Set("@theme"), tuimark inspect, TUIMARK_LOG, the written-out key dispatch with the built-in actions and over the focus chain, on containers, multi-select on and , /, / (with the golden at 30x5, the SPEC §6.9.5 fixture in ), , , / (with focus on activation and focus requests into inactive tabs), , with /, and (goldens , , , and , the SPEC literal fixtures in ), the mouse (SGR reports, click on release, the wheel, 's / steps), and the acceptance fixture with its goldens and specs.

License

MIT — see LICENSE.