KGP Integration

TUI provides complete integration with the Kitty Graphics Protocol via the kgp package. All KGP features are exposed through idiomatic Go APIs.

Architecture

TUI integrates KGP at the buffer level. During Render, components add ImagePlacement values to the buffer. After diff-based text rendering, the framework encodes and flushes all image placements as KGP escape sequences.

Component.Render()
    └─► Buffer
         ├── Cell grid (text)  ──► Diff ──► ANSI sequences
         └── ImagePlacement[]  ──► KGP  ──► Kitty escape sequences

Protocol Overview

KGP commands use APC (Application Program Command) escape sequences:

ESC_G<control-data>;<payload>ESC\

• Control data: Comma-separated key=value pairs (action, format, dimensions, IDs)
• Payload: Base64-encoded binary data

Actions

Image Formats

Transmission Methods

Chunked Transmission

Large images are automatically chunked into 4096-byte segments. Each chunk is a separate escape sequence with a continuation flag. TUI handles this transparently via EncodeChunked.

Response Handling

Terminals respond to KGP commands with status messages. Use ParseImageResponse to parse them:

resp, err := tui.ParseImageResponse(responseString)
if err != nil {
    // Parse error
}
if resp.Success {
    // Command accepted
} else {
    fmt.Printf("Error %s: %s\n", resp.ErrorCode, resp.Message)
}

Coverage

TUI exposes 100% of the kgp package’s API surface:

• All 8 builder types (Transmit, Put, Delete, Frame, Animate, Compose, Query, Command)
• All transmission methods and formats
• All 20 delete modes with free variants
• Complete animation control (frames, playback, composition)
• Response parsing (standard and strict)
• Pixel helpers (conversion, compression, solid colors)
• Low-level command construction for custom use cases

References

• Kitty Graphics Protocol Specification
• kgp Go Bindings
• kgp Documentation