See also: TypeScript commands · Back to the index
ADR-017 — The transcript paints over its text, and only content paints a background
Status: Accepted · Date: 2026-11-05
· Scope: Orkeon.Cli.TerminalGui (TranscriptBuffer, TranscriptView, SchemeFactory), Orkeon.Cli.Abstractions (IBlockConsole), Orkeon.Cli.Commands.Scripting (ctx.writeBlock)
Context
The split-pane transcript stored plain text, so nothing written in it could carry a colour: not a submitted prompt, not a diff, not rendered markdown. The layout also had a rule, every attribute keeps the terminal's background and a line holds one vivid role, so it never fights the user's theme. A diff needs backgrounds, and a script needs a way to ask for one without knowing about colours.
Decision
- The text of a line stays the one source for the wrap, the positions, the selection and the trim. A styled line adds sorted runs, a role painted over its whole row, a hanging indent and an optional copy source. Nothing of this reaches the wrap except the indent.
- Only content paints a background: a submitted prompt, a diff line, a changed word. The layout around it keeps the terminal's background. A role with a background always sets its foreground too, so it reads the same on a dark and on a light terminal, without knowing which one it runs on.
- A copy of a whole line returns its source when it has one; a copy of a part returns what is shown. Mapping every displayed char back to its source is not worth its cost.
- Scripts hand over a source and a kind, never a colour.
ctx.writeBlock({ kind, text })reaches a console that implementsIBlockConsole, and any other console writestextas plain lines. The styled model stays internal toOrkeon.Cli.TerminalGui: the rendering happens there, so the runs never cross a public interface and scripts cannot depend on them. - Styled lines take the empty line left open after a final line break and open a new one, so they add no blank row and stream text written next never extends them.
Consequences
- Plain and replay output do not change:
--ui plainshows the same source as before. - Rendering a block costs the renderer's time on the UI thread, for each block written.
- A partial selection across a rendered line copies the rendered text, not the source.
- Palettes came after this decision:
Orkeon:Cli:Tui:Themeandctx.setThemename the one in use (Dark,Light, orNone, the terminal's own colours), andSchemeFactoryreads each role in it. The palette is named, never detected, so decisions 2 and 4 hold: a script still hands over no colour.
Alternatives rejected
- ANSI sequences in the text. The wrap, the positions and the selection would all have to skip them, and a script could then print colours that plain output shows as garbage.
- A public styled-run type for scripts. It would freeze the display model into the public API and make every script choose colours.