Termosaic
Termosaic provides structured CLI presentation. It keeps human output, machine-readable text, and opaque bytes as distinct capabilities; renders semantic tokens through application-owned themes; lays out documents and tables without splitting Unicode graphemes; and coordinates human diagnostics with stderr progress.
The library owns no process-global stdout, stderr, color, theme, or progress state.
Each Console instance receives explicit destination capabilities and output
classes, so mixed human and machine streams cannot silently contaminate each other.
Features
| Feature | Default | Capability |
|---|---|---|
serde |
via json |
Validated serialization for names and tokens |
json |
yes | Semantic pretty JSON and compact/pretty machine JSON |
progress |
yes | Coordinated stderr progress handles |
adaptive-tables |
no | Width-aware borderless tables |
background-probe |
no | Opt-in OSC 11 terminal background detection |
The core library, including human and machine-text writers, opaque bytes, semantic tokens, themes, document layout, and fixed tables, builds with default features disabled. Termosaic 0.3 supports Rust 1.88 and newer.
Laidout layout engine
Termosaic re-exports the complete Laidout crate as termosaic::laidout.
Applications can use Termosaic's semantic Doc and prepared rendering APIs,
drop to Laidout's generic annotation and allocation-control surfaces, or use
both without declaring Laidout separately:
use NonZeroU32;
use ;
let doc = group;
let options = new;
let output = render?;
assert_eq!;
# Ok::
Enable Termosaic's laidout-research feature to expose Laidout's optional
research module through the same namespace.
Example
use ;
See examples/basic.rs for a compilable example.
For injected files, buffers, or test sinks,
ConsoleOptions::non_terminal(stdout_class, stderr_class, theme) supplies
explicit non-terminal policy without repeating capability fields.
Widget and cell-grid consumers that own their renderer can call
TerminalColorPolicy::detect_stdout(ColorChoice::Auto) to reuse the same
NO_COLOR, TERM, COLORTERM, TTY, and color-depth decision as
Console::stdio.
Formatters
Termosaic provides human document constructors for wrapped prose,
fixed-width text, lines, words, lists, key/value pairs, diagnostics, and tables.
They return ordinary semantic Doc values and remain fully themeable:
use NonZeroU8;
use formatters;
let prose = word_wrapped;
let fixed = fixed_width_with_tab_width;
With the json feature, human JSON is adaptive and semantically tokenized,
while NDJSON remains validated machine text:
#
MachineTextWriter::write_ndjson writes one compact record and one line feed.
Machine JsonStyle::Pretty is fixed serialized JSON; it never
uses terminal width, themes, or ANSI styling.
formatters::ByteSize keeps an exact u64 byte count while rendering a
human-scale binary unit:
use ByteSize;
assert_eq!;
assert_eq!;
Backgrounds and backend-owned attributes
TokenStyle carries the four attributes every terminal backend understands, plus
a background. Cell-grid hosts signal selection with a fill rather than a text
color:
use ;
const SLATE: Color = Rgb ;
let selected = on;
assert_eq!;
Backends need more than Termosaic can enumerate — fill characters, hyperlinks,
modifiers with no Termosaic equivalent. Style attributes are the seam. The
vocabulary is open, exactly like TokenId; the value domain is closed, so styles
remain comparable and use compact shared storage:
use ;
const REVERSED: StyleAttr = from_static;
let style = default.with_attr;
assert_eq!;
Termosaic's own writers ignore every attribute. An attribute means whatever the
backend that minted it decides, and no other backend is affected by it. Themes
resolve attributes alongside colors, so a rule inherits an ancestor's attributes
and overlays its own. ThemeRule::clear_attr removes an inherited attribute.
Background-aware themes
Background discovery is application-controlled. background::from_env checks
COLORFGBG without terminal I/O. The background-probe feature exposes an
explicit bounded OSC 11 query. Unknown is the result when the terminal does
not answer. themes::for_background selects the theme:
use ;
let theme = for_background;
assert_eq!;
Neither path installs process-global policy, and Console construction never
performs a terminal round-trip.
Prepared documents and strict rendering
Human documents use Laidout internally, but every public document, option, capacity, and error type is owned by Termosaic. Laidout remains usable on its own and never depends on or names Termosaic.
For repeated output, retain one HumanWriter, prepare the document once, and
warm the width/strategy before entering a latency-sensitive path:
use ;
#
Preparation and warming allocate as needed. Once adequately reserved,
doc_strict performs layout, ANSI generation, terminal-newline handling, and
the complete no-progress write through a preinitialized nonallocating sink with
zero allocator calls. Insufficient storage is a typed error and writes no
document bytes. doc_prepared is the Growable alternative;
release_rendering_capacity drops a retained high-water mark.
Cell-grid hosts retain the same storage without exposing Laidout:
use NonZeroU16;
use ;
#
The returned lines borrow the workspace. After warming at the required
high-water mark, compatible render_styled_into calls reuse layout, line, run,
and text allocations. release_capacity drops the retained storage.
See the 0.2 migration guide for constructor, error, Fast-layout, and dependency changes.
Verification
This checks formatting, every feature lane, core/default/all-feature tests, the example, and Clippy with warnings denied.
License
MIT