comparing 553b68934bdd81558bd96b9784e960fd9964a627 and main on anil.recoil.org/ocaml-kgp

.ocamlformat

···

       1
       1
       +
       version=0.28.1

+49

.tangled/workflows/build.yml

···

       1
       1
       +
       when:

     

       2
       2
       +
         - event: ["push", "pull_request"]

     

       3
       3
       +
           branch: ["main"]

     

       4
       4
       +
       

     

       5
       5
       +
       engine: nixery

     

       6
       6
       +
       

     

       7
       7
       +
       dependencies:

     

       8
       8
       +
         nixpkgs:

     

       9
       9
       +
           - shell

     

       10
       10
       +
           - stdenv

     

       11
       11
       +
           - findutils

     

       12
       12
       +
           - binutils

     

       13
       13
       +
           - libunwind

     

       14
       14
       +
           - ncurses

     

       15
       15
       +
           - opam

     

       16
       16
       +
           - git

     

       17
       17
       +
           - gawk

     

       18
       18
       +
           - gnupatch

     

       19
       19
       +
           - gnum4

     

       20
       20
       +
           - gnumake

     

       21
       21
       +
           - gnutar

     

       22
       22
       +
           - gnused

     

       23
       23
       +
           - gnugrep

     

       24
       24
       +
           - diffutils

     

       25
       25
       +
           - gzip

     

       26
       26
       +
           - bzip2

     

       27
       27
       +
           - gcc

     

       28
       28
       +
           - ocaml

     

       29
       29
       +
       

     

       30
       30
       +
       steps:

     

       31
       31
       +
         - name: opam

     

       32
       32
       +
           command: |

     

       33
       33
       +
              opam init --disable-sandboxing -any

     

       34
       34
       +
         - name: switch

     

       35
       35
       +
           command: |

     

       36
       36
       +
              opam install . --confirm-level=unsafe-yes --deps-only

     

       37
       37
       +
         - name: build

     

       38
       38
       +
           command: |

     

       39
       39
       +
              opam exec -- dune build

     

       40
       40
       +
         - name: switch-test

     

       41
       41
       +
           command: |

     

       42
       42
       +
              opam install . --confirm-level=unsafe-yes --deps-only --with-test

     

       43
       43
       +
         - name: test

     

       44
       44
       +
           command: |

     

       45
       45
       +
              opam exec -- dune runtest --verbose

     

       46
       46
       +
         - name: doc

     

       47
       47
       +
           command: |

     

       48
       48
       +
              opam install -y odoc

     

       49
       49
       +
              opam exec -- dune build @doc

CHANGES.md

···

       1
       1
       +
       v1.0.0 (dev)

     

       2
       2
       +
       ------------

     

       3
       3
       +
       

     

       4
       4
       +
       - Initial public release (@avsm)

+18

LICENSE.md

···

       1
       1
       +
       (*

     

       2
       2
       +
        * ISC License

     

       3
       3
       +
        * 

     

       4
       4
       +
        * Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>

     

       5
       5
       +
        *

     

       6
       6
       +
        * Permission to use, copy, modify, and distribute this software for any

     

       7
       7
       +
        * purpose with or without fee is hereby granted, provided that the above

     

       8
       8
       +
        * copyright notice and this permission notice appear in all copies.

     

       9
       9
       +
        *

     

       10
       10
       +
        * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES

     

       11
       11
       +
        * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF

     

       12
       12
       +
        * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR

     

       13
       13
       +
        * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES

     

       14
       14
       +
        * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN

     

       15
       15
       +
        * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF

     

       16
       16
       +
        * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

     

       17
       17
       +
        *

     

       18
       18
       +
        *)

+66

README.md

···

       1
       1
       +
       # kgp - Kitty Graphics Protocol for OCaml

     

       2
       2
       +
       

     

       3
       3
       +
       An OCaml library for displaying images in terminals using the [Kitty Graphics Protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/).

     

       4
       4
       +
       

     

       5
       5
       +
       This library can display PNG images in supported terminals (e.g. Kitty, WezTerm, Konsole, Ghostty) with varying levels of support depending on the terminal. Most core features work but some advanced things like animations might be only partially supported outside of Kitty.

     

       6
       6
       +
       

     

       7
       7
       +
       Other features include:

     

       8
       8
       +
       - Image transmission with automatic chunking and base64 encoding

     

       9
       9
       +
       - Multiple placements of the same image

     

       10
       10
       +
       - Animation support with frame deltas

     

       11
       11
       +
       - Unicode placeholder mode for proper scrolling

     

       12
       12
       +
       - tmux passthrough support (requires tmux 3.3+)

     

       13
       13
       +
       - Terminal capability detection

     

       14
       14
       +
       

     

       15
       15
       +
       The library provides a Cmdliner term via the `kgp.cli` package to make integration into other CLI tools easier.

     

       16
       16
       +
       

     

       17
       17
       +
       ## Installation

     

       18
       18
       +
       

     

       19
       19
       +
       ```

     

       20
       20
       +
       opam install kgp

     

       21
       21
       +
       ```

     

       22
       22
       +
       

     

       23
       23
       +
       ## Usage

     

       24
       24
       +
       

     

       25
       25
       +
       ### Library

     

       26
       26
       +
       

     

       27
       27
       +
       ```ocaml

     

       28
       28
       +
       (* Display a PNG image *)

     

       29
       29
       +
       let png_data = read_file "image.png" in

     

       30
       30
       +
       let cmd = Kgp.transmit_and_display ~format:`Png () in

     

       31
       31
       +
       let buf = Buffer.create 1024 in

     

       32
       32
       +
       Kgp.write buf cmd ~data:png_data;

     

       33
       33
       +
       print_string (Buffer.contents buf)

     

       34
       34
       +
       ```

     

       35
       35
       +
       

     

       36
       36
       +
       ```ocaml

     

       37
       37
       +
       (* Transmit once, display multiple times *)

     

       38
       38
       +
       let cmd = Kgp.transmit ~image_id:1 ~format:`Png () in

     

       39
       39
       +
       Kgp.write buf cmd ~data:png_data;

     

       40
       40
       +
       

     

       41
       41
       +
       let cmd = Kgp.display ~image_id:1 () in

     

       42
       42
       +
       Kgp.write buf cmd ~data:""

     

       43
       43
       +
       ```

     

       44
       44
       +
       

     

       45
       45
       +
       ### CLI

     

       46
       46
       +
       

     

       47
       47
       +
       ```

     

       48
       48
       +
       # Display an image

     

       49
       49
       +
       kgpcat image.png

     

       50
       50
       +
       

     

       51
       51
       +
       # Display at specific size and position

     

       52
       52
       +
       kgpcat --place 40x20@10,5 image.png

     

       53
       53
       +
       

     

       54
       54
       +
       # Display from stdin

     

       55
       55
       +
       curl -s https://example.com/image.png | kgpcat

     

       56
       56
       +
       

     

       57
       57
       +
       # Detect terminal support

     

       58
       58
       +
       kgpcat --detect-support

     

       59
       59
       +
       

     

       60
       60
       +
       # Clear displayed images

     

       61
       61
       +
       kgpcat --clear

     

       62
       62
       +
       ```

     

       63
       63
       +
       

     

       64
       64
       +
       ## License

     

       65
       65
       +
       

     

       66
       66
       +
       ISC

TODO.md

···

       1
       1
       +
       - Support zlib via decompress or similar

bin/dune

···

       1
       1
       +
       (executable

     

       2
       2
       +
        (name kgpcat)

     

       3
       3
       +
        (public_name kgpcat)

     

       4
       4
       +
        (package kgp)

     

       5
       5
       +
        (libraries kgp kgp.cli cmdliner unix))

+352

