TODO - Termext Library Development#

Current Status#

Completed#

• ✅ Text sizing protocol (Textsize module)
• ✅ Graphics protocol interface design (Termgraph module)
• ✅ Library renamed from textsize to termext
• ✅ Dependencies added (base64, camlzip)

In Progress#

• 🚧 Termgraph module implementation
• 🚧 Animation support
• 🚧 Example binaries

Graphics Protocol Implementation Plan#

Phase 1: Core Transmission (Current)#

Direct Transmission

• Interface design
• Base64 encoding of image data
• Chunking for large images (4096 byte chunks)
• PNG format support (user-provided bytes)
• RGB/RGBA raw format support
• Escape sequence generation (APC format)

File Transmission

• Interface design
• File path validation
• Escape sequence generation for file paths
• Handle file transmission medium (t=f)

Placement Control

• Interface design
• Position control (x, y offsets)
• Size control (width, height, rows, columns)
• Z-index support
• Cursor movement control
• Image and placement IDs

Deletion

• Interface design
• Delete by image ID
• Delete by placement ID
• Delete at cursor
• Delete all images

Phase 2: Animation Support#

Frame Transmission

• Interface design
• Frame numbering (1-based)
• Composition modes (blend, overwrite)
• Frame gap timing (milliseconds)
• Multi-frame upload

Animation Control

• Interface design
• Set gap for specific frames
• Loop control (count, infinite)
• Start/stop animation
• Frame composition control

Phase 3: Advanced Features (Future)#

Compression

• ZLIB compression for image data
• Automatic compression for large images
• Compression level control

Temporary File Transmission

• Temp file creation
• Escape sequence generation (t=t)
• Cleanup handling

Shared Memory Transmission

• Shared memory name generation
• Escape sequence generation (t=s)
• Platform-specific support (POSIX shared memory)

Virtual Placements

• Unicode placeholder support
• Virtual placement references
• Diacritic composition

Query/Response Handling

• Terminal capability detection
• Success/failure response parsing
• Error handling

Advanced Placement Options

• Source rectangle (crop images)
• Cell offset positioning
• Relative positioning
• Background/foreground placement

Image Composition

• Alpha blending modes
• Composition operations
• Multi-layer support

Phase 4: Eio Integration (Future)#

Async Operations

• Eio-based file reading
• Async chunked transmission
• Streaming large images
• Non-blocking operations

Buf_read/Buf_write Integration

• Use Eio.Buf_read for parsing responses
• Use Eio.Buf_write for efficient serialization
• Zero-copy optimizations

Phase 5: Quality & Documentation#

Testing

• Unit tests for escape sequence generation
• Unit tests for chunking logic
• Unit tests for base64 encoding
• Integration tests with mock terminal
• Animation frame sequencing tests
• Example binaries for manual testing

Documentation

• Complete API documentation
• Usage examples
• Animation tutorial
• Performance guidelines
• Terminal compatibility matrix

Examples

• Simple image display
• Animated GIF-style display
• Image gallery
• Terminal image viewer
• Progress indicator with graphics

Design Decisions#

Transmission Format#

The Kitty graphics protocol uses APC escape sequences:

ESC _G<control>;<payload>ESC \

• Control data: Comma-separated key=value pairs
• Payload: Base64-encoded image data (for direct transmission)

Key Control Parameters#

Animation-Specific Parameters#

Chunking Strategy#

• Maximum chunk size: 4096 bytes (protocol limit)
• For images larger than 4096 bytes when base64-encoded:
  1. First chunk: Include full control data, set m=1
  2. Middle chunks: Only payload data, set m=1
  3. Last chunk: Only payload data, set m=0

Error Handling#

• Validate all parameters before encoding
• Check file existence for file-based transmission
• Ensure image data dimensions match declared width/height
• Validate ID formats (image_id max 24 chars)
• Raise Invalid_argument for out-of-range values

Memory Efficiency#

• Use bytes for image data (mutable, efficient)
• Stream large files rather than loading into memory
• Base64 encode in chunks to limit memory usage
• Consider compression for large images

Future Enhancements#

Additional Protocols#

• Kitty keyboard protocol
• Kitty clipboard protocol
• Synchronized output protocol

Utilities#

• Image format detection
• Automatic format conversion
• Image resizing/scaling helpers
• Color quantization

Integration#

• Notty integration
• Direct terminal detection
• Fallback for non-Kitty terminals

Notes#

Dependencies Rationale#

• fmt: Already used in Textsize, provides consistent formatting API
• base64: Standard library for base64 encoding/decoding, well-tested
• camlzip: ZLIB compression support, mature library

No Image Library Dependencies#

Deliberately not depending on image libraries (camlimages, imagelib) because:

1. Keeps library lightweight
2. Users may already have image data in memory
3. PNG format can be passed through without decoding
4. Allows flexibility in image source (file, network, generated, etc.)
5. User can choose their preferred image library

Compatibility#

Terminals with full support:

• Kitty (v0.40.0+ for text sizing, earlier for graphics)
• Ghostty (with graphics protocol support)

Terminals with partial support:

• WezTerm (graphics protocol)
• Konsole (partial graphics support)

Graceful degradation:

• Other terminals typically ignore unknown escape sequences
• No visible output, but no crashes or errors