Version: 0.1.1 · Release notes
Build text-and-cell terminal interfaces in Zsh: styled panels, scrolling lists and tables, editable forms, and responsive layouts. Choose the companion libraries you need and customize their colors, borders, spacing and states.
The native module supplies drawing, Unicode cell measurement, structured input
and terminal lifecycle operations. It is derived from zsh/curses, with a
separate zdraw builtin; stock zcurses stays separate. Applications own their
data, commands and event-loop policy.
Current focus: improve the usefulness, usability and reliability of the existing toolkit. Feature expansion is stopped. Images and scaled text are out of scope. See the scope and quality bar.
A bounded text-selection companion experiment provides pane-confined mouse selection, source-text extraction and a standalone two-pane example. Its API is provisional; tests and a Kitty comparison are recorded.
A separately authorized R1/R2 raster experiment evaluates bounded triangle filling and half-block packing. It is experimental; the general scope stop remains in force.
You need Zsh 5.8 or later, GNU Make, a C compiler, Autoconf/Autoheader, M4, Patch, curses
headers/libraries, Python 3.9+, and a UTF-8 locale. The test terminfo database
must include xterm-256color and vt100; truecolor fixtures need tic -x.
Download the public minimum-version source and build from the repository root
(Linux; see the build guide for other source versions):
mkdir -p .build/downloads .build/sources
curl -fL https://www.zsh.org/pub/old/zsh-5.8.tar.xz \
-o .build/downloads/zsh-5.8.tar.xz
# Verify against the publisher's SHA256SUM before extracting:
printf '%s %s\n' \
dcc4b54cc5565670a65581760261c163d720991f0d06486da61f8d839b52de27 \
.build/downloads/zsh-5.8.tar.xz | sha256sum -c -
tar -xJf .build/downloads/zsh-5.8.tar.xz -C .build/sources
export ZSH_BUILD_ROOT="$PWD/.build/sources/zsh-5.8"
# Compatibility settings for old upstream configure probes on modern Linux:
export CFLAGS='-O2 -std=gnu17 -Wno-error=implicit-int -Wno-error=implicit-function-declaration -Wno-error=incompatible-pointer-types'
export zsh_cv_sys_tcsetpgrp=yes
make build
make test ZSH_BIN="$PWD/.build/zsh/Src/zsh"The build works in .build/, preserves the supplied sources and does not install
anything. Tests use the shell built alongside the module. A module built for one
Zsh configuration is not a universal binary for other shells or platforms.
Linux is verified; BSD/macOS remain unverified. Zsh 5.8 and 5.9.2 are exercised
separately in CI; 5.9.2 is not a runtime requirement.
See build options, ABI matching, migration and upstream contributions for the full instructions and publisher checksum link.
VERSION is the authoritative project version. Releases use annotated
Git tags named vMAJOR.MINOR.PATCH, starting with v0.1.0, and are recorded in
CHANGELOG.md. The version covers the native module and bundled
Zsh companions; it is independent of the Zsh source version and ABI.
For a release, update VERSION, the displayed version above and the changelog,
run the documented checks, commit the changes, and tag that commit. During the
0.x series, incompatible supported-API changes increment the minor version;
compatible fixes increment the patch version. Explicitly experimental APIs
remain provisional.
Start with Choose and combine TUI pieces to select a treatment by its purpose, appearance and space requirements. The review example combines a linked list, status display and change gutter under one theme:
.build/zsh/Src/zsh -df examples/review-composition.zshPress j/k to select a file, Tab to focus its changes, t to switch the shared
theme, and v to vary only the status treatment. These three pieces are
experimental examples; the guide also points to the existing library components.
Run these with the matching built shell from the repository root:
.build/zsh/Src/zsh -df examples/gallery.zsh
.build/zsh/Src/zsh -df examples/list-detail.zsh
.build/zsh/Src/zsh -df examples/table-inspector.zsh
.build/zsh/Src/zsh -df examples/form.zshThe gallery shows theme, border and state variations. The list/detail and inspector recipes demonstrate responsive panes, selection and scrolling. The form demonstrates editing and validation.
For broader colors, use zdraw-ui-theme dark auto after initialization. Author
theme and instance colors as #RRGGBB; the helper selects RGB when supported
or converts to the available palette. The standalone color companion also
supplies reusable gradients. See the color guide, or try:
.build/zsh/Src/zsh -df examples/color-studio.zshFor a small first program, save this as hello.zsh in the repository root and
run .build/zsh/Src/zsh -df hello.zsh:
emulate -R zsh
module_path=("$PWD/.build/modules")
zmodload zdraw || exit 1
source ./lib/zdraw-ui.zsh || exit 1
typeset -A zdraw_ui_theme event
typeset -a size
zdraw-ui-theme dark mono || exit 1
zdraw init || exit 1
{
zdraw position stdscr size || exit 1
zdraw-label stdscr 0 0 "$size[6]" 'Hello from zdraw — q to quit' normal bold || exit 1
zdraw refresh stdscr || exit 1
while zdraw event stdscr event; do
[[ $event[type] == character && $event[text] == q ]] && break
done
} always {
zdraw end
}This draws a greeting; press q to leave. Start with the recipes for a complete
application that handles resize and render failures.
| Task | Start here |
|---|---|
| Choose reusable treatments and combine their data, themes and layout | Choose and combine |
| Explore three visual directions with real terminal captures | Design study |
| Reuse a themed list/detail treatment | Linked detail prototype |
| Show compact line numbers and added/removed review markers | Change gutter prototype |
| Show compact working, waiting, done and failed states | Status display prototype |
| Combine selection, change gutters and status under one theme | Review composition |
| Choose components, themes and style utilities | UI toolkit |
| Debug component failures | Toolkit diagnostics |
| Compose responsive panes | List/detail recipe |
| Build configurable tables | Tables, inspector recipe |
| Use tabs, meters, badges and shortcut hints | Presentation components |
| Edit and validate text | Inputs and forms |
| Display structured documents | Semantic documents |
| Display compact data | Charts, character canvas |
| Handle paste, commands and asynchronous work | Application integration |
| Track simultaneous held keys with explicit fallback and cleanup | Held-key inspector |
| Use native drawing and input operations | Native API guide, Zsh module manual |
| Check terminal support | Capabilities, tested configurations |
| Verify appearance and performance | Visual regression, benchmarks |
Original zdraw contributions use the Zsh licence, recorded in LICENCE.
Source identifiers use LicenseRef-Zsh to refer to those exact terms. Upstream
copyright and permission notices are retained. Unicode-derived tables and test
data retain their separate Unicode licence.