bin/kgpcat.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (* kgpcat - Display images in the terminal using Kitty Graphics Protocol *)

     

       7
       7
       +
       

     

       8
       8
       +
       open Cmdliner

     

       9
       9
       +
       

     

       10
       10
       +
       module K = Kgp

     

       11
       11
       +
       

     

       12
       12
       +
       type align = Center | Left | Right

     

       13
       13
       +
       type fit = Width | Height | Both | None_

     

       14
       14
       +
       

     

       15
       15
       +
       type config = {

     

       16
       16
       +
         files : string list;

     

       17
       17
       +
         clear : bool;

     

       18
       18
       +
         clear_all : bool;

     

       19
       19
       +
         detect_support : bool;

     

       20
       20
       +
         align : align; [@warning "-69"]

     

       21
       21
       +
         place : (int * int * int * int) option;

     

       22
       22
       +
         scale_up : bool; [@warning "-69"]

     

       23
       23
       +
         fit : fit; [@warning "-69"]

     

       24
       24
       +
         z_index : int;

     

       25
       25
       +
         unicode_placeholder : bool;

     

       26
       26
       +
         no_trailing_newline : bool;

     

       27
       27
       +
         hold : bool;

     

       28
       28
       +
         graphics_mode : K.Terminal.graphics_mode;

     

       29
       29
       +
       }

     

       30
       30
       +
       

     

       31
       31
       +
       (* Default image size in cells when not using --place *)

     

       32
       32
       +
       let default_rows = 10

     

       33
       33
       +
       let default_cols = 20

     

       34
       34
       +
       

     

       35
       35
       +
       (* Read file contents *)

     

       36
       36
       +
       let read_file filename =

     

       37
       37
       +
         let ic = open_in_bin filename in

     

       38
       38
       +
         let n = in_channel_length ic in

     

       39
       39
       +
         let s = really_input_string ic n in

     

       40
       40
       +
         close_in ic;

     

       41
       41
       +
         s

     

       42
       42
       +
       

     

       43
       43
       +
       (* Read from stdin *)

     

       44
       44
       +
       let read_stdin () =

     

       45
       45
       +
         let buf = Buffer.create 4096 in

     

       46
       46
       +
         try

     

       47
       47
       +
           while true do

     

       48
       48
       +
             Buffer.add_channel buf stdin 4096

     

       49
       49
       +
           done;

     

       50
       50
       +
           assert false

     

       51
       51
       +
         with End_of_file -> Buffer.contents buf

     

       52
       52
       +
       

     

       53
       53
       +
       (* Detect if stdin has data *)

     

       54
       54
       +
       let stdin_has_data () =

     

       55
       55
       +
         let fd = Unix.descr_of_in_channel stdin in

     

       56
       56
       +
         not (Unix.isatty fd)

     

       57
       57
       +
       

     

       58
       58
       +
       (* Send command to terminal *)

     

       59
       59
       +
       let send ?(tmux = false) cmd ~data =

     

       60
       60
       +
         let s = if tmux then K.to_string_tmux cmd ~data else K.to_string cmd ~data in

     

       61
       61
       +
         print_string s;

     

       62
       62
       +
         flush stdout

     

       63
       63
       +
       

     

       64
       64
       +
       (* Check if file is a supported format (PNG only) *)

     

       65
       65
       +
       let is_supported_format filename =

     

       66
       66
       +
         let ext =

     

       67
       67
       +
           try

     

       68
       68
       +
             let dot = String.rindex filename '.' in

     

       69
       69
       +
             String.lowercase_ascii (String.sub filename (dot + 1) (String.length filename - dot - 1))

     

       70
       70
       +
           with Not_found -> ""

     

       71
       71
       +
         in

     

       72
       72
       +
         ext = "png" || filename = "stdin"

     

       73
       73
       +
       

     

       74
       74
       +
       (* Display a single image *)

     

       75
       75
       +
       let display_image config filename data =

     

       76
       76
       +
         let resolved_mode = K.Terminal.resolve_mode config.graphics_mode in

     

       77
       77
       +
         match resolved_mode with

     

       78
       78
       +
         | `Placeholder ->

     

       79
       79
       +
             (* No graphics support - show placeholder text *)

     

       80
       80
       +
             Printf.printf "[Image: %s (%d bytes)]\n" filename (String.length data)

     

       81
       81
       +
         | `Graphics | `Tmux ->

     

       82
       82
       +
             let use_tmux = resolved_mode = `Tmux in

     

       83
       83
       +
             (* Use unicode placeholders if requested or if in tmux mode *)

     

       84
       84
       +
             let use_unicode = config.unicode_placeholder || use_tmux in

     

       85
       85
       +
             let cols, rows =

     

       86
       86
       +
               match config.place with

     

       87
       87
       +
               | Some (w, h, _, _) -> (w, h)

     

       88
       88
       +
               | None -> (default_cols, default_rows)

     

       89
       89
       +
             in

     

       90
       90
       +
             if use_unicode then (

     

       91
       91
       +
               (* Unicode placeholder mode: transmit image, then output placeholder chars *)

     

       92
       92
       +
               let image_id = K.next_image_id () in

     

       93
       93
       +
               let placement =

     

       94
       94
       +
                 match config.place with

     

       95
       95
       +
                 | Some (w, h, x, y) ->

     

       96
       96
       +
                     K.Placement.make ~columns:w ~rows:h ~cell_x_offset:x ~cell_y_offset:y

     

       97
       97
       +
                       ~z_index:config.z_index ~unicode_placeholder:true ~cursor:`Static ()

     

       98
       98
       +
                 | None ->

     

       99
       99
       +
                     let z = if config.z_index <> 0 then Some config.z_index else None in

     

       100
       100
       +
                     K.Placement.make ~columns:cols ~rows ?z_index:z ~unicode_placeholder:true

     

       101
       101
       +
                       ~cursor:`Static ()

     

       102
       102
       +
               in

     

       103
       103
       +
               (* Transmit the image data with virtual placement *)

     

       104
       104
       +
               let cmd =

     

       105
       105
       +
                 K.transmit_and_display ~image_id ~format:`Png ~placement ~quiet:`Errors_only ()

     

       106
       106
       +
               in

     

       107
       107
       +
               send ~tmux:use_tmux cmd ~data;

     

       108
       108
       +
               (* Output unicode placeholder characters that reference the image *)

     

       109
       109
       +
               let buf = Buffer.create 256 in

     

       110
       110
       +
               K.Unicode_placeholder.write buf ~image_id ~rows ~cols ();

     

       111
       111
       +
               print_string (Buffer.contents buf);

     

       112
       112
       +
               if not config.no_trailing_newline then print_newline ()

     

       113
       113
       +
             ) else (

     

       114
       114
       +
               (* Direct graphics mode *)

     

       115
       115
       +
               let image_id = K.next_image_id () in

     

       116
       116
       +
               let placement =

     

       117
       117
       +
                 match config.place with

     

       118
       118
       +
                 | Some (w, h, x, y) ->

     

       119
       119
       +
                     Some

     

       120
       120
       +
                       (K.Placement.make ~columns:w ~rows:h ~cell_x_offset:x ~cell_y_offset:y

     

       121
       121
       +
                          ~z_index:config.z_index ~cursor:`Static ())

     

       122
       122
       +
                 | None ->

     

       123
       123
       +
                     let z = if config.z_index <> 0 then Some config.z_index else None in

     

       124
       124
       +
                     Some

     

       125
       125
       +
                       (K.Placement.make ?z_index:z

     

       126
       126
       +
                          ~cursor:(if config.no_trailing_newline then `Static else `Move) ())

     

       127
       127
       +
               in

     

       128
       128
       +
               let cmd =

     

       129
       129
       +
                 K.transmit_and_display ~image_id ~format:`Png ?placement ~quiet:`Errors_only ()

     

       130
       130
       +
               in

     

       131
       131
       +
               send ~tmux:use_tmux cmd ~data;

     

       132
       132
       +
               if not config.no_trailing_newline && config.place = None then print_newline ()

     

       133
       133
       +
             )

     

       134
       134
       +
       

     

       135
       135
       +
       (* Clear all images *)

     

       136
       136
       +
       let do_clear () =

     

       137
       137
       +
         send (K.delete `All_visible) ~data:""

     

       138
       138
       +
       

     

       139
       139
       +
       (* Clear all images including scrollback *)

     

       140
       140
       +
       let do_clear_all () =

     

       141
       141
       +
         (* Delete all images by ID range 1 to max, freeing data *)

     

       142
       142
       +
         send (K.delete ~free:true (`By_id_range (1, 4294967295))) ~data:""

     

       143
       143
       +
       

     

       144
       144
       +
       (* Detect terminal support *)

     

       145
       145
       +
       let do_detect_support () =

     

       146
       146
       +
         if K.Terminal.is_graphics_terminal () then (

     

       147
       147
       +
           let mode =

     

       148
       148
       +
             if K.Terminal.is_tmux () then "tmux"

     

       149
       149
       +
             else if K.Terminal.is_kitty () then "kitty"

     

       150
       150
       +
             else if K.Terminal.is_wezterm () then "wezterm"

     

       151
       151
       +
             else if K.Terminal.is_ghostty () then "ghostty"

     

       152
       152
       +
             else "stream"

     

       153
       153
       +
           in

     

       154
       154
       +
           Printf.eprintf "%s\n" mode;

     

       155
       155
       +
           0

     

       156
       156
       +
         ) else (

     

       157
       157
       +
           Printf.eprintf "not supported\n";

     

       158
       158
       +
           1

     

       159
       159
       +
         )

     

       160
       160
       +
       

     

       161
       161
       +
       (* Main run function *)

     

       162
       162
       +
       let run config =

     

       163
       163
       +
         (* Handle clear operations first *)

     

       164
       164
       +
         if config.clear_all then do_clear_all ()

     

       165
       165
       +
         else if config.clear then do_clear ();

     

       166
       166
       +
       

     

       167
       167
       +
         (* Handle detect support *)

     

       168
       168
       +
         if config.detect_support then exit (do_detect_support ());

     

       169
       169
       +
       

     

       170
       170
       +
         (* Process files *)

     

       171
       171
       +
         let files =

     

       172
       172
       +
           if config.files = [] && stdin_has_data () then [ "-" ] else config.files

     

       173
       173
       +
         in

     

       174
       174
       +
         if files = [] && not config.clear && not config.clear_all then (

     

       175
       175
       +
           Printf.eprintf "Usage: kgpcat [OPTIONS] IMAGE_FILE...\n";

     

       176
       176
       +
           Printf.eprintf "Try 'kgpcat --help' for more information.\n";

     

       177
       177
       +
           exit 1);

     

       178
       178
       +
       

     

       179
       179
       +
         List.iter

     

       180
       180
       +
           (fun file ->

     

       181
       181
       +
             let name = if file = "-" then "stdin" else file in

     

       182
       182
       +
             if not (is_supported_format name) then

     

       183
       183
       +
               Printf.eprintf "Error: %s is not a PNG file (only PNG format is supported)\n" file

     

       184
       184
       +
             else

     

       185
       185
       +
               try

     

       186
       186
       +
                 let data =

     

       187
       187
       +
                   if file = "-" then read_stdin () else read_file file

     

       188
       188
       +
                 in

     

       189
       189
       +
                 display_image config name data

     

       190
       190
       +
               with

     

       191
       191
       +
               | Sys_error msg ->

     

       192
       192
       +
                   Printf.eprintf "Error reading %s: %s\n" file msg

     

       193
       193
       +
               | exn ->

     

       194
       194
       +
                   Printf.eprintf "Error processing %s: %s\n" file (Printexc.to_string exn))

     

       195
       195
       +
           files;

     

       196
       196
       +
       

     

       197
       197
       +
         (* Ensure all output is flushed before exiting *)

     

       198
       198
       +
         flush stdout;

     

       199
       199
       +
       

     

       200
       200
       +
         if config.hold then (

     

       201
       201
       +
           Printf.eprintf "Press Enter to exit...";

     

       202
       202
       +
           flush stderr;

     

       203
       203
       +
           ignore (read_line ()))

     

       204
       204
       +
       

     

       205
       205
       +
       (* Cmdliner argument definitions *)

     

       206
       206
       +
       

     

       207
       207
       +
       let files_arg =

     

       208
       208
       +
         Arg.(value & pos_all file [] & info [] ~docv:"IMAGE" ~doc:"Image files to display.")

     

       209
       209
       +
       

     

       210
       210
       +
       let clear_arg =

     

       211
       211
       +
         let doc = "Remove all images currently displayed on the screen." in

     

       212
       212
       +
         Arg.(value & flag & info [ "clear" ] ~doc)

     

       213
       213
       +
       

     

       214
       214
       +
       let clear_all_arg =

     

       215
       215
       +
         let doc = "Remove all images from screen and scrollback." in

     

       216
       216
       +
         Arg.(value & flag & info [ "clear-all" ] ~doc)

     

       217
       217
       +
       

     

       218
       218
       +
       let detect_support_arg =

     

       219
       219
       +
         let doc =

     

       220
       220
       +
           "Detect support for image display in the terminal. Exits with code 0 if \

     

       221
       221
       +
            supported, 1 otherwise. Prints the supported transfer mode to stderr."

     

       222
       222
       +
         in

     

       223
       223
       +
         Arg.(value & flag & info [ "detect-support" ] ~doc)

     

       224
       224
       +
       

     

       225
       225
       +
       let align_arg =

     

       226
       226
       +
         let doc = "Horizontal alignment for the displayed image." in

     

       227
       227
       +
         let align_enum = Arg.enum [ ("center", Center); ("left", Left); ("right", Right) ] in

     

       228
       228
       +
         Arg.(value & opt align_enum Center & info [ "align" ] ~doc ~docv:"ALIGN")

     

       229
       229
       +
       

     

       230
       230
       +
       let place_arg =

     

       231
       231
       +
         let doc =

     

       232
       232
       +
           "Display image in specified rectangle. Format: WxH@X,Y where W and H are \

     

       233
       233
       +
            width and height in cells, and X,Y is the position. Example: 40x20@10,5"

     

       234
       234
       +
         in

     

       235
       235
       +
         let parse s =

     

       236
       236
       +
           try

     

       237
       237
       +
             let at_pos = String.index s '@' in

     

       238
       238
       +
             let size_part = String.sub s 0 at_pos in

     

       239
       239
       +
             let pos_part = String.sub s (at_pos + 1) (String.length s - at_pos - 1) in

     

       240
       240
       +
             let x_pos = String.index size_part 'x' in

     

       241
       241
       +
             let w = int_of_string (String.sub size_part 0 x_pos) in

     

       242
       242
       +
             let h = int_of_string (String.sub size_part (x_pos + 1) (String.length size_part - x_pos - 1)) in

     

       243
       243
       +
             let comma_pos = String.index pos_part ',' in

     

       244
       244
       +
             let x = int_of_string (String.sub pos_part 0 comma_pos) in

     

       245
       245
       +
             let y = int_of_string (String.sub pos_part (comma_pos + 1) (String.length pos_part - comma_pos - 1)) in

     

       246
       246
       +
             Ok (w, h, x, y)

     

       247
       247
       +
           with _ -> Error (`Msg "Invalid place format. Use WxH@X,Y (e.g., 40x20@10,5)")

     

       248
       248
       +
         in

     

       249
       249
       +
         let print ppf (w, h, x, y) = Format.fprintf ppf "%dx%d@%d,%d" w h x y in

     

       250
       250
       +
         let place_conv = Arg.conv (parse, print) in

     

       251
       251
       +
         Arg.(value & opt (some place_conv) None & info [ "place" ] ~doc ~docv:"WxH@X,Y")

     

       252
       252
       +
       

     

       253
       253
       +
       let scale_up_arg =

     

       254
       254
       +
         let doc =

     

       255
       255
       +
           "Scale up images smaller than the specified area to use as much of the \

     

       256
       256
       +
            area as possible."

     

       257
       257
       +
         in

     

       258
       258
       +
         Arg.(value & flag & info [ "scale-up" ] ~doc)

     

       259
       259
       +
       

     

       260
       260
       +
       let fit_arg =

     

       261
       261
       +
         let doc = "Control how the image is scaled relative to the screen." in

     

       262
       262
       +
         let fit_enum =

     

       263
       263
       +
           Arg.enum [ ("width", Width); ("height", Height); ("both", Both); ("none", None_) ]

     

       264
       264
       +
         in

     

       265
       265
       +
         Arg.(value & opt fit_enum Width & info [ "fit" ] ~doc ~docv:"FIT")

     

       266
       266
       +
       

     

       267
       267
       +
       let z_index_arg =

     

       268
       268
       +
         let doc =

     

       269
       269
       +
           "Z-index of the image. Negative values display text on top of the image."

     

       270
       270
       +
         in

     

       271
       271
       +
         Arg.(value & opt int 0 & info [ "z"; "z-index" ] ~doc ~docv:"Z")

     

       272
       272
       +
       

     

       273
       273
       +
       let unicode_placeholder_arg =

     

       274
       274
       +
         let doc =

     

       275
       275
       +
           "Use Unicode placeholder method to display images. This allows images to \

     

       276
       276
       +
            scroll properly with text in terminals and multiplexers. Automatically \

     

       277
       277
       +
            enabled when using tmux passthrough mode."

     

       278
       278
       +
         in

     

       279
       279
       +
         Arg.(value & flag & info [ "unicode-placeholder" ] ~doc)

     

       280
       280
       +
       

     

       281
       281
       +
       let no_trailing_newline_arg =

     

       282
       282
       +
         let doc = "Don't move cursor to next line after displaying an image." in

     

       283
       283
       +
         Arg.(value & flag & info [ "n"; "no-trailing-newline" ] ~doc)

     

       284
       284
       +
       

     

       285
       285
       +
       let hold_arg =

     

       286
       286
       +
         let doc = "Wait for a key press before exiting after displaying images." in

     

       287
       287
       +
         Arg.(value & flag & info [ "hold" ] ~doc)

     

       288
       288
       +
       

     

       289
       289
       +
       let config_term =

     

       290
       290
       +
         let combine files clear clear_all detect_support align place scale_up fit z_index

     

       291
       291
       +
             unicode_placeholder no_trailing_newline hold graphics_mode =

     

       292
       292
       +
           {

     

       293
       293
       +
             files;

     

       294
       294
       +
             clear;

     

       295
       295
       +
             clear_all;

     

       296
       296
       +
             detect_support;

     

       297
       297
       +
             align;

     

       298
       298
       +
             place;

     

       299
       299
       +
             scale_up;

     

       300
       300
       +
             fit;

     

       301
       301
       +
             z_index;

     

       302
       302
       +
             unicode_placeholder;

     

       303
       303
       +
             no_trailing_newline;

     

       304
       304
       +
             hold;

     

       305
       305
       +
             graphics_mode;

     

       306
       306
       +
           }

     

       307
       307
       +
         in

     

       308
       308
       +
         Term.(

     

       309
       309
       +
           const combine

     

       310
       310
       +
           $ files_arg

     

       311
       311
       +
           $ clear_arg

     

       312
       312
       +
           $ clear_all_arg

     

       313
       313
       +
           $ detect_support_arg

     

       314
       314
       +
           $ align_arg

     

       315
       315
       +
           $ place_arg

     

       316
       316
       +
           $ scale_up_arg

     

       317
       317
       +
           $ fit_arg

     

       318
       318
       +
           $ z_index_arg

     

       319
       319
       +
           $ unicode_placeholder_arg

     

       320
       320
       +
           $ no_trailing_newline_arg

     

       321
       321
       +
           $ hold_arg

     

       322
       322
       +
           $ Kgp_cli.graphics_term)

     

       323
       323
       +
       

     

       324
       324
       +
       let cmd =

     

       325
       325
       +
         let doc = "Display images in the terminal using Kitty Graphics Protocol" in

     

       326
       326
       +
         let man =

     

       327
       327
       +
           [

     

       328
       328
       +
             `S Manpage.s_description;

     

       329
       329
       +
             `P

     

       330
       330
       +
               "$(tname) displays images in terminals that support the Kitty Graphics \

     

       331
       331
       +
                Protocol (Kitty, WezTerm, Konsole, Ghostty, etc.).";

     

       332
       332
       +
             `P

     

       333
       333
       +
               "You can specify multiple image files. If no files are given and stdin \

     

       334
       334
       +
                is not a terminal, image data is read from stdin.";

     

       335
       335
       +
             `S Manpage.s_examples;

     

       336
       336
       +
             `P "Display an image:";

     

       337
       337
       +
             `Pre "  $(tname) photo.png";

     

       338
       338
       +
             `P "Display multiple images:";

     

       339
       339
       +
             `Pre "  $(tname) *.png";

     

       340
       340
       +
             `P "Display image from stdin:";

     

       341
       341
       +
             `Pre "  curl -s https://example.com/image.png | $(tname)";

     

       342
       342
       +
             `P "Display image at specific position:";

     

       343
       343
       +
             `Pre "  $(tname) --place 40x20@10,5 photo.png";

     

       344
       344
       +
             `P "Clear all displayed images:";

     

       345
       345
       +
             `Pre "  $(tname) --clear";

     

       346
       346
       +
             `S Kgp_cli.graphics_docs;

     

       347
       347
       +
           ]

     

       348
       348
       +
         in

     

       349
       349
       +
         let info = Cmd.info "kgpcat" ~version:"%%VERSION%%" ~doc ~man in

     

       350
       350
       +
         Cmd.v info Term.(const run $ config_term)

     

       351
       351
       +
       

     

       352
       352
       +
       let () = exit (Cmd.eval cmd)

+11 -1

dune-project

···

       1
       1
        
       (lang dune 3.20)

     

       2
       2
        
       (name kgp)

     

       3
       3
        
       

     

       4
       4
       +
       (generate_opam_files true)

     

       5
       5
       +
       

     

       6
       6
       +
       (license ISC)

     

       7
       7
       +
       (authors "Anil Madhavapeddy")

     

       8
       8
       +
       (homepage "https://tangled.org/@anil.recoil.org/ocaml-kgp")

     

       9
       9
       +
       (maintainers "Anil Madhavapeddy <anil@recoil.org>")

     

       10
       10
       +
       (bug_reports "https://tangled.org/@anil.recoil.org/ocaml-kgp/issues")

     

       11
       11
       +
       (maintenance_intent "(latest)")

     

       12
       12
       +
       

     

       4
       13
        
       (package

     

       5
       14
        
        (name kgp)

     

       6
       15
        
        (synopsis "OCaml implementation of the Kitty terminal graphics protocol")

     

       7
       16
        
        (description

     

       8
       8
       -
         "A standalone library for rendering images in terminals that support the Kitty graphics protocol. Supports image transmission, display, animation, Unicode placeholders, and terminal capability detection.")

     

       17
       17
       +
         "Library for rendering images in terminals that support the Kitty graphics protocol. Supports image transmission, display, animation, Unicode placeholders, and terminal capability detection.")

     

       9
       18
        
        (depends

     

       10
       19
        
         (ocaml (>= 4.14.0))

     

       20
       20
       +
         cmdliner

     

       11
       21
        
         base64))

-97

example/anim_test.ml

···

       1
       1
       -
       (* Minimal animation test - shows exact bytes sent *)

     

       2
       2
       -
       

     

       3
       3
       -
       module K = Kgp

     

       4
       4
       -
       

     

       5
       5
       -
       let solid_color_rgba ~width ~height ~r ~g ~b ~a =

     

       6
       6
       -
         let pixels = Bytes.create (width * height * 4) in

     

       7
       7
       -
         for i = 0 to (width * height) - 1 do

     

       8
       8
       -
           let idx = i * 4 in

     

       9
       9
       -
           Bytes.set pixels idx (Char.chr r);

     

       10
       10
       -
           Bytes.set pixels (idx + 1) (Char.chr g);

     

       11
       11
       -
           Bytes.set pixels (idx + 2) (Char.chr b);

     

       12
       12
       -
           Bytes.set pixels (idx + 3) (Char.chr a)

     

       13
       13
       -
         done;

     

       14
       14
       -
         Bytes.to_string pixels

     

       15
       15
       -
       

     

       16
       16
       -
       let send cmd ~data =

     

       17
       17
       -
         print_string (K.Command.to_string cmd ~data);

     

       18
       18
       -
         flush stdout

     

       19
       19
       -
       

     

       20
       20
       -
       let () =

     

       21
       21
       -
         let width, height = 40, 40 in  (* Smaller for faster testing *)

     

       22
       22
       -
         let image_id = 500 in

     

       23
       23
       -
       

     

       24
       24
       -
         (* Clear any existing image *)

     

       25
       25
       -
         send (K.Command.delete ~quiet:`Errors_only (`All_visible_and_free)) ~data:"";

     

       26
       26
       -
       

     

       27
       27
       -
         (* Step 1: Transmit base frame (red) *)

     

       28
       28
       -
         let red_frame = solid_color_rgba ~width ~height ~r:255 ~g:0 ~b:0 ~a:255 in

     

       29
       29
       -
         send

     

       30
       30
       -
           (K.Command.transmit

     

       31
       31
       -
              ~image_id

     

       32
       32
       -
              ~format:`Rgba32

     

       33
       33
       -
              ~width ~height

     

       34
       34
       -
              ~quiet:`Errors_only

     

       35
       35
       -
              ())

     

       36
       36
       -
           ~data:red_frame;

     

       37
       37
       -
       

     

       38
       38
       -
         (* Step 2: Add frame (blue) *)

     

       39
       39
       -
         let blue_frame = solid_color_rgba ~width ~height ~r:0 ~g:0 ~b:255 ~a:255 in

     

       40
       40
       -
         send

     

       41
       41
       -
           (K.Command.frame

     

       42
       42
       -
              ~image_id

     

       43
       43
       -
              ~format:`Rgba32

     

       44
       44
       -
              ~width ~height

     

       45
       45
       -
              ~frame:(K.Frame.make ~gap_ms:500 ~composition:`Overwrite ())

     

       46
       46
       -
              ~quiet:`Errors_only

     

       47
       47
       -
              ())

     

       48
       48
       -
           ~data:blue_frame;

     

       49
       49
       -
       

     

       50
       50
       -
         (* Step 3: Add frame (green) *)

     

       51
       51
       -
         let green_frame = solid_color_rgba ~width ~height ~r:0 ~g:255 ~b:0 ~a:255 in

     

       52
       52
       -
         send

     

       53
       53
       -
           (K.Command.frame

     

       54
       54
       -
              ~image_id

     

       55
       55
       -
              ~format:`Rgba32

     

       56
       56
       -
              ~width ~height

     

       57
       57
       -
              ~frame:(K.Frame.make ~gap_ms:500 ~composition:`Overwrite ())

     

       58
       58
       -
              ~quiet:`Errors_only

     

       59
       59
       -
              ())

     

       60
       60
       -
           ~data:green_frame;

     

       61
       61
       -
       

     

       62
       62
       -
         (* Step 4: Create placement *)

     

       63
       63
       -
         send

     

       64
       64
       -
           (K.Command.display

     

       65
       65
       -
              ~image_id

     

       66
       66
       -
              ~placement:(K.Placement.make

     

       67
       67
       -
                            ~placement_id:1

     

       68
       68
       -
                            ~cursor:`Static

     

       69
       69
       -
                            ())

     

       70
       70
       -
              ~quiet:`Errors_only

     

       71
       71
       -
              ())

     

       72
       72
       -
           ~data:"";

     

       73
       73
       -
       

     

       74
       74
       -
         (* Step 5: Set root frame gap - IMPORTANT: root frame has no gap by default *)

     

       75
       75
       -
         send

     

       76
       76
       -
           (K.Command.animate ~image_id (K.Animation.set_gap ~frame:1 ~gap_ms:500))

     

       77
       77
       -
           ~data:"";

     

       78
       78
       -
       

     

       79
       79
       -
         (* Step 6: Start animation *)

     

       80
       80
       -
         send

     

       81
       81
       -
           (K.Command.animate ~image_id (K.Animation.set_state ~loops:1 `Run))

     

       82
       82
       -
           ~data:"";

     

       83
       83
       -
       

     

       84
       84
       -
         print_endline "";

     

       85
       85
       -
         print_endline "Animation should be playing (red -> blue -> green).";

     

       86
       86
       -
         print_endline "Press Enter to stop...";

     

       87
       87
       -
         flush stdout;

     

       88
       88
       -
         let _ = read_line () in

     

       89
       89
       -
       

     

       90
       90
       -
         (* Stop animation *)

     

       91
       91
       -
         send

     

       92
       92
       -
           (K.Command.animate ~image_id (K.Animation.set_state `Stop))

     

       93
       93
       -
           ~data:"";

     

       94
       94
       -
       

     

       95
       95
       -
         (* Clean up *)

     

       96
       96
       -
         send (K.Command.delete ~quiet:`Errors_only (`All_visible_and_free)) ~data:"";

     

       97
       97
       -
         print_endline "Done."

example/camel.png

This is a binary file and will not be displayed.

-94

example/debug_anim.ml

···

       1
       1
       -
       (* Debug: Output animation escape sequences for comparison with Go *)

     

       2
       2
       -
       

     

       3
       3
       -
       module K = Kgp

     

       4
       4
       -
       

     

       5
       5
       -
       let solid_color_rgba ~width ~height ~r ~g ~b ~a =

     

       6
       6
       -
         let pixels = Bytes.create (width * height * 4) in

     

       7
       7
       -
         for i = 0 to (width * height) - 1 do

     

       8
       8
       -
           let idx = i * 4 in

     

       9
       9
       -
           Bytes.set pixels idx (Char.chr r);

     

       10
       10
       -
           Bytes.set pixels (idx + 1) (Char.chr g);

     

       11
       11
       -
           Bytes.set pixels (idx + 2) (Char.chr b);

     

       12
       12
       -
           Bytes.set pixels (idx + 3) (Char.chr a)

     

       13
       13
       -
         done;

     

       14
       14
       -
         Bytes.to_string pixels

     

       15
       15
       -
       

     

       16
       16
       -
       let send cmd ~data =

     

       17
       17
       -
         let s = K.Command.to_string cmd ~data in

     

       18
       18
       -
         (* Print escaped version for debugging *)

     

       19
       19
       -
         String.iter (fun c ->

     

       20
       20
       -
           let code = Char.code c in

     

       21
       21
       -
           if code = 27 then print_string "\\x1b"

     

       22
       22
       -
           else if code < 32 || code > 126 then Printf.printf "\\x%02x" code

     

       23
       23
       -
           else print_char c

     

       24
       24
       -
         ) s;

     

       25
       25
       -
         print_newline ()

     

       26
       26
       -
       

     

       27
       27
       -
       let () =

     

       28
       28
       -
         let width, height = 80, 80 in

     

       29
       29
       -
         let image_id = 300 in

     

       30
       30
       -
       

     

       31
       31
       -
         print_endline "=== OCaml Animation Debug ===\n";

     

       32
       32
       -
       

     

       33
       33
       -
         (* Step 1: Transmit base frame *)

     

       34
       34
       -
         print_endline "1. Transmit base frame (a=t):";

     

       35
       35
       -
         let red_frame = solid_color_rgba ~width ~height ~r:255 ~g:0 ~b:0 ~a:255 in

     

       36
       36
       -
         send

     

       37
       37
       -
           (K.Command.transmit

     

       38
       38
       -
              ~image_id

     

       39
       39
       -
              ~format:`Rgba32

     

       40
       40
       -
              ~width ~height

     

       41
       41
       -
              ~quiet:`Errors_only

     

       42
       42
       -
              ())

     

       43
       43
       -
           ~data:red_frame;

     

       44
       44
       -
         print_newline ();

     

       45
       45
       -
       

     

       46
       46
       -
         (* Step 2: Add frame *)

     

       47
       47
       -
         print_endline "2. Add frame (a=f):";

     

       48
       48
       -
         let orange_frame = solid_color_rgba ~width ~height ~r:255 ~g:165 ~b:0 ~a:255 in

     

       49
       49
       -
         send

     

       50
       50
       -
           (K.Command.frame

     

       51
       51
       -
              ~image_id

     

       52
       52
       -
              ~format:`Rgba32

     

       53
       53
       -
              ~width ~height

     

       54
       54
       -
              ~frame:(K.Frame.make ~gap_ms:100 ~composition:`Overwrite ())

     

       55
       55
       -
              ~quiet:`Errors_only

     

       56
       56
       -
              ())

     

       57
       57
       -
           ~data:orange_frame;

     

       58
       58
       -
         print_newline ();

     

       59
       59
       -
       

     

       60
       60
       -
         (* Step 3: Put/display placement *)

     

       61
       61
       -
         print_endline "3. Create placement (a=p):";

     

       62
       62
       -
         send

     

       63
       63
       -
           (K.Command.display

     

       64
       64
       -
              ~image_id

     

       65
       65
       -
              ~placement:(K.Placement.make

     

       66
       66
       -
                            ~placement_id:1

     

       67
       67
       -
                            ~cell_x_offset:0

     

       68
       68
       -
                            ~cell_y_offset:0

     

       69
       69
       -
                            ~cursor:`Static

     

       70
       70
       -
                            ())

     

       71
       71
       -
              ~quiet:`Errors_only

     

       72
       72
       -
              ())

     

       73
       73
       -
           ~data:"";

     

       74
       74
       -
         print_newline ();

     

       75
       75
       -
       

     

       76
       76
       -
         (* Step 4: Set root frame gap *)

     

       77
       77
       -
         print_endline "4. Set root frame gap (a=a,r=1,z=100):";

     

       78
       78
       -
         send

     

       79
       79
       -
           (K.Command.animate ~image_id (K.Animation.set_gap ~frame:1 ~gap_ms:100))

     

       80
       80
       -
           ~data:"";

     

       81
       81
       -
         print_newline ();

     

       82
       82
       -
       

     

       83
       83
       -
         (* Step 5: Animate *)

     

       84
       84
       -
         print_endline "5. Start animation (a=a,s=3,v=1):";

     

       85
       85
       -
         send

     

       86
       86
       -
           (K.Command.animate ~image_id (K.Animation.set_state ~loops:1 `Run))

     

       87
       87
       -
           ~data:"";

     

       88
       88
       -
         print_newline ();

     

       89
       89
       -
       

     

       90
       90
       -
         (* Step 6: Stop animation *)

     

       91
       91
       -
         print_endline "6. Stop animation:";

     

       92
       92
       -
         send

     

       93
       93
       -
           (K.Command.animate ~image_id (K.Animation.set_state `Stop))

     

       94
       94
       -
           ~data:""

+3 -11

example/dune

···

       2
       2
        
        (name example)

     

       3
       3
        
        (libraries kgp unix))

     

       4
       4
        
       

     

       5
       5
       -
       (executable

     

       6
       6
       -
        (name debug_anim)

     

       7
       7
       -
        (libraries kgp))

     

       8
       8
       -
       

     

       9
       9
       -
       (executable

     

       10
       10
       -
        (name test_output)

     

       11
       11
       -
        (libraries kgp))

     

       12
       12
       -
       

     

       13
       13
       -
       (executable

     

       14
       14
       -
        (name anim_test)

     

       15
       15
       -
        (libraries kgp))

     

       5
       5
       +
       (alias

     

       6
       6
       +
        (name example)

     

       7
       7
       +
        (deps example.exe camel.png))

     

       16
       8
        
       

     

       17
       9
        
       (executable

     

       18
       10
        
        (name tiny_anim)

+97 -161

example/example.ml

···

       1
       1
       -
       (* Kitty Graphics Protocol Demo - Matching kgp/examples/demo *)

     

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (* Kitty Graphics Protocol Demo  *)

     

       2
       7
        
       

     

       3
       8
        
       module K = Kgp

     

       4
       9
        
       

     
···

       30
       35
        
         let pixels = Bytes.create (width * height * 4) in

     

       31
       36
        
         for y = 0 to height - 1 do

     

       32
       37
        
           for x = 0 to width - 1 do

     

       33
       33
       -
             let idx = (y * width + x) * 4 in

     

       38
       38
       +
             let idx = ((y * width) + x) * 4 in

     

       34
       39
        
             let r = 255 * x / width in

     

       35
       40
        
             let b = 255 * (width - x) / width in

     

       36
       41
        
             Bytes.set pixels idx (Char.chr r);

     
···

       50
       55
        
         s

     

       51
       56
        
       

     

       52
       57
        
       let send cmd ~data =

     

       53
       53
       -
         print_string (K.Command.to_string cmd ~data);

     

       58
       58
       +
         print_string (K.to_string cmd ~data);

     

       54
       59
        
         flush stdout

     

       55
       60
        
       

     

       56
       61
        
       let wait_for_enter () =

     
···

       61
       66
        
       

     

       62
       67
        
       let clear_screen () =

     

       63
       68
        
         print_string "\x1b[2J\x1b[H";

     

       64
       64
       -
         for _ = 1 to 5 do print_newline () done;

     

       69
       69
       +
         for _ = 1 to 5 do

     

       70
       70
       +
           print_newline ()

     

       71
       71
       +
         done;

     

       65
       72
        
         flush stdout

     

       66
       73
        
       

     

       67
       74
        
       let () =

     
···

       78
       85
        
         (* Demo 1: Basic formats - PNG *)

     

       79
       86
        
         clear_screen ();

     

       80
       87
        
         print_endline "Demo 1: Image Formats - PNG format";

     

       81
       81
       -
         (* Read sf.png and display a small portion as demo *)

     

       88
       88
       +
         (* Read camel.png and display a small portion as demo *)

     

       82
       89
        
         (try

     

       83
       83
       -
            let png_data = read_file "sf.png" in

     

       90
       90
       +
            let png_data = read_file "camel.png" in

     

       84
       91
        
            send

     

       85
       85
       -
              (K.Command.transmit_and_display

     

       86
       86
       -
                 ~image_id:1

     

       87
       87
       -
                 ~format:`Png

     

       88
       88
       -
                 ~quiet:`Errors_only

     

       92
       92
       +
              (K.transmit_and_display ~image_id:1 ~format:`Png ~quiet:`Errors_only

     

       89
       93
        
                 ~placement:(K.Placement.make ~columns:15 ~rows:8 ())

     

       90
       94
        
                 ())

     

       91
       95
        
              ~data:png_data;

     

       92
       92
       -
            print_endline "sf.png displayed using PNG format"

     

       96
       96
       +
            print_endline "camel.png displayed using PNG format"

     

       93
       97
        
          with _ ->

     

       94
       98
        
            (* Fallback: red square as RGBA *)

     

       95
       95
       -
            let red_data = solid_color_rgba ~width:100 ~height:100 ~r:255 ~g:0 ~b:0 ~a:255 in

     

       99
       99
       +
            let red_data =

     

       100
       100
       +
              solid_color_rgba ~width:100 ~height:100 ~r:255 ~g:0 ~b:0 ~a:255

     

       101
       101
       +
            in

     

       96
       102
        
            send

     

       97
       97
       -
              (K.Command.transmit_and_display

     

       98
       98
       -
                 ~image_id:1

     

       99
       99
       -
                 ~format:`Rgba32

     

       100
       100
       -
                 ~width:100 ~height:100

     

       101
       101
       -
                 ~quiet:`Errors_only

     

       102
       102
       -
                 ())

     

       103
       103
       +
              (K.transmit_and_display ~image_id:1 ~format:`Rgba32 ~width:100

     

       104
       104
       +
                 ~height:100 ~quiet:`Errors_only ())

     

       103
       105
        
              ~data:red_data;

     

       104
       104
       -
            print_endline "Red square displayed (sf.png not found)");

     

       106
       106
       +
            print_endline "Red square displayed (camel.png not found)");

     

       105
       107
        
         print_newline ();

     

       106
       108
        
         wait_for_enter ();

     

       107
       109
        
       

     

       108
       110
        
         (* Demo 2: Basic formats - RGBA *)

     

       109
       111
        
         clear_screen ();

     

       110
       112
        
         print_endline "Demo 2: Image Formats - RGBA format (32-bit)";

     

       111
       111
       -
         let blue_data = solid_color_rgba ~width:100 ~height:100 ~r:0 ~g:0 ~b:255 ~a:255 in

     

       113
       113
       +
         let blue_data =

     

       114
       114
       +
           solid_color_rgba ~width:100 ~height:100 ~r:0 ~g:0 ~b:255 ~a:255

     

       115
       115
       +
         in

     

       112
       116
        
         send

     

       113
       113
       -
           (K.Command.transmit_and_display

     

       114
       114
       -
              ~image_id:2

     

       115
       115
       -
              ~format:`Rgba32

     

       116
       116
       -
              ~width:100 ~height:100

     

       117
       117
       -
              ~quiet:`Errors_only

     

       118
       118
       -
              ())

     

       117
       117
       +
           (K.transmit_and_display ~image_id:2 ~format:`Rgba32 ~width:100 ~height:100

     

       118
       118
       +
              ~quiet:`Errors_only ())

     

       119
       119
        
           ~data:blue_data;

     

       120
       120
        
         print_endline "Blue square displayed using raw RGBA format";

     

       121
       121
        
         print_newline ();

     
···

       126
       126
        
         print_endline "Demo 3: Image Formats - RGB format (24-bit)";

     

       127
       127
        
         let green_data = solid_color_rgb ~width:100 ~height:100 ~r:0 ~g:255 ~b:0 in

     

       128
       128
        
         send

     

       129
       129
       -
           (K.Command.transmit_and_display

     

       130
       130
       -
              ~image_id:3

     

       131
       131
       -
              ~format:`Rgb24

     

       132
       132
       -
              ~width:100 ~height:100

     

       133
       133
       -
              ~quiet:`Errors_only

     

       134
       134
       -
              ())

     

       129
       129
       +
           (K.transmit_and_display ~image_id:3 ~format:`Rgb24 ~width:100 ~height:100

     

       130
       130
       +
              ~quiet:`Errors_only ())

     

       135
       131
        
           ~data:green_data;

     

       136
       132
        
         print_endline "Green square displayed using raw RGB format (no alpha channel)";

     

       137
       133
        
         print_newline ();

     
···

       140
       136
        
         (* Demo 4: Compression - Note: would need zlib library for actual compression *)

     

       141
       137
        
         clear_screen ();

     

       142
       138
        
         print_endline "Demo 4: Large Image (compression requires zlib library)";

     

       143
       143
       -
         let orange_data = solid_color_rgba ~width:200 ~height:200 ~r:255 ~g:165 ~b:0 ~a:255 in

     

       139
       139
       +
         let orange_data =

     

       140
       140
       +
           solid_color_rgba ~width:200 ~height:200 ~r:255 ~g:165 ~b:0 ~a:255

     

       141
       141
       +
         in

     

       144
       142
        
         send

     

       145
       145
       -
           (K.Command.transmit_and_display

     

       146
       146
       -
              ~image_id:4

     

       147
       147
       -
              ~format:`Rgba32

     

       148
       148
       -
              ~width:200 ~height:200

     

       149
       149
       -
              ~quiet:`Errors_only

     

       150
       150
       -
              ())

     

       143
       143
       +
           (K.transmit_and_display ~image_id:4 ~format:`Rgba32 ~width:200 ~height:200

     

       144
       144
       +
              ~quiet:`Errors_only ())

     

       151
       145
        
           ~data:orange_data;

     

       152
       152
       -
         Printf.printf "Orange square (200x200) - %d bytes uncompressed\n" (String.length orange_data);

     

       146
       146
       +
         Printf.printf "Orange square (200x200) - %d bytes uncompressed\n"

     

       147
       147
       +
           (String.length orange_data);

     

       153
       148
        
         print_newline ();

     

       154
       149
        
         wait_for_enter ();

     

       155
       150
        
       

     

       156
       151
        
         (* Demo 5: Load and display external PNG file *)

     

       157
       152
        
         clear_screen ();

     

       158
       158
       -
         print_endline "Demo 5: Loading external PNG file (sf.png)";

     

       153
       153
       +
         print_endline "Demo 5: Loading external PNG file (camel.png)";

     

       159
       154
        
         (try

     

       160
       160
       -
            let png_data = read_file "sf.png" in

     

       155
       155
       +
            let png_data = read_file "camel.png" in

     

       161
       156
        
            send

     

       162
       162
       -
              (K.Command.transmit_and_display

     

       163
       163
       -
                 ~image_id:10

     

       164
       164
       -
                 ~format:`Png

     

       165
       165
       -
                 ~quiet:`Errors_only

     

       166
       166
       -
                 ())

     

       157
       157
       +
              (K.transmit_and_display ~image_id:10 ~format:`Png ~quiet:`Errors_only ())

     

       167
       158
        
              ~data:png_data;

     

       168
       168
       -
            print_endline "sf.png loaded and displayed"

     

       169
       169
       -
          with Sys_error msg ->

     

       170
       170
       -
            Printf.printf "sf.png not found: %s\n" msg);

     

       159
       159
       +
            print_endline "camel.png loaded and displayed"

     

       160
       160
       +
          with Sys_error msg -> Printf.printf "camel.png not found: %s\n" msg);

     

       171
       161
        
         print_newline ();

     

       172
       162
        
         wait_for_enter ();

     

       173
       163
        
       

     
···

       176
       166
        
         print_endline "Demo 6: Cropping and Scaling - Display part of an image";

     

       177
       167
        
         let gradient = gradient_rgba ~width:200 ~height:200 in

     

       178
       168
        
         send

     

       179
       179
       -
           (K.Command.transmit_and_display

     

       180
       180
       -
              ~image_id:20

     

       181
       181
       -
              ~format:`Rgba32

     

       182
       182
       -
              ~width:200 ~height:200

     

       183
       183
       -
              ~placement:(K.Placement.make

     

       184
       184
       -
                            ~source_x:50 ~source_y:50

     

       185
       185
       -
                            ~source_width:100 ~source_height:100

     

       186
       186
       -
                            ~columns:10 ~rows:10

     

       187
       187
       -
                            ())

     

       188
       188
       -
              ~quiet:`Errors_only

     

       189
       189
       -
              ())

     

       169
       169
       +
           (K.transmit_and_display ~image_id:20 ~format:`Rgba32 ~width:200 ~height:200

     

       170
       170
       +
              ~placement:

     

       171
       171
       +
                (K.Placement.make ~source_x:50 ~source_y:50 ~source_width:100

     

       172
       172
       +
                   ~source_height:100 ~columns:10 ~rows:10 ())

     

       173
       173
       +
              ~quiet:`Errors_only ())

     

       190
       174
        
           ~data:gradient;

     

       191
       175
        
         print_endline "Cropped to center 100x100 region of a 200x200 gradient";

     

       192
       176
        
         print_newline ();

     
···

       195
       179
        
         (* Demo 7: Multiple placements *)

     

       196
       180
        
         clear_screen ();

     

       197
       181
        
         print_endline "Demo 7: Multiple Placements - One image, multiple displays";

     

       198
       198
       -
         let cyan_data = solid_color_rgba ~width:80 ~height:80 ~r:0 ~g:255 ~b:255 ~a:255 in

     

       182
       182
       +
         let cyan_data =

     

       183
       183
       +
           solid_color_rgba ~width:80 ~height:80 ~r:0 ~g:255 ~b:255 ~a:255

     

       184
       184
       +
         in

     

       199
       185
        
         (* Transmit once with an ID *)

     

       200
       186
        
         send

     

       201
       201
       -
           (K.Command.transmit

     

       202
       202
       -
              ~image_id:100

     

       203
       203
       -
              ~format:`Rgba32

     

       204
       204
       -
              ~width:80 ~height:80

     

       205
       205
       -
              ~quiet:`Errors_only

     

       206
       206
       -
              ())

     

       187
       187
       +
           (K.transmit ~image_id:100 ~format:`Rgba32 ~width:80 ~height:80

     

       188
       188
       +
              ~quiet:`Errors_only ())

     

       207
       189
        
           ~data:cyan_data;

     

       208
       190
        
         (* Create first placement *)

     

       209
       191
        
         send

     

       210
       210
       -
           (K.Command.display

     

       211
       211
       -
              ~image_id:100

     

       192
       192
       +
           (K.display ~image_id:100

     

       212
       193
        
              ~placement:(K.Placement.make ~columns:10 ~rows:5 ())

     

       213
       213
       -
              ~quiet:`Errors_only

     

       214
       214
       -
              ())

     

       194
       194
       +
              ~quiet:`Errors_only ())

     

       215
       195
        
           ~data:"";

     

       216
       196
        
         (* Create second placement *)

     

       217
       197
        
         send

     

       218
       218
       -
           (K.Command.display

     

       219
       219
       -
              ~image_id:100

     

       198
       198
       +
           (K.display ~image_id:100

     

       220
       199
        
              ~placement:(K.Placement.make ~columns:5 ~rows:3 ())

     

       221
       221
       -
              ~quiet:`Errors_only

     

       222
       222
       -
              ())

     

       200
       200
       +
              ~quiet:`Errors_only ())

     

       223
       201
        
           ~data:"";

     

       224
       202
        
         print_newline ();

     

       225
       203
        
         wait_for_enter ();

     
···

       234
       212
        
         let grad_small = gradient_rgba ~width:100 ~height:100 in

     

       235
       213
        
         (* Transmit once *)

     

       236
       214
        
         send

     

       237
       237
       -
           (K.Command.transmit

     

       238
       238
       -
              ~image_id:160

     

       239
       239
       -
              ~format:`Rgba32

     

       240
       240
       -
              ~width:100 ~height:100

     

       241
       241
       -
              ~quiet:`Errors_only

     

       242
       242
       -
              ())

     

       215
       215
       +
           (K.transmit ~image_id:160 ~format:`Rgba32 ~width:100 ~height:100

     

       216
       216
       +
              ~quiet:`Errors_only ())

     

       243
       217
        
           ~data:grad_small;

     

       244
       218
        
         (* Place same image three times at different sizes *)

     

       245
       219
        
         send

     

       246
       246
       -
           (K.Command.display

     

       247
       247
       -
              ~image_id:160

     

       220
       220
       +
           (K.display ~image_id:160

     

       248
       221
        
              ~placement:(K.Placement.make ~columns:5 ~rows:5 ())

     

       249
       249
       -
              ~quiet:`Errors_only

     

       250
       250
       -
              ())

     

       222
       222
       +
              ~quiet:`Errors_only ())

     

       251
       223
        
           ~data:"";

     

       252
       224
        
         print_string "  ";

     

       253
       225
        
         send

     

       254
       254
       -
           (K.Command.display

     

       255
       255
       -
              ~image_id:160

     

       226
       226
       +
           (K.display ~image_id:160

     

       256
       227
        
              ~placement:(K.Placement.make ~columns:8 ~rows:8 ())

     

       257
       257
       -
              ~quiet:`Errors_only

     

       258
       258
       -
              ())

     

       228
       228
       +
              ~quiet:`Errors_only ())

     

       259
       229
        
           ~data:"";

     

       260
       230
        
         print_string "  ";

     

       261
       231
        
         send

     

       262
       262
       -
           (K.Command.display

     

       263
       263
       -
              ~image_id:160

     

       232
       232
       +
           (K.display ~image_id:160

     

       264
       233
        
              ~placement:(K.Placement.make ~columns:12 ~rows:12 ())

     

       265
       265
       -
              ~quiet:`Errors_only

     

       266
       266
       -
              ())

     

       234
       234
       +
              ~quiet:`Errors_only ())

     

       267
       235
        
           ~data:"";

     

       268
       236
        
         print_newline ();

     

       269
       237
        
         print_newline ();

     
···

       274
       242
        
         (* Demo 9: Z-index layering *)

     

       275
       243
        
         clear_screen ();

     

       276
       244
        
         print_endline "Demo 9: Z-Index Layering - Images above/below text";

     

       277
       277
       -
         let bg_data = solid_color_rgba ~width:200 ~height:100 ~r:255 ~g:165 ~b:0 ~a:128 in

     

       245
       245
       +
         let bg_data =

     

       246
       246
       +
           solid_color_rgba ~width:200 ~height:100 ~r:255 ~g:165 ~b:0 ~a:128

     

       247
       247
       +
         in

     

       278
       248
        
         send

     

       279
       279
       -
           (K.Command.transmit_and_display

     

       280
       280
       -
              ~image_id:200

     

       281
       281
       -
              ~format:`Rgba32

     

       282
       282
       -
              ~width:200 ~height:100

     

       249
       249
       +
           (K.transmit_and_display ~image_id:200 ~format:`Rgba32 ~width:200 ~height:100

     

       283
       250
        
              ~placement:(K.Placement.make ~z_index:(-1) ~cursor:`Static ())

     

       284
       284
       -
              ~quiet:`Errors_only

     

       285
       285
       -
              ())

     

       251
       251
       +
              ~quiet:`Errors_only ())

     

       286
       252
        
           ~data:bg_data;

     

       287
       253
        
         print_endline "This orange square should appear behind the text!";

     

       288
       254
        
         print_newline ();

     
···

       303
       269
        
         print_endline "Demo 11: Animation - Color-changing square";

     

       304
       270
        
         print_endline "Creating animated sequence with 4 colors...";

     

       305
       271
        
       

     

       306
       306
       -
         let width, height = 80, 80 in

     

       272
       272
       +
         let width, height = (80, 80) in

     

       307
       273
        
         let image_id = 300 in

     

       308
       274
        
       

     

       309
       275
        
         (* Create base frame (red) - transmit without displaying *)

     

       310
       276
        
         let red_frame = solid_color_rgba ~width ~height ~r:255 ~g:0 ~b:0 ~a:255 in

     

       311
       277
        
         send

     

       312
       312
       -
           (K.Command.transmit

     

       313
       313
       -
              ~image_id

     

       314
       314
       -
              ~format:`Rgba32

     

       315
       315
       -
              ~width ~height

     

       316
       316
       -
              ~quiet:`Errors_only

     

       317
       317
       -
              ())

     

       278
       278
       +
           (K.transmit ~image_id ~format:`Rgba32 ~width ~height ~quiet:`Errors_only ())

     

       318
       279
        
           ~data:red_frame;

     

       319
       280
        
       

     

       320
       281
        
         (* Add frames with composition replace *)

     

       321
       321
       -
         let orange_frame = solid_color_rgba ~width ~height ~r:255 ~g:165 ~b:0 ~a:255 in

     

       282
       282
       +
         let orange_frame =

     

       283
       283
       +
           solid_color_rgba ~width ~height ~r:255 ~g:165 ~b:0 ~a:255

     

       284
       284
       +
         in

     

       322
       285
        
         send

     

       323
       323
       -
           (K.Command.frame

     

       324
       324
       -
              ~image_id

     

       325
       325
       -
              ~format:`Rgba32

     

       326
       326
       -
              ~width ~height

     

       286
       286
       +
           (K.frame ~image_id ~format:`Rgba32 ~width ~height

     

       327
       287
        
              ~frame:(K.Frame.make ~gap_ms:100 ~composition:`Overwrite ())

     

       328
       328
       -
              ~quiet:`Errors_only

     

       329
       329
       -
              ())

     

       288
       288
       +
              ~quiet:`Errors_only ())

     

       330
       289
        
           ~data:orange_frame;

     

       331
       290
        
       

     

       332
       332
       -
         let yellow_frame = solid_color_rgba ~width ~height ~r:255 ~g:255 ~b:0 ~a:255 in

     

       291
       291
       +
         let yellow_frame =

     

       292
       292
       +
           solid_color_rgba ~width ~height ~r:255 ~g:255 ~b:0 ~a:255

     

       293
       293
       +
         in

     

       333
       294
        
         send

     

       334
       334
       -
           (K.Command.frame

     

       335
       335
       -
              ~image_id

     

       336
       336
       -
              ~format:`Rgba32

     

       337
       337
       -
              ~width ~height

     

       295
       295
       +
           (K.frame ~image_id ~format:`Rgba32 ~width ~height

     

       338
       296
        
              ~frame:(K.Frame.make ~gap_ms:100 ~composition:`Overwrite ())

     

       339
       339
       -
              ~quiet:`Errors_only

     

       340
       340
       -
              ())

     

       297
       297
       +
              ~quiet:`Errors_only ())

     

       341
       298
        
           ~data:yellow_frame;

     

       342
       299
        
       

     

       343
       300
        
         let green_frame = solid_color_rgba ~width ~height ~r:0 ~g:255 ~b:0 ~a:255 in

     

       344
       301
        
         send

     

       345
       345
       -
           (K.Command.frame

     

       346
       346
       -
              ~image_id

     

       347
       347
       -
              ~format:`Rgba32

     

       348
       348
       -
              ~width ~height

     

       302
       302
       +
           (K.frame ~image_id ~format:`Rgba32 ~width ~height

     

       349
       303
        
              ~frame:(K.Frame.make ~gap_ms:100 ~composition:`Overwrite ())

     

       350
       350
       -
              ~quiet:`Errors_only

     

       351
       351
       -
              ())

     

       304
       304
       +
              ~quiet:`Errors_only ())

     

       352
       305
        
           ~data:green_frame;

     

       353
       306
        
       

     

       354
       307
        
         (* Create placement and start animation *)

     

       355
       308
        
         send

     

       356
       356
       -
           (K.Command.display

     

       357
       357
       -
              ~image_id

     

       358
       358
       -
              ~placement:(K.Placement.make

     

       359
       359
       -
                            ~placement_id:1

     

       360
       360
       -
                            ~cell_x_offset:0

     

       361
       361
       -
                            ~cell_y_offset:0

     

       362
       362
       -
                            ~cursor:`Static

     

       363
       363
       -
                            ())

     

       364
       364
       -
              ~quiet:`Errors_only

     

       365
       365
       -
              ())

     

       309
       309
       +
           (K.display ~image_id

     

       310
       310
       +
              ~placement:

     

       311
       311
       +
                (K.Placement.make ~placement_id:1 ~cell_x_offset:0 ~cell_y_offset:0

     

       312
       312
       +
                   ~cursor:`Static ())

     

       313
       313
       +
              ~quiet:`Errors_only ())

     

       366
       314
        
           ~data:"";

     

       367
       315
        
       

     

       368
       316
        
         (* Set root frame gap - root frame has no gap by default per Kitty protocol *)

     

       369
       369
       -
         send

     

       370
       370
       -
           (K.Command.animate ~image_id (K.Animation.set_gap ~frame:1 ~gap_ms:100))

     

       371
       371
       -
           ~data:"";

     

       317
       317
       +
         send (K.animate ~image_id (K.Animation.set_gap ~frame:1 ~gap_ms:100)) ~data:"";

     

       372
       318
        
       

     

       373
       319
        
         (* Start animation with infinite looping *)

     

       374
       374
       -
         send

     

       375
       375
       -
           (K.Command.animate ~image_id (K.Animation.set_state ~loops:1 `Run))

     

       376
       376
       -
           ~data:"";

     

       320
       320
       +
         send (K.animate ~image_id (K.Animation.set_state ~loops:1 `Run)) ~data:"";

     

       377
       321
        
       

     

       378
       322
        
         print_newline ();

     

       379
       379
       -
         print_endline "Animation playing with colors: Red -> Orange -> Yellow -> Green";

     

       323
       323
       +
         print_endline

     

       324
       324
       +
           "Animation playing with colors: Red -> Orange -> Yellow -> Green";

     

       380
       325
        
         print_newline ();

     

       381
       326
        
       

     

       382
       327
        
         (* Simulate movement by deleting and recreating placement at different positions *)

     
···

       384
       329
        
           Unix.sleepf 0.4;

     

       385
       330
        
       

     

       386
       331
        
           (* Delete the current placement *)

     

       387
       387
       -
           send

     

       388
       388
       -
             (K.Command.delete ~quiet:`Errors_only (`By_id (image_id, Some 1)))

     

       389
       389
       -
             ~data:"";

     

       332
       332
       +
           send (K.delete ~quiet:`Errors_only (`By_id (image_id, Some 1))) ~data:"";

     

       390
       333
        
       

     

       391
       334
        
           (* Create new placement at next position *)

     

       392
       335
        
           send

     

       393
       393
       -
             (K.Command.display

     

       394
       394
       -
                ~image_id

     

       395
       395
       -
                ~placement:(K.Placement.make

     

       396
       396
       -
                              ~placement_id:1

     

       397
       397
       -
                              ~cell_x_offset:(i * 5)

     

       398
       398
       -
                              ~cell_y_offset:0

     

       399
       399
       -
                              ~cursor:`Static

     

       400
       400
       -
                              ())

     

       401
       401
       -
                ~quiet:`Errors_only

     

       402
       402
       -
                ())

     

       336
       336
       +
             (K.display ~image_id

     

       337
       337
       +
                ~placement:

     

       338
       338
       +
                  (K.Placement.make ~placement_id:1 ~cell_x_offset:(i * 5)

     

       339
       339
       +
                     ~cell_y_offset:0 ~cursor:`Static ())

     

       340
       340
       +
                ~quiet:`Errors_only ())

     

       403
       341
        
             ~data:""

     

       404
       342
        
         done;

     

       405
       343
        
       

     

       406
       344
        
         (* Stop the animation *)

     

       407
       407
       -
         send

     

       408
       408
       -
           (K.Command.animate ~image_id (K.Animation.set_state `Stop))

     

       409
       409
       -
           ~data:"";

     

       345
       345
       +
         send (K.animate ~image_id (K.Animation.set_state `Stop)) ~data:"";

     

       410
       346
        
       

     

       411
       347
        
         print_endline "Animation stopped.";

     

       412
       348
        
         print_newline ();

-59

example/test_output.ml

···

       1
       1
       -
       (* Simple test to show exact escape sequences without data *)

     

       2
       2
       -
       

     

       3
       3
       -
       module K = Kgp

     

       4
       4
       -
       

     

       5
       5
       -
       let print_escaped s =

     

       6
       6
       -
         String.iter (fun c ->

     

       7
       7
       -
           let code = Char.code c in

     

       8
       8
       -
           if code = 27 then print_string "\\x1b"

     

       9
       9
       -
           else if code < 32 || code > 126 then Printf.printf "\\x%02x" code

     

       10
       10
       -
           else print_char c

     

       11
       11
       -
         ) s;

     

       12
       12
       -
         print_newline ()

     

       13
       13
       -
       

     

       14
       14
       -
       let () =

     

       15
       15
       -
         let image_id = 300 in

     

       16
       16
       -
         let width, height = 80, 80 in

     

       17
       17
       -
       

     

       18
       18
       -
         print_endline "=== Animation Escape Sequences (no data) ===\n";

     

       19
       19
       -
       

     

       20
       20
       -
         (* 1. Transmit base frame (no data for testing) *)

     

       21
       21
       -
         print_endline "1. Transmit (a=t):";

     

       22
       22
       -
         let cmd1 = K.Command.transmit

     

       23
       23
       -
           ~image_id ~format:`Rgba32 ~width ~height ~quiet:`Errors_only () in

     

       24
       24
       -
         print_escaped (K.Command.to_string cmd1 ~data:"");

     

       25
       25
       -
       

     

       26
       26
       -
         (* 2. Frame command *)

     

       27
       27
       -
         print_endline "\n2. Frame (a=f):";

     

       28
       28
       -
         let cmd2 = K.Command.frame

     

       29
       29
       -
           ~image_id ~format:`Rgba32 ~width ~height

     

       30
       30
       -
           ~frame:(K.Frame.make ~gap_ms:100 ~composition:`Overwrite ())

     

       31
       31
       -
           ~quiet:`Errors_only () in

     

       32
       32
       -
         print_escaped (K.Command.to_string cmd2 ~data:"");

     

       33
       33
       -
       

     

       34
       34
       -
         (* 3. Put/display command *)

     

       35
       35
       -
         print_endline "\n3. Display/Put (a=p):";

     

       36
       36
       -
         let cmd3 = K.Command.display

     

       37
       37
       -
           ~image_id

     

       38
       38
       -
           ~placement:(K.Placement.make

     

       39
       39
       -
             ~placement_id:1

     

       40
       40
       -
             ~cell_x_offset:0

     

       41
       41
       -
             ~cell_y_offset:0

     

       42
       42
       -
             ~cursor:`Static ())

     

       43
       43
       -
           ~quiet:`Errors_only () in

     

       44
       44
       -
         print_escaped (K.Command.to_string cmd3 ~data:"");

     

       45
       45
       -
       

     

       46
       46
       -
         (* 4. Set root frame gap - IMPORTANT for animation! *)

     

       47
       47
       -
         print_endline "\n4. Set root frame gap (a=a, r=1, z=100):";

     

       48
       48
       -
         let cmd4 = K.Command.animate ~image_id (K.Animation.set_gap ~frame:1 ~gap_ms:100) in

     

       49
       49
       -
         print_escaped (K.Command.to_string cmd4 ~data:"");

     

       50
       50
       -
       

     

       51
       51
       -
         (* 5. Animate - start *)

     

       52
       52
       -
         print_endline "\n5. Animate start (a=a, s=3, v=1):";

     

       53
       53
       -
         let cmd5 = K.Command.animate ~image_id (K.Animation.set_state ~loops:1 `Run) in

     

       54
       54
       -
         print_escaped (K.Command.to_string cmd5 ~data:"");

     

       55
       55
       -
       

     

       56
       56
       -
         (* 6. Animate - stop *)

     

       57
       57
       -
         print_endline "\n6. Animate stop (a=a, s=1):";

     

       58
       58
       -
         let cmd6 = K.Command.animate ~image_id (K.Animation.set_state `Stop) in

     

       59
       59
       -
         print_escaped (K.Command.to_string cmd6 ~data:"")

+33 -50

example/tiny_anim.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       (* Tiny animation test - no chunking needed *)

     

       2
       7
        
       (* Uses 20x20 images which are ~1067 bytes base64 (well under 4096) *)

     

       3
       8
        
       

     
···

       15
       20
        
         Bytes.to_string pixels

     

       16
       21
        
       

     

       17
       22
        
       let send cmd ~data =

     

       18
       18
       -
         print_string (K.Command.to_string cmd ~data);

     

       23
       23
       +
         print_string (K.to_string cmd ~data);

     

       19
       24
        
         flush stdout

     

       20
       25
        
       

     

       21
       26
        
       let () =

     

       22
       27
        
         (* Use 20x20 to avoid chunking: 20*20*4 = 1600 bytes, base64 ~2134 bytes *)

     

       23
       23
       -
         let width, height = 20, 20 in

     

       28
       28
       +
         let width, height = (20, 20) in

     

       24
       29
        
         let image_id = 999 in

     

       25
       30
        
       

     

       26
       31
        
         (* Clear any existing images *)

     

       27
       27
       -
         send (K.Command.delete ~quiet:`Errors_only (`All_visible_and_free)) ~data:"";

     

       32
       32
       +
         send (K.delete ~free:true ~quiet:`Errors_only `All_visible) ~data:"";

     

       28
       33
        
       

     

       29
       29
       -
         (* Step 1: Transmit base frame (red) - matching Go's sequence *)

     

       34
       34
       +
         (* Step 1: Transmit base frame (red) *)

     

       30
       35
        
         let red_frame = solid_color_rgba ~width ~height ~r:255 ~g:0 ~b:0 ~a:255 in

     

       31
       36
        
         send

     

       32
       32
       -
           (K.Command.transmit

     

       33
       33
       -
              ~image_id

     

       34
       34
       -
              ~format:`Rgba32

     

       35
       35
       -
              ~width ~height

     

       36
       36
       -
              ~quiet:`Errors_only

     

       37
       37
       -
              ())

     

       37
       37
       +
           (K.transmit ~image_id ~format:`Rgba32 ~width ~height ~quiet:`Errors_only ())

     

       38
       38
        
           ~data:red_frame;

     

       39
       39
        
       

     

       40
       40
       -
         (* Step 2: Add frame (orange) with 100ms gap - like Go *)

     

       41
       41
       -
         let orange_frame = solid_color_rgba ~width ~height ~r:255 ~g:165 ~b:0 ~a:255 in

     

       40
       40
       +
         (* Step 2: Add frame (orange) with 100ms gap *)

     

       41
       41
       +
         let orange_frame =

     

       42
       42
       +
           solid_color_rgba ~width ~height ~r:255 ~g:165 ~b:0 ~a:255

     

       43
       43
       +
         in

     

       42
       44
        
         send

     

       43
       43
       -
           (K.Command.frame

     

       44
       44
       -
              ~image_id

     

       45
       45
       -
              ~format:`Rgba32

     

       46
       46
       -
              ~width ~height

     

       45
       45
       +
           (K.frame ~image_id ~format:`Rgba32 ~width ~height

     

       47
       46
        
              ~frame:(K.Frame.make ~gap_ms:100 ~composition:`Overwrite ())

     

       48
       48
       -
              ~quiet:`Errors_only

     

       49
       49
       -
              ())

     

       47
       47
       +
              ~quiet:`Errors_only ())

     

       50
       48
        
           ~data:orange_frame;

     

       51
       49
        
       

     

       52
       50
        
         (* Step 3: Add frame (yellow) *)

     

       53
       53
       -
         let yellow_frame = solid_color_rgba ~width ~height ~r:255 ~g:255 ~b:0 ~a:255 in

     

       51
       51
       +
         let yellow_frame =

     

       52
       52
       +
           solid_color_rgba ~width ~height ~r:255 ~g:255 ~b:0 ~a:255

     

       53
       53
       +
         in

     

       54
       54
        
         send

     

       55
       55
       -
           (K.Command.frame

     

       56
       56
       -
              ~image_id

     

       57
       57
       -
              ~format:`Rgba32

     

       58
       58
       -
              ~width ~height

     

       55
       55
       +
           (K.frame ~image_id ~format:`Rgba32 ~width ~height

     

       59
       56
        
              ~frame:(K.Frame.make ~gap_ms:100 ~composition:`Overwrite ())

     

       60
       60
       -
              ~quiet:`Errors_only

     

       61
       61
       -
              ())

     

       57
       57
       +
              ~quiet:`Errors_only ())

     

       62
       58
        
           ~data:yellow_frame;

     

       63
       59
        
       

     

       64
       60
        
         (* Step 4: Add frame (green) *)

     

       65
       61
        
         let green_frame = solid_color_rgba ~width ~height ~r:0 ~g:255 ~b:0 ~a:255 in

     

       66
       62
        
         send

     

       67
       67
       -
           (K.Command.frame

     

       68
       68
       -
              ~image_id

     

       69
       69
       -
              ~format:`Rgba32

     

       70
       70
       -
              ~width ~height

     

       63
       63
       +
           (K.frame ~image_id ~format:`Rgba32 ~width ~height

     

       71
       64
        
              ~frame:(K.Frame.make ~gap_ms:100 ~composition:`Overwrite ())

     

       72
       72
       -
              ~quiet:`Errors_only

     

       73
       73
       -
              ())

     

       65
       65
       +
              ~quiet:`Errors_only ())

     

       74
       66
        
           ~data:green_frame;

     

       75
       67
        
       

     

       76
       76
       -
         (* Step 5: Create placement - exactly like Go *)

     

       68
       68
       +
         (* Step 5: Create placement *)

     

       77
       69
        
         send

     

       78
       78
       -
           (K.Command.display

     

       79
       79
       -
              ~image_id

     

       80
       80
       -
              ~placement:(K.Placement.make

     

       81
       81
       -
                            ~placement_id:1

     

       82
       82
       -
                            ~cell_x_offset:0

     

       83
       83
       -
                            ~cell_y_offset:0

     

       84
       84
       -
                            ~cursor:`Static

     

       85
       85
       -
                            ())

     

       86
       86
       -
              ~quiet:`Errors_only

     

       87
       87
       -
              ())

     

       70
       70
       +
           (K.display ~image_id

     

       71
       71
       +
              ~placement:

     

       72
       72
       +
                (K.Placement.make ~placement_id:1 ~cell_x_offset:0 ~cell_y_offset:0

     

       73
       73
       +
                   ~cursor:`Static ())

     

       74
       74
       +
              ~quiet:`Errors_only ())

     

       88
       75
        
           ~data:"";

     

       89
       76
        
       

     

       90
       90
       -
         (* Step 6: Start animation - exactly like Go (NO root frame gap) *)

     

       91
       91
       -
         send

     

       92
       92
       -
           (K.Command.animate ~image_id (K.Animation.set_state ~loops:1 `Run))

     

       93
       93
       -
           ~data:"";

     

       77
       77
       +
         (* Step 6: Start animation *)

     

       78
       78
       +
         send (K.animate ~image_id (K.Animation.set_state ~loops:1 `Run)) ~data:"";

     

       94
       79
        
       

     

       95
       80
        
         print_endline "";

     

       96
       81
        
         print_endline "Tiny animation (20x20) - Red -> Orange -> Yellow -> Green";

     
···

       99
       84
        
         let _ = read_line () in

     

       100
       85
        
       

     

       101
       86
        
         (* Stop animation *)

     

       102
       102
       -
         send

     

       103
       103
       -
           (K.Command.animate ~image_id (K.Animation.set_state `Stop))

     

       104
       104
       -
           ~data:"";

     

       87
       87
       +
         send (K.animate ~image_id (K.Animation.set_state `Stop)) ~data:"";

     

       105
       88
        
       

     

       106
       89
        
         (* Clean up *)

     

       107
       107
       -
         send (K.Command.delete ~quiet:`Errors_only (`All_visible_and_free)) ~data:"";

     

       90
       90
       +
         send (K.delete ~free:true ~quiet:`Errors_only `All_visible) ~data:"";

     

       108
       91
        
         print_endline "Done."

+32

kgp.opam

···

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

     

       2
       2
       +
       opam-version: "2.0"

     

       3
       3
       +
       synopsis: "OCaml implementation of the Kitty terminal graphics protocol"

     

       4
       4
       +
       description:

     

       5
       5
       +
         "Library for rendering images in terminals that support the Kitty graphics protocol. Supports image transmission, display, animation, Unicode placeholders, and terminal capability detection."

     

       6
       6
       +
       maintainer: ["Anil Madhavapeddy <anil@recoil.org>"]

     

       7
       7
       +
       authors: ["Anil Madhavapeddy"]

     

       8
       8
       +
       license: "ISC"

     

       9
       9
       +
       homepage: "https://tangled.org/@anil.recoil.org/ocaml-kgp"

     

       10
       10
       +
       bug-reports: "https://tangled.org/@anil.recoil.org/ocaml-kgp/issues"

     

       11
       11
       +
       depends: [

     

       12
       12
       +
         "dune" {>= "3.20"}

     

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

     

       14
       14
       +
         "cmdliner"

     

       15
       15
       +
         "base64"

     

       16
       16
       +
         "odoc" {with-doc}

     

       17
       17
       +
       ]

     

       18
       18
       +
       build: [

     

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

     

       20
       20
       +
         [

     

       21
       21
       +
           "dune"

     

       22
       22
       +
           "build"

     

       23
       23
       +
           "-p"

     

       24
       24
       +
           name

     

       25
       25
       +
           "-j"

     

       26
       26
       +
           jobs

     

       27
       27
       +
           "@install"

     

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

     

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

     

       30
       30
       +
         ]

     

       31
       31
       +
       ]

     

       32
       32
       +
       x-maintenance-intent: ["(latest)"]

+1 -1

lib/dune

···

       1
       1
        
       (library

     

       2
       2
        
        (name kgp)

     

       3
       3
        
        (public_name kgp)

     

       4
       4
       -
        (libraries base64))

     

       4
       4
       +
        (libraries base64 unix))

+23 -7

lib/kgp.ml

···

       1
       1
       -
       (* Kitty Terminal Graphics Protocol - Main Module *)

     

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       2
       5
        
       

     

       3
       3
       -
       (* Type modules *)

     

       4
       6
        
       module Format = Kgp_format

     

       5
       7
        
       module Transmission = Kgp_transmission

     

       6
       8
        
       module Compression = Kgp_compression

     
···

       9
       11
        
       module Composition = Kgp_composition

     

       10
       12
        
       module Delete = Kgp_delete

     

       11
       13
        
       module Animation_state = Kgp_animation_state

     

       12
       12
       -
       

     

       13
       13
       -
       (* Configuration modules *)

     

       14
       14
        
       module Placement = Kgp_placement

     

       15
       15
        
       module Frame = Kgp_frame

     

       16
       16
        
       module Animation = Kgp_animation

     

       17
       17
        
       module Compose = Kgp_compose

     

       18
       18
        
       

     

       19
       19
       -
       (* Core modules *)

     

       20
       20
       -
       module Command = Kgp_command

     

       19
       19
       +
       type command = Kgp_command.t

     

       20
       20
       +
       

     

       21
       21
       +
       let transmit = Kgp_command.transmit

     

       22
       22
       +
       let transmit_and_display = Kgp_command.transmit_and_display

     

       23
       23
       +
       let query = Kgp_command.query

     

       24
       24
       +
       let display = Kgp_command.display

     

       25
       25
       +
       let delete = Kgp_command.delete

     

       26
       26
       +
       let frame = Kgp_command.frame

     

       27
       27
       +
       let animate = Kgp_command.animate

     

       28
       28
       +
       let compose = Kgp_command.compose

     

       29
       29
       +
       let write = Kgp_command.write

     

       30
       30
       +
       let to_string = Kgp_command.to_string

     

       31
       31
       +
       let write_tmux = Kgp_command.write_tmux

     

       32
       32
       +
       let to_string_tmux = Kgp_command.to_string_tmux

     

       33
       33
       +
       

     

       21
       34
        
       module Response = Kgp_response

     

       22
       35
        
       

     

       23
       23
       -
       (* Utility modules *)

     

       36
       36
       +
       let next_image_id = Kgp_unicode.next_image_id

     

       37
       37
       +
       

     

       24
       38
        
       module Unicode_placeholder = Kgp_unicode

     

       25
       39
        
       module Detect = Kgp_detect

     

       40
       40
       +
       module Tmux = Kgp_tmux

     

       41
       41
       +
       module Terminal = Kgp_terminal

+337 -13

lib/kgp.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       (** Kitty Terminal Graphics Protocol

     

       2
       7
        
       

     

       3
       3
       -
           This library implements the Kitty terminal graphics protocol, allowing

     

       4
       4
       -
           OCaml programs to display images in terminals that support the protocol

     

       5
       5
       -
           (Kitty, WezTerm, Konsole, Ghostty, etc.).

     

       8
       8
       +
           This library implements the Kitty terminal graphics protocol, allowing OCaml

     

       9
       9
       +
           programs to display images in terminals that support the protocol (Kitty,

     

       10
       10
       +
           WezTerm, Konsole, Ghostty, etc.).

     

       6
       11
        
       

     

       7
       7
       -
           The protocol uses APC (Application Programming Command) escape sequences

     

       8
       8
       -
           to transmit and display pixel graphics. Images can be transmitted as raw

     

       9
       9
       -
           RGB/RGBA data or PNG, and displayed at specific positions with various

     

       10
       10
       -
           placement options.

     

       12
       12
       +
           {1 Protocol Overview}

     

       13
       13
       +
       

     

       14
       14
       +
           The Kitty Graphics Protocol is a flexible, performant protocol for rendering

     

       15
       15
       +
           arbitrary pixel (raster) graphics in terminal emulators. Key features:

     

       16
       16
       +
       

     

       17
       17
       +
           - No requirement for terminal emulators to understand image formats

     

       18
       18
       +
           - Pixel-level positioning of graphics

     

       19
       19
       +
           - Integration with text (graphics can be drawn below/above text with alpha

     

       20
       20
       +
             blending)

     

       21
       21
       +
           - Automatic scrolling with text

     

       22
       22
       +
           - Animation support with frame deltas for efficiency

     

       23
       23
       +
       

     

       24
       24
       +
           {2 Escape Sequence Format}

     

       25
       25
       +
       

     

       26
       26
       +
           All graphics commands use the Application Programming Command (APC) format:

     

       27
       27
       +
       

     

       28
       28
       +
           {v <ESC>_G<control data>;<payload><ESC> v}

     

       29
       29
       +
       

     

       30
       30
       +
           Where:

     

       31
       31
       +
           - [ESC _G] is the APC start sequence (bytes 0x1B 0x5F 0x47)

     

       32
       32
       +
           - Control data is comma-separated key=value pairs

     

       33
       33
       +
           - Payload is base64-encoded binary data (RFC-4648)

     

       34
       34
       +
           - [ESC] is the APC terminator (bytes 0x1B 0x5C)

     

       35
       35
       +
       

     

       36
       36
       +
           Most terminal emulators ignore unrecognized APC sequences, making the

     

       37
       37
       +
           protocol safe to use even in unsupported terminals.

     

       38
       38
       +
       

     

       39
       39
       +
           {2 Terminal Responses}

     

       40
       40
       +
       

     

       41
       41
       +
           When an image ID is specified, the terminal responds:

     

       42
       42
       +
           - On success: [ESC _Gi=ID;OK ESC]

     

       43
       43
       +
           - On failure: [ESC _Gi=ID;error ESC]

     

       44
       44
       +
       

     

       45
       45
       +
           Common error codes include [ENOENT] (image not found), [EINVAL] (invalid

     

       46
       46
       +
           parameter), and [ENOSPC] (storage quota exceeded).

     

       47
       47
       +
       

     

       48
       48
       +
           {2 Image Storage}

     

       49
       49
       +
       

     

       50
       50
       +
           Terminal emulators maintain a storage quota for images (typically ~320MB).

     

       51
       51
       +
           When the quota is exceeded, older images are deleted to make room for new

     

       52
       52
       +
           ones. Images without active placements are preferred for deletion.

     

       53
       53
       +
       

     

       54
       54
       +
           For animations, frame data is stored separately with a larger quota

     

       55
       55
       +
           (typically 5x the base quota).

     

       11
       56
        
       

     

       12
       57
        
           {2 Basic Usage}

     

       13
       58
        
       

     

       14
       59
        
           {[

     

       15
       60
        
             (* Display a PNG image *)

     

       16
       61
        
             let png_data = read_file "image.png" in

     

       17
       17
       -
             let cmd = Kgp.Command.transmit_and_display ~format:`Png () in

     

       62
       62
       +
             let cmd = Kgp.transmit_and_display ~format:`Png () in

     

       18
       63
        
             let buf = Buffer.create 1024 in

     

       19
       19
       -
             Kgp.Command.write buf cmd ~data:png_data;

     

       64
       64
       +
             Kgp.write buf cmd ~data:png_data;

     

       20
       65
        
             print_string (Buffer.contents buf)

     

       21
       66
        
           ]}

     

       22
       67
        
       

     

       68
       68
       +
           {[

     

       69
       69
       +
             (* Transmit an image, then display it multiple times *)

     

       70
       70
       +
             let png_data = read_file "icon.png" in

     

       71
       71
       +
             let cmd = Kgp.transmit ~image_id:1 ~format:`Png () in

     

       72
       72
       +
             Kgp.write buf cmd ~data:png_data;

     

       73
       73
       +
       

     

       74
       74
       +
             (* Display at different positions *)

     

       75
       75
       +
             let cmd = Kgp.display ~image_id:1 () in

     

       76
       76
       +
             Kgp.write buf cmd ~data:""

     

       77
       77
       +
           ]}

     

       78
       78
       +
       

     

       23
       79
        
           {2 Protocol Reference}

     

       24
       80
        
       

     

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

     

       26
       26
       -
           for the full specification. *)

     

       81
       81
       +
           See

     

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

     

       83
       83
       +
            Protocol} for the full specification. *)

     

       27
       84
        
       

     

       28
       85
        
       (** {1 Type Modules} *)

     

       29
       86
        
       

     
···

       43
       100
        
       module Animation = Kgp_animation

     

       44
       101
        
       module Compose = Kgp_compose

     

       45
       102
        
       

     

       46
       46
       -
       (** {1 Command and Response} *)

     

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

     

       104
       104
       +
       

     

       105
       105
       +
       type command = Kgp_command.t

     

       106
       106
       +
       (** A graphics protocol command. Commands are built using the functions below

     

       107
       107
       +
           and then serialized using {!write} or {!to_string}. *)

     

       108
       108
       +
       

     

       109
       109
       +
       (** {2 Image Transmission}

     

       110
       110
       +
       

     

       111
       111
       +
           Images can be transmitted to the terminal for storage and later display. The

     

       112
       112
       +
           terminal assigns storage and responds with success or failure.

     

       113
       113
       +
       

     

       114
       114
       +
           For large images, the library automatically handles chunked transmission

     

       115
       115
       +
           (splitting data into 4096-byte base64-encoded chunks). *)

     

       116
       116
       +
       

     

       117
       117
       +
       val transmit :

     

       118
       118
       +
         ?image_id:int ->

     

       119
       119
       +
         ?image_number:int ->

     

       120
       120
       +
         ?format:Format.t ->

     

       121
       121
       +
         ?transmission:Transmission.t ->

     

       122
       122
       +
         ?compression:Compression.t ->

     

       123
       123
       +
         ?width:int ->

     

       124
       124
       +
         ?height:int ->

     

       125
       125
       +
         ?size:int ->

     

       126
       126
       +
         ?offset:int ->

     

       127
       127
       +
         ?quiet:Quiet.t ->

     

       128
       128
       +
         unit ->

     

       129
       129
       +
         command

     

       130
       130
       +
       (** Transmit image data without displaying.

     

       131
       131
       +
       

     

       132
       132
       +
           The image is stored by the terminal and can be displayed later using

     

       133
       133
       +
           {!val:display} with the same [image_id].

     

       134
       134
       +
       

     

       135
       135
       +
           @param image_id

     

       136
       136
       +
             Unique identifier (1-4294967295) for later reference. If specified, the

     

       137
       137
       +
             terminal responds with success/failure.

     

       138
       138
       +
           @param image_number

     

       139
       139
       +
             Alternative to [image_id] where the terminal assigns a unique ID and

     

       140
       140
       +
             returns it in the response. Useful when multiple programs share the

     

       141
       141
       +
             terminal.

     

       142
       142
       +
           @param format Pixel format of the data. Default is [`Rgba32].

     

       143
       143
       +
           @param transmission How data is sent. Default is [`Direct] (inline).

     

       144
       144
       +
           @param compression Compression applied to data. Default is [`None].

     

       145
       145
       +
           @param width Image width in pixels (required for raw RGB/RGBA formats).

     

       146
       146
       +
           @param height Image height in pixels (required for raw RGB/RGBA formats).

     

       147
       147
       +
           @param size Size in bytes when reading from file.

     

       148
       148
       +
           @param offset Byte offset when reading from file.

     

       149
       149
       +
           @param quiet Response suppression level. *)

     

       150
       150
       +
       

     

       151
       151
       +
       val transmit_and_display :

     

       152
       152
       +
         ?image_id:int ->

     

       153
       153
       +
         ?image_number:int ->

     

       154
       154
       +
         ?format:Format.t ->

     

       155
       155
       +
         ?transmission:Transmission.t ->

     

       156
       156
       +
         ?compression:Compression.t ->

     

       157
       157
       +
         ?width:int ->

     

       158
       158
       +
         ?height:int ->

     

       159
       159
       +
         ?size:int ->

     

       160
       160
       +
         ?offset:int ->

     

       161
       161
       +
         ?quiet:Quiet.t ->

     

       162
       162
       +
         ?placement:Placement.t ->

     

       163
       163
       +
         unit ->

     

       164
       164
       +
         command

     

       165
       165
       +
       (** Transmit image data and display it immediately.

     

       166
       166
       +
       

     

       167
       167
       +
           Combines transmission and display in a single command. The image is rendered

     

       168
       168
       +
           at the current cursor position unless placement options specify otherwise.

     

       169
       169
       +
       

     

       170
       170
       +
           See {!transmit} for parameter descriptions. The [placement] parameter

     

       171
       171
       +
           controls display position and scaling. *)

     

       172
       172
       +
       

     

       173
       173
       +
       val query :

     

       174
       174
       +
         ?format:Format.t ->

     

       175
       175
       +
         ?transmission:Transmission.t ->

     

       176
       176
       +
         ?width:int ->

     

       177
       177
       +
         ?height:int ->

     

       178
       178
       +
         ?quiet:Quiet.t ->

     

       179
       179
       +
         unit ->

     

       180
       180
       +
         command

     

       181
       181
       +
       (** Query terminal support without storing the image.

     

       182
       182
       +
       

     

       183
       183
       +
           Performs the same validation as {!transmit} but does not store the image.

     

       184
       184
       +
           Useful for testing whether the terminal supports the graphics protocol and

     

       185
       185
       +
           specific formats.

     

       186
       186
       +
       

     

       187
       187
       +
           To detect graphics support, send a query and check for a response:

     

       188
       188
       +
           {[

     

       189
       189
       +
             (* Send query with a tiny 1x1 RGB image *)

     

       190
       190
       +
             let cmd = Kgp.query ~format:`Rgb24 ~width:1 ~height:1 () in

     

       191
       191
       +
             Kgp.write buf cmd ~data:"\x00\x00\x00"

     

       192
       192
       +
             (* If terminal responds, it supports the protocol *)

     

       193
       193
       +
           ]} *)

     

       194
       194
       +
       

     

       195
       195
       +
       (** {2 Display}

     

       47
       196
        
       

     

       48
       48
       -
       module Command = Kgp_command

     

       197
       197
       +
           Previously transmitted images can be displayed multiple times at different

     

       198
       198
       +
           positions with different cropping and scaling options. *)

     

       199
       199
       +
       

     

       200
       200
       +
       val display :

     

       201
       201
       +
         ?image_id:int ->

     

       202
       202
       +
         ?image_number:int ->

     

       203
       203
       +
         ?placement:Placement.t ->

     

       204
       204
       +
         ?quiet:Quiet.t ->

     

       205
       205
       +
         unit ->

     

       206
       206
       +
         command

     

       207
       207
       +
       (** Display a previously transmitted image.

     

       208
       208
       +
       

     

       209
       209
       +
           The image is rendered at the current cursor position. Use [placement] to

     

       210
       210
       +
           control cropping, scaling, z-index, and other display options.

     

       211
       211
       +
       

     

       212
       212
       +
           Each display creates a "placement" of the image. Multiple placements of the

     

       213
       213
       +
           same image share the underlying image data.

     

       214
       214
       +
       

     

       215
       215
       +
           @param image_id ID of a previously transmitted image.

     

       216
       216
       +
           @param image_number

     

       217
       217
       +
             Image number (acts on the newest image with this number).

     

       218
       218
       +
           @param placement Display configuration (position, size, z-index, etc.). *)

     

       219
       219
       +
       

     

       220
       220
       +
       (** {2 Deletion}

     

       221
       221
       +
       

     

       222
       222
       +
           Images and placements can be deleted to free terminal resources. By default,

     

       223
       223
       +
           only placements are removed and image data is retained for potential reuse.

     

       224
       224
       +
           Use [~free:true] to also release the image data. *)

     

       225
       225
       +
       

     

       226
       226
       +
       val delete : ?free:bool -> ?quiet:Quiet.t -> Delete.t -> command

     

       227
       227
       +
       (** Delete images or placements.

     

       228
       228
       +
       

     

       229
       229
       +
           See {!Delete} for the full list of deletion targets.

     

       230
       230
       +
       

     

       231
       231
       +
           @param free

     

       232
       232
       +
             If true, also free the image data from memory (default: false). Without

     

       233
       233
       +
             [~free:true], only placements are removed and the image data can be reused

     

       234
       234
       +
             for new placements.

     

       235
       235
       +
       

     

       236
       236
       +
           Examples:

     

       237
       237
       +
           {[

     

       238
       238
       +
             (* Delete all visible images, keep data *)

     

       239
       239
       +
             Kgp.delete `All_visible

     

       240
       240
       +
               (* Delete specific image, keeping data for reuse *)

     

       241
       241
       +
               Kgp.delete

     

       242
       242
       +
               (`By_id (42, None))

     

       243
       243
       +
               (* Delete specific image and free its data *)

     

       244
       244
       +
               Kgp.delete ~free:true

     

       245
       245
       +
               (`By_id (42, None))

     

       246
       246
       +
               (* Delete all placements at a specific cell *)

     

       247
       247
       +
               Kgp.delete

     

       248
       248
       +
               (`At_cell (10, 5))

     

       249
       249
       +
           ]} *)

     

       250
       250
       +
       

     

       251
       251
       +
       (** {2 Animation}

     

       252
       252
       +
       

     

       253
       253
       +
           The protocol supports both client-driven and terminal-driven animations.

     

       254
       254
       +
           Animations are created by first transmitting a base image, then adding

     

       255
       255
       +
           frames with optional delta encoding for efficiency.

     

       256
       256
       +
       

     

       257
       257
       +
           Frame numbers are 1-based: frame 1 is the root (base) image, frame 2 is the

     

       258
       258
       +
           first added frame, etc. *)

     

       259
       259
       +
       

     

       260
       260
       +
       val frame :

     

       261
       261
       +
         ?image_id:int ->

     

       262
       262
       +
         ?image_number:int ->

     

       263
       263
       +
         ?format:Format.t ->

     

       264
       264
       +
         ?transmission:Transmission.t ->

     

       265
       265
       +
         ?compression:Compression.t ->

     

       266
       266
       +
         ?width:int ->

     

       267
       267
       +
         ?height:int ->

     

       268
       268
       +
         ?quiet:Quiet.t ->

     

       269
       269
       +
         frame:Frame.t ->

     

       270
       270
       +
         unit ->

     

       271
       271
       +
         command

     

       272
       272
       +
       (** Transmit animation frame data.

     

       273
       273
       +
       

     

       274
       274
       +
           Adds a new frame to an existing image or edits an existing frame. The frame

     

       275
       275
       +
           can be a full image or a partial update (rectangle).

     

       276
       276
       +
       

     

       277
       277
       +
           Use {!Frame.make} to configure the frame's position, timing, and composition

     

       278
       278
       +
           options.

     

       279
       279
       +
       

     

       280
       280
       +
           @param frame Frame configuration including timing and composition. *)

     

       281
       281
       +
       

     

       282
       282
       +
       val animate :

     

       283
       283
       +
         ?image_id:int -> ?image_number:int -> ?quiet:Quiet.t -> Animation.t -> command

     

       284
       284
       +
       (** Control animation playback.

     

       285
       285
       +
       

     

       286
       286
       +
           For terminal-driven animation:

     

       287
       287
       +
           {[

     

       288
       288
       +
             (* Start infinite loop animation *)

     

       289
       289
       +
             Kgp.animate ~image_id:1

     

       290
       290
       +
               (Animation.set_state ~loops:1 `Run)

     

       291
       291
       +
               (* Stop animation *)

     

       292
       292
       +
               Kgp.animate ~image_id:1

     

       293
       293
       +
               (Animation.set_state `Stop)

     

       294
       294
       +
               (* Change frame timing *)

     

       295
       295
       +
               Kgp.animate ~image_id:1

     

       296
       296
       +
               (Animation.set_gap ~frame:3 ~gap_ms:100)

     

       297
       297
       +
           ]}

     

       298
       298
       +
       

     

       299
       299
       +
           For client-driven animation:

     

       300
       300
       +
           {[

     

       301
       301
       +
             (* Manually advance to specific frame *)

     

       302
       302
       +
             Kgp.animate ~image_id:1 (Animation.set_current_frame 5)

     

       303
       303
       +
           ]} *)

     

       304
       304
       +
       

     

       305
       305
       +
       val compose :

     

       306
       306
       +
         ?image_id:int -> ?image_number:int -> ?quiet:Quiet.t -> Compose.t -> command

     

       307
       307
       +
       (** Compose animation frames.

     

       308
       308
       +
       

     

       309
       309
       +
           Copies a rectangular region from one frame onto another. Useful for building

     

       310
       310
       +
           complex frames from simpler components.

     

       311
       311
       +
       

     

       312
       312
       +
           {[

     

       313
       313
       +
             (* Copy a 50x50 region from frame 2 to frame 5 *)

     

       314
       314
       +
             let comp =

     

       315
       315
       +
               Compose.make ~source_frame:2 ~dest_frame:5 ~width:50 ~height:50

     

       316
       316
       +
                 ~source_x:10 ~source_y:10 ~dest_x:20 ~dest_y:20 ()

     

       317
       317
       +
             in

     

       318
       318
       +
             Kgp.compose ~image_id:1 comp

     

       319
       319
       +
           ]} *)

     

       320
       320
       +
       

     

       321
       321
       +
       (** {2 Output}

     

       322
       322
       +
       

     

       323
       323
       +
           Commands are serialized to escape sequences that can be written to the

     

       324
       324
       +
           terminal. *)

     

       325
       325
       +
       

     

       326
       326
       +
       val write : Buffer.t -> command -> data:string -> unit

     

       327
       327
       +
       (** Write the command to a buffer.

     

       328
       328
       +
       

     

       329
       329
       +
           The [data] parameter contains the raw image/frame data (before base64

     

       330
       330
       +
           encoding). Pass an empty string for commands that don't include payload data

     

       331
       331
       +
           (like {!val:display}, {!val:delete}, {!val:animate}).

     

       332
       332
       +
       

     

       333
       333
       +
           The library handles base64 encoding and chunking automatically. *)

     

       334
       334
       +
       

     

       335
       335
       +
       val to_string : command -> data:string -> string

     

       336
       336
       +
       (** Convert command to a string.

     

       337
       337
       +
       

     

       338
       338
       +
           Convenience wrapper around {!write} that returns the serialized command as a

     

       339
       339
       +
           string. *)

     

       340
       340
       +
       

     

       341
       341
       +
       val write_tmux : Buffer.t -> command -> data:string -> unit

     

       342
       342
       +
       (** Write the command to a buffer with tmux passthrough support.

     

       343
       343
       +
       

     

       344
       344
       +
           If running inside tmux (detected via [TMUX] environment variable), wraps the

     

       345
       345
       +
           graphics command in a DCS passthrough sequence so it reaches the underlying

     

       346
       346
       +
           terminal. Otherwise, behaves like {!write}.

     

       347
       347
       +
       

     

       348
       348
       +
           Requires tmux 3.3+ with [allow-passthrough] enabled. *)

     

       349
       349
       +
       

     

       350
       350
       +
       val to_string_tmux : command -> data:string -> string

     

       351
       351
       +
       (** Convert command to a string with tmux passthrough support.

     

       352
       352
       +
       

     

       353
       353
       +
           Convenience wrapper around {!write_tmux}. If running inside tmux, wraps the

     

       354
       354
       +
           output for passthrough. Otherwise, behaves like {!to_string}. *)

     

       355
       355
       +
       

     

       356
       356
       +
       (** {1 Response} *)

     

       357
       357
       +
       

     

       49
       358
        
       module Response = Kgp_response

     

       50
       359
        
       

     

       51
       360
        
       (** {1 Utilities} *)

     

       52
       361
        
       

     

       362
       362
       +
       val next_image_id : unit -> int

     

       363
       363
       +
       (** Generate a unique image ID suitable for use with all graphics commands.

     

       364
       364
       +
       

     

       365
       365
       +
           Returns a random ID with non-zero bytes in all positions, making it

     

       366
       366
       +
           compatible with both regular display and Unicode placeholder modes.

     

       367
       367
       +
           Uses [Random] internally. *)

     

       368
       368
       +
       

     

       53
       369
        
       module Unicode_placeholder = Kgp_unicode

     

       54
       370
        
       module Detect = Kgp_detect

     

       371
       371
       +
       

     

       372
       372
       +
       module Tmux = Kgp_tmux

     

       373
       373
       +
       (** Tmux passthrough support. Provides functions to detect if running inside

     

       374
       374
       +
           tmux and to wrap escape sequences for passthrough. *)

     

       375
       375
       +
       

     

       376
       376
       +
       module Terminal = Kgp_terminal

     

       377
       377
       +
       (** Terminal environment detection. Provides functions to detect terminal

     

       378
       378
       +
           capabilities, pager mode, and resolve graphics output mode. *)

lib/kgp_animation.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       type t =

     

       2
       7
        
         [ `Set_state of Kgp_animation_state.t * int option

     

       3
       8
        
         | `Set_gap of int * int

+100 -8

lib/kgp_animation.mli

···

       1
       1
       -
       (** Kitty Graphics Protocol Animation

     

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** Animation Control

     

       7
       7
       +
       

     

       8
       8
       +
           Operations for controlling animation playback. The protocol supports both

     

       9
       9
       +
           terminal-driven and client-driven animation modes.

     

       10
       10
       +
       

     

       11
       11
       +
           {2 Protocol Overview}

     

       12
       12
       +
       

     

       13
       13
       +
           Animation control uses action [a=a] with various keys:

     

       14
       14
       +
           - [s]: Set playback state (1=stop, 2=loading, 3=run)

     

       15
       15
       +
           - [c]: Set current frame (1-based frame number)

     

       16
       16
       +
           - [r]: Target frame number for gap changes

     

       17
       17
       +
           - [z]: Frame gap/delay in milliseconds

     

       18
       18
       +
           - [v]: Loop count

     

       19
       19
       +
       

     

       20
       20
       +
           {2 Terminal-Driven Animation}

     

       2
       21
        
       

     

       3
       3
       -
           Animation control operations. *)

     

       22
       22
       +
           The terminal automatically advances frames based on each frame's gap

     

       23
       23
       +
           (delay). To start terminal-driven animation:

     

       24
       24
       +
       

     

       25
       25
       +
           {[

     

       26
       26
       +
             (* Start infinite loop *)

     

       27
       27
       +
             Kgp.animate ~image_id:1

     

       28
       28
       +
               (Animation.set_state ~loops:1 `Run)

     

       29
       29
       +
               (* Run 3 times then stop *)

     

       30
       30
       +
               Kgp.animate ~image_id:1

     

       31
       31
       +
               (Animation.set_state ~loops:4 `Run)

     

       32
       32
       +
               (* Stop animation *)

     

       33
       33
       +
               Kgp.animate ~image_id:1

     

       34
       34
       +
               (Animation.set_state `Stop)

     

       35
       35
       +
           ]}

     

       36
       36
       +
       

     

       37
       37
       +
           {2 Client-Driven Animation}

     

       38
       38
       +
       

     

       39
       39
       +
           The client manually controls which frame is displayed:

     

       40
       40
       +
       

     

       41
       41
       +
           {[

     

       42
       42
       +
             (* Display specific frame *)

     

       43
       43
       +
             Kgp.animate ~image_id:1 (Animation.set_current_frame 5)

     

       44
       44
       +
       

     

       45
       45
       +
             (* Advance to next frame in application logic *)

     

       46
       46
       +
             let next_frame = (current_frame mod total_frames) + 1 in

     

       47
       47
       +
             Kgp.animate ~image_id:1 (Animation.set_current_frame next_frame)

     

       48
       48
       +
           ]}

     

       49
       49
       +
       

     

       50
       50
       +
           {2 Modifying Frame Timing}

     

       51
       51
       +
       

     

       52
       52
       +
           Frame gaps can be changed during playback:

     

       53
       53
       +
       

     

       54
       54
       +
           {[

     

       55
       55
       +
             (* Slow down frame 3 *)

     

       56
       56
       +
             Kgp.animate ~image_id:1

     

       57
       57
       +
               (Animation.set_gap ~frame:3 ~gap_ms:200)

     

       58
       58
       +
               (* Make frame 5 instant/gapless *)

     

       59
       59
       +
               Kgp.animate ~image_id:1

     

       60
       60
       +
               (Animation.set_gap ~frame:5 ~gap_ms:(-1))

     

       61
       61
       +
           ]}

     

       62
       62
       +
       

     

       63
       63
       +
           {2 Loop Counting}

     

       64
       64
       +
       

     

       65
       65
       +
           The [loops] parameter in {!set_state}:

     

       66
       66
       +
           - 0: Ignored (doesn't change loop setting)

     

       67
       67
       +
           - 1: Infinite loop

     

       68
       68
       +
           - n > 1: Loop (n-1) times, then stop *)

     

       4
       69
        
       

     

       5
       70
        
       type t =

     

       6
       71
        
         [ `Set_state of Kgp_animation_state.t * int option

     

       7
       72
        
         | `Set_gap of int * int

     

       8
       73
        
         | `Set_current of int ]

     

       9
       9
       -
       (** Animation control operations. *)

     

       74
       74
       +
       (** Animation control operations.

     

       75
       75
       +
       

     

       76
       76
       +
           - [`Set_state (state, loops)] - Set animation playback state with optional

     

       77
       77
       +
             loop count.

     

       78
       78
       +
           - [`Set_gap (frame, gap_ms)] - Set the delay for a specific frame.

     

       79
       79
       +
           - [`Set_current frame] - Jump to a specific frame (1-based). *)

     

       10
       80
        
       

     

       11
       81
        
       val set_state : ?loops:int -> Kgp_animation_state.t -> t

     

       12
       12
       -
       (** Set animation state.

     

       13
       13
       -
           @param loops Number of loops: 0 = ignored, 1 = infinite, n = n-1 loops *)

     

       82
       82
       +
       (** Set animation playback state.

     

       83
       83
       +
       

     

       84
       84
       +
           @param loops

     

       85
       85
       +
             Loop count: 0 = ignored, 1 = infinite, n > 1 = (n-1) loops. Protocol key:

     

       86
       86
       +
             [v].

     

       87
       87
       +
           @param state The target playback state.

     

       88
       88
       +
       

     

       89
       89
       +
           Examples:

     

       90
       90
       +
           {[

     

       91
       91
       +
             set_state `Run (* Run with current loop setting *) set_state ~loops:1 `Run

     

       92
       92
       +
               (* Run infinitely *) set_state ~loops:3 `Run

     

       93
       93
       +
               (* Run twice, then stop *) set_state `Stop (* Pause animation *)

     

       94
       94
       +
               set_state `Loading (* Run, wait for more frames at end *)

     

       95
       95
       +
           ]} *)

     

       14
       96
        
       

     

       15
       97
        
       val set_gap : frame:int -> gap_ms:int -> t

     

       16
       98
        
       (** Set the gap (delay) for a specific frame.

     

       17
       17
       -
           @param frame 1-based frame number

     

       18
       18
       -
           @param gap_ms Delay in milliseconds (negative = gapless) *)

     

       99
       99
       +
       

     

       100
       100
       +
           @param frame 1-based frame number to modify. Protocol key: [r].

     

       101
       101
       +
           @param gap_ms

     

       102
       102
       +
             Delay in milliseconds before next frame. Negative values create gapless

     

       103
       103
       +
             frames (not displayed, instant skip). Protocol key: [z].

     

       104
       104
       +
       

     

       105
       105
       +
           Note: Frame 1 is the root/base image. Use 2+ for added frames. *)

     

       19
       106
        
       

     

       20
       107
        
       val set_current_frame : int -> t

     

       21
       21
       -
       (** Make a specific frame (1-based) the current displayed frame. *)

     

       108
       108
       +
       (** Make a specific frame the current displayed frame.

     

       109
       109
       +
       

     

       110
       110
       +
           @param frame 1-based frame number to display. Protocol key: [c].

     

       111
       111
       +
       

     

       112
       112
       +
           Used for client-driven animation where the application controls frame

     

       113
       113
       +
           advancement rather than the terminal. *)

+6 -4

lib/kgp_animation_state.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       type t = [ `Stop | `Loading | `Run ]

     

       2
       7
        
       

     

       3
       3
       -
       let to_int : t -> int = function

     

       4
       4
       -
         | `Stop -> 1

     

       5
       5
       -
         | `Loading -> 2

     

       6
       6
       -
         | `Run -> 3

     

       8
       8
       +
       let to_int : t -> int = function `Stop -> 1 | `Loading -> 2 | `Run -> 3

+60 -5

lib/kgp_animation_state.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       (** Animation Playback State

     

       2
       7
        
       

     

       3
       3
       -
           Controls the playback state of animated images. *)

     

       8
       8
       +
           Controls the playback state of animated images.

     

       9
       9
       +
       

     

       10
       10
       +
           {2 Protocol Details}

     

       11
       11
       +
       

     

       12
       12
       +
           The animation state is specified via the [s] key in the control data when

     

       13
       13
       +
           using action [a=a]:

     

       14
       14
       +
           - [s=1]: stop animation

     

       15
       15
       +
           - [s=2]: run in loading mode

     

       16
       16
       +
           - [s=3]: run normally

     

       17
       17
       +
       

     

       18
       18
       +
           {2 Animation Modes}

     

       19
       19
       +
       

     

       20
       20
       +
           The protocol supports two animation approaches:

     

       21
       21
       +
       

     

       22
       22
       +
           {b Terminal-driven animation}: The terminal automatically advances frames

     

       23
       23
       +
           based on the gap (delay) specified for each frame. Use [{`Run}] or

     

       24
       24
       +
           [{`Loading}] states.

     

       25
       25
       +
       

     

       26
       26
       +
           {b Client-driven animation}: The client manually sets the current frame

     

       27
       27
       +
           using [Kgp.Animation.set_current_frame]. Use [{`Stop}] state to prevent

     

       28
       28
       +
           automatic advancement.

     

       29
       29
       +
       

     

       30
       30
       +
           {2 Stop State}

     

       31
       31
       +
       

     

       32
       32
       +
           [{`Stop}] halts automatic frame advancement. The animation freezes on the

     

       33
       33
       +
           current frame. Use this when:

     

       34
       34
       +
           - Implementing client-driven animation

     

       35
       35
       +
           - Pausing an animation

     

       36
       36
       +
           - Displaying a static frame from an animated image

     

       37
       37
       +
       

     

       38
       38
       +
           {2 Loading State}

     

       39
       39
       +
       

     

       40
       40
       +
           [{`Loading}] runs the animation but waits for new frames when reaching the

     

       41
       41
       +
           end instead of looping. Use this when:

     

       42
       42
       +
           - Streaming animation frames progressively

     

       43
       43
       +
           - Building an animation while displaying it

     

       44
       44
       +
           - The animation is not yet complete

     

       45
       45
       +
       

     

       46
       46
       +
           {2 Run State}

     

       47
       47
       +
       

     

       48
       48
       +
           [{`Run}] runs the animation normally, looping back to the first frame after

     

       49
       49
       +
           the last. The loop count can be controlled via the [loops] parameter in

     

       50
       50
       +
           [Kgp.Animation.set_state]. *)

     

       4
       51
        
       

     

       5
       52
        
       type t = [ `Stop | `Loading | `Run ]

     

       6
       53
        
       (** Animation playback states.

     

       7
       54
        
       

     

       8
       8
       -
           - [`Stop] - Halt animation playback

     

       9
       9
       -
           - [`Loading] - Run animation but wait for new frames at end

     

       10
       10
       -
           - [`Run] - Run animation normally and loop *)

     

       55
       55
       +
           - [`Stop] - Halt animation playback. The animation freezes on the current

     

       56
       56
       +
             frame and does not advance automatically.

     

       57
       57
       +
           - [`Loading] - Run animation but wait for new frames at end. When the last

     

       58
       58
       +
             frame is reached, the animation pauses until more frames are added, then

     

       59
       59
       +
             continues.

     

       60
       60
       +
           - [`Run] - Run animation normally and loop. After the last frame, playback

     

       61
       61
       +
             returns to the first frame (or stops after the specified number of loops).

     

       62
       62
       +
       *)

     

       11
       63
        
       

     

       12
       64
        
       val to_int : t -> int

     

       13
       13
       -
       (** Convert to protocol integer (1, 2, or 3). *)

     

       65
       65
       +
       (** Convert to protocol integer.

     

       66
       66
       +
       

     

       67
       67
       +
           Returns 1 for [`Stop], 2 for [`Loading], or 3 for [`Run]. These values are

     

       68
       68
       +
           used in the [s=] control data key. *)

+40 -22

lib/kgp_command.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       type action =

     

       2
       7
        
         [ `Transmit

     

       3
       8
        
         | `Transmit_and_display

     
···

       22
       27
        
         image_number : int option;

     

       23
       28
        
         placement : Kgp_placement.t option;

     

       24
       29
        
         delete : Kgp_delete.t option;

     

       30
       30
       +
         delete_free : bool;

     

       25
       31
        
         frame : Kgp_frame.t option;

     

       26
       32
        
         animation : Kgp_animation.t option;

     

       27
       33
        
         compose : Kgp_compose.t option;

     
···

       42
       48
        
           image_number = None;

     

       43
       49
        
           placement = None;

     

       44
       50
        
           delete = None;

     

       51
       51
       +
           delete_free = false;

     

       45
       52
        
           frame = None;

     

       46
       53
        
           animation = None;

     

       47
       54
        
           compose = None;

     
···

       86
       93
        
       let display ?image_id ?image_number ?placement ?quiet () =

     

       87
       94
        
         { (make `Display) with image_id; image_number; placement; quiet }

     

       88
       95
        
       

     

       89
       89
       -
       let delete ?quiet del = { (make `Delete) with quiet; delete = Some del }

     

       96
       96
       +
       let delete ?(free = false) ?quiet del =

     

       97
       97
       +
         { (make `Delete) with quiet; delete = Some del; delete_free = free }

     

       90
       98
        
       

     

       91
       99
        
       let frame ?image_id ?image_number ?format ?transmission ?compression ?width

     

       92
       100
        
           ?height ?quiet ~frame () =

     
···

       159
       167
        
         kv_int_opt w 'p' (Kgp_placement.placement_id p);

     

       160
       168
        
         Kgp_placement.cursor p

     

       161
       169
        
         |> Option.iter (fun c ->

     

       162
       162
       -
                kv_int_if w 'C' ~default:0 (Some (Kgp_cursor.to_int c)));

     

       170
       170
       +
             kv_int_if w 'C' ~default:0 (Some (Kgp_cursor.to_int c)));

     

       163
       171
        
         if Kgp_placement.unicode_placeholder p then kv_int w 'U' 1

     

       164
       172
        
       

     

       165
       165
       -
       let write_delete w (d : Kgp_delete.t) =

     

       166
       166
       -
         kv_char w 'd' (Kgp_delete.to_char d);

     

       173
       173
       +
       let write_delete w ~free (d : Kgp_delete.t) =

     

       174
       174
       +
         kv_char w 'd' (Kgp_delete.to_char ~free d);

     

       167
       175
        
         match d with

     

       168
       168
       -
         | `By_id (id, pid) | `By_id_and_free (id, pid) ->

     

       176
       176
       +
         | `By_id (id, pid) ->

     

       169
       177
        
             kv_int w 'i' id;

     

       170
       178
        
             kv_int_opt w 'p' pid

     

       171
       171
       -
         | `By_number (n, pid) | `By_number_and_free (n, pid) ->

     

       179
       179
       +
         | `By_number (n, pid) ->

     

       172
       180
        
             kv_int w 'I' n;

     

       173
       181
        
             kv_int_opt w 'p' pid

     

       174
       174
       -
         | `At_cell (x, y) | `At_cell_and_free (x, y) ->

     

       182
       182
       +
         | `At_cell (x, y) ->

     

       175
       183
        
             kv_int w 'x' x;

     

       176
       184
        
             kv_int w 'y' y

     

       177
       177
       -
         | `At_cell_z (x, y, z) | `At_cell_z_and_free (x, y, z) ->

     

       185
       185
       +
         | `At_cell_z (x, y, z) ->

     

       178
       186
        
             kv_int w 'x' x;

     

       179
       187
        
             kv_int w 'y' y;

     

       180
       188
        
             kv_int w 'z' z

     

       181
       181
       -
         | `By_column c | `By_column_and_free c -> kv_int w 'x' c

     

       182
       182
       -
         | `By_row r | `By_row_and_free r -> kv_int w 'y' r

     

       183
       183
       -
         | `By_z_index z | `By_z_index_and_free z -> kv_int w 'z' z

     

       184
       184
       -
         | `By_id_range (min_id, max_id) | `By_id_range_and_free (min_id, max_id) ->

     

       189
       189
       +
         | `By_column c -> kv_int w 'x' c

     

       190
       190
       +
         | `By_row r -> kv_int w 'y' r

     

       191
       191
       +
         | `By_z_index z -> kv_int w 'z' z

     

       192
       192
       +
         | `By_id_range (min_id, max_id) ->

     

       185
       193
        
             kv_int w 'x' min_id;

     

       186
       194
        
             kv_int w 'y' max_id

     

       187
       187
       -
         | `All_visible | `All_visible_and_free | `At_cursor | `At_cursor_and_free

     

       188
       188
       -
         | `Frames | `Frames_and_free ->

     

       189
       189
       -
             ()

     

       195
       195
       +
         | `All_visible | `At_cursor | `Frames -> ()

     

       190
       196
        
       

     

       191
       197
        
       let write_frame w (f : Kgp_frame.t) =

     

       192
       198
        
         kv_int_opt w 'x' (Kgp_frame.x f);

     
···

       196
       202
        
         kv_int_opt w 'z' (Kgp_frame.gap_ms f);

     

       197
       203
        
         Kgp_frame.composition f

     

       198
       204
        
         |> Option.iter (fun c ->

     

       199
       199
       -
                kv_int_if w 'X' ~default:0 (Some (Kgp_composition.to_int c)));

     

       205
       205
       +
             kv_int_if w 'X' ~default:0 (Some (Kgp_composition.to_int c)));

     

       200
       206
        
         kv_int32_opt w 'Y' (Kgp_frame.background_color f)

     

       201
       207
        
       

     

       202
       208
        
       let write_animation w : Kgp_animation.t -> unit = function

     
···

       220
       226
        
         kv_int_opt w 'Y' (Kgp_compose.source_y c);

     

       221
       227
        
         Kgp_compose.composition c

     

       222
       228
        
         |> Option.iter (fun comp ->

     

       223
       223
       -
                kv_int_if w 'C' ~default:0 (Some (Kgp_composition.to_int comp)))

     

       229
       229
       +
             kv_int_if w 'C' ~default:0 (Some (Kgp_composition.to_int comp)))

     

       224
       230
        
       

     

       225
       231
        
       let write_control_data buf cmd =

     

       226
       232
        
         let w = kv_writer buf in

     
···

       229
       235
        
         (* Quiet - only if non-default *)

     

       230
       236
        
         cmd.quiet

     

       231
       237
        
         |> Option.iter (fun q ->

     

       232
       232
       -
                kv_int_if w 'q' ~default:0 (Some (Kgp_quiet.to_int q)));

     

       238
       238
       +
             kv_int_if w 'q' ~default:0 (Some (Kgp_quiet.to_int q)));

     

       233
       239
        
         (* Format *)

     

       234
       234
       -
         cmd.format

     

       235
       235
       -
         |> Option.iter (fun f -> kv_int w 'f' (Kgp_format.to_int f));

     

       240
       240
       +
         cmd.format |> Option.iter (fun f -> kv_int w 'f' (Kgp_format.to_int f));

     

       236
       241
        
         (* Transmission - only for transmit/frame actions, always include t=d for compatibility *)

     

       237
       242
        
         (match cmd.action with

     

       238
       243
        
         | `Transmit | `Transmit_and_display | `Frame -> (

     
···

       243
       248
        
         (* Compression *)

     

       244
       249
        
         cmd.compression

     

       245
       250
        
         |> Option.iter (fun c ->

     

       246
       246
       -
                Kgp_compression.to_char c |> Option.iter (kv_char w 'o'));

     

       251
       251
       +
             Kgp_compression.to_char c |> Option.iter (kv_char w 'o'));

     

       247
       252
        
         (* Dimensions *)

     

       248
       253
        
         kv_int_opt w 's' cmd.width;

     

       249
       254
        
         kv_int_opt w 'v' cmd.height;

     
···

       255
       260
        
         kv_int_opt w 'I' cmd.image_number;

     

       256
       261
        
         (* Complex options *)

     

       257
       262
        
         cmd.placement |> Option.iter (write_placement w);

     

       258
       258
       -
         cmd.delete |> Option.iter (write_delete w);

     

       263
       263
       +
         cmd.delete |> Option.iter (write_delete w ~free:cmd.delete_free);

     

       259
       264
        
         cmd.frame |> Option.iter (write_frame w);

     

       260
       265
        
         cmd.animation |> Option.iter (write_animation w);

     

       261
       266
        
         cmd.compose |> Option.iter (write_compose w);

     
···

       304
       309
        
         let buf = Buffer.create 1024 in

     

       305
       310
        
         write buf cmd ~data;

     

       306
       311
        
         Buffer.contents buf

     

       312
       312
       +
       

     

       313
       313
       +
       let write_tmux buf cmd ~data =

     

       314
       314
       +
         if Kgp_tmux.is_active () then begin

     

       315
       315
       +
           let inner_buf = Buffer.create 1024 in

     

       316
       316
       +
           write inner_buf cmd ~data;

     

       317
       317
       +
           Kgp_tmux.write_wrapped buf (Buffer.contents inner_buf)

     

       318
       318
       +
         end

     

       319
       319
       +
         else write buf cmd ~data

     

       320
       320
       +
       

     

       321
       321
       +
       let to_string_tmux cmd ~data =

     

       322
       322
       +
         let buf = Buffer.create 1024 in

     

       323
       323
       +
         write_tmux buf cmd ~data;

     

       324
       324
       +
         Buffer.contents buf

+26 -7

lib/kgp_command.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       (** Kitty Graphics Protocol Commands

     

       2
       7
        
       

     

       3
       8
        
           This module provides functions for building and serializing graphics

     
···

       62
       67
        
       

     

       63
       68
        
       (** {1 Deletion} *)

     

       64
       69
        
       

     

       65
       65
       -
       val delete : ?quiet:Kgp_quiet.t -> Kgp_delete.t -> t

     

       66
       66
       -
       (** Delete images or placements. *)

     

       70
       70
       +
       val delete : ?free:bool -> ?quiet:Kgp_quiet.t -> Kgp_delete.t -> t

     

       71
       71
       +
       (** Delete images or placements.

     

       72
       72
       +
       

     

       73
       73
       +
           @param free

     

       74
       74
       +
             If true, also free the image data from memory (default: false). Without

     

       75
       75
       +
             [~free:true], only placements are removed and the image data can be reused

     

       76
       76
       +
             for new placements. *)

     

       67
       77
        
       

     

       68
       78
        
       (** {1 Animation} *)

     

       69
       79
        
       

     
···

       90
       100
        
       (** Control animation playback. *)

     

       91
       101
        
       

     

       92
       102
        
       val compose :

     

       93
       93
       -
         ?image_id:int ->

     

       94
       94
       -
         ?image_number:int ->

     

       95
       95
       -
         ?quiet:Kgp_quiet.t ->

     

       96
       96
       -
         Kgp_compose.t ->

     

       97
       97
       -
         t

     

       103
       103
       +
         ?image_id:int -> ?image_number:int -> ?quiet:Kgp_quiet.t -> Kgp_compose.t -> t

     

       98
       104
        
       (** Compose animation frames. *)

     

       99
       105
        
       

     

       100
       106
        
       (** {1 Output} *)

     
···

       104
       110
        
       

     

       105
       111
        
       val to_string : t -> data:string -> string

     

       106
       112
        
       (** Convert command to a string. *)

     

       113
       113
       +
       

     

       114
       114
       +
       val write_tmux : Buffer.t -> t -> data:string -> unit

     

       115
       115
       +
       (** Write the command to a buffer with tmux passthrough wrapping.

     

       116
       116
       +
       

     

       117
       117
       +
           If running inside tmux (detected via [TMUX] environment variable), wraps the

     

       118
       118
       +
           graphics command in a DCS passthrough sequence. Otherwise, behaves like

     

       119
       119
       +
           {!write}. *)

     

       120
       120
       +
       

     

       121
       121
       +
       val to_string_tmux : t -> data:string -> string

     

       122
       122
       +
       (** Convert command to a string with tmux passthrough wrapping.

     

       123
       123
       +
       

     

       124
       124
       +
           If running inside tmux, wraps the output for passthrough. Otherwise, behaves

     

       125
       125
       +
           like {!to_string}. *)

lib/kgp_compose.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       type t = {

     

       2
       7
        
         source_frame : int;

     

       3
       8
        
         dest_frame : int;

+91 -4

lib/kgp_compose.mli

···

       1
       1
       -
       (** Kitty Graphics Protocol Compose

     

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** Frame Composition

     

       7
       7
       +
       

     

       8
       8
       +
           Operations for compositing rectangular regions between animation frames.

     

       9
       9
       +
           This allows building complex frames from simpler components.

     

       10
       10
       +
       

     

       11
       11
       +
           {2 Protocol Overview}

     

       12
       12
       +
       

     

       13
       13
       +
           Frame composition uses action [a=c] to copy a rectangular region from one

     

       14
       14
       +
           frame onto another. This is useful for:

     

       15
       15
       +
       

     

       16
       16
       +
           - Building frames from reusable sprite components

     

       17
       17
       +
           - Applying partial updates to existing frames

     

       18
       18
       +
           - Creating complex animations efficiently

     

       19
       19
       +
       

     

       20
       20
       +
           {2 Coordinate System}

     

       21
       21
       +
       

     

       22
       22
       +
           All coordinates are in pixels, relative to the top-left corner of the

     

       23
       23
       +
           respective frame:

     

       2
       24
        
       

     

       3
       3
       -
           Frame composition operations. *)

     

       25
       25
       +
           - [source_x], [source_y]: Top-left of rectangle in source frame

     

       26
       26
       +
           - [dest_x], [dest_y]: Top-left of destination in target frame

     

       27
       27
       +
           - [width], [height]: Size of the rectangle to copy

     

       28
       28
       +
       

     

       29
       29
       +
           If width/height are omitted, the entire source frame is used.

     

       30
       30
       +
       

     

       31
       31
       +
           {2 Composition Mode}

     

       32
       32
       +
       

     

       33
       33
       +
           The [composition] parameter controls blending:

     

       34
       34
       +
           - [{`Alpha_blend}]: Standard alpha compositing (default)

     

       35
       35
       +
           - [{`Overwrite}]: Direct pixel replacement

     

       36
       36
       +
       

     

       37
       37
       +
           {2 Error Conditions}

     

       38
       38
       +
       

     

       39
       39
       +
           The terminal responds with errors for:

     

       40
       40
       +
           - [ENOENT]: Source or destination frame doesn't exist

     

       41
       41
       +
           - [EINVAL]: Rectangle out of bounds, or source equals destination with

     

       42
       42
       +
             overlapping regions

     

       43
       43
       +
           - [ENOSPC]: Not enough storage after composition

     

       44
       44
       +
       

     

       45
       45
       +
           {2 Example}

     

       46
       46
       +
       

     

       47
       47
       +
           {[

     

       48
       48
       +
             (* Copy a 32x32 sprite from frame 2 to frame 5 *)

     

       49
       49
       +
             let comp =

     

       50
       50
       +
               Compose.make ~source_frame:2 ~dest_frame:5 ~width:32 ~height:32

     

       51
       51
       +
                 ~source_x:0 ~source_y:0 (* From top-left of source *)

     

       52
       52
       +
                 ~dest_x:100 ~dest_y:50 () (* To position in dest *)

     

       53
       53
       +
             in

     

       54
       54
       +
             Kgp.compose ~image_id:1 comp

     

       55
       55
       +
           ]} *)

     

       4
       56
        
       

     

       5
       57
        
       type t

     

       6
       6
       -
       (** Composition operation. *)

     

       58
       58
       +
       (** Composition operation. Opaque type; use {!make} to construct. *)

     

       7
       59
        
       

     

       8
       60
        
       val make :

     

       9
       61
        
         source_frame:int ->

     
···

       17
       69
        
         ?composition:Kgp_composition.t ->

     

       18
       70
        
         unit ->

     

       19
       71
        
         t

     

       20
       20
       -
       (** Compose a rectangle from one frame onto another. *)

     

       72
       72
       +
       (** Create a composition operation.

     

       73
       73
       +
       

     

       74
       74
       +
           @param source_frame

     

       75
       75
       +
             1-based frame number to copy from. Required. Protocol key: [r].

     

       76
       76
       +
           @param dest_frame

     

       77
       77
       +
             1-based frame number to copy onto. Required. Protocol key: [c].

     

       78
       78
       +
           @param width

     

       79
       79
       +
             Width of rectangle in pixels. Default is full frame. Protocol key: [w].

     

       80
       80
       +
           @param height

     

       81
       81
       +
             Height of rectangle in pixels. Default is full frame. Protocol key: [h].

     

       82
       82
       +
           @param source_x

     

       83
       83
       +
             Left edge of source rectangle (default 0). Protocol key: [X].

     

       84
       84
       +
           @param source_y Top edge of source rectangle (default 0). Protocol key: [Y].

     

       85
       85
       +
           @param dest_x

     

       86
       86
       +
             Left edge of destination position (default 0). Protocol key: [x].

     

       87
       87
       +
           @param dest_y

     

       88
       88
       +
             Top edge of destination position (default 0). Protocol key: [y].

     

       89
       89
       +
           @param composition

     

       90
       90
       +
             Blending mode. Default is alpha blending. Protocol key: [C]. *)

     

       21
       91
        
       

     

       22
       92
        
       (** {1 Field Accessors} *)

     

       23
       93
        
       

     

       24
       94
        
       val source_frame : t -> int

     

       95
       95
       +
       (** 1-based source frame number. *)

     

       96
       96
       +
       

     

       25
       97
        
       val dest_frame : t -> int

     

       98
       98
       +
       (** 1-based destination frame number. *)

     

       99
       99
       +
       

     

       26
       100
        
       val width : t -> int option

     

       101
       101
       +
       (** Width of rectangle in pixels. *)

     

       102
       102
       +
       

     

       27
       103
        
       val height : t -> int option

     

       104
       104
       +
       (** Height of rectangle in pixels. *)

     

       105
       105
       +
       

     

       28
       106
        
       val source_x : t -> int option

     

       107
       107
       +
       (** Left edge of source rectangle. *)

     

       108
       108
       +
       

     

       29
       109
        
       val source_y : t -> int option

     

       110
       110
       +
       (** Top edge of source rectangle. *)

     

       111
       111
       +
       

     

       30
       112
        
       val dest_x : t -> int option

     

       113
       113
       +
       (** Left edge of destination position. *)

     

       114
       114
       +
       

     

       31
       115
        
       val dest_y : t -> int option

     

       116
       116
       +
       (** Top edge of destination position. *)

     

       117
       117
       +
       

     

       32
       118
        
       val composition : t -> Kgp_composition.t option

     

       119
       119
       +
       (** Blending mode for composition. *)

+6 -3

lib/kgp_composition.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       type t = [ `Alpha_blend | `Overwrite ]

     

       2
       7
        
       

     

       3
       3
       -
       let to_int : t -> int = function

     

       4
       4
       -
         | `Alpha_blend -> 0

     

       5
       5
       -
         | `Overwrite -> 1

     

       8
       8
       +
       let to_int : t -> int = function `Alpha_blend -> 0 | `Overwrite -> 1

+44 -4

lib/kgp_composition.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       (** Pixel Composition Mode

     

       2
       7
        
       

     

       3
       3
       -
           Controls how pixels are blended when compositing images or animation frames. *)

     

       8
       8
       +
           Controls how pixels are blended when compositing images or animation frames.

     

       9
       9
       +
       

     

       10
       10
       +
           {2 Protocol Details}

     

       11
       11
       +
       

     

       12
       12
       +
           The composition mode is specified via the [X] key in the control data (for

     

       13
       13
       +
           animation frames) or the [C] key (for frame composition operations):

     

       14
       14
       +
           - Value 0 or omitted: alpha blending (default)

     

       15
       15
       +
           - Value 1: simple overwrite/replacement

     

       16
       16
       +
       

     

       17
       17
       +
           {2 Alpha Blending}

     

       18
       18
       +
       

     

       19
       19
       +
           [{`Alpha_blend}] performs standard alpha compositing using the source

     

       20
       20
       +
           pixel's alpha channel. For each pixel:

     

       21
       21
       +
           - If source alpha is 255 (opaque), source pixel replaces destination

     

       22
       22
       +
           - If source alpha is 0 (transparent), destination pixel is unchanged

     

       23
       23
       +
           - Otherwise, colors are blended proportionally

     

       24
       24
       +
       

     

       25
       25
       +
           This mode is essential for:

     

       26
       26
       +
           - Transparent PNG images

     

       27
       27
       +
           - Overlaying graphics on backgrounds

     

       28
       28
       +
           - Anti-aliased edges and text

     

       29
       29
       +
       

     

       30
       30
       +
           {2 Overwrite Mode}

     

       31
       31
       +
       

     

       32
       32
       +
           [{`Overwrite}] simply replaces destination pixels with source pixels,

     

       33
       33
       +
           ignoring the alpha channel. This is useful for:

     

       34
       34
       +
           - Performance optimization when transparency isn't needed

     

       35
       35
       +
           - Replacing rectangular regions entirely

     

       36
       36
       +
           - Animation frames that completely replace the previous frame *)

     

       4
       37
        
       

     

       5
       38
        
       type t = [ `Alpha_blend | `Overwrite ]

     

       6
       39
        
       (** Composition modes.

     

       7
       40
        
       

     

       8
       8
       -
           - [`Alpha_blend] - Full alpha blending (default)

     

       9
       9
       -
           - [`Overwrite] - Simple pixel replacement *)

     

       41
       41
       +
           - [`Alpha_blend] - Full alpha blending (default). Source pixels are

     

       42
       42
       +
             composited onto the destination using standard Porter-Duff "over"

     

       43
       43
       +
             compositing based on the source alpha channel.

     

       44
       44
       +
           - [`Overwrite] - Simple pixel replacement. Source pixels completely replace

     

       45
       45
       +
             destination pixels, ignoring alpha values. Faster but no transparency

     

       46
       46
       +
             support. *)

     

       10
       47
        
       

     

       11
       48
        
       val to_int : t -> int

     

       12
       12
       -
       (** Convert to protocol integer (0 or 1). *)

     

       49
       49
       +
       (** Convert to protocol integer.

     

       50
       50
       +
       

     

       51
       51
       +
           Returns 0 for [`Alpha_blend] or 1 for [`Overwrite]. These values are used in

     

       52
       52
       +
           the [X=] or [C=] control data keys. *)

+6 -3

lib/kgp_compression.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       type t = [ `None | `Zlib ]

     

       2
       7
        
       

     

       3
       3
       -
       let to_char : t -> char option = function

     

       4
       4
       -
         | `None -> None

     

       5
       5
       -
         | `Zlib -> Some 'z'

     

       8
       8
       +
       let to_char : t -> char option = function `None -> None | `Zlib -> Some 'z'

+40 -5

lib/kgp_compression.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       (** Data Compression

     

       2
       7
        
       

     

       3
       3
       -
           Specifies compression applied to image data before transmission. *)

     

       8
       8
       +
           Specifies compression applied to image data before transmission.

     

       9
       9
       +
       

     

       10
       10
       +
           {2 Protocol Details}

     

       11
       11
       +
       

     

       12
       12
       +
           Compression is specified via the [o] key in the control data:

     

       13
       13
       +
           - No [o] key means no compression

     

       14
       14
       +
           - [o=z] means zlib (RFC 1950 DEFLATE) compression

     

       15
       15
       +
       

     

       16
       16
       +
           Compression is applied to the raw pixel/PNG data {i before} base64 encoding.

     

       17
       17
       +
           The terminal decompresses after base64 decoding.

     

       18
       18
       +
       

     

       19
       19
       +
           {2 When to Use Compression}

     

       20
       20
       +
       

     

       21
       21
       +
           Zlib compression is beneficial for:

     

       22
       22
       +
           - Large images with repetitive patterns

     

       23
       23
       +
           - Screenshots and UI graphics

     

       24
       24
       +
           - Images with large solid color regions

     

       25
       25
       +
       

     

       26
       26
       +
           It may not help (or could increase size) for:

     

       27
       27
       +
           - Already-compressed PNG data

     

       28
       28
       +
           - Photographic images with high entropy

     

       29
       29
       +
           - Very small images (compression overhead)

     

       30
       30
       +
       

     

       31
       31
       +
           {2 PNG with Compression}

     

       32
       32
       +
       

     

       33
       33
       +
           When using both [{`Png}] format and [{`Zlib}] compression, the [size]

     

       34
       34
       +
           parameter must be specified with the original (uncompressed) PNG size. The

     

       35
       35
       +
           terminal needs this to allocate the correct buffer for decompression. *)

     

       4
       36
        
       

     

       5
       37
        
       type t = [ `None | `Zlib ]

     

       6
       38
        
       (** Compression options.

     

       7
       39
        
       

     

       8
       8
       -
           - [`None] - Raw uncompressed data

     

       9
       9
       -
           - [`Zlib] - RFC 1950 zlib compression *)

     

       40
       40
       +
           - [`None] - Raw uncompressed data. No [o=] key is sent.

     

       41
       41
       +
           - [`Zlib] - RFC 1950 zlib/DEFLATE compression. Data is compressed before

     

       42
       42
       +
             base64 encoding and decompressed by the terminal. *)

     

       10
       43
        
       

     

       11
       44
        
       val to_char : t -> char option

     

       12
       12
       -
       (** Convert to protocol character. Returns [None] for no compression,

     

       13
       13
       -
           [Some 'z'] for zlib. *)

     

       45
       45
       +
       (** Convert to protocol character.

     

       46
       46
       +
       

     

       47
       47
       +
           Returns [None] for [`None] (no key sent), or [Some 'z'] for [`Zlib]. When

     

       48
       48
       +
           [Some c] is returned, [o=c] is added to the control data. *)

+6 -3

lib/kgp_cursor.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       type t = [ `Move | `Static ]

     

       2
       7
        
       

     

       3
       3
       -
       let to_int : t -> int = function

     

       4
       4
       -
         | `Move -> 0

     

       5
       5
       -
         | `Static -> 1

     

       8
       8
       +
       let to_int : t -> int = function `Move -> 0 | `Static -> 1

+45 -4

lib/kgp_cursor.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       (** Cursor Movement Behavior

     

       2
       7
        
       

     

       3
       3
       -
           Controls cursor position after displaying an image. *)

     

       8
       8
       +
           Controls cursor position after displaying an image.

     

       9
       9
       +
       

     

       10
       10
       +
           {2 Protocol Details}

     

       11
       11
       +
       

     

       12
       12
       +
           Cursor movement is specified via the [C] key in the control data:

     

       13
       13
       +
           - [C=0] or no [C] key: move cursor after display (default)

     

       14
       14
       +
           - [C=1]: keep cursor in place (static)

     

       15
       15
       +
       

     

       16
       16
       +
           This key was added in Kitty 0.20.0.

     

       17
       17
       +
       

     

       18
       18
       +
           {2 Default Behavior}

     

       19
       19
       +
       

     

       20
       20
       +
           By default ([{`Move}]), after displaying an image the cursor advances:

     

       21
       21
       +
           - Right by the number of columns the image occupies

     

       22
       22
       +
           - Down by the number of rows the image occupies

     

       23
       23
       +
       

     

       24
       24
       +
           This matches how the cursor moves after printing text, allowing images to

     

       25
       25
       +
           flow naturally with text content.

     

       26
       26
       +
       

     

       27
       27
       +
           {2 Static Cursor}

     

       28
       28
       +
       

     

       29
       29
       +
           With [{`Static}], the cursor remains at its original position. This is

     

       30
       30
       +
           useful when:

     

       31
       31
       +
           - Overlaying images on existing content

     

       32
       32
       +
           - Positioning multiple images relative to the same starting point

     

       33
       33
       +
           - Implementing custom cursor management

     

       34
       34
       +
       

     

       35
       35
       +
           {2 Relative Placements}

     

       36
       36
       +
       

     

       37
       37
       +
           Note: When using relative placements (positioning images relative to other

     

       38
       38
       +
           placements), the cursor never moves regardless of this setting. *)

     

       4
       39
        
       

     

       5
       40
        
       type t = [ `Move | `Static ]

     

       6
       41
        
       (** Cursor movement behavior.

     

       7
       42
        
       

     

       8
       8
       -
           - [`Move] - Advance cursor past the displayed image (default)

     

       9
       9
       -
           - [`Static] - Keep cursor in place *)

     

       43
       43
       +
           - [`Move] - Advance cursor past the displayed image (default). Cursor moves

     

       44
       44
       +
             right by the number of columns and down by the number of rows occupied by

     

       45
       45
       +
             the image.

     

       46
       46
       +
           - [`Static] - Keep cursor at its original position. The image is displayed

     

       47
       47
       +
             but cursor position is unchanged. *)

     

       10
       48
        
       

     

       11
       49
        
       val to_int : t -> int

     

       12
       12
       -
       (** Convert to protocol integer (0 or 1). *)

     

       50
       50
       +
       (** Convert to protocol integer.

     

       51
       51
       +
       

     

       52
       52
       +
           Returns 0 for [`Move] or 1 for [`Static]. These values are used in the [C=]

     

       53
       53
       +
           control data key. *)

+23 -35

lib/kgp_delete.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       type t =

     

       2
       7
        
         [ `All_visible

     

       3
       3
       -
         | `All_visible_and_free

     

       4
       8
        
         | `By_id of int * int option

     

       5
       5
       -
         | `By_id_and_free of int * int option

     

       6
       9
        
         | `By_number of int * int option

     

       7
       7
       -
         | `By_number_and_free of int * int option

     

       8
       10
        
         | `At_cursor

     

       9
       9
       -
         | `At_cursor_and_free

     

       10
       11
        
         | `At_cell of int * int

     

       11
       11
       -
         | `At_cell_and_free of int * int

     

       12
       12
        
         | `At_cell_z of int * int * int

     

       13
       13
       -
         | `At_cell_z_and_free of int * int * int

     

       14
       13
        
         | `By_column of int

     

       15
       15
       -
         | `By_column_and_free of int

     

       16
       14
        
         | `By_row of int

     

       17
       17
       -
         | `By_row_and_free of int

     

       18
       15
        
         | `By_z_index of int

     

       19
       19
       -
         | `By_z_index_and_free of int

     

       20
       16
        
         | `By_id_range of int * int

     

       21
       21
       -
         | `By_id_range_and_free of int * int

     

       22
       22
       -
         | `Frames

     

       23
       23
       -
         | `Frames_and_free ]

     

       17
       17
       +
         | `Frames ]

     

       24
       18
        
       

     

       25
       25
       -
       let to_char : t -> char = function

     

       26
       26
       -
         | `All_visible -> 'a'

     

       27
       27
       -
         | `All_visible_and_free -> 'A'

     

       28
       28
       -
         | `By_id _ -> 'i'

     

       29
       29
       -
         | `By_id_and_free _ -> 'I'

     

       30
       30
       -
         | `By_number _ -> 'n'

     

       31
       31
       -
         | `By_number_and_free _ -> 'N'

     

       32
       32
       -
         | `At_cursor -> 'c'

     

       33
       33
       -
         | `At_cursor_and_free -> 'C'

     

       34
       34
       -
         | `At_cell _ -> 'p'

     

       35
       35
       -
         | `At_cell_and_free _ -> 'P'

     

       36
       36
       -
         | `At_cell_z _ -> 'q'

     

       37
       37
       -
         | `At_cell_z_and_free _ -> 'Q'

     

       38
       38
       -
         | `By_column _ -> 'x'

     

       39
       39
       -
         | `By_column_and_free _ -> 'X'

     

       40
       40
       -
         | `By_row _ -> 'y'

     

       41
       41
       -
         | `By_row_and_free _ -> 'Y'

     

       42
       42
       -
         | `By_z_index _ -> 'z'

     

       43
       43
       -
         | `By_z_index_and_free _ -> 'Z'

     

       44
       44
       -
         | `By_id_range _ -> 'r'

     

       45
       45
       -
         | `By_id_range_and_free _ -> 'R'

     

       46
       46
       -
         | `Frames -> 'f'

     

       47
       47
       -
         | `Frames_and_free -> 'F'

     

       19
       19
       +
       let to_char ~free : t -> char =

     

       20
       20
       +
         let base = function

     

       21
       21
       +
           | `All_visible -> 'a'

     

       22
       22
       +
           | `By_id _ -> 'i'

     

       23
       23
       +
           | `By_number _ -> 'n'

     

       24
       24
       +
           | `At_cursor -> 'c'

     

       25
       25
       +
           | `At_cell _ -> 'p'

     

       26
       26
       +
           | `At_cell_z _ -> 'q'

     

       27
       27
       +
           | `By_column _ -> 'x'

     

       28
       28
       +
           | `By_row _ -> 'y'

     

       29
       29
       +
           | `By_z_index _ -> 'z'

     

       30
       30
       +
           | `By_id_range _ -> 'r'

     

       31
       31
       +
           | `Frames -> 'f'

     

       32
       32
       +
         in

     

       33
       33
       +
         fun t ->

     

       34
       34
       +
           let c = base t in

     

       35
       35
       +
           if free then Char.uppercase_ascii c else c

+82 -28

lib/kgp_delete.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       (** Image Deletion Target

     

       2
       7
        
       

     

       3
       3
       -
           Specifies which images or placements to delete. Each deletion type has

     

       4
       4
       -
           two variants: one that only removes placements and one that also frees

     

       5
       5
       -
           the underlying image data. *)

     

       8
       8
       +
           Specifies which images or placements to delete.

     

       9
       9
       +
       

     

       10
       10
       +
           {2 Protocol Details}

     

       11
       11
       +
       

     

       12
       12
       +
           Deletion is performed with action [a=d] and the [d] key specifies the

     

       13
       13
       +
           deletion type. The [d] key uses single characters:

     

       14
       14
       +
       

     

       15
       15
       +
           {v

     

       16
       16
       +
           | Char | Meaning                                                |

     

       17
       17
       +
           |------|--------------------------------------------------------|

     

       18
       18
       +
           | a/A  | All placements visible on screen                       |

     

       19
       19
       +
           | i/I  | By image ID (with optional placement ID)               |

     

       20
       20
       +
           | n/N  | By image number (newest with that number)              |

     

       21
       21
       +
           | c/C  | At current cursor position                             |

     

       22
       22
       +
           | p/P  | At specific cell coordinates (x, y)                    |

     

       23
       23
       +
           | q/Q  | At specific cell with z-index (x, y, z)                |

     

       24
       24
       +
           | x/X  | All in specific column                                 |

     

       25
       25
       +
           | y/Y  | All in specific row                                    |

     

       26
       26
       +
           | z/Z  | All with specific z-index                              |

     

       27
       27
       +
           | r/R  | By image ID range (min_id to max_id)                   |

     

       28
       28
       +
           | f/F  | Animation frames only                                  |

     

       29
       29
       +
           v}

     

       30
       30
       +
       

     

       31
       31
       +
           {2 Placements vs Image Data}

     

       32
       32
       +
       

     

       33
       33
       +
           Each deletion type can optionally free image data (controlled by the [~free]

     

       34
       34
       +
           parameter in the delete command):

     

       35
       35
       +
           - {b Without free}: Removes placements only. The image data remains in

     

       36
       36
       +
             memory and can be displayed again later. (Protocol: lowercase char)

     

       37
       37
       +
           - {b With free}: Removes placements AND frees the image data. The image

     

       38
       38
       +
             cannot be displayed again without retransmitting. (Protocol: uppercase

     

       39
       39
       +
             char)

     

       40
       40
       +
       

     

       41
       41
       +
           {2 Placement IDs}

     

       42
       42
       +
       

     

       43
       43
       +
           When deleting by image ID or number, an optional placement ID can be

     

       44
       44
       +
           specified to delete only a specific placement. If [None], all placements of

     

       45
       45
       +
           that image are deleted.

     

       46
       46
       +
       

     

       47
       47
       +
           {2 Coordinate-Based Deletion}

     

       48
       48
       +
       

     

       49
       49
       +
           For [{`At_cell}] and [{`At_cell_z}], coordinates are 0-based cell positions

     

       50
       50
       +
           (not pixel positions). Only placements that intersect the specified cell are

     

       51
       51
       +
           deleted.

     

       52
       52
       +
       

     

       53
       53
       +
           {2 Virtual Placements}

     

       54
       54
       +
       

     

       55
       55
       +
           Virtual placements (used for Unicode placeholder mode) are only affected by:

     

       56
       56
       +
           [{`By_id}], [{`By_number}], and [{`By_id_range}]. Other deletion commands do

     

       57
       57
       +
           not affect virtual placements. *)

     

       6
       58
        
       

     

       7
       59
        
       type t =

     

       8
       60
        
         [ `All_visible

     

       9
       9
       -
         | `All_visible_and_free

     

       10
       61
        
         | `By_id of int * int option

     

       11
       11
       -
         | `By_id_and_free of int * int option

     

       12
       62
        
         | `By_number of int * int option

     

       13
       13
       -
         | `By_number_and_free of int * int option

     

       14
       63
        
         | `At_cursor

     

       15
       15
       -
         | `At_cursor_and_free

     

       16
       64
        
         | `At_cell of int * int

     

       17
       17
       -
         | `At_cell_and_free of int * int

     

       18
       65
        
         | `At_cell_z of int * int * int

     

       19
       19
       -
         | `At_cell_z_and_free of int * int * int

     

       20
       66
        
         | `By_column of int

     

       21
       21
       -
         | `By_column_and_free of int

     

       22
       67
        
         | `By_row of int

     

       23
       23
       -
         | `By_row_and_free of int

     

       24
       68
        
         | `By_z_index of int

     

       25
       25
       -
         | `By_z_index_and_free of int

     

       26
       69
        
         | `By_id_range of int * int

     

       27
       27
       -
         | `By_id_range_and_free of int * int

     

       28
       28
       -
         | `Frames

     

       29
       29
       -
         | `Frames_and_free ]

     

       70
       70
       +
         | `Frames ]

     

       30
       71
        
       (** Deletion target specification.

     

       31
       72
        
       

     

       32
       32
       -
           - [`All_visible] - All visible placements

     

       33
       33
       -
           - [`By_id (id, placement_id)] - By image ID and optional placement ID

     

       34
       34
       -
           - [`By_number (n, placement_id)] - By image number and optional placement ID

     

       35
       35
       -
           - [`At_cursor] - Placement at cursor position

     

       36
       36
       -
           - [`At_cell (x, y)] - Placement at cell coordinates

     

       37
       37
       -
           - [`At_cell_z (x, y, z)] - Placement at cell with specific z-index

     

       38
       38
       -
           - [`By_column c] - All placements in column c

     

       39
       39
       -
           - [`By_row r] - All placements in row r

     

       73
       73
       +
           {b Screen-based:}

     

       74
       74
       +
           - [`All_visible] - All placements currently visible on screen

     

       75
       75
       +
           - [`At_cursor] - Placements at current cursor position

     

       76
       76
       +
           - [`At_cell (x, y)] - Placements intersecting cell at column x, row y

     

       77
       77
       +
           - [`At_cell_z (x, y, z)] - Like [`At_cell] but only with z-index z

     

       78
       78
       +
           - [`By_column x] - All placements intersecting column x

     

       79
       79
       +
           - [`By_row y] - All placements intersecting row y

     

       40
       80
        
           - [`By_z_index z] - All placements with z-index z

     

       41
       41
       -
           - [`By_id_range (min, max)] - All images with IDs in range

     

       42
       42
       -
           - [`Frames] - Animation frames only

     

       81
       81
       +
       

     

       82
       82
       +
           {b ID-based:}

     

       83
       83
       +
           - [`By_id (id, placement_id)] - By image ID. If [placement_id] is [Some p],

     

       84
       84
       +
             only that specific placement; if [None], all placements.

     

       85
       85
       +
           - [`By_number (n, placement_id)] - By image number (newest image with that

     

       86
       86
       +
             number). Placement ID works as above.

     

       87
       87
       +
           - [`By_id_range (min, max)] - All images with IDs in range [min..max]

     

       88
       88
       +
       

     

       89
       89
       +
           {b Animation:}

     

       90
       90
       +
           - [`Frames] - Animation frames only (not the base image)

     

       91
       91
       +
       

     

       92
       92
       +
           Use the [~free] parameter in the delete command to also release image data

     

       93
       93
       +
           from memory. *)

     

       43
       94
        
       

     

       44
       44
       -
           The [_and_free] variants also release the image data from memory. *)

     

       95
       95
       +
       val to_char : free:bool -> t -> char

     

       96
       96
       +
       (** Convert to protocol character for the delete command.

     

       45
       97
        
       

     

       46
       46
       -
       val to_char : t -> char

     

       47
       47
       -
       (** Convert to protocol character for the delete command. *)

     

       98
       98
       +
           Returns the character used in the [d=] control data key.

     

       99
       99
       +
           @param free

     

       100
       100
       +
             If true, returns uppercase (frees data); if false, returns lowercase

     

       101
       101
       +
             (keeps data). *)

lib/kgp_detect.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       (* Kitty Graphics Protocol Detection - Implementation *)

     

       2
       7
        
       

     

       3
       8
        
       let make_query () =

lib/kgp_detect.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       (** Kitty Graphics Protocol Detection

     

       2
       7
        
       

     

       3
       8
        
           Detect terminal graphics support capabilities. *)

+6 -4

lib/kgp_format.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       type t = [ `Rgba32 | `Rgb24 | `Png ]

     

       2
       7
        
       

     

       3
       3
       -
       let to_int : t -> int = function

     

       4
       4
       -
         | `Rgba32 -> 32

     

       5
       5
       -
         | `Rgb24 -> 24

     

       6
       6
       -
         | `Png -> 100

     

       8
       8
       +
       let to_int : t -> int = function `Rgba32 -> 32 | `Rgb24 -> 24 | `Png -> 100

+42 -5

lib/kgp_format.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       (** Image Data Format

     

       2
       7
        
       

     

       3
       3
       -
           Specifies the pixel format of image data being transmitted. *)

     

       8
       8
       +
           Specifies the pixel format of image data being transmitted to the terminal.

     

       9
       9
       +
       

     

       10
       10
       +
           {2 Protocol Details}

     

       11
       11
       +
       

     

       12
       12
       +
           The format is specified via the [f] key in the control data:

     

       13
       13
       +
           - [f=24] for RGB (3 bytes per pixel)

     

       14
       14
       +
           - [f=32] for RGBA (4 bytes per pixel, default)

     

       15
       15
       +
           - [f=100] for PNG

     

       16
       16
       +
       

     

       17
       17
       +
           {2 Raw Pixel Formats}

     

       18
       18
       +
       

     

       19
       19
       +
           For [{`Rgb24}] and [{`Rgba32}], the data consists of raw pixel values in

     

       20
       20
       +
           row-major order (left-to-right, top-to-bottom). The image dimensions must be

     

       21
       21
       +
           specified via the [width] and [height] parameters.

     

       22
       22
       +
       

     

       23
       23
       +
           - [{`Rgb24}]: 3 bytes per pixel in sRGB color space (red, green, blue)

     

       24
       24
       +
           - [{`Rgba32}]: 4 bytes per pixel (red, green, blue, alpha)

     

       25
       25
       +
       

     

       26
       26
       +
           {2 PNG Format}

     

       27
       27
       +
       

     

       28
       28
       +
           For [{`Png}], the data is a complete PNG image. The terminal extracts

     

       29
       29
       +
           dimensions from PNG metadata, so [width] and [height] are optional.

     

       30
       30
       +
       

     

       31
       31
       +
           When using both PNG format and zlib compression, you must also specify the

     

       32
       32
       +
           [size] parameter with the uncompressed PNG data size. *)

     

       4
       33
        
       

     

       5
       34
        
       type t = [ `Rgba32 | `Rgb24 | `Png ]

     

       6
       35
        
       (** Image data formats.

     

       7
       36
        
       

     

       8
       8
       -
           - [`Rgba32] - 32-bit RGBA (4 bytes per pixel)

     

       9
       9
       -
           - [`Rgb24] - 24-bit RGB (3 bytes per pixel)

     

       10
       10
       -
           - [`Png] - PNG encoded data *)

     

       37
       37
       +
           - [`Rgba32] - 32-bit RGBA (4 bytes per pixel). Default format. Pixels are

     

       38
       38
       +
             ordered red, green, blue, alpha. Alpha of 255 is fully opaque, 0 is fully

     

       39
       39
       +
             transparent.

     

       40
       40
       +
           - [`Rgb24] - 24-bit RGB (3 bytes per pixel). No alpha channel; pixels are

     

       41
       41
       +
             fully opaque. More compact than RGBA for opaque images.

     

       42
       42
       +
           - [`Png] - PNG encoded data. The terminal decodes the PNG internally.

     

       43
       43
       +
             Supports all PNG color types and bit depths. Most convenient format as

     

       44
       44
       +
             dimensions are embedded in the data. *)

     

       11
       45
        
       

     

       12
       46
        
       val to_int : t -> int

     

       13
       13
       -
       (** Convert to protocol integer value (32, 24, or 100). *)

     

       47
       47
       +
       (** Convert to protocol integer value.

     

       48
       48
       +
       

     

       49
       49
       +
           Returns 24 for [`Rgb24], 32 for [`Rgba32], or 100 for [`Png]. These values

     

       50
       50
       +
           are used in the [f=] control data key. *)

+7 -1

lib/kgp_frame.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       type t = {

     

       2
       7
        
         x : int option;

     

       3
       8
        
         y : int option;

     
···

       19
       24
        
           background_color = None;

     

       20
       25
        
         }

     

       21
       26
        
       

     

       22
       22
       -
       let make ?x ?y ?base_frame ?edit_frame ?gap_ms ?composition ?background_color () =

     

       27
       27
       +
       let make ?x ?y ?base_frame ?edit_frame ?gap_ms ?composition ?background_color ()

     

       28
       28
       +
           =

     

       23
       29
        
         { x; y; base_frame; edit_frame; gap_ms; composition; background_color }

     

       24
       30
        
       

     

       25
       31
        
       let x t = t.x

+103 -11

lib/kgp_frame.mli

···

       1
       1
       -
       (** Kitty Graphics Protocol Frame

     

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** Animation Frame Configuration

     

       7
       7
       +
       

     

       8
       8
       +
           Configuration for adding or editing animation frames. Frames can be full

     

       9
       9
       +
           images or partial updates (rectangles), with options for timing and

     

       10
       10
       +
           composition.

     

       11
       11
       +
       

     

       12
       12
       +
           {2 Protocol Overview}

     

       13
       13
       +
       

     

       14
       14
       +
           Animations are created by: 1. Transmitting a base image (becomes frame 1) 2.

     

       15
       15
       +
           Adding frames using the frame action ([a=f]) 3. Controlling playback with

     

       16
       16
       +
           animation commands

     

       17
       17
       +
       

     

       18
       18
       +
           Frame numbers are 1-based:

     

       19
       19
       +
           - Frame 1: The original/base image

     

       20
       20
       +
           - Frame 2+: Added animation frames

     

       21
       21
       +
       

     

       22
       22
       +
           {2 Frame Positioning}

     

       23
       23
       +
       

     

       24
       24
       +
           For partial frame updates, [x] and [y] specify where the new pixel data is

     

       25
       25
       +
           placed within the frame canvas:

     

       26
       26
       +
           - [x]: Left edge position in pixels (default 0)

     

       27
       27
       +
           - [y]: Top edge position in pixels (default 0)

     

       28
       28
       +
       

     

       29
       29
       +
           The frame data dimensions come from the [width] and [height] parameters of

     

       30
       30
       +
           the frame command.

     

       31
       31
       +
       

     

       32
       32
       +
           {2 Frame Canvas}

     

       2
       33
        
       

     

       3
       3
       -
           Animation frame configuration. *)

     

       34
       34
       +
           Each frame needs a background canvas to composite onto. Options:

     

       35
       35
       +
       

     

       36
       36
       +
           {b Solid color background} ([background_color]): Use a 32-bit RGBA color.

     

       37
       37
       +
           Format: [0xRRGGBBAA] where AA is alpha. Default is 0 (transparent black).

     

       38
       38
       +
       

     

       39
       39
       +
           {b Copy from existing frame} ([base_frame]): Use another frame as the

     

       40
       40
       +
           starting canvas. Specified as 1-based frame number. The base frame's pixels

     

       41
       41
       +
           are copied, then new data is composited.

     

       42
       42
       +
       

     

       43
       43
       +
           {2 Editing Existing Frames}

     

       44
       44
       +
       

     

       45
       45
       +
           Instead of creating a new frame, you can edit an existing one:

     

       46
       46
       +
           - Set [edit_frame] to the 1-based frame number

     

       47
       47
       +
           - The frame itself becomes the canvas

     

       48
       48
       +
           - New data is composited onto it

     

       49
       49
       +
       

     

       50
       50
       +
           {2 Frame Timing}

     

       51
       51
       +
       

     

       52
       52
       +
           The [gap_ms] parameter controls the delay before transitioning to the next

     

       53
       53
       +
           frame:

     

       54
       54
       +
           - Positive value: Delay in milliseconds

     

       55
       55
       +
           - Zero: Ignored (keeps existing gap)

     

       56
       56
       +
           - Negative value: "Gapless" frame - not displayed, used as a base for other

     

       57
       57
       +
             frames

     

       58
       58
       +
       

     

       59
       59
       +
           Default gap for new frames is 40ms. The root frame (frame 1) has a default

     

       60
       60
       +
           gap of 0ms.

     

       61
       61
       +
       

     

       62
       62
       +
           {2 Composition Mode}

     

       63
       63
       +
       

     

       64
       64
       +
           The [composition] parameter controls how new pixel data is blended onto the

     

       65
       65
       +
           canvas. *)

     

       4
       66
        
       

     

       5
       67
        
       type t

     

       6
       6
       -
       (** Animation frame configuration. *)

     

       68
       68
       +
       (** Animation frame configuration. Opaque type; use {!make} to construct. *)

     

       7
       69
        
       

     

       8
       70
        
       val make :

     

       9
       71
        
         ?x:int ->

     
···

       17
       79
        
         t

     

       18
       80
        
       (** Create a frame specification.

     

       19
       81
        
       

     

       20
       20
       -
           @param x Left edge where frame data is placed (pixels)

     

       21
       21
       -
           @param y Top edge where frame data is placed (pixels)

     

       22
       22
       -
           @param base_frame 1-based frame number to use as background canvas

     

       23
       23
       -
           @param edit_frame 1-based frame number to edit (0 = new frame)

     

       24
       24
       -
           @param gap_ms Delay before next frame in milliseconds

     

       25
       25
       -
           @param composition How to blend pixels onto the canvas

     

       26
       26
       -
           @param background_color 32-bit RGBA background when no base frame *)

     

       82
       82
       +
           @param x

     

       83
       83
       +
             Left edge where frame data is placed in pixels (default 0). Protocol key:

     

       84
       84
       +
             [x].

     

       85
       85
       +
           @param y

     

       86
       86
       +
             Top edge where frame data is placed in pixels (default 0). Protocol key:

     

       87
       87
       +
             [y].

     

       88
       88
       +
           @param base_frame

     

       89
       89
       +
             1-based frame number to use as background canvas. Frame 1 is the root

     

       90
       90
       +
             image. Protocol key: [c].

     

       91
       91
       +
           @param edit_frame

     

       92
       92
       +
             1-based frame number to edit instead of creating new. If 0 or unset, a new

     

       93
       93
       +
             frame is created. Protocol key: [r].

     

       94
       94
       +
           @param gap_ms

     

       95
       95
       +
             Delay before next frame in milliseconds. Negative values create gapless

     

       96
       96
       +
             frames. Protocol key: [z].

     

       97
       97
       +
           @param composition

     

       98
       98
       +
             How to blend new pixels onto the canvas. Default is alpha blending.

     

       99
       99
       +
             Protocol key: [X].

     

       100
       100
       +
           @param background_color

     

       101
       101
       +
             32-bit RGBA background color when not using a base frame. Format:

     

       102
       102
       +
             [0xRRGGBBAA]. Protocol key: [Y]. *)

     

       27
       103
        
       

     

       28
       104
        
       val empty : t

     

       29
       29
       -
       (** Empty frame spec with defaults. *)

     

       105
       105
       +
       (** Empty frame spec with all defaults.

     

       106
       106
       +
       

     

       107
       107
       +
           Creates a new frame with transparent black background, composited at

     

       108
       108
       +
           position (0, 0) with default timing (40ms gap). *)

     

       30
       109
        
       

     

       31
       110
        
       (** {1 Field Accessors} *)

     

       32
       111
        
       

     

       33
       112
        
       val x : t -> int option

     

       113
       113
       +
       (** Left edge position for frame data in pixels. *)

     

       114
       114
       +
       

     

       34
       115
        
       val y : t -> int option

     

       116
       116
       +
       (** Top edge position for frame data in pixels. *)

     

       117
       117
       +
       

     

       35
       118
        
       val base_frame : t -> int option

     

       119
       119
       +
       (** 1-based frame number to use as background canvas. *)

     

       120
       120
       +
       

     

       36
       121
        
       val edit_frame : t -> int option

     

       122
       122
       +
       (** 1-based frame number being edited (0 or None = new frame). *)

     

       123
       123
       +
       

     

       37
       124
        
       val gap_ms : t -> int option

     

       125
       125
       +
       (** Delay before next frame in milliseconds. *)

     

       126
       126
       +
       

     

       38
       127
        
       val composition : t -> Kgp_composition.t option

     

       128
       128
       +
       (** Pixel composition mode. *)

     

       129
       129
       +
       

     

       39
       130
        
       val background_color : t -> int32 option

     

       131
       131
       +
       (** 32-bit RGBA background color. *)

lib/kgp_placement.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       type t = {

     

       2
       7
        
         source_x : int option;

     

       3
       8
        
         source_y : int option;

+127 -16

lib/kgp_placement.mli

···

       1
       1
       -
       (** Kitty Graphics Protocol Placement

     

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       2
       5
        
       

     

       3
       3
       -
           Configuration for where and how to display images. *)

     

       6
       6
       +
       (** Image Placement Configuration

     

       7
       7
       +
       

     

       8
       8
       +
           Configuration for where and how to display images. Placements control

     

       9
       9
       +
           cropping, scaling, positioning, and layering of images.

     

       10
       10
       +
       

     

       11
       11
       +
           {2 Protocol Overview}

     

       12
       12
       +
       

     

       13
       13
       +
           When displaying an image, the protocol allows specifying:

     

       14
       14
       +
           - Which part of the source image to display (source rectangle)

     

       15
       15
       +
           - Where to display it (cell position and pixel offsets)

     

       16
       16
       +
           - How large to display it (scaling to cell dimensions)

     

       17
       17
       +
           - How it layers with other content (z-index)

     

       18
       18
       +
           - Whether it can be referenced via Unicode placeholders

     

       19
       19
       +
       

     

       20
       20
       +
           {2 Source Rectangle}

     

       21
       21
       +
       

     

       22
       22
       +
           The source rectangle specifies which portion of the image to display:

     

       23
       23
       +
           - [source_x], [source_y]: Top-left corner in pixels (default: 0, 0)

     

       24
       24
       +
           - [source_width], [source_height]: Size in pixels (default: full image)

     

       25
       25
       +
       

     

       26
       26
       +
           The displayed area is the intersection of this rectangle with the actual

     

       27
       27
       +
           image bounds. This allows cropping images without modifying the original

     

       28
       28
       +
           data.

     

       29
       29
       +
       

     

       30
       30
       +
           {2 Cell-Based Sizing}

     

       31
       31
       +
       

     

       32
       32
       +
           Images are sized in terminal cells:

     

       33
       33
       +
           - [columns]: Number of columns to span (width in cells)

     

       34
       34
       +
           - [rows]: Number of rows to span (height in cells)

     

       35
       35
       +
       

     

       36
       36
       +
           If both are specified, the source rectangle is scaled to fit. If only one is

     

       37
       37
       +
           specified, the other is computed to maintain aspect ratio. If neither is

     

       38
       38
       +
           specified, the image is displayed at natural size.

     

       39
       39
       +
       

     

       40
       40
       +
           {2 Pixel Offsets}

     

       41
       41
       +
       

     

       42
       42
       +
           Fine-grained positioning within the starting cell:

     

       43
       43
       +
           - [cell_x_offset]: Horizontal offset in pixels from cell left edge

     

       44
       44
       +
           - [cell_y_offset]: Vertical offset in pixels from cell top edge

     

       45
       45
       +
       

     

       46
       46
       +
           These offsets must be smaller than the cell dimensions.

     

       47
       47
       +
       

     

       48
       48
       +
           {2 Z-Index Layering}

     

       49
       49
       +
       

     

       50
       50
       +
           The [z_index] controls vertical stacking:

     

       51
       51
       +
           - Positive values: drawn above text

     

       52
       52
       +
           - Zero: drawn at text level

     

       53
       53
       +
           - Negative values: drawn below text

     

       54
       54
       +
           - Values < INT32_MIN/2 (-1,073,741,824): drawn under cells with non-default

     

       55
       55
       +
             background colors

     

       56
       56
       +
       

     

       57
       57
       +
           Overlapping images with the same z-index are ordered by image ID (lower ID

     

       58
       58
       +
           draws first/underneath).

     

       59
       59
       +
       

     

       60
       60
       +
           {2 Placement IDs}

     

       61
       61
       +
       

     

       62
       62
       +
           Each placement can have a unique [placement_id] (1-4294967295). This

     

       63
       63
       +
           enables:

     

       64
       64
       +
           - Updating a specific placement without affecting others

     

       65
       65
       +
           - Deleting specific placements

     

       66
       66
       +
           - Moving placements by resending with same image_id + placement_id

     

       67
       67
       +
       

     

       68
       68
       +
           If [placement_id] is 0 or unspecified, each display creates an independent

     

       69
       69
       +
           placement. *)

     

       4
       70
        
       

     

       5
       71
        
       type t

     

       6
       6
       -
       (** Placement configuration. *)

     

       72
       72
       +
       (** Placement configuration. Opaque type; use {!make} to construct. *)

     

       7
       73
        
       

     

       8
       74
        
       val make :

     

       9
       75
        
         ?source_x:int ->

     
···

       22
       88
        
         t

     

       23
       89
        
       (** Create a placement configuration.

     

       24
       90
        
       

     

       25
       25
       -
           @param source_x Left edge of source rectangle in pixels (default 0)

     

       26
       26
       -
           @param source_y Top edge of source rectangle in pixels (default 0)

     

       27
       27
       -
           @param source_width Width of source rectangle (default: full width)

     

       28
       28
       -
           @param source_height Height of source rectangle (default: full height)

     

       29
       29
       -
           @param cell_x_offset X offset within the first cell in pixels

     

       30
       30
       -
           @param cell_y_offset Y offset within the first cell in pixels

     

       31
       31
       -
           @param columns Number of columns to display over (scales image)

     

       32
       32
       -
           @param rows Number of rows to display over (scales image)

     

       33
       33
       -
           @param z_index Stacking order (negative = under text)

     

       34
       34
       -
           @param placement_id Unique ID for this placement

     

       35
       35
       -
           @param cursor Cursor movement policy after display

     

       36
       36
       -
           @param unicode_placeholder Create virtual placement for Unicode mode *)

     

       91
       91
       +
           @param source_x

     

       92
       92
       +
             Left edge of source rectangle in pixels (default 0). Protocol key: [x].

     

       93
       93
       +
           @param source_y

     

       94
       94
       +
             Top edge of source rectangle in pixels (default 0). Protocol key: [y].

     

       95
       95
       +
           @param source_width

     

       96
       96
       +
             Width of source rectangle in pixels. Default is the full image width.

     

       97
       97
       +
             Protocol key: [w].

     

       98
       98
       +
           @param source_height

     

       99
       99
       +
             Height of source rectangle in pixels. Default is the full image height.

     

       100
       100
       +
             Protocol key: [h].

     

       101
       101
       +
           @param cell_x_offset

     

       102
       102
       +
             X offset within the first cell in pixels. Must be smaller than cell width.

     

       103
       103
       +
             Protocol key: [X].

     

       104
       104
       +
           @param cell_y_offset

     

       105
       105
       +
             Y offset within the first cell in pixels. Must be smaller than cell

     

       106
       106
       +
             height. Protocol key: [Y].

     

       107
       107
       +
           @param columns

     

       108
       108
       +
             Number of columns to display over. Image is scaled to fit. Protocol key:

     

       109
       109
       +
             [c].

     

       110
       110
       +
           @param rows

     

       111
       111
       +
             Number of rows to display over. Image is scaled to fit. Protocol key: [r].

     

       112
       112
       +
           @param z_index

     

       113
       113
       +
             Stacking order. Positive = above text, negative = below. Protocol key:

     

       114
       114
       +
             [z].

     

       115
       115
       +
           @param placement_id

     

       116
       116
       +
             Unique ID (1-4294967295) for this placement. Allows updating/deleting

     

       117
       117
       +
             specific placements. Protocol key: [p].

     

       118
       118
       +
           @param cursor Cursor movement policy after display.

     

       119
       119
       +
           @param unicode_placeholder

     

       120
       120
       +
             If true, creates a virtual (invisible) placement for Unicode placeholder

     

       121
       121
       +
             mode. Protocol key: [U=1]. *)

     

       37
       122
        
       

     

       38
       123
        
       val empty : t

     

       39
       39
       -
       (** Empty placement with all defaults. *)

     

       124
       124
       +
       (** Empty placement with all defaults.

     

       125
       125
       +
       

     

       126
       126
       +
           Equivalent to [make ()]. The image displays at natural size at the current

     

       127
       127
       +
           cursor position with default z-index (0). *)

     

       40
       128
        
       

     

       41
       129
        
       (** {1 Field Accessors} *)

     

       42
       130
        
       

     

       43
       131
        
       val source_x : t -> int option

     

       132
       132
       +
       (** Left edge of source rectangle in pixels. *)

     

       133
       133
       +
       

     

       44
       134
        
       val source_y : t -> int option

     

       135
       135
       +
       (** Top edge of source rectangle in pixels. *)

     

       136
       136
       +
       

     

       45
       137
        
       val source_width : t -> int option

     

       138
       138
       +
       (** Width of source rectangle in pixels. *)

     

       139
       139
       +
       

     

       46
       140
        
       val source_height : t -> int option

     

       141
       141
       +
       (** Height of source rectangle in pixels. *)

     

       142
       142
       +
       

     

       47
       143
        
       val cell_x_offset : t -> int option

     

       144
       144
       +
       (** X offset within the first cell in pixels. *)

     

       145
       145
       +
       

     

       48
       146
        
       val cell_y_offset : t -> int option

     

       147
       147
       +
       (** Y offset within the first cell in pixels. *)

     

       148
       148
       +
       

     

       49
       149
        
       val columns : t -> int option

     

       150
       150
       +
       (** Number of columns to display over. *)

     

       151
       151
       +
       

     

       50
       152
        
       val rows : t -> int option

     

       153
       153
       +
       (** Number of rows to display over. *)

     

       154
       154
       +
       

     

       51
       155
        
       val z_index : t -> int option

     

       156
       156
       +
       (** Stacking order (z-index). *)

     

       157
       157
       +
       

     

       52
       158
        
       val placement_id : t -> int option

     

       159
       159
       +
       (** Unique placement identifier. *)

     

       160
       160
       +
       

     

       53
       161
        
       val cursor : t -> Kgp_cursor.t option

     

       162
       162
       +
       (** Cursor movement policy. *)

     

       163
       163
       +
       

     

       54
       164
        
       val unicode_placeholder : t -> bool

     

       165
       165
       +
       (** Whether this is a virtual placement for Unicode mode. *)

lib/kgp_quiet.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       type t = [ `Noisy | `Errors_only | `Silent ]

     

       2
       7
        
       

     

       3
       8
        
       let to_int : t -> int = function

+45 -5

lib/kgp_quiet.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       (** Response Suppression Level

     

       2
       7
        
       

     

       3
       3
       -
           Controls which terminal responses are sent back to the application. *)

     

       8
       8
       +
           Controls which terminal responses are sent back to the application.

     

       9
       9
       +
       

     

       10
       10
       +
           {2 Protocol Details}

     

       11
       11
       +
       

     

       12
       12
       +
           The quiet level is specified via the [q] key in the control data:

     

       13
       13
       +
           - [q=0] or no [q] key: send all responses (default)

     

       14
       14
       +
           - [q=1]: suppress OK responses, only send errors

     

       15
       15
       +
           - [q=2]: suppress all responses

     

       16
       16
       +
       

     

       17
       17
       +
           {2 Terminal Responses}

     

       18
       18
       +
       

     

       19
       19
       +
           Normally, when an [image_id] is specified, the terminal responds:

     

       20
       20
       +
           - On success: [ESC _Gi=ID;OK ESC]

     

       21
       21
       +
           - On failure: [ESC _Gi=ID;ECODE:message ESC]

     

       22
       22
       +
       

     

       23
       23
       +
           Response processing requires reading from the terminal, which can be complex

     

       24
       24
       +
           in some applications.

     

       25
       25
       +
       

     

       26
       26
       +
           {2 Use Cases}

     

       27
       27
       +
       

     

       28
       28
       +
           [{`Noisy}] (default): Use when you need to verify operations succeeded or

     

       29
       29
       +
           want to handle errors programmatically.

     

       30
       30
       +
       

     

       31
       31
       +
           [{`Errors_only}]: Use when you want to detect failures but don't need

     

       32
       32
       +
           confirmation of success. Reduces response traffic.

     

       33
       33
       +
       

     

       34
       34
       +
           [{`Silent}]: Use in fire-and-forget scenarios like shell scripts or when the

     

       35
       35
       +
           application cannot easily read terminal responses. Also useful for

     

       36
       36
       +
           high-frequency animation updates where response processing would add

     

       37
       37
       +
           latency. *)

     

       4
       38
        
       

     

       5
       39
        
       type t = [ `Noisy | `Errors_only | `Silent ]

     

       6
       40
        
       (** Response suppression levels.

     

       7
       41
        
       

     

       8
       8
       -
           - [`Noisy] - Send all responses (default)

     

       9
       9
       -
           - [`Errors_only] - Suppress OK responses, only send errors

     

       10
       10
       -
           - [`Silent] - Suppress all responses *)

     

       42
       42
       +
           - [`Noisy] - Send all responses including OK confirmations (default).

     

       43
       43
       +
             Required for detecting success and getting assigned image IDs.

     

       44
       44
       +
           - [`Errors_only] - Suppress OK responses, only send error messages. Useful

     

       45
       45
       +
             when success is expected but errors should be caught.

     

       46
       46
       +
           - [`Silent] - Suppress all responses including errors. Useful for shell

     

       47
       47
       +
             scripts or when response handling is not possible. *)

     

       11
       48
        
       

     

       12
       49
        
       val to_int : t -> int

     

       13
       13
       -
       (** Convert to protocol integer (0, 1, or 2). *)

     

       50
       50
       +
       (** Convert to protocol integer.

     

       51
       51
       +
       

     

       52
       52
       +
           Returns 0 for [`Noisy], 1 for [`Errors_only], or 2 for [`Silent]. These

     

       53
       53
       +
           values are used in the [q=] control data key. *)

+6 -1

lib/kgp_response.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       (* Kitty Graphics Protocol Response - Implementation *)

     

       2
       7
        
       

     

       3
       8
        
       type t = {

     
···

       15
       20
        
         else

     

       16
       21
        
           String.index_opt t.message ':'

     

       17
       22
        
           |> Option.fold ~none:(Some t.message) ~some:(fun i ->

     

       18
       18
       -
                  Some (String.sub t.message 0 i))

     

       23
       23
       +
               Some (String.sub t.message 0 i))

     

       19
       24
        
       

     

       20
       25
        
       let image_id t = t.image_id

     

       21
       26
        
       let image_number t = t.image_number

lib/kgp_response.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       (** Kitty Graphics Protocol Response

     

       2
       7
        
       

     

       3
       8
        
           Parse and interpret terminal responses to graphics commands. *)

+60

lib/kgp_terminal.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (* Terminal Environment Detection *)

     

       7
       7
       +
       

     

       8
       8
       +
       type graphics_mode = [ `Auto | `Enabled | `Disabled | `Tmux ]

     

       9
       9
       +
       

     

       10
       10
       +
       let is_kitty () =

     

       11
       11
       +
         Option.is_some (Sys.getenv_opt "KITTY_WINDOW_ID")

     

       12
       12
       +
         || (match Sys.getenv_opt "TERM" with

     

       13
       13
       +
           | Some term -> String.lowercase_ascii term = "xterm-kitty"

     

       14
       14
       +
           | None -> false)

     

       15
       15
       +
         ||

     

       16
       16
       +
         match Sys.getenv_opt "TERM_PROGRAM" with

     

       17
       17
       +
         | Some prog -> String.lowercase_ascii prog = "kitty"

     

       18
       18
       +
         | None -> false

     

       19
       19
       +
       

     

       20
       20
       +
       let is_wezterm () =

     

       21
       21
       +
         Option.is_some (Sys.getenv_opt "WEZTERM_PANE")

     

       22
       22
       +
         ||

     

       23
       23
       +
         match Sys.getenv_opt "TERM_PROGRAM" with

     

       24
       24
       +
         | Some prog -> String.lowercase_ascii prog = "wezterm"

     

       25
       25
       +
         | None -> false

     

       26
       26
       +
       

     

       27
       27
       +
       let is_ghostty () =

     

       28
       28
       +
         Option.is_some (Sys.getenv_opt "GHOSTTY_RESOURCES_DIR")

     

       29
       29
       +
         ||

     

       30
       30
       +
         match Sys.getenv_opt "TERM_PROGRAM" with

     

       31
       31
       +
         | Some prog -> String.lowercase_ascii prog = "ghostty"

     

       32
       32
       +
         | None -> false

     

       33
       33
       +
       

     

       34
       34
       +
       let is_graphics_terminal () = is_kitty () || is_wezterm () || is_ghostty ()

     

       35
       35
       +
       let is_tmux () = Kgp_tmux.is_active ()

     

       36
       36
       +
       let is_interactive () = Unix.isatty Unix.stdout

     

       37
       37
       +
       

     

       38
       38
       +
       let is_pager () =

     

       39
       39
       +
         (* Not interactive = likely piped to pager *)

     

       40
       40
       +
         (not (is_interactive ()))

     

       41
       41
       +
         ||

     

       42
       42
       +
         (* PAGER set and not in a known graphics terminal *)

     

       43
       43
       +
         (Option.is_some (Sys.getenv_opt "PAGER") && not (is_graphics_terminal ()))

     

       44
       44
       +
       

     

       45
       45
       +
       let resolve_mode = function

     

       46
       46
       +
         | `Disabled -> `Placeholder

     

       47
       47
       +
         | `Enabled -> `Graphics

     

       48
       48
       +
         | `Tmux -> `Tmux

     

       49
       49
       +
         | `Auto ->

     

       50
       50
       +
             if is_pager () || not (is_interactive ()) then `Placeholder

     

       51
       51
       +
             else if is_tmux () then

     

       52
       52
       +
               (* Inside tmux - use passthrough if underlying terminal supports graphics *)

     

       53
       53
       +
               if is_graphics_terminal () then `Tmux else `Placeholder

     

       54
       54
       +
             else if is_graphics_terminal () then `Graphics

     

       55
       55
       +
             else `Placeholder

     

       56
       56
       +
       

     

       57
       57
       +
       let supports_graphics mode =

     

       58
       58
       +
         match resolve_mode mode with

     

       59
       59
       +
         | `Graphics | `Tmux -> true

     

       60
       60
       +
         | `Placeholder -> false

+85

lib/kgp_terminal.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** Terminal Environment Detection

     

       7
       7
       +
       

     

       8
       8
       +
           Detect terminal capabilities and environment for graphics protocol support.

     

       9
       9
       +
       

     

       10
       10
       +
           {2 Supported Terminals}

     

       11
       11
       +
       

     

       12
       12
       +
           The following terminals support the Kitty Graphics Protocol:

     

       13
       13
       +
           - Kitty (the original implementation)

     

       14
       14
       +
           - WezTerm

     

       15
       15
       +
           - Ghostty

     

       16
       16
       +
           - Konsole (partial support)

     

       17
       17
       +
       

     

       18
       18
       +
           {2 Environment Detection}

     

       19
       19
       +
       

     

       20
       20
       +
           Detection is based on environment variables:

     

       21
       21
       +
           - [KITTY_WINDOW_ID] - set by Kitty

     

       22
       22
       +
           - [WEZTERM_PANE] - set by WezTerm

     

       23
       23
       +
           - [GHOSTTY_RESOURCES_DIR] - set by Ghostty

     

       24
       24
       +
           - [TERM_PROGRAM] - may contain terminal name

     

       25
       25
       +
           - [TERM] - may contain "kitty"

     

       26
       26
       +
           - [TMUX] - set when inside tmux

     

       27
       27
       +
           - [PAGER] / output to non-tty - indicates pager mode *)

     

       28
       28
       +
       

     

       29
       29
       +
       (** {1 Graphics Mode} *)

     

       30
       30
       +
       

     

       31
       31
       +
       type graphics_mode = [ `Auto | `Enabled | `Disabled | `Tmux ]

     

       32
       32
       +
       (** Graphics output mode.

     

       33
       33
       +
       

     

       34
       34
       +
           - [`Auto] - Auto-detect based on environment

     

       35
       35
       +
           - [`Enabled] - Force graphics enabled

     

       36
       36
       +
           - [`Disabled] - Force graphics disabled (use placeholders)

     

       37
       37
       +
           - [`Tmux] - Force tmux passthrough mode *)

     

       38
       38
       +
       

     

       39
       39
       +
       (** {1 Detection} *)

     

       40
       40
       +
       

     

       41
       41
       +
       val is_kitty : unit -> bool

     

       42
       42
       +
       (** Detect if running in Kitty terminal. *)

     

       43
       43
       +
       

     

       44
       44
       +
       val is_wezterm : unit -> bool

     

       45
       45
       +
       (** Detect if running in WezTerm terminal. *)

     

       46
       46
       +
       

     

       47
       47
       +
       val is_ghostty : unit -> bool

     

       48
       48
       +
       (** Detect if running in Ghostty terminal. *)

     

       49
       49
       +
       

     

       50
       50
       +
       val is_graphics_terminal : unit -> bool

     

       51
       51
       +
       (** Detect if running in any terminal that supports the graphics protocol. *)

     

       52
       52
       +
       

     

       53
       53
       +
       val is_tmux : unit -> bool

     

       54
       54
       +
       (** Detect if running inside tmux. *)

     

       55
       55
       +
       

     

       56
       56
       +
       val is_pager : unit -> bool

     

       57
       57
       +
       (** Detect if output is likely going to a pager.

     

       58
       58
       +
       

     

       59
       59
       +
           Returns [true] if:

     

       60
       60
       +
           - stdout is not a tty, or

     

       61
       61
       +
           - [PAGER] environment variable is set and we're not in a known

     

       62
       62
       +
             graphics-capable terminal *)

     

       63
       63
       +
       

     

       64
       64
       +
       val is_interactive : unit -> bool

     

       65
       65
       +
       (** Detect if running interactively (stdout is a tty). *)

     

       66
       66
       +
       

     

       67
       67
       +
       (** {1 Mode Resolution} *)

     

       68
       68
       +
       

     

       69
       69
       +
       val resolve_mode : graphics_mode -> [ `Graphics | `Tmux | `Placeholder ]

     

       70
       70
       +
       (** Resolve a graphics mode to the actual output method.

     

       71
       71
       +
       

     

       72
       72
       +
           - [`Graphics] - use direct graphics protocol

     

       73
       73
       +
           - [`Tmux] - use graphics protocol with tmux passthrough

     

       74
       74
       +
           - [`Placeholder] - use text placeholders (block characters)

     

       75
       75
       +
       

     

       76
       76
       +
           For [Auto] mode:

     

       77
       77
       +
           - If in a pager or non-interactive: [`Placeholder]

     

       78
       78
       +
           - If in tmux with graphics terminal: [`Tmux]

     

       79
       79
       +
           - If in graphics terminal: [`Graphics]

     

       80
       80
       +
           - Otherwise: [`Placeholder] *)

     

       81
       81
       +
       

     

       82
       82
       +
       val supports_graphics : graphics_mode -> bool

     

       83
       83
       +
       (** Check if the resolved mode supports graphics output.

     

       84
       84
       +
       

     

       85
       85
       +
           Returns [true] for [`Graphics] and [`Tmux], [false] for [`Placeholder]. *)

+27

lib/kgp_tmux.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (* Tmux Passthrough Support - Implementation *)

     

       7
       7
       +
       

     

       8
       8
       +
       let is_active () = Option.is_some (Sys.getenv_opt "TMUX")

     

       9
       9
       +
       

     

       10
       10
       +
       let write_wrapped buf s =

     

       11
       11
       +
         (* DCS passthrough prefix: ESC P tmux ; *)

     

       12
       12
       +
         Buffer.add_string buf "\027Ptmux;";

     

       13
       13
       +
         (* Double all ESC characters in the content *)

     

       14
       14
       +
         String.iter

     

       15
       15
       +
           (fun c ->

     

       16
       16
       +
             if c = '\027' then Buffer.add_string buf "\027\027"

     

       17
       17
       +
             else Buffer.add_char buf c)

     

       18
       18
       +
           s;

     

       19
       19
       +
         (* DCS terminator: ESC \ *)

     

       20
       20
       +
         Buffer.add_string buf "\027\\"

     

       21
       21
       +
       

     

       22
       22
       +
       let wrap_always s =

     

       23
       23
       +
         let buf = Buffer.create ((String.length s * 2) + 10) in

     

       24
       24
       +
         write_wrapped buf s;

     

       25
       25
       +
         Buffer.contents buf

     

       26
       26
       +
       

     

       27
       27
       +
       let wrap s = if is_active () then wrap_always s else s

+69

lib/kgp_tmux.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** Tmux Passthrough Support

     

       7
       7
       +
       

     

       8
       8
       +
           Support for passing graphics protocol escape sequences through tmux to the

     

       9
       9
       +
           underlying terminal emulator.

     

       10
       10
       +
       

     

       11
       11
       +
           {2 Background}

     

       12
       12
       +
       

     

       13
       13
       +
           When running inside tmux, graphics protocol escape sequences need to be

     

       14
       14
       +
           wrapped in a DCS (Device Control String) passthrough sequence so that tmux

     

       15
       15
       +
           forwards them to the actual terminal (kitty, wezterm, ghostty, etc.) rather

     

       16
       16
       +
           than interpreting them itself.

     

       17
       17
       +
       

     

       18
       18
       +
           The passthrough format is:

     

       19
       19
       +
           - Prefix: [ESC P tmux ;]

     

       20
       20
       +
           - Content with all ESC characters doubled

     

       21
       21
       +
           - Suffix: [ESC]

     

       22
       22
       +
       

     

       23
       23
       +
           {2 Requirements}

     

       24
       24
       +
       

     

       25
       25
       +
           For tmux passthrough to work:

     

       26
       26
       +
           {ul

     

       27
       27
       +
            {- tmux version 3.3 or later }

     

       28
       28
       +
            {- [allow-passthrough] must be enabled in tmux.conf:

     

       29
       29
       +
               {v set -g allow-passthrough on v}

     

       30
       30
       +
            }

     

       31
       31
       +
           }

     

       32
       32
       +
       

     

       33
       33
       +
           {2 Usage}

     

       34
       34
       +
       

     

       35
       35
       +
           {[

     

       36
       36
       +
             if Kgp.Tmux.is_active () then

     

       37
       37
       +
               let wrapped = Kgp.Tmux.wrap graphics_command in

     

       38
       38
       +
               print_string wrapped

     

       39
       39
       +
             else print_string graphics_command

     

       40
       40
       +
           ]} *)

     

       41
       41
       +
       

     

       42
       42
       +
       val is_active : unit -> bool

     

       43
       43
       +
       (** Detect if we are running inside tmux.

     

       44
       44
       +
       

     

       45
       45
       +
           Returns [true] if the [TMUX] environment variable is set, indicating the

     

       46
       46
       +
           process is running inside a tmux session. *)

     

       47
       47
       +
       

     

       48
       48
       +
       val wrap : string -> string

     

       49
       49
       +
       (** Wrap an escape sequence for tmux passthrough.

     

       50
       50
       +
       

     

       51
       51
       +
           Takes a graphics protocol escape sequence and wraps it in the tmux DCS

     

       52
       52
       +
           passthrough format:

     

       53
       53
       +
           - Adds [ESC P tmux ;] prefix

     

       54
       54
       +
           - Doubles all ESC characters in the content

     

       55
       55
       +
           - Adds [ESC] suffix

     

       56
       56
       +
       

     

       57
       57
       +
           If not running inside tmux, returns the input unchanged. *)

     

       58
       58
       +
       

     

       59
       59
       +
       val wrap_always : string -> string

     

       60
       60
       +
       (** Wrap an escape sequence for tmux passthrough unconditionally.

     

       61
       61
       +
       

     

       62
       62
       +
           Like {!wrap} but always applies the wrapping, regardless of whether we are

     

       63
       63
       +
           inside tmux. Useful when you want to pre-generate tmux-compatible output. *)

     

       64
       64
       +
       

     

       65
       65
       +
       val write_wrapped : Buffer.t -> string -> unit

     

       66
       66
       +
       (** Write a wrapped escape sequence directly to a buffer.

     

       67
       67
       +
       

     

       68
       68
       +
           More efficient than {!wrap_always} when building output in a buffer, as it

     

       69
       69
       +
           avoids allocating an intermediate string. *)

lib/kgp_transmission.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       type t = [ `Direct | `File | `Tempfile ]

     

       2
       7
        
       

     

       3
       8
        
       let to_char : t -> char = function

+57 -5

lib/kgp_transmission.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       (** Data Transmission Method

     

       2
       7
        
       

     

       3
       3
       -
           Specifies how image data is transmitted to the terminal. *)

     

       8
       8
       +
           Specifies how image data is transmitted to the terminal.

     

       9
       9
       +
       

     

       10
       10
       +
           {2 Protocol Details}

     

       11
       11
       +
       

     

       12
       12
       +
           The transmission method is specified via the [t] key in the control data:

     

       13
       13
       +
           - [t=d] for direct (inline) transmission (default)

     

       14
       14
       +
           - [t=f] for regular file

     

       15
       15
       +
           - [t=t] for temporary file (deleted after reading)

     

       16
       16
       +
       

     

       17
       17
       +
           {2 Direct Transmission}

     

       18
       18
       +
       

     

       19
       19
       +
           [{`Direct}] sends data inline within the escape sequence itself. The data is

     

       20
       20
       +
           base64-encoded in the payload section. This is the simplest method and works

     

       21
       21
       +
           over any connection (including SSH).

     

       22
       22
       +
       

     

       23
       23
       +
           For images larger than 4096 bytes (after base64 encoding), the data is

     

       24
       24
       +
           automatically split into chunks using the [m=] key:

     

       25
       25
       +
           - [m=1] indicates more chunks follow

     

       26
       26
       +
           - [m=0] indicates the final chunk

     

       27
       27
       +
       

     

       28
       28
       +
           {2 File Transmission}

     

       29
       29
       +
       

     

       30
       30
       +
           [{`File}] tells the terminal to read data from a file path. The path is sent

     

       31
       31
       +
           base64-encoded in the payload. Additional parameters:

     

       32
       32
       +
           - [S=] specifies the number of bytes to read

     

       33
       33
       +
           - [O=] specifies the byte offset to start reading from

     

       34
       34
       +
       

     

       35
       35
       +
           File transmission only works when the terminal and client share a filesystem

     

       36
       36
       +
           (i.e., local terminals, not SSH).

     

       37
       37
       +
       

     

       38
       38
       +
           Security: The terminal will refuse to read device files, sockets, or files

     

       39
       39
       +
           in sensitive locations like [/proc], [/sys], or [/dev].

     

       40
       40
       +
       

     

       41
       41
       +
           {2 Temporary File Transmission}

     

       42
       42
       +
       

     

       43
       43
       +
           [{`Tempfile}] is like [{`File}] but the terminal deletes the file after

     

       44
       44
       +
           reading. The file must be in a recognized temporary directory:

     

       45
       45
       +
           - [/tmp]

     

       46
       46
       +
           - [/dev/shm]

     

       47
       47
       +
           - The [TMPDIR] environment variable location

     

       48
       48
       +
           - Platform-specific temp directories containing [tty-graphics-protocol] *)

     

       4
       49
        
       

     

       5
       50
        
       type t = [ `Direct | `File | `Tempfile ]

     

       6
       51
        
       (** Transmission methods.

     

       7
       52
        
       

     

       8
       8
       -
           - [`Direct] - Data is sent inline in the escape sequence

     

       9
       9
       -
           - [`File] - Terminal reads from a file path

     

       10
       10
       -
           - [`Tempfile] - Terminal reads and deletes a temporary file *)

     

       53
       53
       +
           - [`Direct] - Data is sent inline in the escape sequence (base64-encoded).

     

       54
       54
       +
             Works over any connection including SSH. Automatic chunking for large

     

       55
       55
       +
             images.

     

       56
       56
       +
           - [`File] - Terminal reads from a file path sent in the payload. Only works

     

       57
       57
       +
             when terminal and client share a filesystem.

     

       58
       58
       +
           - [`Tempfile] - Like [`File] but terminal deletes the file after reading.

     

       59
       59
       +
             File must be in a recognized temporary directory. *)

     

       11
       60
        
       

     

       12
       61
        
       val to_char : t -> char

     

       13
       13
       -
       (** Convert to protocol character ('d', 'f', or 't'). *)

     

       62
       62
       +
       (** Convert to protocol character.

     

       63
       63
       +
       

     

       64
       64
       +
           Returns ['d'] for [`Direct], ['f'] for [`File], or ['t'] for [`Tempfile].

     

       65
       65
       +
           These values are used in the [t=] control data key. *)

+284 -44

lib/kgp_unicode.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       (* Kitty Graphics Protocol Unicode Placeholders - Implementation *)

     

       2
       7
        
       

     

       3
       8
        
       let placeholder_char = Uchar.of_int 0x10EEEE

     

       4
       9
        
       

     

       5
       10
        
       let diacritics =

     

       6
       11
        
         [|

     

       7
       7
       -
           0x0305; 0x030D; 0x030E; 0x0310; 0x0312; 0x033D; 0x033E; 0x033F;

     

       8
       8
       -
           0x0346; 0x034A; 0x034B; 0x034C; 0x0350; 0x0351; 0x0352; 0x0357;

     

       9
       9
       -
           0x035B; 0x0363; 0x0364; 0x0365; 0x0366; 0x0367; 0x0368; 0x0369;

     

       10
       10
       -
           0x036A; 0x036B; 0x036C; 0x036D; 0x036E; 0x036F; 0x0483; 0x0484;

     

       11
       11
       -
           0x0485; 0x0486; 0x0487; 0x0592; 0x0593; 0x0594; 0x0595; 0x0597;

     

       12
       12
       -
           0x0598; 0x0599; 0x059C; 0x059D; 0x059E; 0x059F; 0x05A0; 0x05A1;

     

       13
       13
       -
           0x05A8; 0x05A9; 0x05AB; 0x05AC; 0x05AF; 0x05C4; 0x0610; 0x0611;

     

       14
       14
       -
           0x0612; 0x0613; 0x0614; 0x0615; 0x0616; 0x0617; 0x0657; 0x0658;

     

       15
       15
       -
           0x0659; 0x065A; 0x065B; 0x065D; 0x065E; 0x06D6; 0x06D7; 0x06D8;

     

       16
       16
       -
           0x06D9; 0x06DA; 0x06DB; 0x06DC; 0x06DF; 0x06E0; 0x06E1; 0x06E2;

     

       17
       17
       -
           0x06E4; 0x06E7; 0x06E8; 0x06EB; 0x06EC; 0x0730; 0x0732; 0x0733;

     

       18
       18
       -
           0x0735; 0x0736; 0x073A; 0x073D; 0x073F; 0x0740; 0x0741; 0x0743;

     

       19
       19
       -
           0x0745; 0x0747; 0x0749; 0x074A; 0x07EB; 0x07EC; 0x07ED; 0x07EE;

     

       20
       20
       -
           0x07EF; 0x07F0; 0x07F1; 0x07F3; 0x0816; 0x0817; 0x0818; 0x0819;

     

       21
       21
       -
           0x081B; 0x081C; 0x081D; 0x081E; 0x081F; 0x0820; 0x0821; 0x0822;

     

       22
       22
       -
           0x0823; 0x0825; 0x0826; 0x0827; 0x0829; 0x082A; 0x082B; 0x082C;

     

       23
       23
       -
           0x082D; 0x0951; 0x0953; 0x0954; 0x0F82; 0x0F83; 0x0F86; 0x0F87;

     

       24
       24
       -
           0x135D; 0x135E; 0x135F; 0x17DD; 0x193A; 0x1A17; 0x1A75; 0x1A76;

     

       25
       25
       -
           0x1A77; 0x1A78; 0x1A79; 0x1A7A; 0x1A7B; 0x1A7C; 0x1B6B; 0x1B6D;

     

       26
       26
       -
           0x1B6E; 0x1B6F; 0x1B70; 0x1B71; 0x1B72; 0x1B73; 0x1CD0; 0x1CD1;

     

       27
       27
       -
           0x1CD2; 0x1CDA; 0x1CDB; 0x1CE0; 0x1DC0; 0x1DC1; 0x1DC3; 0x1DC4;

     

       28
       28
       -
           0x1DC5; 0x1DC6; 0x1DC7; 0x1DC8; 0x1DC9; 0x1DCB; 0x1DCC; 0x1DD1;

     

       29
       29
       -
           0x1DD2; 0x1DD3; 0x1DD4; 0x1DD5; 0x1DD6; 0x1DD7; 0x1DD8; 0x1DD9;

     

       30
       30
       -
           0x1DDA; 0x1DDB; 0x1DDC; 0x1DDD; 0x1DDE; 0x1DDF; 0x1DE0; 0x1DE1;

     

       31
       31
       -
           0x1DE2; 0x1DE3; 0x1DE4; 0x1DE5; 0x1DE6; 0x1DFE; 0x20D0; 0x20D1;

     

       32
       32
       -
           0x20D4; 0x20D5; 0x20D6; 0x20D7; 0x20DB; 0x20DC; 0x20E1; 0x20E7;

     

       33
       33
       -
           0x20E9; 0x20F0; 0xA66F; 0xA67C; 0xA67D; 0xA6F0; 0xA6F1; 0xA8E0;

     

       34
       34
       -
           0xA8E1; 0xA8E2; 0xA8E3; 0xA8E4; 0xA8E5; 0xA8E6; 0xA8E7; 0xA8E8;

     

       35
       35
       -
           0xA8E9; 0xA8EA; 0xA8EB; 0xA8EC; 0xA8ED; 0xA8EE; 0xA8EF; 0xA8F0;

     

       36
       36
       -
           0xA8F1; 0xAAB0; 0xAAB2; 0xAAB3; 0xAAB7; 0xAAB8; 0xAABE; 0xAABF;

     

       37
       37
       -
           0xAAC1; 0xFE20; 0xFE21; 0xFE22; 0xFE23; 0xFE24; 0xFE25; 0xFE26;

     

       38
       38
       -
           0x10A0F; 0x10A38; 0x1D185; 0x1D186; 0x1D187; 0x1D188; 0x1D189;

     

       39
       39
       -
           0x1D1AA; 0x1D1AB; 0x1D1AC; 0x1D1AD; 0x1D242; 0x1D243; 0x1D244;

     

       12
       12
       +
           0x0305;

     

       13
       13
       +
           0x030D;

     

       14
       14
       +
           0x030E;

     

       15
       15
       +
           0x0310;

     

       16
       16
       +
           0x0312;

     

       17
       17
       +
           0x033D;

     

       18
       18
       +
           0x033E;

     

       19
       19
       +
           0x033F;

     

       20
       20
       +
           0x0346;

     

       21
       21
       +
           0x034A;

     

       22
       22
       +
           0x034B;

     

       23
       23
       +
           0x034C;

     

       24
       24
       +
           0x0350;

     

       25
       25
       +
           0x0351;

     

       26
       26
       +
           0x0352;

     

       27
       27
       +
           0x0357;

     

       28
       28
       +
           0x035B;

     

       29
       29
       +
           0x0363;

     

       30
       30
       +
           0x0364;

     

       31
       31
       +
           0x0365;

     

       32
       32
       +
           0x0366;

     

       33
       33
       +
           0x0367;

     

       34
       34
       +
           0x0368;

     

       35
       35
       +
           0x0369;

     

       36
       36
       +
           0x036A;

     

       37
       37
       +
           0x036B;

     

       38
       38
       +
           0x036C;

     

       39
       39
       +
           0x036D;

     

       40
       40
       +
           0x036E;

     

       41
       41
       +
           0x036F;

     

       42
       42
       +
           0x0483;

     

       43
       43
       +
           0x0484;

     

       44
       44
       +
           0x0485;

     

       45
       45
       +
           0x0486;

     

       46
       46
       +
           0x0487;

     

       47
       47
       +
           0x0592;

     

       48
       48
       +
           0x0593;

     

       49
       49
       +
           0x0594;

     

       50
       50
       +
           0x0595;

     

       51
       51
       +
           0x0597;

     

       52
       52
       +
           0x0598;

     

       53
       53
       +
           0x0599;

     

       54
       54
       +
           0x059C;

     

       55
       55
       +
           0x059D;

     

       56
       56
       +
           0x059E;

     

       57
       57
       +
           0x059F;

     

       58
       58
       +
           0x05A0;

     

       59
       59
       +
           0x05A1;

     

       60
       60
       +
           0x05A8;

     

       61
       61
       +
           0x05A9;

     

       62
       62
       +
           0x05AB;

     

       63
       63
       +
           0x05AC;

     

       64
       64
       +
           0x05AF;

     

       65
       65
       +
           0x05C4;

     

       66
       66
       +
           0x0610;

     

       67
       67
       +
           0x0611;

     

       68
       68
       +
           0x0612;

     

       69
       69
       +
           0x0613;

     

       70
       70
       +
           0x0614;

     

       71
       71
       +
           0x0615;

     

       72
       72
       +
           0x0616;

     

       73
       73
       +
           0x0617;

     

       74
       74
       +
           0x0657;

     

       75
       75
       +
           0x0658;

     

       76
       76
       +
           0x0659;

     

       77
       77
       +
           0x065A;

     

       78
       78
       +
           0x065B;

     

       79
       79
       +
           0x065D;

     

       80
       80
       +
           0x065E;

     

       81
       81
       +
           0x06D6;

     

       82
       82
       +
           0x06D7;

     

       83
       83
       +
           0x06D8;

     

       84
       84
       +
           0x06D9;

     

       85
       85
       +
           0x06DA;

     

       86
       86
       +
           0x06DB;

     

       87
       87
       +
           0x06DC;

     

       88
       88
       +
           0x06DF;

     

       89
       89
       +
           0x06E0;

     

       90
       90
       +
           0x06E1;

     

       91
       91
       +
           0x06E2;

     

       92
       92
       +
           0x06E4;

     

       93
       93
       +
           0x06E7;

     

       94
       94
       +
           0x06E8;

     

       95
       95
       +
           0x06EB;

     

       96
       96
       +
           0x06EC;

     

       97
       97
       +
           0x0730;

     

       98
       98
       +
           0x0732;

     

       99
       99
       +
           0x0733;

     

       100
       100
       +
           0x0735;

     

       101
       101
       +
           0x0736;

     

       102
       102
       +
           0x073A;

     

       103
       103
       +
           0x073D;

     

       104
       104
       +
           0x073F;

     

       105
       105
       +
           0x0740;

     

       106
       106
       +
           0x0741;

     

       107
       107
       +
           0x0743;

     

       108
       108
       +
           0x0745;

     

       109
       109
       +
           0x0747;

     

       110
       110
       +
           0x0749;

     

       111
       111
       +
           0x074A;

     

       112
       112
       +
           0x07EB;

     

       113
       113
       +
           0x07EC;

     

       114
       114
       +
           0x07ED;

     

       115
       115
       +
           0x07EE;

     

       116
       116
       +
           0x07EF;

     

       117
       117
       +
           0x07F0;

     

       118
       118
       +
           0x07F1;

     

       119
       119
       +
           0x07F3;

     

       120
       120
       +
           0x0816;

     

       121
       121
       +
           0x0817;

     

       122
       122
       +
           0x0818;

     

       123
       123
       +
           0x0819;

     

       124
       124
       +
           0x081B;

     

       125
       125
       +
           0x081C;

     

       126
       126
       +
           0x081D;

     

       127
       127
       +
           0x081E;

     

       128
       128
       +
           0x081F;

     

       129
       129
       +
           0x0820;

     

       130
       130
       +
           0x0821;

     

       131
       131
       +
           0x0822;

     

       132
       132
       +
           0x0823;

     

       133
       133
       +
           0x0825;

     

       134
       134
       +
           0x0826;

     

       135
       135
       +
           0x0827;

     

       136
       136
       +
           0x0829;

     

       137
       137
       +
           0x082A;

     

       138
       138
       +
           0x082B;

     

       139
       139
       +
           0x082C;

     

       140
       140
       +
           0x082D;

     

       141
       141
       +
           0x0951;

     

       142
       142
       +
           0x0953;

     

       143
       143
       +
           0x0954;

     

       144
       144
       +
           0x0F82;

     

       145
       145
       +
           0x0F83;

     

       146
       146
       +
           0x0F86;

     

       147
       147
       +
           0x0F87;

     

       148
       148
       +
           0x135D;

     

       149
       149
       +
           0x135E;

     

       150
       150
       +
           0x135F;

     

       151
       151
       +
           0x17DD;

     

       152
       152
       +
           0x193A;

     

       153
       153
       +
           0x1A17;

     

       154
       154
       +
           0x1A75;

     

       155
       155
       +
           0x1A76;

     

       156
       156
       +
           0x1A77;

     

       157
       157
       +
           0x1A78;

     

       158
       158
       +
           0x1A79;

     

       159
       159
       +
           0x1A7A;

     

       160
       160
       +
           0x1A7B;

     

       161
       161
       +
           0x1A7C;

     

       162
       162
       +
           0x1B6B;

     

       163
       163
       +
           0x1B6D;

     

       164
       164
       +
           0x1B6E;

     

       165
       165
       +
           0x1B6F;

     

       166
       166
       +
           0x1B70;

     

       167
       167
       +
           0x1B71;

     

       168
       168
       +
           0x1B72;

     

       169
       169
       +
           0x1B73;

     

       170
       170
       +
           0x1CD0;

     

       171
       171
       +
           0x1CD1;

     

       172
       172
       +
           0x1CD2;

     

       173
       173
       +
           0x1CDA;

     

       174
       174
       +
           0x1CDB;

     

       175
       175
       +
           0x1CE0;

     

       176
       176
       +
           0x1DC0;

     

       177
       177
       +
           0x1DC1;

     

       178
       178
       +
           0x1DC3;

     

       179
       179
       +
           0x1DC4;

     

       180
       180
       +
           0x1DC5;

     

       181
       181
       +
           0x1DC6;

     

       182
       182
       +
           0x1DC7;

     

       183
       183
       +
           0x1DC8;

     

       184
       184
       +
           0x1DC9;

     

       185
       185
       +
           0x1DCB;

     

       186
       186
       +
           0x1DCC;

     

       187
       187
       +
           0x1DD1;

     

       188
       188
       +
           0x1DD2;

     

       189
       189
       +
           0x1DD3;

     

       190
       190
       +
           0x1DD4;

     

       191
       191
       +
           0x1DD5;

     

       192
       192
       +
           0x1DD6;

     

       193
       193
       +
           0x1DD7;

     

       194
       194
       +
           0x1DD8;

     

       195
       195
       +
           0x1DD9;

     

       196
       196
       +
           0x1DDA;

     

       197
       197
       +
           0x1DDB;

     

       198
       198
       +
           0x1DDC;

     

       199
       199
       +
           0x1DDD;

     

       200
       200
       +
           0x1DDE;

     

       201
       201
       +
           0x1DDF;

     

       202
       202
       +
           0x1DE0;

     

       203
       203
       +
           0x1DE1;

     

       204
       204
       +
           0x1DE2;

     

       205
       205
       +
           0x1DE3;

     

       206
       206
       +
           0x1DE4;

     

       207
       207
       +
           0x1DE5;

     

       208
       208
       +
           0x1DE6;

     

       209
       209
       +
           0x1DFE;

     

       210
       210
       +
           0x20D0;

     

       211
       211
       +
           0x20D1;

     

       212
       212
       +
           0x20D4;

     

       213
       213
       +
           0x20D5;

     

       214
       214
       +
           0x20D6;

     

       215
       215
       +
           0x20D7;

     

       216
       216
       +
           0x20DB;

     

       217
       217
       +
           0x20DC;

     

       218
       218
       +
           0x20E1;

     

       219
       219
       +
           0x20E7;

     

       220
       220
       +
           0x20E9;

     

       221
       221
       +
           0x20F0;

     

       222
       222
       +
           0xA66F;

     

       223
       223
       +
           0xA67C;

     

       224
       224
       +
           0xA67D;

     

       225
       225
       +
           0xA6F0;

     

       226
       226
       +
           0xA6F1;

     

       227
       227
       +
           0xA8E0;

     

       228
       228
       +
           0xA8E1;

     

       229
       229
       +
           0xA8E2;

     

       230
       230
       +
           0xA8E3;

     

       231
       231
       +
           0xA8E4;

     

       232
       232
       +
           0xA8E5;

     

       233
       233
       +
           0xA8E6;

     

       234
       234
       +
           0xA8E7;

     

       235
       235
       +
           0xA8E8;

     

       236
       236
       +
           0xA8E9;

     

       237
       237
       +
           0xA8EA;

     

       238
       238
       +
           0xA8EB;

     

       239
       239
       +
           0xA8EC;

     

       240
       240
       +
           0xA8ED;

     

       241
       241
       +
           0xA8EE;

     

       242
       242
       +
           0xA8EF;

     

       243
       243
       +
           0xA8F0;

     

       244
       244
       +
           0xA8F1;

     

       245
       245
       +
           0xAAB0;

     

       246
       246
       +
           0xAAB2;

     

       247
       247
       +
           0xAAB3;

     

       248
       248
       +
           0xAAB7;

     

       249
       249
       +
           0xAAB8;

     

       250
       250
       +
           0xAABE;

     

       251
       251
       +
           0xAABF;

     

       252
       252
       +
           0xAAC1;

     

       253
       253
       +
           0xFE20;

     

       254
       254
       +
           0xFE21;

     

       255
       255
       +
           0xFE22;

     

       256
       256
       +
           0xFE23;

     

       257
       257
       +
           0xFE24;

     

       258
       258
       +
           0xFE25;

     

       259
       259
       +
           0xFE26;

     

       260
       260
       +
           0x10A0F;

     

       261
       261
       +
           0x10A38;

     

       262
       262
       +
           0x1D185;

     

       263
       263
       +
           0x1D186;

     

       264
       264
       +
           0x1D187;

     

       265
       265
       +
           0x1D188;

     

       266
       266
       +
           0x1D189;

     

       267
       267
       +
           0x1D1AA;

     

       268
       268
       +
           0x1D1AB;

     

       269
       269
       +
           0x1D1AC;

     

       270
       270
       +
           0x1D1AD;

     

       271
       271
       +
           0x1D242;

     

       272
       272
       +
           0x1D243;

     

       273
       273
       +
           0x1D244;

     

       40
       274
        
         |]

     

       41
       275
        
       

     

       42
       276
        
       let diacritic n = Uchar.of_int diacritics.(n mod Array.length diacritics)

     

       43
       277
        
       let row_diacritic = diacritic

     

       44
       278
        
       let column_diacritic = diacritic

     

       45
       279
        
       let id_high_byte_diacritic = diacritic

     

       280
       280
       +
       

     

       281
       281
       +
       let next_image_id () =

     

       282
       282
       +
         let rec gen () =

     

       283
       283
       +
           let id = Random.int32 Int32.max_int |> Int32.to_int in

     

       284
       284
       +
           (* Ensure high byte and middle bytes are non-zero *)

     

       285
       285
       +
           if id land 0xFF000000 = 0 || id land 0x00FFFF00 = 0 then gen () else id

     

       286
       286
       +
         in

     

       287
       287
       +
         gen ()

     

       46
       288
        
       

     

       47
       289
        
       let add_uchar buf u =

     

       48
       290
        
         let code = Uchar.to_int u in

     
···

       62
       304
        
           put (Char.chr (0x80 lor (code land 0x3F))))

     

       63
       305
        
       

     

       64
       306
        
       let write buf ~image_id ?placement_id ~rows ~cols () =

     

       65
       65
       -
         (* Set foreground color *)

     

       66
       66
       -
         Printf.bprintf buf "\027[38;2;%d;%d;%dm"

     

       307
       307
       +
         (* Set foreground color using colon subparameter format *)

     

       308
       308
       +
         Printf.bprintf buf "\027[38:2:%d:%d:%dm"

     

       67
       309
        
           ((image_id lsr 16) land 0xFF)

     

       68
       310
        
           ((image_id lsr 8) land 0xFF)

     

       69
       311
        
           (image_id land 0xFF);

     

       70
       312
        
         (* Optional placement ID in underline color *)

     

       71
       313
        
         placement_id

     

       72
       314
        
         |> Option.iter (fun pid ->

     

       73
       73
       -
                Printf.bprintf buf "\027[58;2;%d;%d;%dm"

     

       74
       74
       -
                  ((pid lsr 16) land 0xFF)

     

       75
       75
       -
                  ((pid lsr 8) land 0xFF)

     

       76
       76
       -
                  (pid land 0xFF));

     

       77
       77
       -
         (* High byte diacritic *)

     

       315
       315
       +
             Printf.bprintf buf "\027[58:2:%d:%d:%dm"

     

       316
       316
       +
               ((pid lsr 16) land 0xFF)

     

       317
       317
       +
               ((pid lsr 8) land 0xFF)

     

       318
       318
       +
               (pid land 0xFF));

     

       319
       319
       +
         (* High byte diacritic - always written, even when 0 *)

     

       78
       320
        
         let high_byte = (image_id lsr 24) land 0xFF in

     

       79
       79
       -
         let high_diac =

     

       80
       80
       -
           if high_byte > 0 then Some (id_high_byte_diacritic high_byte) else None

     

       81
       81
       -
         in

     

       321
       321
       +
         let id_diac = id_high_byte_diacritic high_byte in

     

       82
       322
        
         (* Write grid *)

     

       83
       323
        
         for row = 0 to rows - 1 do

     

       84
       324
        
           for col = 0 to cols - 1 do

     

       85
       325
        
             add_uchar buf placeholder_char;

     

       86
       326
        
             add_uchar buf (row_diacritic row);

     

       87
       327
        
             add_uchar buf (column_diacritic col);

     

       88
       88
       -
             high_diac |> Option.iter (add_uchar buf)

     

       328
       328
       +
             add_uchar buf id_diac

     

       89
       329
        
           done;

     

       90
       330
        
           if row < rows - 1 then Buffer.add_string buf "\n\r"

     

       91
       331
        
         done;

+34 -3

lib/kgp_unicode.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       1
       6
        
       (** Kitty Graphics Protocol Unicode Placeholders

     

       2
       7
        
       

     

       3
       3
       -
           Support for invisible Unicode placeholder characters that encode

     

       4
       4
       -
           image position metadata for accessibility and compatibility. *)

     

       8
       8
       +
           Support for invisible Unicode placeholder characters that encode image

     

       9
       9
       +
           position metadata for accessibility and compatibility.

     

       10
       10
       +
       

     

       11
       11
       +
           {2 Image ID Requirements}

     

       12
       12
       +
       

     

       13
       13
       +
           When using unicode placeholders, image IDs must have non-zero bytes in

     

       14
       14
       +
           specific positions for correct rendering:

     

       15
       15
       +
           - High byte (bits 24-31): encoded as the third combining diacritic

     

       16
       16
       +
           - Middle bytes (bits 8-23): encoded in the foreground RGB color

     

       17
       17
       +
       

     

       18
       18
       +
           Use {!next_image_id} to generate IDs that satisfy these requirements. *)

     

       5
       19
        
       

     

       6
       20
        
       val placeholder_char : Uchar.t

     

       7
       21
        
       (** The Unicode placeholder character U+10EEEE. *)

     

       8
       22
        
       

     

       23
       23
       +
       val next_image_id : unit -> int

     

       24
       24
       +
       (** Generate a random image ID suitable for unicode placeholders.

     

       25
       25
       +
       

     

       26
       26
       +
           The returned ID has non-zero bytes in all required positions:

     

       27
       27
       +
           - High byte (bits 24-31) is non-zero

     

       28
       28
       +
           - Middle bytes (bits 8-23) are non-zero

     

       29
       29
       +
       

     

       30
       30
       +
           This ensures the foreground color encoding and diacritic encoding work

     

       31
       31
       +
           correctly. Uses [Random] internally. *)

     

       32
       32
       +
       

     

       9
       33
        
       val write :

     

       10
       34
        
         Buffer.t ->

     

       11
       35
        
         image_id:int ->

     
···

       14
       38
        
         cols:int ->

     

       15
       39
        
         unit ->

     

       16
       40
        
         unit

     

       17
       17
       -
       (** Write placeholder characters to a buffer. *)

     

       41
       41
       +
       (** Write placeholder characters to a buffer.

     

       42
       42
       +
       

     

       43
       43
       +
           @param image_id

     

       44
       44
       +
             Should be generated with {!next_image_id} for correct rendering.

     

       45
       45
       +
           @param placement_id

     

       46
       46
       +
             Optional placement ID for multiple placements of same image.

     

       47
       47
       +
           @param rows Number of rows in the placeholder grid.

     

       48
       48
       +
           @param cols Number of columns in the placeholder grid. *)

     

       18
       49
        
       

     

       19
       50
        
       val row_diacritic : int -> Uchar.t

     

       20
       51
        
       (** Get the combining diacritic for a row number (0-based). *)

lib-cli/dune

···

       1
       1
       +
       (library

     

       2
       2
       +
        (name kgp_cli)

     

       3
       3
       +
        (public_name kgp.cli)

     

       4
       4
       +
        (libraries kgp cmdliner))

+29

lib-cli/kgp_cli.ml

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (* Cmdliner Support for Kitty Graphics Protocol *)

     

       7
       7
       +
       

     

       8
       8
       +
       open Cmdliner

     

       9
       9
       +
       

     

       10
       10
       +
       let graphics_docs = "GRAPHICS OPTIONS"

     

       11
       11
       +
       

     

       12
       12
       +
       let graphics_term =

     

       13
       13
       +
         let doc = "Force graphics output enabled, ignoring terminal detection." in

     

       14
       14
       +
         let enable = Arg.info [ "g"; "graphics" ] ~doc ~docs:graphics_docs in

     

       15
       15
       +
         let doc = "Disable graphics output, use text placeholders instead." in

     

       16
       16
       +
         let disable = Arg.info [ "no-graphics" ] ~doc ~docs:graphics_docs in

     

       17
       17
       +
         let doc = "Force tmux passthrough mode for graphics." in

     

       18
       18
       +
         let tmux = Arg.info [ "tmux" ] ~doc ~docs:graphics_docs in

     

       19
       19
       +
         let choose enable disable tmux : Kgp.Terminal.graphics_mode =

     

       20
       20
       +
           if enable then `Enabled

     

       21
       21
       +
           else if disable then `Disabled

     

       22
       22
       +
           else if tmux then `Tmux

     

       23
       23
       +
           else `Auto

     

       24
       24
       +
         in

     

       25
       25
       +
         Term.(

     

       26
       26
       +
           const choose

     

       27
       27
       +
           $ Arg.(value & flag enable)

     

       28
       28
       +
           $ Arg.(value & flag disable)

     

       29
       29
       +
           $ Arg.(value & flag tmux))

+52

lib-cli/kgp_cli.mli

···

       1
       1
       +
       (*---------------------------------------------------------------------------

     

       2
       2
       +
          Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.

     

       3
       3
       +
          SPDX-License-Identifier: ISC

     

       4
       4
       +
         ---------------------------------------------------------------------------*)

     

       5
       5
       +
       

     

       6
       6
       +
       (** Cmdliner Support for Kitty Graphics Protocol

     

       7
       7
       +
       

     

       8
       8
       +
           This module provides Cmdliner terms for configuring graphics output mode in

     

       9
       9
       +
           CLI applications. It allows users to override auto-detection with

     

       10
       10
       +
           command-line flags.

     

       11
       11
       +
       

     

       12
       12
       +
           {2 Usage}

     

       13
       13
       +
       

     

       14
       14
       +
           Add the graphics term to your command:

     

       15
       15
       +
       

     

       16
       16
       +
           {[

     

       17
       17
       +
             let cmd =

     

       18
       18
       +
               let graphics = Kgp_cli.graphics_term in

     

       19
       19
       +
               let my_args = ... in

     

       20
       20
       +
               Cmd.v info Term.(const my_run $ graphics $ my_args)

     

       21
       21
       +
           ]}

     

       22
       22
       +
       

     

       23
       23
       +
           Then use the resolved mode in your application:

     

       24
       24
       +
       

     

       25
       25
       +
           {[

     

       26
       26
       +
             let my_run graphics_mode args =

     

       27
       27
       +
               if Kgp.Terminal.supports_graphics graphics_mode then

     

       28
       28
       +
                 (* render with graphics *)

     

       29
       29
       +
               else

     

       30
       30
       +
                 (* use text fallback *)

     

       31
       31
       +
           ]} *)

     

       32
       32
       +
       

     

       33
       33
       +
       (** {1 Terms} *)

     

       34
       34
       +
       

     

       35
       35
       +
       val graphics_term : Kgp.Terminal.graphics_mode Cmdliner.Term.t

     

       36
       36
       +
       (** Cmdliner term for graphics mode selection.

     

       37
       37
       +
       

     

       38
       38
       +
           Provides the following command-line options:

     

       39
       39
       +
       

     

       40
       40
       +
           - [--graphics] / [-g]: Force graphics output enabled

     

       41
       41
       +
           - [--no-graphics]: Force graphics output disabled (use placeholders)

     

       42
       42
       +
           - [--tmux]: Force tmux passthrough mode

     

       43
       43
       +
           - (default): Auto-detect based on terminal environment

     

       44
       44
       +
       

     

       45
       45
       +
           The term evaluates to a {!Kgp.Terminal.graphics_mode} value which can be

     

       46
       46
       +
           passed to {!Kgp.Terminal.supports_graphics} or {!Kgp.Terminal.resolve_mode}.

     

       47
       47
       +
       *)

     

       48
       48
       +
       

     

       49
       49
       +
       val graphics_docs : string

     

       50
       50
       +
       (** Section name for graphics options in help output ("GRAPHICS OPTIONS").

     

       51
       51
       +
       

     

       52
       52
       +
           Use this when grouping graphics options in a separate help section. *)

Compare changes