Quickstart and Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• mise.toml
• Cargo.toml
• crates/guiltty-core/src/lib.rs
• crates/guiltty-kitty/src/lib.rs
• tasks/plan.md
• tasks/issue-16-consumability-assessment-from-iklo-guiltty-s.md

Guiltty is a Rust library designed for drawing pixel-level 2D graphics directly into a terminal using the Kitty graphics protocol. It provides a backend-agnostic core for managing canvases, shapes, text, and sprites, while delegating the actual terminal transmission to specific backend implementations.

The project is currently in an early scaffold/pre-alpha stage. While the core drawing logic for shapes and sprites is implemented and tested, real-world terminal rendering via the Kitty protocol is being finalized.

Sources: README.md:1-20, README.md:22-38

Development Environment Setup

Guiltty uses a pinned Rust toolchain and specific development tools managed through mise.

Prerequisites

• Rust Toolchain: Version 1.96.0 (MSRV).
• Mise: Used for tool version management.
• Cargo Plugins: cargo-llvm-cov for coverage reporting.

Sources: mise.toml:1-4, Cargo.toml:12, tasks/issue-16-consumability-assessment-from-iklo-guiltty-s.md:50-55

Build and Test Commands

Standard Cargo commands are used for development. CI quality gates enforce formatting, linting, and coverage floors.

Action	Command
Build Workspace	cargo build --workspace
Run Tests	cargo test --workspace
Linting	cargo clippy --workspace --all-targets -- -D warnings
Formatting Check	cargo fmt --all -- --check
Coverage Check	cargo llvm-cov --workspace --summary-only --fail-under-lines 90

Sources: README.md:40-47, tasks/issue-16-consumability-assessment-from-iklo-guiltty-s.md:5-7

Project Architecture

Guiltty is organized as a Cargo workspace with three primary crates that separate core logic from protocol-specific implementation.

Workspace Components

1. guiltty-core: Contains the Backend trait, Canvas, and drawing primitives (Color, Shape, Sprite). It is entirely backend-agnostic.
2. guiltty-kitty: Implements the KittyBackend. It handles the encoding of pixel data into Kitty graphics protocol escape sequences.
3. guiltty: A facade crate that re-exports the core API and the default Kitty backend for end-users.

Sources: README.md:25-33, crates/guiltty/src/lib.rs:1-8

Basic Usage Workflow

To render graphics, a developer typically follows a workflow of creating a canvas, drawing elements, and presenting the result via a backend.

1. Initializing the Canvas

The Canvas is a row-major RGBA8 pixel buffer.

// Create a canvas 100x100 pixels
let mut canvas = Canvas::new(100, 100);

Sources: crates/guiltty-core/src/lib.rs:114-135

2. Drawing Shapes and Text

Shapes include Lines, Rects, Circles, Ellipses, Triangles, and Paths.

let color = Color::rgb(255, 0, 0);
canvas.draw_shape(&Shape::circle(Point::new(50, 50), 20), Fill::solid(color));

Sources: crates/guiltty-core/src/lib.rs:335-353, crates/guiltty-core/src/lib.rs:408-422

3. Using Sprites

Sprites support "save-under/restore-under" logic, allowing them to move across a canvas without corrupting the background.

let bitmap = Bitmap::solid(10, 10, Color::rgb(0, 255, 0));
let mut sprite = Sprite::new(bitmap, Point::new(0, 0));

// Draw sprite
canvas.draw_sprite(&mut sprite);

// Move and redraw (automatically restores background at old position)
sprite.move_to(Point::new(5, 5));
canvas.draw_sprite(&mut sprite);

Sources: crates/guiltty-core/src/lib.rs:757-790, crates/guiltty-core/src/lib.rs:800-844

4. Presenting to the Terminal

The KittyBackend encodes the canvas into base64-encoded RGBA data wrapped in Application Program Command (APC) sequences.

Parameter	Function
i (Image ID)	Unique ID per backend instance to prevent collision.
p (Placement ID)	Matches Image ID to update existing placement.
q=2	Suppresses terminal OK/Error responses.
C=1	Prevents cursor movement after display to allow overdrawing.

Sources: crates/guiltty-kitty/src/lib.rs:69-106

Summary

The Guiltty project provides the foundational tools for terminal-based pixel graphics. Setup involves a standard Rust environment with mise for toolchain consistency. Developers interact primarily with the Canvas for drawing operations and the KittyBackend for rendering, benefiting from built-in sprite management and shape rasterization.

Sources: README.md:1-20, tasks/plan.md:10-25