simple-termshot

simple-termshot turns captured terminal output into the final fixed-size screen produced by its documented terminal model. It applies a focused subset of VT100/xterm cursor movement, overwriting, clearing, scrolling, and styling instead of treating the input as an ordinary text stream.

It is a small C program with no runtime dependencies beyond a POSIX-like system. The normal output is plain UTF-8, which makes it useful in scripts, tests, logs, and AI workflows.

For example, a carriage-return progress display contains both updates:

printf 'Progress 10%%\rProgress 100%%\n' | simple-termshot

The result contains only the final visible state:

Progress 100%

make
make test

This produces ./simple-termshot. To install it:

make install PREFIX="$HOME/.local"

PREFIX defaults to /usr/local. Packagers can stage an installation with DESTDIR. CI builds and tests Ubuntu 24.04 on x86-64 and ARM64 with GCC and Clang, and macOS 15 on Intel and Apple silicon with Apple Clang.

simple-termshot capture.log
simple-termshot < capture.log
command-producing-terminal-codes | simple-termshot
simple-termshot --width=120 --height=40 capture.log

Options:

--width=COLUMNS   Screen width (default: 80; range: 1–10000)
--height=ROWS     Screen height (default: 24; range: 1–10000)
--preserve-sgr    Re-create colour and style sequences in the result
--no-strip        Compatibility alias for --preserve-sgr
-h, --help        Show help
-V, --version     Show the version

Use - as the filename to explicitly read standard input. Choose dimensions that match the terminal which produced the capture: wrapping and cursor positions depend on them.

By default, decoration is removed. --preserve-sgr emits terminal escape sequences, so redirect its output to a file first when handling untrusted data.

• A fixed primary screen with delayed auto-wrap, scrolling, and scroll regions
• VT100/xterm cursor positioning, erasure, line/character editing, and tabs
• CR, backspace, and a deliberate newline mode in which bare LF also returns the cursor to column zero
• Valid UTF-8 with bundled Unicode 15.1 zero-width and double-width tables
• Per-line visual ordering for ordinary mixed-direction text, backed by a Unicode 13.0 UAX #9 resolver and mirrored-character data; Unicode Bidi_Control input characters are discarded
• SGR attributes and 16/256-colour output when preservation is requested; RGB input is quantised to the xterm 256-colour palette
• Consumption of OSC strings terminated by BEL or ST and DCS strings terminated by ST

This is deliberately a focused terminal renderer, not a complete xterm. It produces the final fixed-size screen, not scrollback or a time-based replay. It does not model alternate screens, terminal queries, character-set designation, configurable modes, grapheme shaping, or Arabic joining. Unknown and unsupported controls are ignored. Alternate-screen mode switches are ignored, although separately supported clear-and-home sequences still act on the one screen.

The exact control subset, output normalization, Unicode behavior, and failure boundaries are documented in docs/TERMINAL.md.

make test       # 147 core cases plus black-box CLI checks
make sanitize   # tests under AddressSanitizer and UBSan
make analyze    # GCC path-sensitive static analysis
make test-bidi-conformance # official Unicode 13.0 UAX #9 corpora

Warnings fail the build. The suite covers realistic terminal sessions, malformed sequences, split input chunks, Unicode, wide characters, bidi, scrolling, cursor operations, and SGR handling. Every testable claim in the terminal contract is mapped to named evidence in docs/TESTING.md.

The bundled bidirectional resolver implements UAX #9 with Unicode 13.0.0 properties. The terminal snapshot applies that resolver to ordinary screen-cell text after discarding directional formatting controls. Its algorithm, integration boundary, data provenance, and conformance evidence are documented in docs/BIDI.md.

• src/term_snapshot.c — streaming terminal state machine and screen buffer
• src/unicode_width.c — display widths for Unicode characters
• src/bidi.c — bidirectional reordering and bracket mirroring
• src/term_style.c — controlled SGR reconstruction
• src/main.c — file/stdin command-line interface

The extraction history and its verification evidence are recorded in docs/EXTRACTION.md.

simple-termshot was extracted from SonicField/nbs-framework. The path-filtered Git history retains the original authorship and commit messages.

Released under the MIT License. Generated Unicode property data is covered by the Unicode Data Files and Software License.