Skip to content

Frames — rendered output in both clients

How a transcript shows what was rendered from something: the model's prose, a code block, a diff, a tool call and what it returned, reasoning, data. One vocabulary, two implementations: the terminal UI builds it from this page (TUI Decision 161), and so does the desktop app (Decision 877). Issue #474 is the why; this is the what; what #474 left is #659.

A turn shows its answer, not its working. Everything else on this page serves that.


1. A frame

A frame is a header, a body and its affordances.

  • The header says what this is and one fact about it, on one line.
  • The body is the rendered content, on the surface (§3).
  • The affordances are open or close and, where it applies, open in the scratchpad (#472); copying a frame and opening one in the viewer (#61) are #659's. Neither client has a copy control on a frame yet: the terminal UI copies a selection and /copy.

2. The six kinds

kind what it holds header body
prose the model's Markdown: the answer, and the prose between its calls none the Markdown, rendered
code a fenced block, or a file a call read language, then · path when known highlighted source; line numbers when it came from a file
diff a fenced diff, or the edit a call made or asks to make diff · path +n −m added and removed lines in their colours
tool one call and what came back glyph, name, target, · outcome, · duration the result
reasoning what the model thought before it answered thinking · duration dim, in the reader's ink
data a fenced json, csv or tsv json · n rows, csv · n rows a table when it parses as one, the source when it does not

Header grammar

The parts are separated by · (space, middle dot, space). Counts are words, not symbols: 1 row, 2 rows, 1 step, 7 steps. The minus in +n −m is U+2212.

  • code: elixir · lib/p.ex. The language is the fence's first word, the path its second word when that has a / or a . in it. With neither, the desktop app's label is code and the terminal UI's header is the bare rule.
  • diff: diff · lib/p.ex +3 −1. The path is the fence's, else the +++ line's with its b/ taken off. +n counts the added lines and −m the removed, the +++ and --- lines aside.
  • tool: ✓ read_file lib/p.ex · 120 lines · 2s. The glyph is ✓ done, ✗ failed, ⋯ running. The target is what the call is about: the path, the command, the URL, the agent delegated to. The outcome is a few words: 120 lines, +3 −1, the first line of an error with (n lines) when it has more. The duration is said from one second up; under a second it says nothing a person reads for.
  • reasoning: thinking · 12s, from the first reasoning the model streamed to its reply. A transcript replayed from the log, or attached to mid-turn, draws the frame from the reasoning the logged reply carries, as thinking alone: the log has no time for it.
  • data: csv · 4 rows, the header row not counted; json · 2 rows for an array of flat objects, whose columns are the keys in the order they first appear.
  • prose has no header. It is the frame read most, and it is recognised by its surface. In the desktop app the rendered/source toggle sits where the header would be.

Durations: 14s under a minute, 4m 2s from a minute.

3. The surface

Three surfaces, and not more.

surface what is on it desktop app terminal
the chat notes, a turn's strip, the curtain line, a tool's header the session's background the terminal's own background
a person's turn what a person typed, a command they ran --bg-panel and a coloured left edge, as today the > or ! marker in the accent
rendered every frame's body, and prose whole --bg-sunken and a hairline border the surface background and the frame's rail, ▎

The step. Rendered output sits one step from the chat's background, and the step reads as rendered, not as important: nothing louder than a background and a hairline or a rail. In every theme and mode --bg-sunken is a step from the canvas (Afterglow dark's below its void).

The width (desktop app). Prose keeps the reading measure, 78ch; what is not prose runs to the session's column. A frame is as wide as what is in it, from the measure up to the column: a reply of sentences is a frame of the measure, and one with a wide code block, diff or table widens to show it while its paragraphs stay at the measure. A call's output does the same. A body wider than the column scrolls sideways inside its frame. Reasoning and the strip are words, and keep the measure. The terminal draws to its pane's width.

In the terminal the step is the surface role, the theme's bg.hover token: of the background tokens it is the one that moves away from both a dark terminal's black and a light one's white in every theme, which is what a terminal whose own background nobody knows needs. It is drawn at truecolor and at 256 colours. With 16 colours, or none (NO_COLOR), there is no background, and the rail and the rules carry the frame alone. The rail is drawn at every depth, so a frame takes the same rows and columns whatever the terminal can colour, and what a person selects or copies does not depend on it. Copying leaves the rail out.

