guiltty

A Rust library for drawing real, pixel-level 2D graphics in the terminal, using the Kitty Graphics Protocol as its first backend.

Why

Currently, TUI toolkits such as ratatui and cursive can't display real images, smooth shapes, or pixel-precise positioning because they're fundamentally built around a grid of character cells.

The Kitty Graphics Protocol, however, can render actual pixels in compatible terminals. A few projects have explored building graphical UIs on top of it (for example, kui.nvim), but the ecosystem remains small and the results have generally been experimental.

guiltty aims to provide that same capability — drawable canvases, shapes, sprites, and viewports — as a standalone, host-independent Rust library, rather than tying it to a single host application. It does not aim to provide interactive UI controls (buttons, clickable widgets) or event handling — see docs/spec.md's Boundaries for what's explicitly out of scope.

Status: early scaffold, pre-alpha

This project is still in its early stages of development, but its ambitions are considerable.

Its goals include:

• Creating canvases. [DONE]
• Drawing text and vector shapes. [DONE]
• Placing and animating sprites over preserved backgrounds. [DONE]
• Encoding and transmitting frames via the kitty graphics protocol. [DONE]
• Confirming live rendering against a real kitty-compatible terminal. [IN PROGRESS]
  Code-complete but unverified: no kitty-compatible terminal has been available in this environment.
  See docs/spec-kitty-e2e.md for the planned automated + manual verification work.
• Carving a terminal into multiple independent viewports. [NOT STARTED]
  Design complete — see docs/design/viewport-regions-zoom-scroll.md — but not yet broken into tasks or implemented.
• Zooming and panning across large canvases. [NOT STARTED]
  Same design, same status.

What exists today:

• A three-crate Cargo workspace (guiltty-core, guiltty-kitty, guiltty) matching the architecture described in docs/spec.md.
• guiltty-core: the Color (RGBA8), Point, and Rect primitives; the backend-agnostic Backend trait that rendering backends implement; and a Canvas supporting text, shape drawing (lines, rectangles, circles, ellipses, triangles, and arbitrary paths), and movable Sprites over a preserved background — all implemented and unit-tested.
• guiltty-kitty: a KittyBackend implementing Backend — encodes and transmits a Canvas's pixel buffer as a real kitty graphics protocol escape sequence (built on the kittage crate), covered by protocol-level tests. Not yet confirmed against a real terminal — see the goals checklist above.
• guiltty: a facade crate re-exporting the above.
• A runnable example (examples/src/bin/demo.rs) exercising canvas/text/shapes/sprites and two rendered frames, for manual visual verification once a kitty-compatible terminal is available.

Still missing: independent viewport regions, zoom, and scroll/pan for canvases larger than the terminal (see the goals checklist above). See docs/spec.md's Success Criteria for the full v0 scope, and docs/intent/kitty-graphics-ui-toolkit.md for the confirmed project intent this spec implements.

This is a solo project (author + AI coding agents) with no fixed deadline.

Building

cargo build --workspace
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all -- --check

Rust toolchain is pinned via mise (see mise.toml).

License

MIT — see LICENSE.