Viewport Regions
Relevant source files
The following files were used as context for generating this wiki page:
Viewport Regions are a planned architectural feature of the guiltty project designed to allow developers to carve out multiple independent areas within a single terminal window. Each region acts as a distinct window into a potentially larger underlying Canvas. This system is intended to support advanced UI patterns such as independent scrolling, zooming, and positioning of graphics sequences that TUIs built on character-cell grids cannot traditionally express.
As of the current development status (pre-alpha), Viewport Regions are identified as a core success criterion for the v0 release but are not yet fully implemented in the codebase. The logic for managing these regions will reside primarily in guiltty-core, while the guiltty-kitty backend will handle the protocol-specific image placement and positioning required to render these regions onto the terminal.
Sources: README.md:16-19, tasks/plan.md:7-13
Architecture and Design Status
The architecture for Viewport Regions is currently in the design phase. While guiltty-core already provides the primitive building blocks (such as Rect and Point), the high-level API for independent regions is deferred to a dedicated design pass.
Design Objectives
- Independence: Each region should be able to render a specific portion of a
Canvasindependently of other regions. - Composition: Multiple regions must be displayable within one terminal session.
- Coordinate Mapping: The system must map regional coordinates to terminal cell locations.
Sources: tasks/plan.md:7-13, README.md:32-37
The following diagram illustrates the intended relationship between a high-resolution Canvas and multiple Viewport Regions mapped to a Terminal.
Viewports act as filters or windows into the larger pixel buffer, which are then transmitted to the terminal as distinct graphics sequences.
Sources: README.md:12-19, tasks/plan.md:10-13
Integration with Backends
The implementation of Viewport Regions relies heavily on the ability of the backend to perform "multi-image placement." In the KittyBackend, this requires moving beyond transmitting a single full-canvas image to using the Kitty Graphics Protocol's image positioning features.
Kitty Graphics Protocol Considerations
| Feature | Protocol Requirement | Status |
|---|---|---|
| Independent Placement | Multiple Image IDs (i) and Placement IDs (p) | Identified in KittyBackend::present |
| Cell Positioning | Coordinate-specific placement escape sequences | Deferred to design pass |
| Cursor Management | C=1 control key (don't move cursor) | Implemented in KittyBackend |
The current KittyBackend implementation includes a unique image_id per instance to prevent collisions, which is a prerequisite for managing multiple independent regions.
Sources: crates/guiltty-kitty/src/lib.rs:18-28, crates/guiltty-kitty/src/lib.rs:88-105, tasks/plan.md:46-51
Related Primitives
While the "Region" struct is not yet defined, guiltty-core provides the necessary spatial primitives to define boundaries and offsets.
Core Data Structures
Point: Used for top-left origins of regions and offsets within a canvas.Rect: Defines the bounds of a viewport region.Canvas: The underlying pixel buffer (Vec<Color>) that regions sample from.
Sources: crates/guiltty-core/src/lib.rs:25-56, crates/guiltty-core/src/lib.rs:105-112
Diagram shows the spatial relationship between basic drawing primitives and the Canvas, which will be extended to support Viewport Regions.
Sources: crates/guiltty-core/src/lib.rs:105-112, crates/guiltty-core/src/lib.rs:25-56, crates/guiltty-core/src/lib.rs:480-484
Implementation Roadmap
The development of Viewport Regions is scheduled following the completion of static image transmission (T1) and shape fills (T2). It is explicitly categorized as a "v0 work" item that requires a separate design document (docs/design/viewport-regions-zoom-scroll.md) before implementation tasks can be assigned.
Remaining Requirements
- Multi-image wire encoding:
KittyBackendmust be updated to support arbitrary terminal cell locations. - Scroll/Pan Logic: Implementing offsets for regions larger than the terminal view.
- Zoom Logic: Scaling the
Canvaspixels during the sampling process for a specific region.
Sources: tasks/plan.md:7-13, tasks/issue-16-consumability-assessment-from-iklo-guiltty-s.md:27-31
Conclusion
Viewport Regions represent guiltty's solution for creating complex layouts in a pixel-aware terminal environment. By decoupling the drawing surface (Canvas) from the display area (Viewport), the library will allow for independent UI components that can be zoomed and scrolled, eventually providing a more flexible alternative to traditional cell-based TUI frameworks.
Sources: README.md:10-15, tasks/plan.md:10-13