Nesting: one level of surface. A code, diff or data block inside prose is a frame of its own — its own header between rules, ┌─ elixir ─── above and └─── below, its own rail — on the prose's surface, with no second step. A transcript must not turn into a stack of boxes.

4. Collapsing

The strip. A turn's working — its reasoning, its calls, and the prose between its calls — is one line where it began, above the answer:

▸ 7 steps · 1 failed · grep, read_file, edit_file · 14s

n steps counts the calls, finish aside, which says itself in the line under it. The desktop app's transcript holds a subagent's calls beside its parent's, so its strip counts every call it stands for, theirs too (Decision 877). · k failed is there when one failed, in the error colour. Then the tools used, in the order first used, four at most and and n more; then the time from the first call's start to the last one's end, or to now while one runs. ▸ when the steps are shut, ▾ above them when they are open.

The answer is the prose after the turn's last call. It is open at every level, and its prose is never cut short: it is the thing the turn was for.

transcript.detail says how much is open, in three values:

value a turn draws
quiet (the default) the strip, the answer, and what is never collapsed (§5)
tools the strip open (▾), the prose between calls, each call's frame open with a long result cut short, reasoning as its header alone
everything nothing collapsed: reasoning open, every result whole — what a bug report wants

It is a key on the config ladder (transcript.detail, quiet by default), set like any other, and /detail quiet | tools | everything changes it for one session in either client. The view is a client's own business: switching re-draws the whole history at the new level, and nothing is written to the session's log.

One key opens the whole turn. In the terminal, e opens every frame of the turn in view — the last one while the pane follows the tail, the one at the top of the view when it is scrolled — as everything draws it, and closes it again; at everything it closes the turn to quiet. The entry at the top of the view stays where it is. In the desktop app, a click on the strip does the same.

Long frames. A frame body past 24 lines shows its first 20 and a line saying the rest, … 42 more lines; opening the turn expands it in place. A code, diff or data block inside prose is cut the same way; the prose around it is not. A person's own command keeps its last 20 lines, … 42 earlier lines, because the end of a command's output is what a person ran it to read. At everything nothing is cut.

Sleeping and waking. A session that sleeps and wakes writes notes for it: session went to sleep, agent restarted, replaying n events, session resumed, session woke on the platform, four for each wake of a pod session. Below everything, a run of them with nothing between is drawn as its latest line, which says where the session stands; at everything every one is drawn. Notes that need a person (a model error, a budget, a failed agent) are not among them and are never folded. The desktop app does this (Decision 1021); the terminal UI draws them all still.

Past 500 lines a frame is to be a card that opens the viewer (§9) instead of a body in the transcript, as a scratchpad document is already a card that opens the scratchpad (TUI Decision 159). Until the viewer exists, both clients cut such a frame as above.

5. Never collapsed

Whatever the level:

  • a failed call — its frame opens itself, the error in its header and its body;
  • an approval or a question — the session waits on a person, so it is drawn whole, in the reserved colour (Decisions tui/0126 and tui/0149), and is never a joke;
  • the turn's cost line, where the client draws one;
  • anything after a budget stop — from the moment a budget ran out, every entry after it is drawn as everything would draw it.

A scratchpad document stays a card at every level (TUI Decision 159).

6. Colour roles

