commit 62761b656ac9f68f3675d09bbe9879050248fec7 · anil.recoil.org/slop

+113 -46

tgp/README.md

···

       1
       1
       -
       # Textsize

     

       1
       1
       +
       # Termext - Terminal Extensions for OCaml

     

       2
       2
        
       

     

       3
       3
       -
       A clean, standalone OCaml library implementing the [Kitty text sizing protocol](https://sw.kovidgoyal.net/kitty/text-sizing-protocol/).

     

       3
       3
       +
       A clean OCaml library implementing Kitty terminal protocols for enhanced terminal output.

     

       4
       4
        
       

     

       5
       5
        
       ## Overview

     

       6
       6
        
       

     

       7
       7
       -
       The Kitty text sizing protocol (introduced in kitty v0.40.0) allows terminals to render text in different sizes, enabling typographic features like headlines, superscripts, and subscripts.

     

       7
       7
       +
       Termext provides OCaml bindings for modern terminal protocols:

     

       8
       8
       +
       

     

       9
       9
       +
       - **Text Sizing**: The [Kitty text sizing protocol](https://sw.kovidgoyal.net/kitty/text-sizing-protocol/) for rendering text at different sizes

     

       10
       10
       +
       - **Graphics**: The [Kitty graphics protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/) for displaying images and animations

     

       8
       11
        
       

     

       9
       12
        
       ## Features

     

       10
       13
        
       

     

       14
       14
       +
       ### Text Sizing (Textsize module)

     

       11
       15
        
       - ✨ Clean, type-safe API with validation

     

       12
       12
       -
       - 📦 Zero dependencies (besides OCaml standard library)

     

       13
       16
        
       - 🎯 Full protocol support (scale, width, fractional sizing, alignment)

     

       14
       14
       -
       - 🚀 Convenient helper functions for common use cases

     

       15
       15
       -
       - 📝 Comprehensive documentation

     

       17
       17
       +
       - 🚀 Convenient helper functions (double, triple, superscript, subscript)

     

       18
       18
       +
       - 📐 Fmt-style formatters

     

       19
       19
       +
       

     

       20
       20
       +
       ### Graphics (Termgraph module - In Development)

     

       21
       21
       +
       - 🖼️ PNG image display

     

       22
       22
       +
       - 📁 File and direct transmission

     

       23
       23
       +
       - 🎬 Animation support

     

       24
       24
       +
       - 🎨 Z-index layering

     

       25
       25
       +
       - 📦 Fmt-style formatters

     

       26
       26
       +
       - 🎯 Type-safe placement control

     

       16
       27
        
       

     

       17
       28
        
       ## Installation

     

       18
       29
        
       

     

       19
       30
        
       ```bash

     

       20
       31
        
       # Via opam (once published)

     

       21
       21
       -
       opam install textsize

     

       32
       32
       +
       opam install termext

     

       22
       33
        
       

     

       23
       34
        
       # Or add to your dune-project dependencies

     

       24
       35
        
       (depends

     

       25
       25
       -
         (textsize (>= 0.1.0)))

     

       36
       36
       +
         (termext (>= 0.1.0)))

     

       26
       37
        
       ```

     

       27
       38
        
       

     

       28
       39
        
       ## Quick Start

     

       29
       40
        
       

     

       41
       41
       +
       ### Text Sizing

     

       42
       42
       +
       

     

       30
       43
        
       ```ocaml

     

       31
       44
        
       (* Simple convenience functions *)

     

       32
       32
       -
       print_string (Textsize.double "Hello, World!");;

     

       33
       33
       -
       print_string (Textsize.triple "Big Text");;

     

       34
       34
       -
       print_string (Textsize.half "Small text");;

     

       45
       45
       +
       print_string (Termext.Textsize.double "Hello, World!");;

     

       46
       46
       +
       print_string (Termext.Textsize.triple "Big Text");;

     

       47
       47
       +
       print_string (Termext.Textsize.half "Small text");;

     

       35
       48
        
       

     

       36
       49
        
       (* Superscripts and subscripts *)

     

       37
       50
        
       print_string "E=mc";

     

       38
       38
       -
       print_string (Textsize.superscript "2");;

     

       51
       51
       +
       print_string (Termext.Textsize.superscript "2");;

     

       39
       52
        
       

     

       40
       53
        
       print_string "H";

     

       41
       41
       -
       print_string (Textsize.subscript "2");

     

       54
       54
       +
       print_string (Termext.Textsize.subscript "2");

     

       42
       55
        
       print_string "O";;

     

       43
       56
        
       

     

       44
       44
       -
       (* Custom sizing with metadata *)

     

       45
       45
       -
       let custom =

     

       46
       46
       -
         Textsize.empty

     

       47
       47
       -
         |> Textsize.with_scale (Textsize.make_scale 4)

     

       48
       48
       -
         |> Textsize.with_width (Textsize.make_width 6)

     

       57
       57
       +
       (* Fmt integration *)

     

       58
       58
       +
       Fmt.pr "The answer is %a\n"

     

       59
       59
       +
         (Termext.Textsize.styled_double Fmt.int) 42;;

     

       60
       60
       +
       ```

     

       61
       61
       +
       

     

       62
       62
       +
       ### Graphics (Preview)

     

       63
       63
       +
       

     

       64
       64
       +
       ```ocaml

     

       65
       65
       +
       (* Display a PNG file *)

     

       66
       66
       +
       print_string (Termext.Termgraph.display_png_file "image.png");;

     

       67
       67
       +
       

     

       68
       68
       +
       (* With size control *)

     

       69
       69
       +
       print_string (Termext.Termgraph.display_png_file

     

       70
       70
       +
         ~rows:10

     

       71
       71
       +
         ~columns:20

     

       72
       72
       +
         "logo.png");;

     

       73
       73
       +
       

     

       74
       74
       +
       (* Fmt integration *)

     

       75
       75
       +
       let img = Termext.Termgraph.v

     

       76
       76
       +
         ~rows:15

     

       77
       77
       +
         (Termext.Termgraph.File { path = "banner.png" })

     

       78
       78
       +
         ()

     

       49
       79
        
       in

     

       50
       50
       -
       print_string (Textsize.render custom "Custom sized");;

     

       80
       80
       +
       Fmt.pr "Welcome! %a\n" Termext.Termgraph.pp img;;

     

       81
       81
       +
       

     

       82
       82
       +
       (* Animation *)

     

       83
       83
       +
       let anim_id = Termext.Termgraph.image_id_of_string "spinner" in

     

       84
       84
       +
       let frame1 = Termext.Termgraph.Animation.frame

     

       85
       85
       +
         ~gap:100

     

       86
       86
       +
         (Termext.Termgraph.File { path = "frame1.png" })

     

       87
       87
       +
         1

     

       88
       88
       +
       in

     

       89
       89
       +
       print_string (Termext.Termgraph.Animation.render_frame anim_id frame1);;

     

       51
       90
        
       ```

     

       52
       91
        
       

     

       53
       92
        
       ## API Overview

     

       54
       93
        
       

     

       55
       55
       -
       ### Core Types

     

       94
       94
       +
       ### Textsize Module

     

       56
       95
        
       

     

       57
       57
       -
       - `scale` - Text scale factor (1-7)

     

       58
       58
       -
       - `width` - Width in cells (0-7)

     

       59
       59
       -
       - `numerator`/`denominator` - Fractional scaling (0-15)

     

       60
       60
       -
       - `vertical_align` - Vertical alignment (Bottom, Center, Top)

     

       61
       61
       -
       - `horizontal_align` - Horizontal alignment (Left, Center, Right)

     

       62
       62
       -
       - `metadata` - Combined sizing metadata

     

       63
       63
       -
       

     

       64
       64
       -
       ### Convenience Functions

     

       96
       96
       +
       **Types & Builders**

     

       97
       97
       +
       - `vertical`, `horizontal` - Alignment types

     

       98
       98
       +
       - `v ?scale ?width ?fraction ?vertical ?horizontal ()` - Create sizing metadata

     

       99
       99
       +
       - `empty` - Empty metadata

     

       65
       100
        
       

     

       101
       101
       +
       **Convenience Functions**

     

       66
       102
        
       - `double`, `triple`, `quadruple` - Quick size multipliers

     

       67
       103
        
       - `half` - Half-sized text

     

       68
       104
        
       - `superscript`, `subscript` - Typographic positioning

     

       69
       105
        
       - `scaled n` - Arbitrary scale factor

     

       70
       106
        
       

     

       71
       71
       -
       ### Metadata Builders

     

       107
       107
       +
       **Rendering**

     

       108
       108
       +
       - `render metadata text` - Generate escape sequence

     

       109
       109
       +
       - `render_to_channel oc metadata text` - Write to channel

     

       110
       110
       +
       - `pp`, `styled` - Fmt formatters

     

       72
       111
        
       

     

       73
       73
       -
       - `empty` - Start with empty metadata

     

       74
       74
       -
       - `with_scale` - Set scale factor

     

       75
       75
       -
       - `with_width` - Set width

     

       76
       76
       -
       - `with_fraction` - Set fractional scaling

     

       77
       77
       -
       - `with_vertical_align` - Set vertical alignment

     

       78
       78
       -
       - `with_horizontal_align` - Set horizontal alignment

     

       112
       112
       +
       ### Termgraph Module (In Development)

     

       113
       113
       +
       

     

       114
       114
       +
       **Core Types**

     

       115
       115
       +
       - `format` - RGB, RGBA, PNG

     

       116
       116
       +
       - `compression` - No_compression, Zlib

     

       117
       117
       +
       - `transmission` - Direct, File

     

       118
       118
       +
       - `image_id`, `placement_id` - Identifiers

     

       119
       119
       +
       

     

       120
       120
       +
       **Placement**

     

       121
       121
       +
       - `v ?image_id ?x ?y ?width ?height ?rows ?columns ?z_index transmission ()` - Create placement

     

       122
       122
       +
       

     

       123
       123
       +
       **Animation**

     

       124
       124
       +
       - `Animation.frame` - Define animation frames

     

       125
       125
       +
       - `Animation.render_frame` - Upload frames

     

       126
       126
       +
       - `Animation.render_control` - Control playback

     

       127
       127
       +
       

     

       128
       128
       +
       **Deletion**

     

       129
       129
       +
       - `Delete.render` - Delete images by various criteria

     

       79
       130
        
       

     

       80
       80
       -
       ### Rendering

     

       131
       131
       +
       **Convenience**

     

       132
       132
       +
       - `display_png_file` - Quick PNG display

     

       133
       133
       +
       - `display_png_bytes` - Display PNG from bytes

     

       134
       134
       +
       - `pp`, `pp_delete`, `pp_animation_*` - Fmt formatters

     

       81
       135
        
       

     

       82
       82
       -
       - `render metadata text` - Generate escape sequence

     

       83
       83
       -
       - `render_to_channel oc metadata text` - Write to channel

     

       136
       136
       +
       See [TODO.md](TODO.md) for implementation status and roadmap.

     

       84
       137
        
       

     

       85
       138
        
       ## Building from Source

     

       86
       139
        
       

     

       87
       140
        
       ```bash

     

       88
       88
       -
       cd textsize

     

       141
       141
       +
       cd termext

     

       89
       142
        
       dune build

     

       90
       90
       -
       dune exec example/demo.exe  # Run example

     

       143
       143
       +
       dune exec example/demo.exe           # Text sizing demo

     

       144
       144
       +
       dune exec example/graphics_demo.exe  # Graphics demo (requires PNG files)

     

       91
       145
        
       ```

     

       92
       146
        
       

     

       93
       147
        
       ## Terminal Compatibility

     

       94
       148
        
       

     

       95
       95
       -
       This library generates escape sequences for the Kitty text sizing protocol. It requires a terminal emulator that supports this protocol:

     

       149
       149
       +
       This library generates escape sequences for Kitty terminal protocols.

     

       96
       150
        
       

     

       151
       151
       +
       **Text Sizing Protocol:**

     

       97
       152
        
       - ✅ [Kitty](https://sw.kovidgoyal.net/kitty/) (v0.40.0+)

     

       98
       98
       -
       - ✅ [Ghostty](https://ghostty.org/) (with protocol support)

     

       153
       153
       +
       - ✅ [Ghostty](https://ghostty.org/)

     

       154
       154
       +
       

     

       155
       155
       +
       **Graphics Protocol:**

     

       156
       156
       +
       - ✅ [Kitty](https://sw.kovidgoyal.net/kitty/)

     

       157
       157
       +
       - ✅ [Ghostty](https://ghostty.org/)

     

       158
       158
       +
       - ⚠️ [WezTerm](https://wezfurlong.org/wezterm/) (partial support)

     

       159
       159
       +
       - ⚠️ [Konsole](https://konsole.kde.org/) (partial support)

     

       99
       160
        
       

     

       100
       100
       -
       Other terminals will typically ignore these sequences gracefully.

     

       161
       161
       +
       Other terminals will typically ignore these sequences gracefully (no errors, just no special rendering).

     

       101
       162
        
       

     

       102
       163
        
       ## Protocol Reference

     

       103
       164
        
       

     

       104
       104
       -
       The library implements OSC 66 sequences as specified in the [Kitty text sizing protocol documentation](https://sw.kovidgoyal.net/kitty/text-sizing-protocol/).

     

       165
       165
       +
       **Text Sizing:** OSC 66 sequences - `ESC ] 66 ; metadata ; text BEL`

     

       166
       166
       +
       - See: [Kitty Text Sizing Protocol](https://sw.kovidgoyal.net/kitty/text-sizing-protocol/)

     

       167
       167
       +
       

     

       168
       168
       +
       **Graphics:** APC sequences - `ESC _G<control>;<payload>ESC \`

     

       169
       169
       +
       - See: [Kitty Graphics Protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/)

     

       105
       170
        
       

     

       106
       106
       -
       Format: `ESC ] 66 ; metadata ; text BEL`

     

       171
       171
       +
       ## Dependencies

     

       107
       172
        
       

     

       108
       108
       -
       Where metadata is colon-separated key=value pairs.

     

       173
       173
       +
       - **fmt**: Formatting library (already widely used)

     

       174
       174
       +
       - **base64**: Base64 encoding for graphics transmission

     

       175
       175
       +
       - **camlzip**: Zlib compression for graphics (optional optimization)

     

       109
       176
        
       

     

       110
       177
        
       ## License

     

       111
       178

+252

tgp/TODO.md

···

       1
       1
       +
       # TODO - Termext Library Development

     

       2
       2
       +
       

     

       3
       3
       +
       ## Current Status

     

       4
       4
       +
       

     

       5
       5
       +
       ### Completed

     

       6
       6
       +
       - ✅ Text sizing protocol (Textsize module)

     

       7
       7
       +
       - ✅ Graphics protocol interface design (Termgraph module)

     

       8
       8
       +
       - ✅ Library renamed from `textsize` to `termext`

     

       9
       9
       +
       - ✅ Dependencies added (base64, camlzip)

     

       10
       10
       +
       

     

       11
       11
       +
       ### In Progress

     

       12
       12
       +
       - 🚧 Termgraph module implementation

     

       13
       13
       +
       - 🚧 Animation support

     

       14
       14
       +
       - 🚧 Example binaries

     

       15
       15
       +
       

     

       16
       16
       +
       ## Graphics Protocol Implementation Plan

     

       17
       17
       +
       

     

       18
       18
       +
       ### Phase 1: Core Transmission (Current)

     

       19
       19
       +
       

     

       20
       20
       +
       **Direct Transmission**

     

       21
       21
       +
       - [x] Interface design

     

       22
       22
       +
       - [ ] Base64 encoding of image data

     

       23
       23
       +
       - [ ] Chunking for large images (4096 byte chunks)

     

       24
       24
       +
       - [ ] PNG format support (user-provided bytes)

     

       25
       25
       +
       - [ ] RGB/RGBA raw format support

     

       26
       26
       +
       - [ ] Escape sequence generation (APC format)

     

       27
       27
       +
       

     

       28
       28
       +
       **File Transmission**

     

       29
       29
       +
       - [x] Interface design

     

       30
       30
       +
       - [ ] File path validation

     

       31
       31
       +
       - [ ] Escape sequence generation for file paths

     

       32
       32
       +
       - [ ] Handle file transmission medium (t=f)

     

       33
       33
       +
       

     

       34
       34
       +
       **Placement Control**

     

       35
       35
       +
       - [x] Interface design

     

       36
       36
       +
       - [ ] Position control (x, y offsets)

     

       37
       37
       +
       - [ ] Size control (width, height, rows, columns)

     

       38
       38
       +
       - [ ] Z-index support

     

       39
       39
       +
       - [ ] Cursor movement control

     

       40
       40
       +
       - [ ] Image and placement IDs

     

       41
       41
       +
       

     

       42
       42
       +
       **Deletion**

     

       43
       43
       +
       - [x] Interface design

     

       44
       44
       +
       - [ ] Delete by image ID

     

       45
       45
       +
       - [ ] Delete by placement ID

     

       46
       46
       +
       - [ ] Delete at cursor

     

       47
       47
       +
       - [ ] Delete all images

     

       48
       48
       +
       

     

       49
       49
       +
       ### Phase 2: Animation Support

     

       50
       50
       +
       

     

       51
       51
       +
       **Frame Transmission**

     

       52
       52
       +
       - [x] Interface design

     

       53
       53
       +
       - [ ] Frame numbering (1-based)

     

       54
       54
       +
       - [ ] Composition modes (blend, overwrite)

     

       55
       55
       +
       - [ ] Frame gap timing (milliseconds)

     

       56
       56
       +
       - [ ] Multi-frame upload

     

       57
       57
       +
       

     

       58
       58
       +
       **Animation Control**

     

       59
       59
       +
       - [x] Interface design

     

       60
       60
       +
       - [ ] Set gap for specific frames

     

       61
       61
       +
       - [ ] Loop control (count, infinite)

     

       62
       62
       +
       - [ ] Start/stop animation

     

       63
       63
       +
       - [ ] Frame composition control

     

       64
       64
       +
       

     

       65
       65
       +
       ### Phase 3: Advanced Features (Future)

     

       66
       66
       +
       

     

       67
       67
       +
       **Compression**

     

       68
       68
       +
       - [ ] ZLIB compression for image data

     

       69
       69
       +
       - [ ] Automatic compression for large images

     

       70
       70
       +
       - [ ] Compression level control

     

       71
       71
       +
       

     

       72
       72
       +
       **Temporary File Transmission**

     

       73
       73
       +
       - [ ] Temp file creation

     

       74
       74
       +
       - [ ] Escape sequence generation (t=t)

     

       75
       75
       +
       - [ ] Cleanup handling

     

       76
       76
       +
       

     

       77
       77
       +
       **Shared Memory Transmission**

     

       78
       78
       +
       - [ ] Shared memory name generation

     

       79
       79
       +
       - [ ] Escape sequence generation (t=s)

     

       80
       80
       +
       - [ ] Platform-specific support (POSIX shared memory)

     

       81
       81
       +
       

     

       82
       82
       +
       **Virtual Placements**

     

       83
       83
       +
       - [ ] Unicode placeholder support

     

       84
       84
       +
       - [ ] Virtual placement references

     

       85
       85
       +
       - [ ] Diacritic composition

     

       86
       86
       +
       

     

       87
       87
       +
       **Query/Response Handling**

     

       88
       88
       +
       - [ ] Terminal capability detection

     

       89
       89
       +
       - [ ] Success/failure response parsing

     

       90
       90
       +
       - [ ] Error handling

     

       91
       91
       +
       

     

       92
       92
       +
       **Advanced Placement Options**

     

       93
       93
       +
       - [ ] Source rectangle (crop images)

     

       94
       94
       +
       - [ ] Cell offset positioning

     

       95
       95
       +
       - [ ] Relative positioning

     

       96
       96
       +
       - [ ] Background/foreground placement

     

       97
       97
       +
       

     

       98
       98
       +
       **Image Composition**

     

       99
       99
       +
       - [ ] Alpha blending modes

     

       100
       100
       +
       - [ ] Composition operations

     

       101
       101
       +
       - [ ] Multi-layer support

     

       102
       102
       +
       

     

       103
       103
       +
       ### Phase 4: Eio Integration (Future)

     

       104
       104
       +
       

     

       105
       105
       +
       **Async Operations**

     

       106
       106
       +
       - [ ] Eio-based file reading

     

       107
       107
       +
       - [ ] Async chunked transmission

     

       108
       108
       +
       - [ ] Streaming large images

     

       109
       109
       +
       - [ ] Non-blocking operations

     

       110
       110
       +
       

     

       111
       111
       +
       **Buf_read/Buf_write Integration**

     

       112
       112
       +
       - [ ] Use Eio.Buf_read for parsing responses

     

       113
       113
       +
       - [ ] Use Eio.Buf_write for efficient serialization

     

       114
       114
       +
       - [ ] Zero-copy optimizations

     

       115
       115
       +
       

     

       116
       116
       +
       ### Phase 5: Quality & Documentation

     

       117
       117
       +
       

     

       118
       118
       +
       **Testing**

     

       119
       119
       +
       - [ ] Unit tests for escape sequence generation

     

       120
       120
       +
       - [ ] Unit tests for chunking logic

     

       121
       121
       +
       - [ ] Unit tests for base64 encoding

     

       122
       122
       +
       - [ ] Integration tests with mock terminal

     

       123
       123
       +
       - [ ] Animation frame sequencing tests

     

       124
       124
       +
       - [ ] Example binaries for manual testing

     

       125
       125
       +
       

     

       126
       126
       +
       **Documentation**

     

       127
       127
       +
       - [ ] Complete API documentation

     

       128
       128
       +
       - [ ] Usage examples

     

       129
       129
       +
       - [ ] Animation tutorial

     

       130
       130
       +
       - [ ] Performance guidelines

     

       131
       131
       +
       - [ ] Terminal compatibility matrix

     

       132
       132
       +
       

     

       133
       133
       +
       **Examples**

     

       134
       134
       +
       - [ ] Simple image display

     

       135
       135
       +
       - [ ] Animated GIF-style display

     

       136
       136
       +
       - [ ] Image gallery

     

       137
       137
       +
       - [ ] Terminal image viewer

     

       138
       138
       +
       - [ ] Progress indicator with graphics

     

       139
       139
       +
       

     

       140
       140
       +
       ## Design Decisions

     

       141
       141
       +
       

     

       142
       142
       +
       ### Transmission Format

     

       143
       143
       +
       

     

       144
       144
       +
       The Kitty graphics protocol uses APC escape sequences:

     

       145
       145
       +
       ```

     

       146
       146
       +
       ESC _G<control>;<payload>ESC \

     

       147
       147
       +
       ```

     

       148
       148
       +
       

     

       149
       149
       +
       - **Control data**: Comma-separated key=value pairs

     

       150
       150
       +
       - **Payload**: Base64-encoded image data (for direct transmission)

     

       151
       151
       +
       

     

       152
       152
       +
       ### Key Control Parameters

     

       153
       153
       +
       

     

       154
       154
       +
       | Key | Description | Values |

     

       155
       155
       +
       |-----|-------------|--------|

     

       156
       156
       +
       | `a` | Action | `t`=transmit+display, `T`=transmit only, `p`=display, `d`=delete, `f`=frame, `a`=animate |

     

       157
       157
       +
       | `f` | Format | `24`=RGB, `32`=RGBA, `100`=PNG |

     

       158
       158
       +
       | `t` | Transmission | `d`=direct, `f`=file, `t`=temp, `s`=shared |

     

       159
       159
       +
       | `i` | Image ID | Number or string (max 24 chars) |

     

       160
       160
       +
       | `p` | Placement ID | Number |

     

       161
       161
       +
       | `s` | Width | Pixels |

     

       162
       162
       +
       | `v` | Height | Pixels |

     

       163
       163
       +
       | `c` | Columns | Terminal cells |

     

       164
       164
       +
       | `r` | Rows | Terminal cells |

     

       165
       165
       +
       | `x` | X offset | Pixels |

     

       166
       166
       +
       | `y` | Y offset | Pixels |

     

       167
       167
       +
       | `z` | Z-index | Integer |

     

       168
       168
       +
       | `C` | Cursor | `0`=don't move, `1`=move |

     

       169
       169
       +
       | `o` | Compression | `z`=zlib |

     

       170
       170
       +
       | `m` | More chunks | `1`=more coming, `0`=last |

     

       171
       171
       +
       

     

       172
       172
       +
       ### Animation-Specific Parameters

     

       173
       173
       +
       

     

       174
       174
       +
       | Key | Description | Values |

     

       175
       175
       +
       |-----|-------------|--------|

     

       176
       176
       +
       | `z` | Frame number | Integer (1-based) |

     

       177
       177
       +
       | `g` | Gap | Milliseconds (0-65535) |

     

       178
       178
       +
       | `c` | Composition | `0`=blend, `1`=overwrite |

     

       179
       179
       +
       | `v` | Loop | Number (0=infinite) |

     

       180
       180
       +
       | `s` | Animation state | `1`=stop, `2`=run |

     

       181
       181
       +
       

     

       182
       182
       +
       ### Chunking Strategy

     

       183
       183
       +
       

     

       184
       184
       +
       - Maximum chunk size: 4096 bytes (protocol limit)

     

       185
       185
       +
       - For images larger than 4096 bytes when base64-encoded:

     

       186
       186
       +
         1. First chunk: Include full control data, set `m=1`

     

       187
       187
       +
         2. Middle chunks: Only payload data, set `m=1`

     

       188
       188
       +
         3. Last chunk: Only payload data, set `m=0`

     

       189
       189
       +
       

     

       190
       190
       +
       ### Error Handling

     

       191
       191
       +
       

     

       192
       192
       +
       - Validate all parameters before encoding

     

       193
       193
       +
       - Check file existence for file-based transmission

     

       194
       194
       +
       - Ensure image data dimensions match declared width/height

     

       195
       195
       +
       - Validate ID formats (image_id max 24 chars)

     

       196
       196
       +
       - Raise `Invalid_argument` for out-of-range values

     

       197
       197
       +
       

     

       198
       198
       +
       ### Memory Efficiency

     

       199
       199
       +
       

     

       200
       200
       +
       - Use `bytes` for image data (mutable, efficient)

     

       201
       201
       +
       - Stream large files rather than loading into memory

     

       202
       202
       +
       - Base64 encode in chunks to limit memory usage

     

       203
       203
       +
       - Consider compression for large images

     

       204
       204
       +
       

     

       205
       205
       +
       ## Future Enhancements

     

       206
       206
       +
       

     

       207
       207
       +
       ### Additional Protocols

     

       208
       208
       +
       - [ ] Kitty keyboard protocol

     

       209
       209
       +
       - [ ] Kitty clipboard protocol

     

       210
       210
       +
       - [ ] Synchronized output protocol

     

       211
       211
       +
       

     

       212
       212
       +
       ### Utilities

     

       213
       213
       +
       - [ ] Image format detection

     

       214
       214
       +
       - [ ] Automatic format conversion

     

       215
       215
       +
       - [ ] Image resizing/scaling helpers

     

       216
       216
       +
       - [ ] Color quantization

     

       217
       217
       +
       

     

       218
       218
       +
       ### Integration

     

       219
       219
       +
       - [ ] Notty integration

     

       220
       220
       +
       - [ ] Direct terminal detection

     

       221
       221
       +
       - [ ] Fallback for non-Kitty terminals

     

       222
       222
       +
       

     

       223
       223
       +
       ## Notes

     

       224
       224
       +
       

     

       225
       225
       +
       ### Dependencies Rationale

     

       226
       226
       +
       

     

       227
       227
       +
       - **fmt**: Already used in Textsize, provides consistent formatting API

     

       228
       228
       +
       - **base64**: Standard library for base64 encoding/decoding, well-tested

     

       229
       229
       +
       - **camlzip**: ZLIB compression support, mature library

     

       230
       230
       +
       

     

       231
       231
       +
       ### No Image Library Dependencies

     

       232
       232
       +
       

     

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

     

       234
       234
       +
       1. Keeps library lightweight

     

       235
       235
       +
       2. Users may already have image data in memory

     

       236
       236
       +
       3. PNG format can be passed through without decoding

     

       237
       237
       +
       4. Allows flexibility in image source (file, network, generated, etc.)

     

       238
       238
       +
       5. User can choose their preferred image library

     

       239
       239
       +
       

     

       240
       240
       +
       ### Compatibility

     

       241
       241
       +
       

     

       242
       242
       +
       **Terminals with full support:**

     

       243
       243
       +
       - Kitty (v0.40.0+ for text sizing, earlier for graphics)

     

       244
       244
       +
       - Ghostty (with graphics protocol support)

     

       245
       245
       +
       

     

       246
       246
       +
       **Terminals with partial support:**

     

       247
       247
       +
       - WezTerm (graphics protocol)

     

       248
       248
       +
       - Konsole (partial graphics support)

     

       249
       249
       +
       

     

       250
       250
       +
       **Graceful degradation:**

     

       251
       251
       +
       - Other terminals typically ignore unknown escape sequences

     

       252
       252
       +
       - No visible output, but no crashes or errors

+8 -5

tgp/dune-project

···

       1
       1
        
       (lang dune 3.0)

     

       2
       2
       -
       (name textsize)

     

       2
       2
       +
       (name termext)

     

       3
       3
        
       (version 0.1.0)

     

       4
       4
        
       

     

       5
       5
        
       (generate_opam_files true)

     

       6
       6
        
       

     

       7
       7
       -
       (source (github username/textsize))

     

       7
       7
       +
       (source (github username/termext))

     

       8
       8
        
       (license MIT)

     

       9
       9
        
       (authors "Anonymous")

     

       10
       10
        
       (maintainers "Anonymous")

     

       11
       11
        
       

     

       12
       12
        
       (package

     

       13
       13
       -
        (name textsize)

     

       14
       14
       -
        (synopsis "OCaml implementation of the Kitty text sizing protocol")

     

       15
       15
       -
        (description "A clean, standalone library for generating escape sequences to render text in different sizes using the Kitty terminal's text sizing protocol.")

     

       13
       13
       +
        (name termext)

     

       14
       14
       +
        (synopsis "OCaml implementation of Kitty terminal protocols")

     

       15
       15
       +
        (description "A library for generating escape sequences for Kitty terminal protocols including text sizing and graphics display.")

     

       16
       16
        
        (depends

     

       17
       17
        
         (ocaml (>= 4.14))

     

       18
       18
       +
         (fmt (>= 0.9.0))

     

       19
       19
       +
         (base64 (>= 3.5.0))

     

       20
       20
       +
         (camlzip (>= 1.11))

     

       18
       21
        
         dune))

+22 -22

tgp/example/demo.ml

···

       4
       4
        
         print_endline "=== Kitty Text Sizing Protocol Demo ===\n";

     

       5
       5
        
       

     

       6
       6
        
         (* Simple convenience functions *)

     

       7
       7
       -
         print_string (Textsize.double "Double sized text");

     

       7
       7
       +
         print_string (Termext.Textsize.double "Double sized text");

     

       8
       8
        
         print_endline "\n";

     

       9
       9
        
       

     

       10
       10
       -
         print_string (Textsize.triple "Triple sized text");

     

       10
       10
       +
         print_string (Termext.Textsize.triple "Triple sized text");

     

       11
       11
        
         print_endline "\n\n";

     

       12
       12
        
       

     

       13
       13
       -
         print_string (Textsize.quadruple "Quadruple sized text");

     

       13
       13
       +
         print_string (Termext.Textsize.quadruple "Quadruple sized text");

     

       14
       14
        
         print_endline "\n\n\n";

     

       15
       15
        
       

     

       16
       16
        
         (* Scaled text *)

     

       17
       17
       -
         print_string (Textsize.scaled 5 "Scale 5 text");

     

       17
       17
       +
         print_string (Termext.Textsize.scaled 5 "Scale 5 text");

     

       18
       18
        
         print_endline "\n\n\n\n";

     

       19
       19
        
       

     

       20
       20
        
         (* Fractional scaling *)

     

       21
       21
       -
         print_string (Textsize.half "Half sized text");

     

       21
       21
       +
         print_string (Termext.Textsize.half "Half sized text");

     

       22
       22
        
         print_newline ();

     

       23
       23
        
       

     

       24
       24
        
         (* Superscripts and subscripts *)

     

       25
       25
        
         print_string "E=mc";

     

       26
       26
       -
         print_string (Textsize.superscript "2");

     

       26
       26
       +
         print_string (Termext.Textsize.superscript "2");

     

       27
       27
        
         print_newline ();

     

       28
       28
        
       

     

       29
       29
        
         print_string "H";

     

       30
       30
       -
         print_string (Textsize.subscript "2");

     

       30
       30
       +
         print_string (Termext.Textsize.subscript "2");

     

       31
       31
        
         print_string "O";

     

       32
       32
        
         print_newline ();

     

       33
       33
        
       

     

       34
       34
        
         (* Custom metadata *)

     

       35
       35
        
         print_newline ();

     

       36
       36
       -
         let custom = Textsize.v ~scale:3 ~width:5 () in

     

       37
       37
       -
         print_string (Textsize.render custom "Custom sized text");

     

       36
       36
       +
         let custom = Termext.Textsize.v ~scale:3 ~width:5 () in

     

       37
       37
       +
         print_string (Termext.Textsize.render custom "Custom sized text");

     

       38
       38
        
         print_endline "\n\n";

     

       39
       39
        
       

     

       40
       40
        
         (* Fractional with alignment *)

     

       41
       41
       -
         let aligned = Textsize.v ~fraction:(1, 3) ~vertical:`Center ~horizontal:`Center () in

     

       42
       42
       -
         print_string (Textsize.render aligned "Centered 1/3 size text");

     

       41
       41
       +
         let aligned = Termext.Textsize.v ~fraction:(1, 3) ~vertical:`Center ~horizontal:`Center () in

     

       42
       42
       +
         print_string (Termext.Textsize.render aligned "Centered 1/3 size text");

     

       43
       43
        
         print_newline ();

     

       44
       44
        
       

     

       45
       45
        
         (* Fmt-style combinators *)

     

       46
       46
        
         print_endline "\n=== Fmt-style Examples ===\n";

     

       47
       47
        
       

     

       48
       48
        
         (* Basic pp formatter *)

     

       49
       49
       -
         Fmt.pr "This is %a text\n" Textsize.pp_double "double-sized";

     

       50
       50
       -
         Fmt.pr "This is %a text\n" Textsize.pp_triple "triple-sized";

     

       49
       49
       +
         Fmt.pr "This is %a text\n" Termext.Textsize.pp_double "double-sized";

     

       50
       50
       +
         Fmt.pr "This is %a text\n" Termext.Textsize.pp_triple "triple-sized";

     

       51
       51
        
       

     

       52
       52
        
         (* Superscripts and subscripts with Fmt *)

     

       53
       53
       -
         Fmt.pr "E=mc%a\n" Textsize.pp_superscript "2";

     

       54
       54
       -
         Fmt.pr "H%aO\n" Textsize.pp_subscript "2";

     

       53
       53
       +
         Fmt.pr "E=mc%a\n" Termext.Textsize.pp_superscript "2";

     

       54
       54
       +
         Fmt.pr "H%aO\n" Termext.Textsize.pp_subscript "2";

     

       55
       55
        
       

     

       56
       56
        
         (* Styled combinators wrapping other formatters *)

     

       57
       57
       -
         Fmt.pr "The answer is %a\n" (Textsize.styled_double Fmt.int) 42;

     

       58
       58
       -
         Fmt.pr "Pi is approximately %a\n" (Textsize.styled_triple Fmt.float) 3.14159;

     

       57
       57
       +
         Fmt.pr "The answer is %a\n" (Termext.Textsize.styled_double Fmt.int) 42;

     

       58
       58
       +
         Fmt.pr "Pi is approximately %a\n" (Termext.Textsize.styled_triple Fmt.float) 3.14159;

     

       59
       59
        
       

     

       60
       60
        
         (* Complex formatting with Fmt *)

     

       61
       61
        
         Fmt.pr "Temperature: %a°C (that's %a°F)\n"

     

       62
       62
       -
           (Textsize.styled_superscript Fmt.int) 25

     

       63
       63
       -
           (Textsize.styled_subscript Fmt.int) 77;

     

       62
       62
       +
           (Termext.Textsize.styled_superscript Fmt.int) 25

     

       63
       63
       +
           (Termext.Textsize.styled_subscript Fmt.int) 77;

     

       64
       64
        
       

     

       65
       65
        
         (* Custom metadata with Fmt *)

     

       66
       66
       -
         let custom_meta = Textsize.v ~scale:4 () in

     

       67
       67
       -
         Fmt.pr "\n%a\n" (Textsize.pp custom_meta) "Custom Fmt-styled text";

     

       66
       66
       +
         let custom_meta = Termext.Textsize.v ~scale:4 () in

     

       67
       67
       +
         Fmt.pr "\n%a\n" (Termext.Textsize.pp custom_meta) "Custom Fmt-styled text";

     

       68
       68
        
       

     

       69
       69
        
         (* Composing with other Fmt combinators *)

     

       70
       70
        
         Fmt.pr "\nList items: %a\n"

     

       71
       71
       -
           (Fmt.list ~sep:(Fmt.any ", ") (Textsize.styled_double Fmt.string))

     

       71
       71
       +
           (Fmt.list ~sep:(Fmt.any ", ") (Termext.Textsize.styled_double Fmt.string))

     

       72
       72
        
           ["apple"; "banana"; "cherry"];

     

       73
       73
        
       

     

       74
       74
        
         print_endline "\n=== Demo Complete ===";

+7 -1

tgp/example/dune

···

       1
       1
        
       (executable

     

       2
       2
        
        (name demo)

     

       3
       3
       -
        (libraries textsize fmt))

     

       3
       3
       +
        (modules demo)

     

       4
       4
       +
        (libraries termext fmt))

     

       5
       5
       +
       

     

       6
       6
       +
       (executable

     

       7
       7
       +
        (name graphics_demo)

     

       8
       8
       +
        (modules graphics_demo)

     

       9
       9
       +
        (libraries termext fmt unix))

+156

tgp/example/graphics_demo.ml

···

       1
       1
       +
       (* Example demonstrating the Termgraph module of termext library *)

     

       2
       2
       +
       

     

       3
       3
       +
       let () =

     

       4
       4
       +
         print_endline "=== Kitty Graphics Protocol Demo ===\n";

     

       5
       5
       +
       

     

       6
       6
       +
         (* Example 1: Display a PNG file *)

     

       7
       7
       +
         print_endline "--- Example 1: Display PNG file ---";

     

       8
       8
       +
         let png_path = "example.png" in

     

       9
       9
       +
         (* Simple convenience function *)

     

       10
       10
       +
         print_string (Termext.Termgraph.display_png_file png_path);

     

       11
       11
       +
         print_endline "\n";

     

       12
       12
       +
       

     

       13
       13
       +
         (* Example 2: Display PNG file with size control *)

     

       14
       14
       +
         print_endline "--- Example 2: PNG file with sizing ---";

     

       15
       15
       +
         print_string (Termext.Termgraph.display_png_file

     

       16
       16
       +
           ~rows:10

     

       17
       17
       +
           ~columns:20

     

       18
       18
       +
           png_path);

     

       19
       19
       +
         print_endline "\n";

     

       20
       20
       +
       

     

       21
       21
       +
         (* Example 3: Using the full placement API *)

     

       22
       22
       +
         print_endline "--- Example 3: Full placement control ---";

     

       23
       23
       +
         let img_id = Termext.Termgraph.image_id_of_string "demo-image" in

     

       24
       24
       +
         let placement = Termext.Termgraph.v

     

       25
       25
       +
           ~image_id:img_id

     

       26
       26
       +
           ~x:10

     

       27
       27
       +
           ~y:5

     

       28
       28
       +
           ~rows:15

     

       29
       29
       +
           ~columns:30

     

       30
       30
       +
           ~z_index:10

     

       31
       31
       +
           (Termext.Termgraph.File { path = png_path })

     

       32
       32
       +
           ()

     

       33
       33
       +
         in

     

       34
       34
       +
         print_string (Termext.Termgraph.render placement);

     

       35
       35
       +
         print_endline "\n";

     

       36
       36
       +
       

     

       37
       37
       +
         (* Example 4: Direct transmission with raw PNG data *)

     

       38
       38
       +
         print_endline "--- Example 4: Direct transmission ---";

     

       39
       39
       +
         (* In a real use case, you would load PNG data from somewhere *)

     

       40
       40
       +
         let png_data = Bytes.of_string "\x89PNG\r\n\x1a\n..." in

     

       41
       41
       +
         print_string (Termext.Termgraph.display_png_bytes

     

       42
       42
       +
           ~w:100

     

       43
       43
       +
           ~h:100

     

       44
       44
       +
           ~rows:10

     

       45
       45
       +
           ~columns:10

     

       46
       46
       +
           png_data);

     

       47
       47
       +
         print_endline "\n";

     

       48
       48
       +
       

     

       49
       49
       +
         (* Example 5: Fmt-style formatters *)

     

       50
       50
       +
         print_endline "--- Example 5: Fmt formatters ---";

     

       51
       51
       +
         let img = Termext.Termgraph.v

     

       52
       52
       +
           (Termext.Termgraph.File { path = "logo.png" })

     

       53
       53
       +
           ()

     

       54
       54
       +
         in

     

       55
       55
       +
         Fmt.pr "Here's our logo: %a\n" (Termext.Termgraph.pp img) ();

     

       56
       56
       +
         print_endline "";

     

       57
       57
       +
       

     

       58
       58
       +
         (* Example 6: Animation *)

     

       59
       59
       +
         print_endline "--- Example 6: Animation frames ---";

     

       60
       60
       +
         let anim_id = Termext.Termgraph.image_id_of_string "animation" in

     

       61
       61
       +
       

     

       62
       62
       +
         (* Upload frame 1 *)

     

       63
       63
       +
         let frame1 = Termext.Termgraph.Animation.frame

     

       64
       64
       +
           ~gap:100  (* 100ms gap *)

     

       65
       65
       +
           (Termext.Termgraph.File { path = "frame1.png" })

     

       66
       66
       +
           1  (* Frame number *)

     

       67
       67
       +
         in

     

       68
       68
       +
         print_string (Termext.Termgraph.Animation.render_frame anim_id frame1);

     

       69
       69
       +
       

     

       70
       70
       +
         (* Upload frame 2 *)

     

       71
       71
       +
         let frame2 = Termext.Termgraph.Animation.frame

     

       72
       72
       +
           ~gap:100

     

       73
       73
       +
           ~composition:Termext.Termgraph.Animation.Blend

     

       74
       74
       +
           (Termext.Termgraph.File { path = "frame2.png" })

     

       75
       75
       +
           2

     

       76
       76
       +
         in

     

       77
       77
       +
         print_string (Termext.Termgraph.Animation.render_frame anim_id frame2);

     

       78
       78
       +
       

     

       79
       79
       +
         (* Upload frame 3 *)

     

       80
       80
       +
         let frame3 = Termext.Termgraph.Animation.frame

     

       81
       81
       +
           ~gap:100

     

       82
       82
       +
           (Termext.Termgraph.File { path = "frame3.png" })

     

       83
       83
       +
           3

     

       84
       84
       +
         in

     

       85
       85
       +
         print_string (Termext.Termgraph.Animation.render_frame anim_id frame3);

     

       86
       86
       +
       

     

       87
       87
       +
         (* Set animation to loop infinitely *)

     

       88
       88
       +
         let loop_control = Termext.Termgraph.Animation.Set_loop 0 in

     

       89
       89
       +
         print_string (Termext.Termgraph.Animation.render_control anim_id loop_control);

     

       90
       90
       +
         print_endline "\n";

     

       91
       91
       +
       

     

       92
       92
       +
         (* Example 7: Using Fmt for animation *)

     

       93
       93
       +
         print_endline "--- Example 7: Animation with Fmt ---";

     

       94
       94
       +
         Fmt.pr "Frame 1: %a\n"

     

       95
       95
       +
           (Termext.Termgraph.pp_animation_frame anim_id frame1) ();

     

       96
       96
       +
         Fmt.pr "Setting loop: %a\n"

     

       97
       97
       +
           (Termext.Termgraph.pp_animation_control anim_id (Termext.Termgraph.Animation.Set_loop 3)) ();

     

       98
       98
       +
         print_endline "";

     

       99
       99
       +
       

     

       100
       100
       +
         (* Example 8: Deletion *)

     

       101
       101
       +
         print_endline "--- Example 8: Deleting images ---";

     

       102
       102
       +
         Unix.sleep 2;  (* Show images for 2 seconds *)

     

       103
       103
       +
       

     

       104
       104
       +
         (* Delete specific image *)

     

       105
       105
       +
         print_string (Termext.Termgraph.delete_by_id img_id);

     

       106
       106
       +
       

     

       107
       107
       +
         (* Or delete all images *)

     

       108
       108
       +
         print_string (Termext.Termgraph.delete_all ());

     

       109
       109
       +
         print_endline "";

     

       110
       110
       +
       

     

       111
       111
       +
         (* Example 9: Complex scene with z-index *)

     

       112
       112
       +
         print_endline "--- Example 9: Layered images ---";

     

       113
       113
       +
         (* Background layer *)

     

       114
       114
       +
         let bg = Termext.Termgraph.v

     

       115
       115
       +
           ~image_id:(Termext.Termgraph.image_id_of_string "background")

     

       116
       116
       +
           ~z_index:(-10)

     

       117
       117
       +
           ~rows:20

     

       118
       118
       +
           ~columns:40

     

       119
       119
       +
           (Termext.Termgraph.File { path = "background.png" })

     

       120
       120
       +
           ()

     

       121
       121
       +
         in

     

       122
       122
       +
         print_string (Termext.Termgraph.render bg);

     

       123
       123
       +
       

     

       124
       124
       +
         (* Foreground layer *)

     

       125
       125
       +
         let fg = Termext.Termgraph.v

     

       126
       126
       +
           ~image_id:(Termext.Termgraph.image_id_of_string "foreground")

     

       127
       127
       +
           ~z_index:10

     

       128
       128
       +
           ~x:50

     

       129
       129
       +
           ~y:50

     

       130
       130
       +
           ~rows:10

     

       131
       131
       +
           ~columns:20

     

       132
       132
       +
           (Termext.Termgraph.File { path = "sprite.png" })

     

       133
       133
       +
           ()

     

       134
       134
       +
         in

     

       135
       135
       +
         print_string (Termext.Termgraph.render fg);

     

       136
       136
       +
         print_endline "\n";

     

       137
       137
       +
       

     

       138
       138
       +
         (* Example 10: Combining text sizing and graphics *)

     

       139
       139
       +
         print_endline "--- Example 10: Mixed text and graphics ---";

     

       140
       140
       +
         print_string (Termext.Textsize.double "Large Title");

     

       141
       141
       +
         print_endline "\n";

     

       142
       142
       +
       

     

       143
       143
       +
         let small_img = Termext.Termgraph.v

     

       144
       144
       +
           ~rows:5

     

       145
       145
       +
           ~columns:10

     

       146
       146
       +
           (Termext.Termgraph.File { path = "icon.png" })

     

       147
       147
       +
           ()

     

       148
       148
       +
         in

     

       149
       149
       +
         Fmt.pr "Icon: %a Description text here\n"

     

       150
       150
       +
           (Termext.Termgraph.pp small_img) ();

     

       151
       151
       +
       

     

       152
       152
       +
         print_string (Termext.Textsize.subscript "footnote");

     

       153
       153
       +
         print_endline "\n";

     

       154
       154
       +
       

     

       155
       155
       +
         print_endline "=== Demo Complete ===";

     

       156
       156
       +
         print_endline "Note: This demo requires PNG files and a Kitty-compatible terminal.";

+4 -3

tgp/src/dune

···

       1
       1
        
       (library

     

       2
       2
       -
        (name textsize)

     

       3
       3
       -
        (public_name textsize)

     

       4
       4
       -
        (libraries fmt))

     

       2
       2
       +
        (name termext)

     

       3
       3
       +
        (public_name termext)

     

       4
       4
       +
        (libraries fmt base64 zip)

     

       5
       5
       +
        (modules_without_implementation termgraph))

+229

tgp/src/termgraph.mli

···

       1
       1
       +
       (** OCaml implementation of the Kitty graphics protocol.

     

       2
       2
       +
       

     

       3
       3
       +
           This library provides a clean API for generating escape sequences to display

     

       4
       4
       +
           images and animations in terminals that support the Kitty graphics protocol.

     

       5
       5
       +
       

     

       6
       6
       +
           The protocol uses APC (Application Program Command) escape sequences to transmit

     

       7
       7
       +
           and display images with extensive control over placement, sizing, and composition.

     

       8
       8
       +
       

     

       9
       9
       +
           See {{: https://sw.kovidgoyal.net/kitty/graphics-protocol/} Kitty Graphics Protocol}

     

       10
       10
       +
           for the complete specification.

     

       11
       11
       +
       *)

     

       12
       12
       +
       

     

       13
       13
       +
       (** {1 Core Types} *)

     

       14
       14
       +
       

     

       15
       15
       +
       (** Image format for raw pixel data. *)

     

       16
       16
       +
       type format =

     

       17
       17
       +
         | RGB    (** 24-bit RGB (3 bytes per pixel) *)

     

       18
       18
       +
         | RGBA   (** 32-bit RGBA (4 bytes per pixel) *)

     

       19
       19
       +
         | PNG    (** PNG format *)

     

       20
       20
       +
       

     

       21
       21
       +
       (** Compression method for image data. *)

     

       22
       22
       +
       type compression =

     

       23
       23
       +
         | No_compression

     

       24
       24
       +
         | Zlib

     

       25
       25
       +
       

     

       26
       26
       +
       (** Transmission medium. *)

     

       27
       27
       +
       type transmission =

     

       28
       28
       +
         | Direct of {

     

       29
       29
       +
             format : format;

     

       30
       30
       +
             data : bytes;

     

       31
       31
       +
             width : int;  (** Width in pixels *)

     

       32
       32
       +
             height : int; (** Height in pixels *)

     

       33
       33
       +
             compression : compression;

     

       34
       34
       +
           }

     

       35
       35
       +
         | File of {

     

       36
       36
       +
             path : string;

     

       37
       37
       +
           }

     

       38
       38
       +
       

     

       39
       39
       +
       (** Image identifier (number or string up to 24 chars). *)

     

       40
       40
       +
       type image_id = private string

     

       41
       41
       +
       

     

       42
       42
       +
       (** Placement identifier. *)

     

       43
       43
       +
       type placement_id = private int

     

       44
       44
       +
       

     

       45
       45
       +
       (** {1 Image Identifiers} *)

     

       46
       46
       +
       

     

       47
       47
       +
       (** [image_id_of_int n] creates an image ID from an integer.

     

       48
       48
       +
           @raise Invalid_argument if [n] is negative *)

     

       49
       49
       +
       val image_id_of_int : int -> image_id

     

       50
       50
       +
       

     

       51
       51
       +
       (** [image_id_of_string s] creates an image ID from a string.

     

       52
       52
       +
           @raise Invalid_argument if [s] is empty or longer than 24 characters *)

     

       53
       53
       +
       val image_id_of_string : string -> image_id

     

       54
       54
       +
       

     

       55
       55
       +
       (** [placement_id_of_int n] creates a placement ID from an integer.

     

       56
       56
       +
           @raise Invalid_argument if [n] is negative *)

     

       57
       57
       +
       val placement_id_of_int : int -> placement_id

     

       58
       58
       +
       

     

       59
       59
       +
       (** {1 Placement Configuration} *)

     

       60
       60
       +
       

     

       61
       61
       +
       (** Placement configuration for displaying images. *)

     

       62
       62
       +
       type placement

     

       63
       63
       +
       

     

       64
       64
       +
       (** [v ?image_id ?placement_id ?x ?y ?width ?height ?rows ?columns ?z_index

     

       65
       65
       +
           ?cursor_movement transmission ()] creates a placement configuration.

     

       66
       66
       +
       

     

       67
       67
       +
           @param image_id Image identifier for reuse/deletion

     

       68
       68
       +
           @param placement_id Placement identifier for this specific display

     

       69
       69
       +
           @param x Left edge offset in pixels

     

       70
       70
       +
           @param y Top edge offset in pixels

     

       71
       71
       +
           @param width Width in pixels (scales image if different from source)

     

       72
       72
       +
           @param height Height in pixels (scales image if different from source)

     

       73
       73
       +
           @param rows Height in terminal cells

     

       74
       74
       +
           @param columns Width in terminal cells

     

       75
       75
       +
           @param z_index Z-order for layering (-2^31 to 2^31-1, default 0)

     

       76
       76
       +
           @param cursor_movement If false, cursor doesn't move after display (default true)

     

       77
       77
       +
           @param transmission The image data transmission method *)

     

       78
       78
       +
       val v :

     

       79
       79
       +
         ?image_id:image_id ->

     

       80
       80
       +
         ?placement_id:placement_id ->

     

       81
       81
       +
         ?x:int ->

     

       82
       82
       +
         ?y:int ->

     

       83
       83
       +
         ?width:int ->

     

       84
       84
       +
         ?height:int ->

     

       85
       85
       +
         ?rows:int ->

     

       86
       86
       +
         ?columns:int ->

     

       87
       87
       +
         ?z_index:int ->

     

       88
       88
       +
         ?cursor_movement:bool ->

     

       89
       89
       +
         transmission ->

     

       90
       90
       +
         unit ->

     

       91
       91
       +
         placement

     

       92
       92
       +
       

     

       93
       93
       +
       (** {1 Rendering} *)

     

       94
       94
       +
       

     

       95
       95
       +
       (** [render placement] generates the complete escape sequence(s) for the placement.

     

       96
       96
       +
           For large images that require chunking, this returns a single string with all chunks. *)

     

       97
       97
       +
       val render : placement -> string

     

       98
       98
       +
       

     

       99
       99
       +
       (** [render_chunked placement] generates escape sequences as a list of chunks.

     

       100
       100
       +
           Useful for streaming large images or interleaving with other output. *)

     

       101
       101
       +
       val render_chunked : placement -> string list

     

       102
       102
       +
       

     

       103
       103
       +
       (** {1 Deletion} *)

     

       104
       104
       +
       

     

       105
       105
       +
       (** Delete images or placements. *)

     

       106
       106
       +
       module Delete : sig

     

       107
       107
       +
         (** Deletion target. *)

     

       108
       108
       +
         type target =

     

       109
       109
       +
           | By_id of image_id

     

       110
       110
       +
           | By_image_id of image_id

     

       111
       111
       +
           | By_placement_id of placement_id

     

       112
       112
       +
           | At_cursor

     

       113
       113
       +
           | All

     

       114
       114
       +
       

     

       115
       115
       +
         (** [render target] generates the escape sequence to delete images. *)

     

       116
       116
       +
         val render : target -> string

     

       117
       117
       +
       end

     

       118
       118
       +
       

     

       119
       119
       +
       (** {1 Animation} *)

     

       120
       120
       +
       

     

       121
       121
       +
       (** Animation support for multi-frame images. *)

     

       122
       122
       +
       module Animation : sig

     

       123
       123
       +
         (** Frame composition mode. *)

     

       124
       124
       +
         type composition =

     

       125
       125
       +
           | Blend      (** Alpha blend with previous frame *)

     

       126
       126
       +
           | Overwrite  (** Replace previous frame *)

     

       127
       127
       +
       

     

       128
       128
       +
         (** Animation frame configuration. *)

     

       129
       129
       +
         type frame

     

       130
       130
       +
       

     

       131
       131
       +
         (** [frame ?composition ?gap transmission frame_number] creates a frame configuration.

     

       132
       132
       +
       

     

       133
       133
       +
             @param composition How to compose this frame with previous frames

     

       134
       134
       +
             @param gap Gap before next frame in milliseconds (0-65535)

     

       135
       135
       +
             @param transmission The frame image data

     

       136
       136
       +
             @param frame_number Frame index (1-based) *)

     

       137
       137
       +
         val frame :

     

       138
       138
       +
           ?composition:composition ->

     

       139
       139
       +
           ?gap:int ->

     

       140
       140
       +
           transmission ->

     

       141
       141
       +
           int ->

     

       142
       142
       +
           frame

     

       143
       143
       +
       

     

       144
       144
       +
         (** Animation control. *)

     

       145
       145
       +
         type control =

     

       146
       146
       +
           | Set_gap of {

     

       147
       147
       +
               frame_number : int;  (** Which frame to modify *)

     

       148
       148
       +
               gap : int;           (** New gap in milliseconds *)

     

       149
       149
       +
             }

     

       150
       150
       +
           | Set_loop of int        (** Number of loops (0 = infinite) *)

     

       151
       151
       +
           | Stop                   (** Stop animation *)

     

       152
       152
       +
           | Run                    (** Resume animation *)

     

       153
       153
       +
       

     

       154
       154
       +
         (** [render_frame image_id frame] generates escape sequence for transmitting an animation frame.

     

       155
       155
       +
       

     

       156
       156
       +
             @param image_id The animation's image identifier *)

     

       157
       157
       +
         val render_frame : image_id -> frame -> string

     

       158
       158
       +
       

     

       159
       159
       +
         (** [render_control image_id control] generates escape sequence for animation control. *)

     

       160
       160
       +
         val render_control : image_id -> control -> string

     

       161
       161
       +
       end

     

       162
       162
       +
       

     

       163
       163
       +
       (** {1 Fmt-style Formatters} *)

     

       164
       164
       +
       

     

       165
       165
       +
       (** [pp placement] creates a Fmt formatter that displays an image.

     

       166
       166
       +
       

     

       167
       167
       +
           Example:

     

       168
       168
       +
           {[

     

       169
       169
       +
             let img = Graphics.v (Graphics.File { path = "image.png" }) () in

     

       170
       170
       +
             Fmt.pr "Here's an image: %a" Graphics.pp img

     

       171
       171
       +
           ]}

     

       172
       172
       +
       *)

     

       173
       173
       +
       val pp : placement -> unit Fmt.t

     

       174
       174
       +
       

     

       175
       175
       +
       (** [pp_delete target] creates a Fmt formatter that deletes images.

     

       176
       176
       +
       

     

       177
       177
       +
           Example:

     

       178
       178
       +
           {[

     

       179
       179
       +
             Fmt.pr "Clearing screen: %a" Graphics.pp_delete Graphics.Delete.All

     

       180
       180
       +
           ]}

     

       181
       181
       +
       *)

     

       182
       182
       +
       val pp_delete : Delete.target -> unit Fmt.t

     

       183
       183
       +
       

     

       184
       184
       +
       (** [pp_animation_frame image_id frame] creates a Fmt formatter for animation frames. *)

     

       185
       185
       +
       val pp_animation_frame : image_id -> Animation.frame -> unit Fmt.t

     

       186
       186
       +
       

     

       187
       187
       +
       (** [pp_animation_control image_id control] creates a Fmt formatter for animation control. *)

     

       188
       188
       +
       val pp_animation_control : image_id -> Animation.control -> unit Fmt.t

     

       189
       189
       +
       

     

       190
       190
       +
       (** {1 Convenience Functions} *)

     

       191
       191
       +
       

     

       192
       192
       +
       (** [display_png_file ?x ?y ?width ?height ?rows ?columns path] displays a PNG file.

     

       193
       193
       +
       

     

       194
       194
       +
           @param path Path to PNG file

     

       195
       195
       +
           @return Escape sequence string *)

     

       196
       196
       +
       val display_png_file :

     

       197
       197
       +
         ?x:int ->

     

       198
       198
       +
         ?y:int ->

     

       199
       199
       +
         ?width:int ->

     

       200
       200
       +
         ?height:int ->

     

       201
       201
       +
         ?rows:int ->

     

       202
       202
       +
         ?columns:int ->

     

       203
       203
       +
         string ->

     

       204
       204
       +
         string

     

       205
       205
       +
       

     

       206
       206
       +
       (** [display_png_bytes ?x ?y ?width ?height ?rows ?columns ~width:w ~height:h data]

     

       207
       207
       +
           displays PNG data from bytes.

     

       208
       208
       +
       

     

       209
       209
       +
           @param width Image width in pixels

     

       210
       210
       +
           @param height Image height in pixels

     

       211
       211
       +
           @param data PNG-encoded image data

     

       212
       212
       +
           @return Escape sequence string *)

     

       213
       213
       +
       val display_png_bytes :

     

       214
       214
       +
         ?x:int ->

     

       215
       215
       +
         ?y:int ->

     

       216
       216
       +
         ?width:int ->

     

       217
       217
       +
         ?height:int ->

     

       218
       218
       +
         ?rows:int ->

     

       219
       219
       +
         ?columns:int ->

     

       220
       220
       +
         w:int ->

     

       221
       221
       +
         h:int ->

     

       222
       222
       +
         bytes ->

     

       223
       223
       +
         string

     

       224
       224
       +
       

     

       225
       225
       +
       (** [delete_all ()] generates escape sequence to delete all images. *)

     

       226
       226
       +
       val delete_all : unit -> string

     

       227
       227
       +
       

     

       228
       228
       +
       (** [delete_by_id id] generates escape sequence to delete image by ID. *)

     

       229
       229
       +
       val delete_by_id : image_id -> string

+34

tgp/termext.opam

···

       1
       1
       +
       # This file is generated by dune, edit dune-project instead

     

       2
       2
       +
       opam-version: "2.0"

     

       3
       3
       +
       version: "0.1.0"

     

       4
       4
       +
       synopsis: "OCaml implementation of Kitty terminal protocols"

     

       5
       5
       +
       description:

     

       6
       6
       +
         "A library for generating escape sequences for Kitty terminal protocols including text sizing and graphics display."

     

       7
       7
       +
       maintainer: ["Anonymous"]

     

       8
       8
       +
       authors: ["Anonymous"]

     

       9
       9
       +
       license: "MIT"

     

       10
       10
       +
       homepage: "https://github.com/username/termext"

     

       11
       11
       +
       bug-reports: "https://github.com/username/termext/issues"

     

       12
       12
       +
       depends: [

     

       13
       13
       +
         "ocaml" {>= "4.14"}

     

       14
       14
       +
         "fmt" {>= "0.9.0"}

     

       15
       15
       +
         "base64" {>= "3.5.0"}

     

       16
       16
       +
         "camlzip" {>= "1.11"}

     

       17
       17
       +
         "dune" {>= "3.0"}

     

       18
       18
       +
         "odoc" {with-doc}

     

       19
       19
       +
       ]

     

       20
       20
       +
       build: [

     

       21
       21
       +
         ["dune" "subst"] {dev}

     

       22
       22
       +
         [

     

       23
       23
       +
           "dune"

     

       24
       24
       +
           "build"

     

       25
       25
       +
           "-p"

     

       26
       26
       +
           name

     

       27
       27
       +
           "-j"

     

       28
       28
       +
           jobs

     

       29
       29
       +
           "@install"

     

       30
       30
       +
           "@runtest" {with-test}

     

       31
       31
       +
           "@doc" {with-doc}

     

       32
       32
       +
         ]

     

       33
       33
       +
       ]

     

       34
       34
       +
       dev-repo: "git+https://github.com/username/termext.git"

+1 -1

tgp/test/dune

···

       1
       1
        
       (test

     

       2
       2
        
        (name test_textsize)

     

       3
       3
       -
        (libraries textsize))

     

       3
       3
       +
        (libraries termext))

+17 -17

tgp/test/test_textsize.ml

···

       13
       13
        
       

     

       14
       14
        
         (* Test scale validation *)

     

       15
       15
        
         test "scale validation - valid range" (fun () ->

     

       16
       16
       -
           let _ = Textsize.v ~scale:1 () in

     

       17
       17
       -
           let _ = Textsize.v ~scale:7 () in

     

       16
       16
       +
           let _ = Termext.Textsize.v ~scale:1 () in

     

       17
       17
       +
           let _ = Termext.Textsize.v ~scale:7 () in

     

       18
       18
        
           ()

     

       19
       19
        
         );

     

       20
       20
        
       

     

       21
       21
        
         test "scale validation - rejects invalid" (fun () ->

     

       22
       22
        
           try

     

       23
       23
       -
             let _ = Textsize.v ~scale:0 () in

     

       23
       23
       +
             let _ = Termext.Textsize.v ~scale:0 () in

     

       24
       24
        
             failwith "Should have raised Invalid_argument"

     

       25
       25
        
           with Invalid_argument _ -> ()

     

       26
       26
        
         );

     

       27
       27
        
       

     

       28
       28
        
         (* Test width validation *)

     

       29
       29
        
         test "width validation - valid range" (fun () ->

     

       30
       30
       -
           let _ = Textsize.v ~width:0 () in

     

       31
       31
       -
           let _ = Textsize.v ~width:7 () in

     

       30
       30
       +
           let _ = Termext.Textsize.v ~width:0 () in

     

       31
       31
       +
           let _ = Termext.Textsize.v ~width:7 () in

     

       32
       32
        
           ()

     

       33
       33
        
         );

     

       34
       34
        
       

     

       35
       35
        
         (* Test escape sequence generation *)

     

       36
       36
        
         test "double escape sequence" (fun () ->

     

       37
       37
       -
           let result = Textsize.double "test" in

     

       37
       37
       +
           let result = Termext.Textsize.double "test" in

     

       38
       38
        
           assert (String.length result > 0);

     

       39
       39
        
           assert (result = "\x1b]66;s=2;test\x07")

     

       40
       40
        
         );

     

       41
       41
        
       

     

       42
       42
        
         test "triple escape sequence" (fun () ->

     

       43
       43
       -
           let result = Textsize.triple "hello" in

     

       43
       43
       +
           let result = Termext.Textsize.triple "hello" in

     

       44
       44
        
           assert (result = "\x1b]66;s=3;hello\x07")

     

       45
       45
        
         );

     

       46
       46
        
       

     

       47
       47
        
         test "half escape sequence" (fun () ->

     

       48
       48
       -
           let result = Textsize.half "tiny" in

     

       48
       48
       +
           let result = Termext.Textsize.half "tiny" in

     

       49
       49
        
           assert (result = "\x1b]66;n=1:d=2;tiny\x07")

     

       50
       50
        
         );

     

       51
       51
        
       

     

       52
       52
        
         test "superscript escape sequence" (fun () ->

     

       53
       53
       -
           let result = Textsize.superscript "2" in

     

       53
       53
       +
           let result = Termext.Textsize.superscript "2" in

     

       54
       54
        
           assert (result = "\x1b]66;n=1:d=2:v=2;2\x07")

     

       55
       55
        
         );

     

       56
       56
        
       

     

       57
       57
        
         test "subscript escape sequence" (fun () ->

     

       58
       58
       -
           let result = Textsize.subscript "2" in

     

       58
       58
       +
           let result = Termext.Textsize.subscript "2" in

     

       59
       59
        
           assert (result = "\x1b]66;n=1:d=2:v=0;2\x07")

     

       60
       60
        
         );

     

       61
       61
        
       

     

       62
       62
        
         (* Test custom metadata *)

     

       63
       63
        
         test "custom metadata - scale and width" (fun () ->

     

       64
       64
       -
           let metadata = Textsize.v ~scale:3 ~width:5 () in

     

       65
       65
       -
           let result = Textsize.render metadata "custom" in

     

       64
       64
       +
           let metadata = Termext.Textsize.v ~scale:3 ~width:5 () in

     

       65
       65
       +
           let result = Termext.Textsize.render metadata "custom" in

     

       66
       66
        
           assert (result = "\x1b]66;s=3:w=5;custom\x07")

     

       67
       67
        
         );

     

       68
       68
        
       

     

       69
       69
        
         test "custom metadata - fractional" (fun () ->

     

       70
       70
       -
           let metadata = Textsize.v ~fraction:(2, 3) () in

     

       71
       71
       -
           let result = Textsize.render metadata "frac" in

     

       70
       70
       +
           let metadata = Termext.Textsize.v ~fraction:(2, 3) () in

     

       71
       71
       +
           let result = Termext.Textsize.render metadata "frac" in

     

       72
       72
        
           assert (result = "\x1b]66;n=2:d=3;frac\x07")

     

       73
       73
        
         );

     

       74
       74
        
       

     

       75
       75
        
         test "empty metadata" (fun () ->

     

       76
       76
       -
           let result = Textsize.render (Textsize.v ()) "plain" in

     

       76
       76
       +
           let result = Termext.Textsize.render (Termext.Textsize.v ()) "plain" in

     

       77
       77
        
           assert (result = "\x1b]66;;plain\x07")

     

       78
       78
        
         );

     

       79
       79
        
       

     

       80
       80
        
         (* Test text length validation *)

     

       81
       81
        
         test "text length validation - accepts valid" (fun () ->

     

       82
       82
        
           let text = String.make 4096 'a' in

     

       83
       83
       -
           let _ = Textsize.double text in

     

       83
       83
       +
           let _ = Termext.Textsize.double text in

     

       84
       84
        
           ()

     

       85
       85
        
         );

     

       86
       86
        
       

     

       87
       87
        
         test "text length validation - rejects oversized" (fun () ->

     

       88
       88
        
           let text = String.make 4097 'a' in

     

       89
       89
        
           try

     

       90
       90
       -
             let _ = Textsize.double text in

     

       90
       90
       +
             let _ = Termext.Textsize.double text in

     

       91
       91
        
             failwith "Should have raised Invalid_argument"

     

       92
       92
        
           with Invalid_argument _ -> ()

     

       93
       93
        
         );

-31

tgp/textsize.opam

···

       1
       1
       -
       # This file is generated by dune, edit dune-project instead

     

       2
       2
       -
       opam-version: "2.0"

     

       3
       3
       -
       version: "0.1.0"

     

       4
       4
       -
       synopsis: "OCaml implementation of the Kitty text sizing protocol"

     

       5
       5
       -
       description:

     

       6
       6
       -
         "A clean, standalone library for generating escape sequences to render text in different sizes using the Kitty terminal's text sizing protocol."

     

       7
       7
       -
       maintainer: ["Anonymous"]

     

       8
       8
       -
       authors: ["Anonymous"]

     

       9
       9
       -
       license: "MIT"

     

       10
       10
       -
       homepage: "https://github.com/username/textsize"

     

       11
       11
       -
       bug-reports: "https://github.com/username/textsize/issues"

     

       12
       12
       -
       depends: [

     

       13
       13
       -
         "ocaml" {>= "4.14"}

     

       14
       14
       -
         "dune" {>= "3.0"}

     

       15
       15
       -
         "odoc" {with-doc}

     

       16
       16
       -
       ]

     

       17
       17
       -
       build: [

     

       18
       18
       -
         ["dune" "subst"] {dev}

     

       19
       19
       -
         [

     

       20
       20
       -
           "dune"

     

       21
       21
       -
           "build"

     

       22
       22
       -
           "-p"

     

       23
       23
       -
           name

     

       24
       24
       -
           "-j"

     

       25
       25
       -
           jobs

     

       26
       26
       -
           "@install"

     

       27
       27
       -
           "@runtest" {with-test}

     

       28
       28
       -
           "@doc" {with-doc}

     

       29
       29
       -
         ]

     

       30
       30
       -
       ]

     

       31
       31
       -
       dev-repo: "git+https://github.com/username/textsize.git"