Zoom, Pan, and Scroll
Relevant source files
The following files were used as context for generating this wiki page:
In the current pre-alpha stage of the guiltty project, Zoom, Pan, and Scroll are defined as core success criteria for the v0 release. These features are intended to allow developers to work with canvases that are larger than the visible terminal window, providing the ability to navigate through oversized graphics and adjust the viewing scale.
While these features are not yet implemented in the current codebase, their architectural requirements are being tracked in the project roadmap. They are closely tied to the concept of independent viewport regions, which will allow for carving out specific sections of the terminal for rendering.
Sources: README.md:14-17, README.md:31-33, crates/guiltty-core/src/lib.rs:1-4
Current Development Status
The following table summarizes the implementation status of navigation and scaling features as of the current development phase.
| Feature | Status | Target | Description |
|---|---|---|---|
| Zoom | Not Implemented | v0 | Ability to scale the canvas rendering. |
| Scroll / Pan | Not Implemented | v0 | Navigation for canvases larger than the visible terminal. |
| Viewport Regions | Not Implemented | v0 | Independent regions within one terminal window. |
Sources: README.md:31-34, tasks/plan.md:6-10, tasks/issue-16-consumability-assessment-from-iklo-guiltty-s.md:23-26
Architectural Roadmap
The implementation of Zoom, Pan, and Scroll is deliberately deferred until a dedicated design pass occurs. This design pass will be documented in docs/design/viewport-regions-zoom-scroll.md to define the API shape for these operations.
The logic for these features is intended to reside within the guiltty-core crate, ensuring that the scaling and navigation math remains backend-agnostic.
Integration with Core Components
The future implementation will interact with several existing primitives:
- Canvas: Will likely be extended to handle dimensions exceeding terminal cell constraints.
- Point & Rect: These primitives will be used to define offsets (Panning) and clipping boundaries (Scrolling).
- Backend Trait: The
presentmethod will need to account for the transformed view (Zoomed/Panned) when transmitting pixel data to backends likeguiltty-kitty.
Sources: tasks/plan.md:6-10, crates/guiltty-core/Cargo.toml:10-10, crates/guiltty-core/src/lib.rs:1-4
Proposed Feature Flow
The following diagram illustrates how the Zoom and Scroll logic is expected to interface between the user application and the terminal backend.
The diagram shows the projected data flow where core logic handles transformations before passing the final visible pixel buffer to the backend.
Sources: tasks/plan.md:6-12, README.md:9-12
Design Considerations
The project identifies several "open questions" regarding the API shape of these features:
- Coordinate Systems: Distinguishing between "World" (Canvas) coordinates and "Screen" (Terminal) coordinates during panning.
- Scaling Algorithms: How
Zoomwill affect the rasterization of shapes (e.g., Lines, Circles) and Sprites. - Independent Regions: Supporting multiple viewports where one region might be zoomed while another remains static.
Sources: tasks/plan.md:6-12, tasks/issue-16-consumability-assessment-from-iklo-guiltty-s.md:23-26
Summary
Zoom, Pan, and Scroll represent the transition from simple static canvas rendering to a dynamic UI toolkit. While the underlying primitives (Point, Rect, Canvas) are ready in guiltty-core, the active implementation of navigation logic is pending the finalization of the Viewport Regions design. Once implemented, these features will allow guiltty to function as a full-featured terminal graphics host capable of handling complex, high-resolution layouts.
Sources: README.md:9-17, tasks/plan.md:6-8