From the generated palette (#228, Decisions tui/0126 and tui/0149), by role, never by colour. The desktop app's tokens are named beside each.

what role (terminal) token (both)
the rendered surface surface terminal bg.hover; desktop bg.sunken with border.hairline
the frame's rail, the rules, a table's lines, line numbers rail border.strong
a code or data label, a heading, a list marker accent border.focus (text.link in Limelight); desktop --frame-accent, generated so
a tool that worked ok status.allowed.fg
a tool that failed, the strip's k failed error status.error.fg
a tool running, the curtain line's facts working status.running.fg
added, removed, a hunk's header added, removed, hunk diff.addedText, diff.removedText, diff.hunkHeader
reasoning, the strip, … n more lines, the curtain's flourish muted text.muted
what waits on a person, and nothing else needs_you status.waiting.fg

Highlighting, in the terminal, takes its colours from the highlighter at truecolor, their nearest of 256 at 256, and the reader's ink with fewer (Decision tui/0126). In the desktop app a token takes a role: a keyword, a tag or a heading the accent; a name being defined text.primary; a string, a number and a type the person palette's third, second and fifth hues (--p3, --p2, --p5), never the reserved colour; a comment and punctuation text.muted; what a diff adds or removes, its colours. The language is the fence's first word, or a file's extension; a fence with none, or one the built-in set lacks, is drawn as written. A grammar a person installs is to map its captures to these roles too (#659).

7. The curtain line

While a turn works, one line under it says what is happening. Two halves:

◐ the actors are powdering their nose — thinking (00:12)
◐ reading the script — running 3 tools: read_file a.ex, read_file b.ex, list_files lib (00:06)
◐ fetching props — running shell mix test (00:04)
waiting for you

The facts are never optional. What is running, how many, and for how long — always there, always after the flourish, in the same place. Somebody debugging at 11pm must not have to expand anything to learn that shell has been going for four minutes.

The flourish is a prefix, never a replacement, and the first thing to go where there is less room: a window's tile in the terminal says the facts alone.

The words are one file, lines.json, for every loading and starting state in the terminal, the desktop app and the console, by what each is said over: starting, thinking, reading (calls that only read: read_file, grep, glob, list_files, git_read, read_branch, read_output, recall, web_fetch), acting (any other call), compacting, long_turn, casting, waiting_for_a_place, daemon_starting, signing_in, checking_for_an_update, first_run, loading, and the two sentence lists, start_screen and curtain_up. The clients read it through generated readers (pnpm lines, mix troupe.lines), checked in CI; a line is added to the file and to nothing else.

The picking rule. Per turn (or per wait) a kind's lines are taken in an order shuffled from a seed: the turn's id, else the session's, else a counter. The n-th time the agent does that in a turn takes the n-th line taken; past the end of a list the line is its facts alone. So nothing repeats within a turn, and two turns do not open the same way. Both clients use the one rule, and a fixture of seed to order keeps their tests to it. A turn past five minutes says a long_turn line in place of the phase's.

The register is fixed: theatre, dry, never sorry, never pretending to be a person, no exclamation mark, no emoji, and the vocabulary of a working theatre (backstage, the prompter, the flies, the green room, the half, the interval, the understudy, the ghost light), not of a performance. A line the curtain says is a lower-case fragment, since it follows ◐ and precedes — the facts; a full sentence stands only where it stands alone (the start screen's quip). A line is localisable, since the facts beside it are.

No flourish on what waits on a person (waiting for you, in the reserved colour), on a model error, or in a subagent's own pane. No curtain line at all in a headless run, troupe bench, CI logs, or anything with --json: those print the facts, and a machine-readable surface with jokes in it is a bug. In the terminal the activated pane draws it, and nothing else does; in the desktop app, the session's transcript, under the turn.

8. Markdown

Prose is Markdown, rendered: headings, emphasis, inline code, quotes, rules, lists nested to any depth (the marker changes with the depth, • ◦ ▪, and a wrapped item lines up under its text), pipe tables (the header bold over a rule, columns aligned as the rule says, a cell past 32 columns cut with …), and the fenced blocks of §2.

What a client does not render, it says plainly rather than drawing badly. The terminal UI leaves raw HTML, images and footnotes as written, and draws a table wider than 100 columns as written under a line that says so. The desktop app disallows raw HTML rather than sanitising it: it is shown as the text it is, and an image as written, never loaded. A link goes where it says only over http or https. A table cell wraps rather than being cut, and a table wider than its frame scrolls inside it. It has a rendered/source toggle on a prose frame, which settles every "is the model's Markdown broken, or is ours?" question (Decision 877).

A mermaid fence is drawn as the diagram in the desktop app: nothing a reply holds runs in the page, so Mermaid draws it at securityLevel: 'strict' and the result is shown as an image, which runs no script and loads nothing. It has a toggle to its source, and a diagram that does not draw is its source with one line saying so. The terminal shows the source, as a code frame.

9. Not here yet

  • Tree-sitter grammars a person installs, and the WASM spike to measure them (#659). The built-in highlighting stays as it is in both clients.
  • The viewer (#61), where a frame past 500 lines will open, and the hand-off to it (#659).