The screenshot tooling
Every colored screen in this guide is the actual terminal output of a running
example, captured live and rendered as selectable HTML. The
hello screen you saw earlier is one of
these. This page explains the pipeline and how to add or regenerate a screen.
The pipeline
A screen is produced entirely by the xtask crate, in pure Rust:
run example in a fixed-size tmux pane
→ tmux send-keys (drive it into the desired state)
→ tmux capture-pane -e -p (colored ANSI + UTF-8 box drawing)
→ repo-owned ANSI→HTML converter (themed <pre class="tv-screen">)
→ written to docs/book/src/screens/<name>.html (committed)
→ embedded into a guide page with {{#include}}
Compared with embedded PNGs, the captured ANSI is selectable, copy-pasteable, scalable, small and diffable in git. It also supports interactive shots: send keystrokes to open a menu or dialog, then capture the result.
The ANSI→HTML converter is repo-owned (no external aha dependency). It resolves
the base SGR colors through Color::BIOS_RGB,
so an embedded screenshot uses exactly the palette the running crate uses. It
also handles the bright colors, bold/underline/reverse, the xterm 256-color cube,
and 24-bit truecolor.
The screen registry
Each documented screen is one entry in the SCREENS table in
xtask/src/screens.rs. An entry names the example to run, the terminal size, the
keystrokes to drive it, and a settle delay:
// Illustrative sketch — not a standalone program.
Screen {
name: "hello", // output file stem → src/screens/hello.html
example: "hello", // cargo run --example hello
cols: 80,
rows: 25,
keys: &[], // tmux send-keys arguments, applied in order
settle_ms: 700, // wait after launch / between keystrokes for repaint
}
Each entry in keys is sent with its own tmux send-keys call, in order, so you
drive the app the way a user would: &["F10", "Down", "Enter"] opens the menu,
moves down, and selects an item before the capture is taken. The capture waits
settle_ms after launch and between keystrokes, giving the app time to repaint.
The blank-capture guard
A capture can come back empty if the app had not finished painting yet (or died
on launch). Writing that blank pane would clobber the committed screenshot, so the
capture step runs a looks_blank check: a pane that contains only whitespace and
escape sequences (no glyphs) is rejected as an error. The committed file is left
untouched, and the message suggests a longer settle_ms. The detached tmux
session is always killed afterward, even on error, so no sessions leak.
Adding or regenerating a screen
-
Add (or reuse) a runnable example under
examples/. -
Add a
Screenentry toSCREENSinxtask/src/screens.rs, with the keys that drive it into the state you want to show. -
Regenerate:
$ cargo xtask screensThis pre-builds every referenced example, then captures each into
docs/book/src/screens/<name>.html. (cargo xtask docsruns the same step as the first stage of the full site build, and skips it with a warning if tmux is unavailable; the committed screens stay usable.) -
Embed it in a guide page:
{{#include ../screens/<name>.html}} -
Commit both the new HTML under
docs/book/src/screens/and yourscreens.rschange. The generated files are checked in, so a plainmdbookbuild (or a reviewer without tmux) still renders the guide with screenshots.
If a regeneration reports a blank capture, bump that screen's settle_ms and run
cargo xtask screens again.