Runnable Examples

Relevant source files

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

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

Runnable examples in the guiltty project serve as the primary vehicle for manual visual verification of the library's graphics capabilities. Since the project targets pixel-level 2D graphics in terminal environments using the Kitty graphics protocol, automated testing is supplemented by these demo binaries to ensure that shapes, text, and sprites render correctly in real-world terminal emulators.

Sources: examples/Cargo.toml, tasks/plan.md:144-150

Purpose and Scope

The examples are designed to exercise the v0 feature set of the guiltty ecosystem. This includes the creation of a Canvas, drawing geometric shapes, rendering text via the built-in bitmap font, and managing Sprite movement with background preservation. The examples specifically target "kitty-compatible" terminals to verify that the KittyBackend correctly encodes and transmits APC escape sequences.

Sources: README.md:12-18, tasks/plan.md:144-148

Example Architecture and Components

Examples are structured as standalone binary crates within the examples/ directory. They depend on the main guiltty facade crate, which re-exports core primitives and backend implementations.

Component Interaction

A typical example follows a standard lifecycle:

1. Initialization: Instantiating a Canvas with specific pixel dimensions.
2. Setup: Loading assets such as Bitmap data from files (e.g., PNGs).
3. Drawing: Utilizing Canvas methods to draw shapes (Shape::Path, Shape::Rect, etc.), text (TextStyle), and Sprites.
4. Presentation: Using a Backend (primarily KittyBackend) to transmit the buffer to the terminal.

Key Features Demonstrated

The following table summarizes the specific library features that runnable examples are required to demonstrate as per the v0 success criteria.

Feature Category	Demonstrated Elements	Technical Implementation
Geometry	Lines, Rects, Circles, Paths	Shape enum variants drawn via Canvas::draw_shape
Typography	3x5 Bitmap Font	Canvas::draw_text with TextStyle scaling
Sprites	Image loading & movement	Bitmap::from_file and Sprite::move_to
Persistence	Background preservation	Sprite save-under/restore-under logic
Protocol	Kitty Graphics Protocol	KittyBackend::present() APC encoding

Sources: tasks/plan.md:144-154, crates/guiltty-core/src/lib.rs:319-335, crates/guiltty-core/src/lib.rs:807-820

Sprite Animation Logic

Runnable examples demonstrate sprite movement by calling present() multiple times. The logic ensures that moving a sprite does not corrupt the background by utilizing the DrawnFootprint system within the Canvas.

Execution and Verification

Examples are executed using standard Cargo commands. Verification is performed manually by a human observer to confirm visual correctness.

Command Syntax

cargo run -p guiltty-examples --bin <example_name>

Sources: tasks/plan.md:164-165

Verification Criteria

• Initial Frame: All shapes and text must be visible at their defined origins.
• Sprite Integrity: Transparent pixels in a Sprite bitmap must not overwrite background content.
• Movement: Calling present() after a Sprite::move_to must show the sprite in the new location with the original background restored at the old location.
• Protocol: Images must render without drift (demonstrating C=1 "don't move cursor" control key) and without APC response noise (demonstrating q=2 suppression).

Sources: tasks/plan.md:144-154, crates/guiltty-kitty/src/lib.rs:90-105

Conclusion

Runnable examples are the definitive test for the guiltty library's visual output. By integrating all core systems—from low-level pixel manipulation in guiltty-core to the complex APC chunking in guiltty-kitty—they provide the only end-to-end validation of the project's goal: pixel-level graphics in a terminal host.