commit a53ec3d6eca0a8e15dc835927efbef54bd8e96a3 · anil.recoil.org/ocaml-kgp

.ocamlformat

···

       1
       1
       +
       version=0.28.1

+10 -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))

     

       11
       20
        
         cmdliner

+83 -152

example/example.ml

···

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

     

       36
       36
        
         for y = 0 to height - 1 do

     

       37
       37
        
           for x = 0 to width - 1 do

     

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

     

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

     

       39
       39
        
             let r = 255 * x / width in

     

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

     

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

     
···

       66
       66
        
       

     

       67
       67
        
       let clear_screen () =

     

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

     

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

     

       69
       69
       +
         for _ = 1 to 5 do

     

       70
       70
       +
           print_newline ()

     

       71
       71
       +
         done;

     

       70
       72
        
         flush stdout

     

       71
       73
        
       

     

       72
       74
        
       let () =

     
···

       87
       89
        
         (try

     

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

     

       89
       91
        
            send

     

       90
       90
       -
              (K.transmit_and_display

     

       91
       91
       -
                 ~image_id:1

     

       92
       92
       -
                 ~format:`Png

     

       93
       93
       -
                 ~quiet:`Errors_only

     

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

     

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

     

       95
       94
        
                 ())

     

       96
       95
        
              ~data:png_data;

     

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

     

       98
       97
        
          with _ ->

     

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

     

       100
       100
       -
            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

     

       101
       102
        
            send

     

       102
       102
       -
              (K.transmit_and_display

     

       103
       103
       -
                 ~image_id:1

     

       104
       104
       -
                 ~format:`Rgba32

     

       105
       105
       -
                 ~width:100 ~height:100

     

       106
       106
       -
                 ~quiet:`Errors_only

     

       107
       107
       -
                 ())

     

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

     

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

     

       108
       105
        
              ~data:red_data;

     

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

     

       110
       107
        
         print_newline ();

     
···

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

     

       114
       111
        
         clear_screen ();

     

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

     

       116
       116
       -
         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

     

       117
       116
        
         send

     

       118
       118
       -
           (K.transmit_and_display

     

       119
       119
       -
              ~image_id:2

     

       120
       120
       -
              ~format:`Rgba32

     

       121
       121
       -
              ~width:100 ~height:100

     

       122
       122
       -
              ~quiet:`Errors_only

     

       123
       123
       -
              ())

     

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

     

       118
       118
       +
              ~quiet:`Errors_only ())

     

       124
       119
        
           ~data:blue_data;

     

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

     

       126
       121
        
         print_newline ();

     
···

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

     

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

     

       133
       128
        
         send

     

       134
       134
       -
           (K.transmit_and_display

     

       135
       135
       -
              ~image_id:3

     

       136
       136
       -
              ~format:`Rgb24

     

       137
       137
       -
              ~width:100 ~height:100

     

       138
       138
       -
              ~quiet:`Errors_only

     

       139
       139
       -
              ())

     

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

     

       130
       130
       +
              ~quiet:`Errors_only ())

     

       140
       131
        
           ~data:green_data;

     

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

     

       142
       133
        
         print_newline ();

     
···

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

     

       146
       137
        
         clear_screen ();

     

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

     

       148
       148
       -
         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

     

       149
       142
        
         send

     

       150
       150
       -
           (K.transmit_and_display

     

       151
       151
       -
              ~image_id:4

     

       152
       152
       -
              ~format:`Rgba32

     

       153
       153
       -
              ~width:200 ~height:200

     

       154
       154
       -
              ~quiet:`Errors_only

     

       155
       155
       -
              ())

     

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

     

       144
       144
       +
              ~quiet:`Errors_only ())

     

       156
       145
        
           ~data:orange_data;

     

       157
       157
       -
         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);

     

       158
       148
        
         print_newline ();

     

       159
       149
        
         wait_for_enter ();

     

       160
       150
        
       

     
···

       164
       154
        
         (try

     

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

     

       166
       156
        
            send

     

       167
       167
       -
              (K.transmit_and_display

     

       168
       168
       -
                 ~image_id:10

     

       169
       169
       -
                 ~format:`Png

     

       170
       170
       -
                 ~quiet:`Errors_only

     

       171
       171
       -
                 ())

     

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

     

       172
       158
        
              ~data:png_data;

     

       173
       159
        
            print_endline "camel.png loaded and displayed"

     

       174
       174
       -
          with Sys_error msg ->

     

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

     

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

     

       176
       161
        
         print_newline ();

     

       177
       162
        
         wait_for_enter ();

     

       178
       163
        
       

     
···

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

     

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

     

       183
       168
        
         send

     

       184
       184
       -
           (K.transmit_and_display

     

       185
       185
       -
              ~image_id:20

     

       186
       186
       -
              ~format:`Rgba32

     

       187
       187
       -
              ~width:200 ~height:200

     

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

     

       189
       189
       -
                            ~source_x:50 ~source_y:50

     

       190
       190
       -
                            ~source_width:100 ~source_height:100

     

       191
       191
       -
                            ~columns:10 ~rows:10

     

       192
       192
       -
                            ())

     

       193
       193
       -
              ~quiet:`Errors_only

     

       194
       194
       -
              ())

     

       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 ())

     

       195
       174
        
           ~data:gradient;

     

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

     

       197
       176
        
         print_newline ();

     
···

       200
       179
        
         (* Demo 7: Multiple placements *)

     

       201
       180
        
         clear_screen ();

     

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

     

       203
       203
       -
         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

     

       204
       185
        
         (* Transmit once with an ID *)

     

       205
       186
        
         send

     

       206
       206
       -
           (K.transmit

     

       207
       207
       -
              ~image_id:100

     

       208
       208
       -
              ~format:`Rgba32

     

       209
       209
       -
              ~width:80 ~height:80

     

       210
       210
       -
              ~quiet:`Errors_only

     

       211
       211
       -
              ())

     

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

     

       188
       188
       +
              ~quiet:`Errors_only ())

     

       212
       189
        
           ~data:cyan_data;

     

       213
       190
        
         (* Create first placement *)

     

       214
       191
        
         send

     

       215
       215
       -
           (K.display

     

       216
       216
       -
              ~image_id:100

     

       192
       192
       +
           (K.display ~image_id:100

     

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

     

       218
       218
       -
              ~quiet:`Errors_only

     

       219
       219
       -
              ())

     

       194
       194
       +
              ~quiet:`Errors_only ())

     

       220
       195
        
           ~data:"";

     

       221
       196
        
         (* Create second placement *)

     

       222
       197
        
         send

     

       223
       223
       -
           (K.display

     

       224
       224
       -
              ~image_id:100

     

       198
       198
       +
           (K.display ~image_id:100

     

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

     

       226
       226
       -
              ~quiet:`Errors_only

     

       227
       227
       -
              ())

     

       200
       200
       +
              ~quiet:`Errors_only ())

     

       228
       201
        
           ~data:"";

     

       229
       202
        
         print_newline ();

     

       230
       203
        
         wait_for_enter ();

     
···

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

     

       240
       213
        
         (* Transmit once *)

     

       241
       214
        
         send

     

       242
       242
       -
           (K.transmit

     

       243
       243
       -
              ~image_id:160

     

       244
       244
       -
              ~format:`Rgba32

     

       245
       245
       -
              ~width:100 ~height:100

     

       246
       246
       -
              ~quiet:`Errors_only

     

       247
       247
       -
              ())

     

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

     

       216
       216
       +
              ~quiet:`Errors_only ())

     

       248
       217
        
           ~data:grad_small;

     

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

     

       250
       219
        
         send

     

       251
       251
       -
           (K.display

     

       252
       252
       -
              ~image_id:160

     

       220
       220
       +
           (K.display ~image_id:160

     

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

     

       254
       254
       -
              ~quiet:`Errors_only

     

       255
       255
       -
              ())

     

       222
       222
       +
              ~quiet:`Errors_only ())

     

       256
       223
        
           ~data:"";

     

       257
       224
        
         print_string "  ";

     

       258
       225
        
         send

     

       259
       259
       -
           (K.display

     

       260
       260
       -
              ~image_id:160

     

       226
       226
       +
           (K.display ~image_id:160

     

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

     

       262
       262
       -
              ~quiet:`Errors_only

     

       263
       263
       -
              ())

     

       228
       228
       +
              ~quiet:`Errors_only ())

     

       264
       229
        
           ~data:"";

     

       265
       230
        
         print_string "  ";

     

       266
       231
        
         send

     

       267
       267
       -
           (K.display

     

       268
       268
       -
              ~image_id:160

     

       232
       232
       +
           (K.display ~image_id:160

     

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

     

       270
       270
       -
              ~quiet:`Errors_only

     

       271
       271
       -
              ())

     

       234
       234
       +
              ~quiet:`Errors_only ())

     

       272
       235
        
           ~data:"";

     

       273
       236
        
         print_newline ();

     

       274
       237
        
         print_newline ();

     
···

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

     

       280
       243
        
         clear_screen ();

     

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

     

       282
       282
       -
         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

     

       283
       248
        
         send

     

       284
       284
       -
           (K.transmit_and_display

     

       285
       285
       -
              ~image_id:200

     

       286
       286
       -
              ~format:`Rgba32

     

       287
       287
       -
              ~width:200 ~height:100

     

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

     

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

     

       289
       289
       -
              ~quiet:`Errors_only

     

       290
       290
       -
              ())

     

       251
       251
       +
              ~quiet:`Errors_only ())

     

       291
       252
        
           ~data:bg_data;

     

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

     

       293
       254
        
         print_newline ();

     
···

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

     

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

     

       310
       271
        
       

     

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

     

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

     

       312
       273
        
         let image_id = 300 in

     

       313
       274
        
       

     

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

     

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

     

       316
       277
        
         send

     

       317
       317
       -
           (K.transmit

     

       318
       318
       -
              ~image_id

     

       319
       319
       -
              ~format:`Rgba32

     

       320
       320
       -
              ~width ~height

     

       321
       321
       -
              ~quiet:`Errors_only

     

       322
       322
       -
              ())

     

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

     

       323
       279
        
           ~data:red_frame;

     

       324
       280
        
       

     

       325
       281
        
         (* Add frames with composition replace *)

     

       326
       326
       -
         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

     

       327
       285
        
         send

     

       328
       328
       -
           (K.frame

     

       329
       329
       -
              ~image_id

     

       330
       330
       -
              ~format:`Rgba32

     

       331
       331
       -
              ~width ~height

     

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

     

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

     

       333
       333
       -
              ~quiet:`Errors_only

     

       334
       334
       -
              ())

     

       288
       288
       +
              ~quiet:`Errors_only ())

     

       335
       289
        
           ~data:orange_frame;

     

       336
       290
        
       

     

       337
       337
       -
         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

     

       338
       294
        
         send

     

       339
       339
       -
           (K.frame

     

       340
       340
       -
              ~image_id

     

       341
       341
       -
              ~format:`Rgba32

     

       342
       342
       -
              ~width ~height

     

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

     

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

     

       344
       344
       -
              ~quiet:`Errors_only

     

       345
       345
       -
              ())

     

       297
       297
       +
              ~quiet:`Errors_only ())

     

       346
       298
        
           ~data:yellow_frame;

     

       347
       299
        
       

     

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

     

       349
       301
        
         send

     

       350
       350
       -
           (K.frame

     

       351
       351
       -
              ~image_id

     

       352
       352
       -
              ~format:`Rgba32

     

       353
       353
       -
              ~width ~height

     

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

     

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

     

       355
       355
       -
              ~quiet:`Errors_only

     

       356
       356
       -
              ())

     

       304
       304
       +
              ~quiet:`Errors_only ())

     

       357
       305
        
           ~data:green_frame;

     

       358
       306
        
       

     

       359
       307
        
         (* Create placement and start animation *)

     

       360
       308
        
         send

     

       361
       361
       -
           (K.display

     

       362
       362
       -
              ~image_id

     

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

     

       364
       364
       -
                            ~placement_id:1

     

       365
       365
       -
                            ~cell_x_offset:0

     

       366
       366
       -
                            ~cell_y_offset:0

     

       367
       367
       -
                            ~cursor:`Static

     

       368
       368
       -
                            ())

     

       369
       369
       -
              ~quiet:`Errors_only

     

       370
       370
       -
              ())

     

       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 ())

     

       371
       314
        
           ~data:"";

     

       372
       315
        
       

     

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

     

       374
       374
       -
         send

     

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

     

       376
       376
       -
           ~data:"";

     

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

     

       377
       318
        
       

     

       378
       319
        
         (* Start animation with infinite looping *)

     

       379
       379
       -
         send

     

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

     

       381
       381
       -
           ~data:"";

     

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

     

       382
       321
        
       

     

       383
       322
        
         print_newline ();

     

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

     

       323
       323
       +
         print_endline

     

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

     

       385
       325
        
         print_newline ();

     

       386
       326
        
       

     

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

     
···

       389
       329
        
           Unix.sleepf 0.4;

     

       390
       330
        
       

     

       391
       331
        
           (* Delete the current placement *)

     

       392
       392
       -
           send

     

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

     

       394
       394
       -
             ~data:"";

     

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

     

       395
       333
        
       

     

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

     

       397
       335
        
           send

     

       398
       398
       -
             (K.display

     

       399
       399
       -
                ~image_id

     

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

     

       401
       401
       -
                              ~placement_id:1

     

       402
       402
       -
                              ~cell_x_offset:(i * 5)

     

       403
       403
       -
                              ~cell_y_offset:0

     

       404
       404
       -
                              ~cursor:`Static

     

       405
       405
       -
                              ())

     

       406
       406
       -
                ~quiet:`Errors_only

     

       407
       407
       -
                ())

     

       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 ())

     

       408
       341
        
             ~data:""

     

       409
       342
        
         done;

     

       410
       343
        
       

     

       411
       344
        
         (* Stop the animation *)

     

       412
       412
       -
         send

     

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

     

       414
       414
       -
           ~data:"";

     

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

     

       415
       346
        
       

     

       416
       347
        
         print_endline "Animation stopped.";

     

       417
       348
        
         print_newline ();

+21 -43

example/tiny_anim.ml

···

       25
       25
        
       

     

       26
       26
        
       let () =

     

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

     

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

     

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

     

       29
       29
        
         let image_id = 999 in

     

       30
       30
        
       

     

       31
       31
        
         (* Clear any existing images *)

     
···

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

     

       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.transmit

     

       38
       38
       -
              ~image_id

     

       39
       39
       -
              ~format:`Rgba32

     

       40
       40
       -
              ~width ~height

     

       41
       41
       -
              ~quiet:`Errors_only

     

       42
       42
       -
              ())

     

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

     

       43
       38
        
           ~data:red_frame;

     

       44
       39
        
       

     

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

     

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

     

       41
       41
       +
         let orange_frame =

     

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

     

       43
       43
       +
         in

     

       47
       44
        
         send

     

       48
       48
       -
           (K.frame

     

       49
       49
       -
              ~image_id

     

       50
       50
       -
              ~format:`Rgba32

     

       51
       51
       -
              ~width ~height

     

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

     

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

     

       53
       53
       -
              ~quiet:`Errors_only

     

       54
       54
       -
              ())

     

       47
       47
       +
              ~quiet:`Errors_only ())

     

       55
       48
        
           ~data:orange_frame;

     

       56
       49
        
       

     

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

     

       58
       58
       -
         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

     

       59
       54
        
         send

     

       60
       60
       -
           (K.frame

     

       61
       61
       -
              ~image_id

     

       62
       62
       -
              ~format:`Rgba32

     

       63
       63
       -
              ~width ~height

     

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

     

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

     

       65
       65
       -
              ~quiet:`Errors_only

     

       66
       66
       -
              ())

     

       57
       57
       +
              ~quiet:`Errors_only ())

     

       67
       58
        
           ~data:yellow_frame;

     

       68
       59
        
       

     

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

     

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

     

       71
       62
        
         send

     

       72
       72
       -
           (K.frame

     

       73
       73
       -
              ~image_id

     

       74
       74
       -
              ~format:`Rgba32

     

       75
       75
       -
              ~width ~height

     

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

     

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

     

       77
       77
       -
              ~quiet:`Errors_only

     

       78
       78
       -
              ())

     

       65
       65
       +
              ~quiet:`Errors_only ())

     

       79
       66
        
           ~data:green_frame;

     

       80
       67
        
       

     

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

     

       82
       69
        
         send

     

       83
       83
       -
           (K.display

     

       84
       84
       -
              ~image_id

     

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

     

       86
       86
       -
                            ~placement_id:1

     

       87
       87
       -
                            ~cell_x_offset:0

     

       88
       88
       -
                            ~cell_y_offset:0

     

       89
       89
       -
                            ~cursor:`Static

     

       90
       90
       -
                            ())

     

       91
       91
       -
              ~quiet:`Errors_only

     

       92
       92
       -
              ())

     

       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 ())

     

       93
       75
        
           ~data:"";

     

       94
       76
        
       

     

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

     

       96
       96
       -
         send

     

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

     

       98
       98
       -
           ~data:"";

     

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

     

       99
       79
        
       

     

       100
       80
        
         print_endline "";

     

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

     
···

       104
       84
        
         let _ = read_line () in

     

       105
       85
        
       

     

       106
       86
        
         (* Stop animation *)

     

       107
       107
       -
         send

     

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

     

       109
       109
       -
           ~data:"";

     

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

     

       110
       88
        
       

     

       111
       89
        
         (* Clean up *)

     

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

+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)"]

+8 -7

lib-cli/kgp_cli.ml

···

       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

     

       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

     

       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

     

       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.(const choose

     

       26
       26
       -
               $ Arg.(value & flag enable)

     

       27
       27
       -
               $ Arg.(value & flag disable)

     

       28
       28
       -
               $ Arg.(value & flag tmux))

     

       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))

+5 -4

lib-cli/kgp_cli.mli

···

       5
       5
        
       

     

       6
       6
        
       (** Cmdliner Support for Kitty Graphics Protocol

     

       7
       7
        
       

     

       8
       8
       -
           This module provides Cmdliner terms for configuring graphics output mode

     

       9
       9
       -
           in CLI applications. It allows users to override auto-detection with

     

       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}

     
···

       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

     

       46
       46
       -
           be passed to {!Kgp.Terminal.supports_graphics} or {!Kgp.Terminal.resolve_mode}. *)

     

       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
       +
       *)

     

       47
       48
        
       

     

       48
       49
        
       val graphics_docs : string

     

       49
       50
        
       (** Section name for graphics options in help output ("GRAPHICS OPTIONS").

-7

lib/kgp.ml

···

       3
       3
        
          SPDX-License-Identifier: ISC

     

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

     

       5
       5
        
       

     

       6
       6
       -
       (* Type modules *)

     

       7
       6
        
       module Format = Kgp_format

     

       8
       7
        
       module Transmission = Kgp_transmission

     

       9
       8
        
       module Compression = Kgp_compression

     
···

       12
       11
        
       module Composition = Kgp_composition

     

       13
       12
        
       module Delete = Kgp_delete

     

       14
       13
        
       module Animation_state = Kgp_animation_state

     

       15
       15
       -
       

     

       16
       16
       -
       (* Configuration modules *)

     

       17
       14
        
       module Placement = Kgp_placement

     

       18
       15
        
       module Frame = Kgp_frame

     

       19
       16
        
       module Animation = Kgp_animation

     

       20
       17
        
       module Compose = Kgp_compose

     

       21
       18
        
       

     

       22
       22
       -
       (* Command type and functions *)

     

       23
       19
        
       type command = Kgp_command.t

     

       24
       20
        
       

     

       25
       21
        
       let transmit = Kgp_command.transmit

     
···

       35
       31
        
       let write_tmux = Kgp_command.write_tmux

     

       36
       32
        
       let to_string_tmux = Kgp_command.to_string_tmux

     

       37
       33
        
       

     

       38
       38
       -
       (* Core modules *)

     

       39
       34
        
       module Response = Kgp_response

     

       40
       40
       -
       

     

       41
       41
       -
       (* Utility modules *)

     

       42
       35
        
       module Unicode_placeholder = Kgp_unicode

     

       43
       36
        
       module Detect = Kgp_detect

     

       44
       37
        
       module Tmux = Kgp_tmux

+82 -86

lib/kgp.mli

···

       5
       5
        
       

     

       6
       6
        
       (** Kitty Terminal Graphics Protocol

     

       7
       7
        
       

     

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

     

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

     

       10
       10
       -
           (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.).

     

       11
       11
        
       

     

       12
       12
        
           {1 Protocol Overview}

     

       13
       13
        
       

     
···

       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 blending)

     

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

     

       20
       20
       +
             blending)

     

       20
       21
        
           - Automatic scrolling with text

     

       21
       22
        
           - Animation support with frame deltas for efficiency

     

       22
       23
        
       

     
···

       72
       73
        
       

     

       73
       74
        
             (* Display at different positions *)

     

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

     

       75
       75
       -
             Kgp.write buf cmd ~data:"";

     

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

     

       76
       77
        
           ]}

     

       77
       78
        
       

     

       78
       79
        
           {2 Protocol Reference}

     

       79
       80
        
       

     

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

     

       81
       81
       -
           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. *)

     

       82
       84
        
       

     

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

     

       84
       86
        
       

     
···

       106
       108
        
       

     

       107
       109
        
       (** {2 Image Transmission}

     

       108
       110
        
       

     

       109
       109
       -
           Images can be transmitted to the terminal for storage and later display.

     

       110
       110
       -
           The terminal assigns storage and responds with success or failure.

     

       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.

     

       111
       113
        
       

     

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

     

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

     
···

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

     

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

     

       132
       134
        
       

     

       133
       133
       -
           @param image_id Unique identifier (1-4294967295) for later reference.

     

       134
       134
       -
             If specified, the terminal responds with success/failure.

     

       135
       135
       -
           @param image_number Alternative to [image_id] where the terminal assigns

     

       136
       136
       -
             a unique ID and returns it in the response. Useful when multiple

     

       137
       137
       -
             programs share the terminal.

     

       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.

     

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

     

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

     

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

     
···

       160
       164
        
         command

     

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

     

       162
       166
        
       

     

       163
       163
       -
           Combines transmission and display in a single command. The image is

     

       164
       164
       -
           rendered at the current cursor position unless placement options

     

       165
       165
       -
           specify otherwise.

     

       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.

     

       166
       169
        
       

     

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

     

       168
       171
        
           controls display position and scaling. *)

     
···

       177
       180
        
         command

     

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

     

       179
       182
        
       

     

       180
       180
       -
           Performs the same validation as {!transmit} but does not store the

     

       181
       181
       -
           image. Useful for testing whether the terminal supports the graphics

     

       182
       182
       -
           protocol and specific formats.

     

       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.

     

       183
       186
        
       

     

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

     

       185
       188
        
           {[

     
···

       191
       194
        
       

     

       192
       195
        
       (** {2 Display}

     

       193
       196
        
       

     

       194
       194
       -
           Previously transmitted images can be displayed multiple times at

     

       195
       195
       -
           different positions with different cropping and scaling options. *)

     

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

     

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

     

       196
       199
        
       

     

       197
       200
        
       val display :

     

       198
       201
        
         ?image_id:int ->

     
···

       203
       206
        
         command

     

       204
       207
        
       (** Display a previously transmitted image.

     

       205
       208
        
       

     

       206
       206
       -
           The image is rendered at the current cursor position. Use [placement]

     

       207
       207
       -
           to control cropping, scaling, z-index, and other display options.

     

       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.

     

       208
       211
        
       

     

       209
       209
       -
           Each display creates a "placement" of the image. Multiple placements

     

       210
       210
       -
           of the same image share the underlying image data.

     

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

     

       213
       213
       +
           same image share the underlying image data.

     

       211
       214
        
       

     

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

     

       213
       213
       -
           @param image_number Image number (acts on the newest image with this number).

     

       216
       216
       +
           @param image_number

     

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

     

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

     

       215
       219
        
       

     

       216
       220
        
       (** {2 Deletion}

     

       217
       221
        
       

     

       218
       218
       -
           Images and placements can be deleted to free terminal resources.

     

       219
       219
       -
           By default, only placements are removed and image data is retained

     

       220
       220
       -
           for potential reuse. Use [~free:true] to also release the image data. *)

     

       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. *)

     

       221
       225
        
       

     

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

     

       223
       227
        
       (** Delete images or placements.

     

       224
       228
        
       

     

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

     

       226
       230
        
       

     

       227
       227
       -
           @param free If true, also free the image data from memory (default: false).

     

       228
       228
       -
             Without [~free:true], only placements are removed and the image data

     

       229
       229
       -
             can be reused for new placements.

     

       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.

     

       230
       235
        
       

     

       231
       236
        
           Examples:

     

       232
       237
        
           {[

     

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

     

       234
       239
        
             Kgp.delete `All_visible

     

       235
       235
       -
       

     

       236
       236
       -
             (* Delete specific image, keeping data for reuse *)

     

       237
       237
       -
             Kgp.delete (`By_id (42, None))

     

       238
       238
       -
       

     

       239
       239
       -
             (* Delete specific image and free its data *)

     

       240
       240
       -
             Kgp.delete ~free:true (`By_id (42, None))

     

       241
       241
       -
       

     

       242
       242
       -
             (* Delete all placements at a specific cell *)

     

       243
       243
       -
             Kgp.delete (`At_cell (10, 5))

     

       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))

     

       244
       249
        
           ]} *)

     

       245
       250
        
       

     

       246
       251
        
       (** {2 Animation}

     
···

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

     

       250
       255
        
           frames with optional delta encoding for efficiency.

     

       251
       256
        
       

     

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

     

       253
       253
       -
           is the first added frame, etc. *)

     

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

     

       258
       258
       +
           first added frame, etc. *)

     

       254
       259
        
       

     

       255
       260
        
       val frame :

     

       256
       261
        
         ?image_id:int ->

     
···

       266
       271
        
         command

     

       267
       272
        
       (** Transmit animation frame data.

     

       268
       273
        
       

     

       269
       269
       -
           Adds a new frame to an existing image or edits an existing frame.

     

       270
       270
       -
           The frame can be a full image or a partial update (rectangle).

     

       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).

     

       271
       276
        
       

     

       272
       272
       -
           Use {!Frame.make} to configure the frame's position, timing, and

     

       273
       273
       -
           composition options.

     

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

     

       278
       278
       +
           options.

     

       274
       279
        
       

     

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

     

       276
       281
        
       

     

       277
       282
        
       val animate :

     

       278
       278
       -
         ?image_id:int ->

     

       279
       279
       -
         ?image_number:int ->

     

       280
       280
       -
         ?quiet:Quiet.t ->

     

       281
       281
       -
         Animation.t ->

     

       282
       282
       -
         command

     

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

     

       283
       284
        
       (** Control animation playback.

     

       284
       285
        
       

     

       285
       286
        
           For terminal-driven animation:

     

       286
       287
        
           {[

     

       287
       288
        
             (* Start infinite loop animation *)

     

       288
       288
       -
             Kgp.animate ~image_id:1 (Animation.set_state ~loops:1 `Run)

     

       289
       289
       -
       

     

       290
       290
       -
             (* Stop animation *)

     

       291
       291
       -
             Kgp.animate ~image_id:1 (Animation.set_state `Stop)

     

       292
       292
       -
       

     

       293
       293
       -
             (* Change frame timing *)

     

       294
       294
       -
             Kgp.animate ~image_id:1 (Animation.set_gap ~frame:3 ~gap_ms:100)

     

       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)

     

       295
       297
        
           ]}

     

       296
       298
        
       

     

       297
       299
        
           For client-driven animation:

     
···

       301
       303
        
           ]} *)

     

       302
       304
        
       

     

       303
       305
        
       val compose :

     

       304
       304
       -
         ?image_id:int ->

     

       305
       305
       -
         ?image_number:int ->

     

       306
       306
       -
         ?quiet:Quiet.t ->

     

       307
       307
       -
         Compose.t ->

     

       308
       308
       -
         command

     

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

     

       309
       307
        
       (** Compose animation frames.

     

       310
       308
        
       

     

       311
       311
       -
           Copies a rectangular region from one frame onto another. Useful for

     

       312
       312
       -
           building complex frames from simpler components.

     

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

     

       310
       310
       +
           complex frames from simpler components.

     

       313
       311
        
       

     

       314
       312
        
           {[

     

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

     

       316
       316
       -
             let comp = Compose.make

     

       317
       317
       -
               ~source_frame:2 ~dest_frame:5

     

       318
       318
       -
               ~width:50 ~height:50

     

       319
       319
       -
               ~source_x:10 ~source_y:10

     

       320
       320
       -
               ~dest_x:20 ~dest_y:20 () in

     

       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

     

       321
       318
        
             Kgp.compose ~image_id:1 comp

     

       322
       319
        
           ]} *)

     

       323
       320
        
       

     

       324
       321
        
       (** {2 Output}

     

       325
       322
        
       

     

       326
       326
       -
           Commands are serialized to escape sequences that can be written

     

       327
       327
       -
           to the terminal. *)

     

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

     

       324
       324
       +
           terminal. *)

     

       328
       325
        
       

     

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

     

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

     

       331
       328
        
       

     

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

     

       333
       333
       -
           encoding). Pass an empty string for commands that don't include payload

     

       334
       334
       -
           data (like {!val:display}, {!val:delete}, {!val:animate}).

     

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

     

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

     

       335
       332
        
       

     

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

     

       337
       334
        
       

     

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

     

       339
       336
        
       (** Convert command to a string.

     

       340
       337
        
       

     

       341
       341
       -
           Convenience wrapper around {!write} that returns the serialized

     

       342
       342
       -
           command as a string. *)

     

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

     

       339
       339
       +
           string. *)

     

       343
       340
        
       

     

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

     

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

     

       346
       343
        
       

     

       347
       347
       -
           If running inside tmux (detected via [TMUX] environment variable),

     

       348
       348
       -
           wraps the graphics command in a DCS passthrough sequence so it

     

       349
       349
       -
           reaches the underlying terminal. Otherwise, behaves like {!write}.

     

       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}.

     

       350
       347
        
       

     

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

     

       352
       349
        
       

     

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

     

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

     

       355
       352
        
       

     

       356
       356
       -
           Convenience wrapper around {!write_tmux}. If running inside tmux,

     

       357
       357
       -
           wraps the output for passthrough. Otherwise, behaves like {!to_string}. *)

     

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

     

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

     

       358
       355
        
       

     

       359
       356
        
       (** {1 Response} *)

     

       360
       357
        
       

     
···

       366
       363
        
       module Detect = Kgp_detect

     

       367
       364
        
       

     

       368
       365
        
       module Tmux = Kgp_tmux

     

       369
       369
       -
       (** Tmux passthrough support. Provides functions to detect if running

     

       370
       370
       -
           inside tmux and to wrap escape sequences for passthrough. *)

     

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

     

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

     

       371
       368
        
       

     

       372
       369
        
       module Terminal = Kgp_terminal

     

       373
       370
        
       (** Terminal environment detection. Provides functions to detect terminal

     

       374
       371
        
           capabilities, pager mode, and resolve graphics output mode. *)

     

       375
       375
       -

+29 -26

lib/kgp_animation.mli

···

       5
       5
        
       

     

       6
       6
        
       (** Animation Control

     

       7
       7
        
       

     

       8
       8
       -
           Operations for controlling animation playback. The protocol supports

     

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

     

       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
        
       

     
···

       24
       24
        
       

     

       25
       25
        
           {[

     

       26
       26
        
             (* Start infinite loop *)

     

       27
       27
       -
             Kgp.animate ~image_id:1 (Animation.set_state ~loops:1 `Run)

     

       28
       28
       -
       

     

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

     

       30
       30
       -
             Kgp.animate ~image_id:1 (Animation.set_state ~loops:4 `Run)

     

       31
       31
       -
       

     

       32
       32
       -
             (* Stop animation *)

     

       33
       33
       -
             Kgp.animate ~image_id:1 (Animation.set_state `Stop)

     

       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)

     

       34
       35
        
           ]}

     

       35
       36
        
       

     

       36
       37
        
           {2 Client-Driven Animation}

     
···

       52
       53
        
       

     

       53
       54
        
           {[

     

       54
       55
        
             (* Slow down frame 3 *)

     

       55
       55
       -
             Kgp.animate ~image_id:1 (Animation.set_gap ~frame:3 ~gap_ms:200)

     

       56
       56
       -
       

     

       57
       57
       -
             (* Make frame 5 instant/gapless *)

     

       58
       58
       -
             Kgp.animate ~image_id:1 (Animation.set_gap ~frame:5 ~gap_ms:(-1))

     

       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))

     

       59
       61
        
           ]}

     

       60
       62
        
       

     

       61
       63
        
           {2 Loop Counting}

     
···

       71
       73
        
         | `Set_current of int ]

     

       72
       74
        
       (** Animation control operations.

     

       73
       75
        
       

     

       74
       74
       -
           - [`Set_state (state, loops)] - Set animation playback state with

     

       75
       75
       -
             optional loop count.

     

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

     

       77
       77
       +
             loop count.

     

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

     

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

     

       78
       80
        
       

     

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

     

       80
       82
        
       (** Set animation playback state.

     

       81
       83
        
       

     

       82
       82
       -
           @param loops Loop count: 0 = ignored, 1 = infinite, n > 1 = (n-1) loops.

     

       83
       83
       -
             Protocol key: [v].

     

       84
       84
       +
           @param loops

     

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

     

       86
       86
       +
             [v].

     

       84
       87
        
           @param state The target playback state.

     

       85
       88
        
       

     

       86
       89
        
           Examples:

     

       87
       90
        
           {[

     

       88
       88
       -
             set_state `Run                (* Run with current loop setting *)

     

       89
       89
       -
             set_state ~loops:1 `Run       (* Run infinitely *)

     

       90
       90
       -
             set_state ~loops:3 `Run       (* Run twice, then stop *)

     

       91
       91
       -
             set_state `Stop               (* Pause animation *)

     

       92
       92
       -
             set_state `Loading            (* Run, wait for more frames at end *)

     

       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 *)

     

       93
       95
        
           ]} *)

     

       94
       96
        
       

     

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

     

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

     

       97
       99
        
       

     

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

     

       99
       99
       -
           @param gap_ms Delay in milliseconds before next frame. Negative values

     

       100
       100
       -
             create gapless frames (not displayed, instant skip). Protocol key: [z].

     

       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].

     

       101
       104
        
       

     

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

     

       103
       106
        
       

     
···

       106
       109
        
       

     

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

     

       108
       111
        
       

     

       109
       109
       -
           Used for client-driven animation where the application controls

     

       110
       110
       -
           frame advancement rather than the terminal. *)

     

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

     

       113
       113
       +
           advancement rather than the terminal. *)

+1 -4

lib/kgp_animation_state.ml

···

       5
       5
        
       

     

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

     

       7
       7
        
       

     

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

     

       9
       9
       -
         | `Stop -> 1

     

       10
       10
       -
         | `Loading -> 2

     

       11
       11
       -
         | `Run -> 3

     

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

+25 -25

lib/kgp_animation_state.mli

···

       9
       9
        
       

     

       10
       10
        
           {2 Protocol Details}

     

       11
       11
        
       

     

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

     

       13
       13
       -
           when using action [a=a]:

     

       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

     
···

       19
       19
        
       

     

       20
       20
        
           The protocol supports two animation approaches:

     

       21
       21
        
       

     

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

     

       23
       23
       -
           frames based on the gap (delay) specified for each frame. Use

     

       24
       24
       -
           [{`Run}] or [{`Loading}] states.

     

       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

     

       27
       27
       -
           frame using [Kgp.Animation.set_current_frame]. Use [{`Stop}] state

     

       28
       28
       -
           to prevent automatic advancement.

     

       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

     

       33
       33
       -
           on the current frame. Use this when:

     

       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

     

       41
       41
       -
           the end instead of looping. Use this when:

     

       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

     

       49
       49
       -
           after the last. The loop count can be controlled via the [loops]

     

       50
       50
       -
           parameter in [Kgp.Animation.set_state]. *)

     

       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]. *)

     

       51
       51
        
       

     

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

     

       53
       53
        
       (** Animation playback states.

     

       54
       54
        
       

     

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

     

       56
       56
       -
             current frame and does not advance automatically.

     

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

     

       58
       58
       -
             the last frame is reached, the animation pauses until more frames

     

       59
       59
       -
             are added, then continues.

     

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

     

       61
       61
       -
             playback returns to the first frame (or stops after the specified

     

       62
       62
       -
             number of loops). *)

     

       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
       +
       *)

     

       63
       63
        
       

     

       64
       64
        
       val to_int : t -> int

     

       65
       65
        
       (** Convert to protocol integer.

     

       66
       66
        
       

     

       67
       67
       -
           Returns 1 for [`Stop], 2 for [`Loading], or 3 for [`Run].

     

       68
       68
       -
           These values are used in the [s=] control data key. *)

     

       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. *)

+8 -9

lib/kgp_command.ml

···

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

     

       168
       168
        
         Kgp_placement.cursor p

     

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

     

       170
       170
       -
                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)));

     

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

     

       172
       172
        
       

     

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

     
···

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

     

       203
       203
        
         Kgp_frame.composition f

     

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

     

       205
       205
       -
                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)));

     

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

     

       207
       207
        
       

     

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

     
···

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

     

       227
       227
        
         Kgp_compose.composition c

     

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

     

       229
       229
       -
                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)))

     

       230
       230
        
       

     

       231
       231
        
       let write_control_data buf cmd =

     

       232
       232
        
         let w = kv_writer buf in

     
···

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

     

       236
       236
        
         cmd.quiet

     

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

     

       238
       238
       -
                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)));

     

       239
       239
        
         (* Format *)

     

       240
       240
       -
         cmd.format

     

       241
       241
       -
         |> 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));

     

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

     

       243
       242
        
         (match cmd.action with

     

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

     
···

       249
       248
        
         (* Compression *)

     

       250
       249
        
         cmd.compression

     

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

     

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

     

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

     

       253
       252
        
         (* Dimensions *)

     

       254
       253
        
         kv_int_opt w 's' cmd.width;

     

       255
       254
        
         kv_int_opt w 'v' cmd.height;

     
···

       316
       315
        
           let inner_buf = Buffer.create 1024 in

     

       317
       316
        
           write inner_buf cmd ~data;

     

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

     

       319
       319
       -
         end else

     

       320
       320
       -
           write buf cmd ~data

     

       318
       318
       +
         end

     

       319
       319
       +
         else write buf cmd ~data

     

       321
       320
        
       

     

       322
       321
        
       let to_string_tmux cmd ~data =

     

       323
       322
        
         let buf = Buffer.create 1024 in

+10 -13

lib/kgp_command.mli

···

       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 If true, also free the image data from memory (default: false).

     

       74
       74
       -
             Without [~free:true], only placements are removed and the image data

     

       75
       75
       -
             can be reused for new placements. *)

     

       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. *)

     

       76
       77
        
       

     

       77
       78
        
       (** {1 Animation} *)

     

       78
       79
        
       

     
···

       99
       100
        
       (** Control animation playback. *)

     

       100
       101
        
       

     

       101
       102
        
       val compose :

     

       102
       102
       -
         ?image_id:int ->

     

       103
       103
       -
         ?image_number:int ->

     

       104
       104
       -
         ?quiet:Kgp_quiet.t ->

     

       105
       105
       -
         Kgp_compose.t ->

     

       106
       106
       -
         t

     

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

     

       107
       104
        
       (** Compose animation frames. *)

     

       108
       105
        
       

     

       109
       106
        
       (** {1 Output} *)

     
···

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

     

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

     

       119
       116
        
       

     

       120
       120
       -
           If running inside tmux (detected via [TMUX] environment variable),

     

       121
       121
       -
           wraps the graphics command in a DCS passthrough sequence. Otherwise,

     

       122
       122
       -
           behaves like {!write}. *)

     

       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}. *)

     

       123
       120
        
       

     

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

     

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

     

       126
       123
        
       

     

       127
       127
       -
           If running inside tmux, wraps the output for passthrough.

     

       128
       128
       -
           Otherwise, behaves like {!to_string}. *)

     

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

     

       125
       125
       +
           like {!to_string}. *)

+27 -29

lib/kgp_compose.mli

···

       10
       10
        
       

     

       11
       11
        
           {2 Protocol Overview}

     

       12
       12
        
       

     

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

     

       14
       14
       -
           one frame onto another. This is useful for:

     

       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

     
···

       19
       19
        
       

     

       20
       20
        
           {2 Coordinate System}

     

       21
       21
        
       

     

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

     

       23
       23
       -
           the respective frame:

     

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

     

       23
       23
       +
           respective frame:

     

       24
       24
        
       

     

       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

     
···

       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

     

       42
       42
       -
             with overlapping regions

     

       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 = Compose.make

     

       50
       50
       -
               ~source_frame:2 ~dest_frame:5

     

       51
       51
       -
               ~width:32 ~height:32

     

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

     

       53
       53
       -
               ~dest_x:100 ~dest_y:50 ()    (* To position in dest *)

     

       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 *)

     

       54
       53
        
             in

     

       55
       54
        
             Kgp.compose ~image_id:1 comp

     

       56
       55
        
           ]} *)

     
···

       72
       71
        
         t

     

       73
       72
        
       (** Create a composition operation.

     

       74
       73
        
       

     

       75
       75
       -
           @param source_frame 1-based frame number to copy from. Required.

     

       76
       76
       -
             Protocol key: [r].

     

       77
       77
       -
           @param dest_frame 1-based frame number to copy onto. Required.

     

       78
       78
       -
             Protocol key: [c].

     

       79
       79
       -
           @param width Width of rectangle in pixels. Default is full frame.

     

       80
       80
       -
             Protocol key: [w].

     

       81
       81
       -
           @param height Height of rectangle in pixels. Default is full frame.

     

       82
       82
       -
             Protocol key: [h].

     

       83
       83
       -
           @param source_x Left edge of source rectangle (default 0).

     

       84
       84
       -
             Protocol key: [X].

     

       85
       85
       -
           @param source_y Top edge of source rectangle (default 0).

     

       86
       86
       -
             Protocol key: [Y].

     

       87
       87
       -
           @param dest_x Left edge of destination position (default 0).

     

       88
       88
       -
             Protocol key: [x].

     

       89
       89
       -
           @param dest_y Top edge of destination position (default 0).

     

       90
       90
       -
             Protocol key: [y].

     

       91
       91
       -
           @param composition Blending mode. Default is alpha blending.

     

       92
       92
       -
             Protocol key: [C]. *)

     

       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]. *)

     

       93
       91
        
       

     

       94
       92
        
       (** {1 Field Accessors} *)

     

       95
       93

+1 -3

lib/kgp_composition.ml

···

       5
       5
        
       

     

       6
       6
        
       type t = [ `Alpha_blend | `Overwrite ]

     

       7
       7
        
       

     

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

     

       9
       9
       -
         | `Alpha_blend -> 0

     

       10
       10
       -
         | `Overwrite -> 1

     

       8
       8
       +
       let to_int : t -> int = function `Alpha_blend -> 0 | `Overwrite -> 1

+7 -7

lib/kgp_composition.mli

···

       9
       9
        
       

     

       10
       10
        
           {2 Protocol Details}

     

       11
       11
        
       

     

       12
       12
       -
           The composition mode is specified via the [X] key in the control data

     

       13
       13
       -
           (for animation frames) or the [C] key (for frame composition operations):

     

       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
        
       

     
···

       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

     

       45
       45
       -
             replace destination pixels, ignoring alpha values. Faster but no

     

       46
       46
       -
             transparency support. *)

     

       44
       44
       +
           - [`Overwrite] - Simple pixel replacement. Source pixels completely replace

     

       45
       45
       +
             destination pixels, ignoring alpha values. Faster but no transparency

     

       46
       46
       +
             support. *)

     

       47
       47
        
       

     

       48
       48
        
       val to_int : t -> int

     

       49
       49
        
       (** Convert to protocol integer.

     

       50
       50
        
       

     

       51
       51
       -
           Returns 0 for [`Alpha_blend] or 1 for [`Overwrite].

     

       52
       52
       -
           These values are used in the [X=] or [C=] control data keys. *)

     

       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. *)

+1 -3

lib/kgp_compression.ml

···

       5
       5
        
       

     

       6
       6
        
       type t = [ `None | `Zlib ]

     

       7
       7
        
       

     

       8
       8
       -
       let to_char : t -> char option = function

     

       9
       9
       -
         | `None -> None

     

       10
       10
       -
         | `Zlib -> Some 'z'

     

       8
       8
       +
       let to_char : t -> char option = function `None -> None | `Zlib -> Some 'z'

+8 -8

lib/kgp_compression.mli

···

       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

     

       17
       17
       -
           encoding. The terminal decompresses after base64 decoding.

     

       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
        
       

     
···

       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.

     

       35
       35
       -
           The terminal needs this to allocate the correct buffer for decompression. *)

     

       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. *)

     

       36
       36
        
       

     

       37
       37
        
       type t = [ `None | `Zlib ]

     

       38
       38
        
       (** Compression options.

     

       39
       39
        
       

     

       40
       40
        
           - [`None] - Raw uncompressed data. No [o=] key is sent.

     

       41
       41
       -
           - [`Zlib] - RFC 1950 zlib/DEFLATE compression. Data is compressed

     

       42
       42
       -
             before base64 encoding and decompressed by the terminal. *)

     

       41
       41
       +
           - [`Zlib] - RFC 1950 zlib/DEFLATE compression. Data is compressed before

     

       42
       42
       +
             base64 encoding and decompressed by the terminal. *)

     

       43
       43
        
       

     

       44
       44
        
       val to_char : t -> char option

     

       45
       45
        
       (** Convert to protocol character.

     

       46
       46
        
       

     

       47
       47
       -
           Returns [None] for [`None] (no key sent), or [Some 'z'] for [`Zlib].

     

       48
       48
       -
           When [Some c] is returned, [o=c] is added to the control data. *)

     

       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. *)

+1 -3

lib/kgp_cursor.ml

···

       5
       5
        
       

     

       6
       6
        
       type t = [ `Move | `Static ]

     

       7
       7
        
       

     

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

     

       9
       9
       -
         | `Move -> 0

     

       10
       10
       -
         | `Static -> 1

     

       8
       8
       +
       let to_int : t -> int = function `Move -> 0 | `Static -> 1

+11 -11

lib/kgp_cursor.mli

···

       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

     

       25
       25
       -
           to flow naturally with text content.

     

       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
        
       

     
···

       34
       34
        
       

     

       35
       35
        
           {2 Relative Placements}

     

       36
       36
        
       

     

       37
       37
       -
           Note: When using relative placements (positioning images relative to

     

       38
       38
       -
           other placements), the cursor never moves regardless of this setting. *)

     

       37
       37
       +
           Note: When using relative placements (positioning images relative to other

     

       38
       38
       +
           placements), the cursor never moves regardless of this setting. *)

     

       39
       39
        
       

     

       40
       40
        
       type t = [ `Move | `Static ]

     

       41
       41
        
       (** Cursor movement behavior.

     

       42
       42
        
       

     

       43
       43
       -
           - [`Move] - Advance cursor past the displayed image (default).

     

       44
       44
       -
             Cursor moves right by the number of columns and down by the

     

       45
       45
       -
             number of rows occupied by the image.

     

       46
       46
       -
           - [`Static] - Keep cursor at its original position. The image

     

       47
       47
       -
             is displayed but cursor position is unchanged. *)

     

       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. *)

     

       48
       48
        
       

     

       49
       49
        
       val to_int : t -> int

     

       50
       50
        
       (** Convert to protocol integer.

     

       51
       51
        
       

     

       52
       52
       -
           Returns 0 for [`Move] or 1 for [`Static].

     

       53
       53
       -
           These values are used in the [C=] control data key. *)

     

       52
       52
       +
           Returns 0 for [`Move] or 1 for [`Static]. These values are used in the [C=]

     

       53
       53
       +
           control data key. *)

+24 -23

lib/kgp_delete.mli

···

       9
       9
        
       

     

       10
       10
        
           {2 Protocol Details}

     

       11
       11
        
       

     

       12
       12
       -
           Deletion is performed with action [a=d] and the [d] key specifies

     

       13
       13
       -
           the deletion type. The [d] key uses single characters:

     

       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                                                |

     
···

       30
       30
        
       

     

       31
       31
        
           {2 Placements vs Image Data}

     

       32
       32
        
       

     

       33
       33
       -
           Each deletion type can optionally free image data (controlled by the

     

       34
       34
       -
           [~free] parameter in the delete command):

     

       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

     

       38
       38
       -
             image cannot be displayed again without retransmitting. (Protocol:

     

       39
       39
       -
             uppercase 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

     

       45
       45
       -
           of that image are deleted.

     

       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

     

       50
       50
       -
           positions (not pixel positions). Only placements that intersect the

     

       51
       51
       -
           specified cell are deleted.

     

       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

     

       56
       56
       -
           by: [{`By_id}], [{`By_number}], and [{`By_id_range}]. Other deletion

     

       57
       57
       -
           commands do not affect virtual placements. *)

     

       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. *)

     

       58
       58
        
       

     

       59
       59
        
       type t =

     

       60
       60
        
         [ `All_visible

     
···

       80
       80
        
           - [`By_z_index z] - All placements with z-index z

     

       81
       81
        
       

     

       82
       82
        
           {b ID-based:}

     

       83
       83
       -
           - [`By_id (id, placement_id)] - By image ID. If [placement_id] is

     

       84
       84
       -
             [Some p], only that specific placement; if [None], all placements.

     

       85
       85
       -
           - [`By_number (n, placement_id)] - By image number (newest image

     

       86
       86
       -
             with that number). Placement ID works as above.

     

       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

     

       93
       93
       -
           image data from memory. *)

     

       92
       92
       +
           Use the [~free] parameter in the delete command to also release image data

     

       93
       93
       +
           from memory. *)

     

       94
       94
        
       

     

       95
       95
        
       val to_char : free:bool -> t -> char

     

       96
       96
        
       (** Convert to protocol character for the delete command.

     

       97
       97
        
       

     

       98
       98
        
           Returns the character used in the [d=] control data key.

     

       99
       99
       -
           @param free If true, returns uppercase (frees data); if false,

     

       100
       100
       -
             returns lowercase (keeps data). *)

     

       99
       99
       +
           @param free

     

       100
       100
       +
             If true, returns uppercase (frees data); if false, returns lowercase

     

       101
       101
       +
             (keeps data). *)

+1 -4

lib/kgp_format.ml

···

       5
       5
        
       

     

       6
       6
        
       type t = [ `Rgba32 | `Rgb24 | `Png ]

     

       7
       7
        
       

     

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

     

       9
       9
       -
         | `Rgba32 -> 32

     

       10
       10
       -
         | `Rgb24 -> 24

     

       11
       11
       -
         | `Png -> 100

     

       8
       8
       +
       let to_int : t -> int = function `Rgba32 -> 32 | `Rgb24 -> 24 | `Png -> 100

+13 -13

lib/kgp_format.mli

···

       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

     

       21
       21
       -
           be specified via the [width] and [height] parameters.

     

       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)

     
···

       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

     

       32
       32
       -
           the [size] parameter with the uncompressed PNG data size. *)

     

       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. *)

     

       33
       33
        
       

     

       34
       34
        
       type t = [ `Rgba32 | `Rgb24 | `Png ]

     

       35
       35
        
       (** Image data formats.

     

       36
       36
        
       

     

       37
       37
       -
           - [`Rgba32] - 32-bit RGBA (4 bytes per pixel). Default format.

     

       38
       38
       -
             Pixels are ordered red, green, blue, alpha. Alpha of 255 is fully

     

       39
       39
       -
             opaque, 0 is fully transparent.

     

       40
       40
       -
           - [`Rgb24] - 24-bit RGB (3 bytes per pixel). No alpha channel;

     

       41
       41
       -
             pixels are fully opaque. More compact than RGBA for opaque images.

     

       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

     

       44
       44
       -
             as dimensions are embedded in the data. *)

     

       43
       43
       +
             Supports all PNG color types and bit depths. Most convenient format as

     

       44
       44
       +
             dimensions are embedded in the data. *)

     

       45
       45
        
       

     

       46
       46
        
       val to_int : t -> int

     

       47
       47
        
       (** Convert to protocol integer value.

     

       48
       48
        
       

     

       49
       49
       -
           Returns 24 for [`Rgb24], 32 for [`Rgba32], or 100 for [`Png].

     

       50
       50
       -
           These values are used in the [f=] control data key. *)

     

       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. *)

+2 -1

lib/kgp_frame.ml

···

       24
       24
        
           background_color = None;

     

       25
       25
        
         }

     

       26
       26
        
       

     

       27
       27
       -
       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
       +
           =

     

       28
       29
        
         { x; y; base_frame; edit_frame; gap_ms; composition; background_color }

     

       29
       30
        
       

     

       30
       31
        
       let x t = t.x

+46 -41

lib/kgp_frame.mli

···

       5
       5
        
       

     

       6
       6
        
       (** Animation Frame Configuration

     

       7
       7
        
       

     

       8
       8
       -
           Configuration for adding or editing animation frames. Frames can be

     

       9
       9
       -
           full images or partial updates (rectangles), with options for timing

     

       10
       10
       -
           and composition.

     

       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:

     

       15
       15
       -
           1. Transmitting a base image (becomes frame 1)

     

       16
       16
       -
           2. Adding frames using the frame action ([a=f])

     

       17
       17
       -
           3. Controlling playback with animation commands

     

       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

     

       18
       17
        
       

     

       19
       18
        
           Frame numbers are 1-based:

     

       20
       19
        
           - Frame 1: The original/base image

     
···

       22
       21
        
       

     

       23
       22
        
           {2 Frame Positioning}

     

       24
       23
        
       

     

       25
       25
       -
           For partial frame updates, [x] and [y] specify where the new pixel

     

       26
       26
       -
           data is placed within the frame canvas:

     

       24
       24
       +
           For partial frame updates, [x] and [y] specify where the new pixel data is

     

       25
       25
       +
           placed within the frame canvas:

     

       27
       26
        
           - [x]: Left edge position in pixels (default 0)

     

       28
       27
        
           - [y]: Top edge position in pixels (default 0)

     

       29
       28
        
       

     

       30
       30
       -
           The frame data dimensions come from the [width] and [height] parameters

     

       31
       31
       -
           of the frame command.

     

       29
       29
       +
           The frame data dimensions come from the [width] and [height] parameters of

     

       30
       30
       +
           the frame command.

     

       32
       31
        
       

     

       33
       32
        
           {2 Frame Canvas}

     

       34
       33
        
       

     

       35
       34
        
           Each frame needs a background canvas to composite onto. Options:

     

       36
       35
        
       

     

       37
       37
       -
           {b Solid color background} ([background_color]):

     

       38
       38
       -
           Use a 32-bit RGBA color. Format: [0xRRGGBBAA] where AA is alpha.

     

       39
       39
       -
           Default is 0 (transparent black).

     

       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).

     

       40
       38
        
       

     

       41
       41
       -
           {b Copy from existing frame} ([base_frame]):

     

       42
       42
       -
           Use another frame as the starting canvas. Specified as 1-based frame

     

       43
       43
       -
           number. The base frame's pixels are copied, then new data is composited.

     

       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.

     

       44
       42
        
       

     

       45
       43
        
           {2 Editing Existing Frames}

     

       46
       44
        
       

     
···

       51
       49
        
       

     

       52
       50
        
           {2 Frame Timing}

     

       53
       51
        
       

     

       54
       54
       -
           The [gap_ms] parameter controls the delay before transitioning to

     

       55
       55
       -
           the next frame:

     

       52
       52
       +
           The [gap_ms] parameter controls the delay before transitioning to the next

     

       53
       53
       +
           frame:

     

       56
       54
        
           - Positive value: Delay in milliseconds

     

       57
       55
        
           - Zero: Ignored (keeps existing gap)

     

       58
       58
       -
           - Negative value: "Gapless" frame - not displayed, used as a base

     

       59
       59
       -
             for other frames

     

       56
       56
       +
           - Negative value: "Gapless" frame - not displayed, used as a base for other

     

       57
       57
       +
             frames

     

       60
       58
        
       

     

       61
       61
       -
           Default gap for new frames is 40ms. The root frame (frame 1) has

     

       62
       62
       -
           a default gap of 0ms.

     

       59
       59
       +
           Default gap for new frames is 40ms. The root frame (frame 1) has a default

     

       60
       60
       +
           gap of 0ms.

     

       63
       61
        
       

     

       64
       62
        
           {2 Composition Mode}

     

       65
       63
        
       

     

       66
       66
       -
           The [composition] parameter controls how new pixel data is blended

     

       67
       67
       -
           onto the canvas. *)

     

       64
       64
       +
           The [composition] parameter controls how new pixel data is blended onto the

     

       65
       65
       +
           canvas. *)

     

       68
       66
        
       

     

       69
       67
        
       type t

     

       70
       68
        
       (** Animation frame configuration. Opaque type; use {!make} to construct. *)

     
···

       81
       79
        
         t

     

       82
       80
        
       (** Create a frame specification.

     

       83
       81
        
       

     

       84
       84
       -
           @param x Left edge where frame data is placed in pixels (default 0).

     

       85
       85
       -
             Protocol key: [x].

     

       86
       86
       -
           @param y Top edge where frame data is placed in pixels (default 0).

     

       87
       87
       -
             Protocol key: [y].

     

       88
       88
       -
           @param base_frame 1-based frame number to use as background canvas.

     

       89
       89
       -
             Frame 1 is the root image. Protocol key: [c].

     

       90
       90
       -
           @param edit_frame 1-based frame number to edit instead of creating new.

     

       91
       91
       -
             If 0 or unset, a new frame is created. Protocol key: [r].

     

       92
       92
       -
           @param gap_ms Delay before next frame in milliseconds. Negative values

     

       93
       93
       -
             create gapless frames. Protocol key: [z].

     

       94
       94
       -
           @param composition How to blend new pixels onto the canvas.

     

       95
       95
       -
             Default is alpha blending. Protocol key: [X].

     

       96
       96
       -
           @param background_color 32-bit RGBA background color when not using

     

       97
       97
       -
             a base frame. Format: [0xRRGGBBAA]. Protocol key: [Y]. *)

     

       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]. *)

     

       98
       103
        
       

     

       99
       104
        
       val empty : t

     

       100
       105
        
       (** Empty frame spec with all defaults.

     

       101
       106
        
       

     

       102
       102
       -
           Creates a new frame with transparent black background, composited

     

       103
       103
       -
           at position (0, 0) with default timing (40ms gap). *)

     

       107
       107
       +
           Creates a new frame with transparent black background, composited at

     

       108
       108
       +
           position (0, 0) with default timing (40ms gap). *)

     

       104
       109
        
       

     

       105
       110
        
       (** {1 Field Accessors} *)

     

       106
       111

+44 -36

lib/kgp_placement.mli

···

       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

     

       27
       27
       -
           actual image bounds. This allows cropping images without modifying

     

       28
       28
       -
           the original data.

     

       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
        
       

     
···

       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.

     

       37
       37
       -
           If only one is specified, the other is computed to maintain aspect ratio.

     

       38
       38
       -
           If neither is specified, the image is displayed at natural size.

     

       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
        
       

     
···

       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

     

       55
       55
       -
             non-default background colors

     

       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

     

       58
       58
       -
           (lower ID draws first/underneath).

     

       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
        
       

     
···

       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

     

       69
       69
       -
           independent placement. *)

     

       68
       68
       +
           If [placement_id] is 0 or unspecified, each display creates an independent

     

       69
       69
       +
           placement. *)

     

       70
       70
        
       

     

       71
       71
        
       type t

     

       72
       72
        
       (** Placement configuration. Opaque type; use {!make} to construct. *)

     
···

       88
       88
        
         t

     

       89
       89
        
       (** Create a placement configuration.

     

       90
       90
        
       

     

       91
       91
       -
           @param source_x Left edge of source rectangle in pixels (default 0).

     

       92
       92
       -
             Protocol key: [x].

     

       93
       93
       -
           @param source_y Top edge of source rectangle in pixels (default 0).

     

       94
       94
       -
             Protocol key: [y].

     

       95
       95
       -
           @param source_width Width of source rectangle in pixels.

     

       96
       96
       -
             Default is the full image width. Protocol key: [w].

     

       97
       97
       -
           @param source_height Height of source rectangle in pixels.

     

       98
       98
       -
             Default is the full image height. Protocol key: [h].

     

       99
       99
       -
           @param cell_x_offset X offset within the first cell in pixels.

     

       100
       100
       -
             Must be smaller than cell width. Protocol key: [X].

     

       101
       101
       -
           @param cell_y_offset Y offset within the first cell in pixels.

     

       102
       102
       -
             Must be smaller than cell height. Protocol key: [Y].

     

       103
       103
       -
           @param columns Number of columns to display over. Image is scaled

     

       104
       104
       -
             to fit. Protocol key: [c].

     

       105
       105
       -
           @param rows Number of rows to display over. Image is scaled to fit.

     

       106
       106
       -
             Protocol key: [r].

     

       107
       107
       -
           @param z_index Stacking order. Positive = above text, negative = below.

     

       108
       108
       -
             Protocol key: [z].

     

       109
       109
       -
           @param placement_id Unique ID (1-4294967295) for this placement.

     

       110
       110
       -
             Allows updating/deleting specific placements. Protocol key: [p].

     

       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].

     

       111
       118
        
           @param cursor Cursor movement policy after display.

     

       112
       112
       -
           @param unicode_placeholder If true, creates a virtual (invisible)

     

       113
       113
       -
             placement for Unicode placeholder mode. Protocol key: [U=1]. *)

     

       119
       119
       +
           @param unicode_placeholder

     

       120
       120
       +
             If true, creates a virtual (invisible) placement for Unicode placeholder

     

       121
       121
       +
             mode. Protocol key: [U=1]. *)

     

       114
       122
        
       

     

       115
       123
        
       val empty : t

     

       116
       124
        
       (** Empty placement with all defaults.

     

       117
       125
        
       

     

       118
       118
       -
           Equivalent to [make ()]. The image displays at natural size at the

     

       119
       119
       -
           current cursor position with default z-index (0). *)

     

       126
       126
       +
           Equivalent to [make ()]. The image displays at natural size at the current

     

       127
       127
       +
           cursor position with default z-index (0). *)

     

       120
       128
        
       

     

       121
       129
        
       (** {1 Field Accessors} *)

     

       122
       130

+14 -14

lib/kgp_quiet.mli

···

       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

     

       24
       24
       -
           complex in some applications.

     

       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

     

       29
       29
       -
           or want to handle errors programmatically.

     

       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

     

       35
       35
       -
           when the application cannot easily read terminal responses. Also useful

     

       36
       36
       -
           for high-frequency animation updates where response processing would

     

       37
       37
       -
           add latency. *)

     

       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. *)

     

       38
       38
        
       

     

       39
       39
        
       type t = [ `Noisy | `Errors_only | `Silent ]

     

       40
       40
        
       (** Response suppression levels.

     

       41
       41
        
       

     

       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.

     

       45
       45
       -
             Useful when success is expected but errors should be caught.

     

       46
       46
       -
           - [`Silent] - Suppress all responses including errors. Useful for

     

       47
       47
       -
             shell scripts or when response handling is not possible. *)

     

       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. *)

     

       48
       48
        
       

     

       49
       49
        
       val to_int : t -> int

     

       50
       50
        
       (** Convert to protocol integer.

     

       51
       51
        
       

     

       52
       52
       -
           Returns 0 for [`Noisy], 1 for [`Errors_only], or 2 for [`Silent].

     

       53
       53
       -
           These values are used in the [q=] control data key. *)

     

       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. *)

+1 -1

lib/kgp_response.ml

···

       20
       20
        
         else

     

       21
       21
        
           String.index_opt t.message ':'

     

       22
       22
        
           |> Option.fold ~none:(Some t.message) ~some:(fun i ->

     

       23
       23
       -
                  Some (String.sub t.message 0 i))

     

       23
       23
       +
               Some (String.sub t.message 0 i))

     

       24
       24
        
       

     

       25
       25
        
       let image_id t = t.image_id

     

       26
       26
        
       let image_number t = t.image_number

+27 -31

lib/kgp_terminal.ml

···

       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
       -
         (match Sys.getenv_opt "TERM_PROGRAM" with

     

       16
       16
       -
          | Some prog -> String.lowercase_ascii prog = "kitty"

     

       17
       17
       -
          | None -> false)

     

       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

     

       18
       19
        
       

     

       19
       20
        
       let is_wezterm () =

     

       20
       20
       -
         Option.is_some (Sys.getenv_opt "WEZTERM_PANE") ||

     

       21
       21
       -
         (match Sys.getenv_opt "TERM_PROGRAM" with

     

       22
       22
       -
          | Some prog -> String.lowercase_ascii prog = "wezterm"

     

       23
       23
       -
          | None -> false)

     

       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

     

       24
       26
        
       

     

       25
       27
        
       let is_ghostty () =

     

       26
       26
       -
         Option.is_some (Sys.getenv_opt "GHOSTTY_RESOURCES_DIR") ||

     

       27
       27
       -
         (match Sys.getenv_opt "TERM_PROGRAM" with

     

       28
       28
       -
          | Some prog -> String.lowercase_ascii prog = "ghostty"

     

       29
       29
       -
          | None -> false)

     

       30
       30
       -
       

     

       31
       31
       -
       let is_graphics_terminal () =

     

       32
       32
       -
         is_kitty () || is_wezterm () || 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 ()

     

       34
       35
        
       let is_tmux () = Kgp_tmux.is_active ()

     

       35
       35
       -
       

     

       36
       36
       -
       let is_interactive () =

     

       37
       37
       -
         Unix.isatty Unix.stdout

     

       36
       36
       +
       let is_interactive () = Unix.isatty Unix.stdout

     

       38
       37
        
       

     

       39
       38
        
       let is_pager () =

     

       40
       39
        
         (* Not interactive = likely piped to pager *)

     

       41
       41
       -
         not (is_interactive ()) ||

     

       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
        
       

     
···

       47
       47
        
         | `Enabled -> `Graphics

     

       48
       48
        
         | `Tmux -> `Tmux

     

       49
       49
        
         | `Auto ->

     

       50
       50
       -
           if is_pager () || not (is_interactive ()) then

     

       51
       51
       -
             `Placeholder

     

       52
       52
       -
           else if is_tmux () then

     

       53
       53
       -
             (* Inside tmux - use passthrough if underlying terminal supports graphics *)

     

       54
       54
       -
             if is_graphics_terminal () then `Tmux

     

       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
       -
           else if is_graphics_terminal () then

     

       57
       57
       -
             `Graphics

     

       58
       58
       -
           else

     

       59
       59
       -
             `Placeholder

     

       60
       56
        
       

     

       61
       57
        
       let supports_graphics mode =

     

       62
       58
        
         match resolve_mode mode with

+8 -9

lib/kgp_tmux.ml

···

       5
       5
        
       

     

       6
       6
        
       (* Tmux Passthrough Support - Implementation *)

     

       7
       7
        
       

     

       8
       8
       -
       let is_active () =

     

       9
       9
       -
         Option.is_some (Sys.getenv_opt "TMUX")

     

       8
       8
       +
       let is_active () = Option.is_some (Sys.getenv_opt "TMUX")

     

       10
       9
        
       

     

       11
       10
        
       let write_wrapped buf s =

     

       12
       11
        
         (* DCS passthrough prefix: ESC P tmux ; *)

     

       13
       12
        
         Buffer.add_string buf "\027Ptmux;";

     

       14
       13
        
         (* Double all ESC characters in the content *)

     

       15
       15
       -
         String.iter (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;

     

       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

     

       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 =

     

       28
       28
       -
         if is_active () then wrap_always s else s

     

       27
       27
       +
       let wrap s = if is_active () then wrap_always s else s

+20 -19

lib/kgp_tmux.mli

···

       5
       5
        
       

     

       6
       6
        
       (** Tmux Passthrough Support

     

       7
       7
        
       

     

       8
       8
       -
           Support for passing graphics protocol escape sequences through tmux

     

       9
       9
       -
           to the underlying terminal emulator.

     

       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

     

       15
       15
       -
           tmux forwards them to the actual terminal (kitty, wezterm, ghostty, etc.)

     

       16
       16
       -
           rather than interpreting them itself.

     

       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 ;]

     
···

       23
       23
        
           {2 Requirements}

     

       24
       24
        
       

     

       25
       25
        
           For tmux passthrough to work:

     

       26
       26
       -
           - tmux version 3.3 or later

     

       27
       27
       -
           - [allow-passthrough] must be enabled in tmux.conf:

     

       28
       28
       -
             {v set -g allow-passthrough on v}

     

       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
       +
           }

     

       29
       32
        
       

     

       30
       33
        
           {2 Usage}

     

       31
       34
        
       

     
···

       33
       36
        
             if Kgp.Tmux.is_active () then

     

       34
       37
        
               let wrapped = Kgp.Tmux.wrap graphics_command in

     

       35
       38
        
               print_string wrapped

     

       36
       36
       -
             else

     

       37
       37
       -
               print_string graphics_command

     

       39
       39
       +
             else print_string graphics_command

     

       38
       40
        
           ]} *)

     

       39
       41
        
       

     

       40
       42
        
       val is_active : unit -> bool

     

       41
       43
        
       (** Detect if we are running inside tmux.

     

       42
       44
        
       

     

       43
       43
       -
           Returns [true] if the [TMUX] environment variable is set,

     

       44
       44
       -
           indicating the process is running inside a tmux session. *)

     

       45
       45
       +
           Returns [true] if the [TMUX] environment variable is set, indicating the

     

       46
       46
       +
           process is running inside a tmux session. *)

     

       45
       47
        
       

     

       46
       48
        
       val wrap : string -> string

     

       47
       49
        
       (** Wrap an escape sequence for tmux passthrough.

     

       48
       50
        
       

     

       49
       49
       -
           Takes a graphics protocol escape sequence and wraps it in the

     

       50
       50
       -
           tmux DCS passthrough format:

     

       51
       51
       +
           Takes a graphics protocol escape sequence and wraps it in the tmux DCS

     

       52
       52
       +
           passthrough format:

     

       51
       53
        
           - Adds [ESC P tmux ;] prefix

     

       52
       54
        
           - Doubles all ESC characters in the content

     

       53
       55
        
           - Adds [ESC] suffix

     
···

       57
       59
        
       val wrap_always : string -> string

     

       58
       60
        
       (** Wrap an escape sequence for tmux passthrough unconditionally.

     

       59
       61
        
       

     

       60
       60
       -
           Like {!wrap} but always applies the wrapping, regardless of

     

       61
       61
       -
           whether we are inside tmux. Useful when you want to pre-generate

     

       62
       62
       -
           tmux-compatible output. *)

     

       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. *)

     

       63
       64
        
       

     

       64
       65
        
       val write_wrapped : Buffer.t -> string -> unit

     

       65
       66
        
       (** Write a wrapped escape sequence directly to a buffer.

     

       66
       67
        
       

     

       67
       67
       -
           More efficient than {!wrap_always} when building output in a buffer,

     

       68
       68
       -
           as it avoids allocating an intermediate string. *)

     

       68
       68
       +
           More efficient than {!wrap_always} when building output in a buffer, as it

     

       69
       69
       +
           avoids allocating an intermediate string. *)

+11 -11

lib/kgp_transmission.mli

···

       16
       16
        
       

     

       17
       17
        
           {2 Direct Transmission}

     

       18
       18
        
       

     

       19
       19
       -
           [{`Direct}] sends data inline within the escape sequence itself. The data

     

       20
       20
       -
           is base64-encoded in the payload section. This is the simplest method and

     

       21
       21
       -
           works over any connection (including SSH).

     

       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:

     
···

       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

     

       31
       31
       -
           sent base64-encoded in the payload. Additional parameters:

     

       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

     

       36
       36
       -
           filesystem (i.e., local terminals, not SSH).

     

       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

     

       39
       39
       -
           files in sensitive locations like [/proc], [/sys], or [/dev].

     

       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
        
       

     
···

       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.

     

       57
       57
       -
             Only works when terminal and client share a filesystem.

     

       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. *)

     

       60
       60

+267 -39

lib/kgp_unicode.ml

···

       9
       9
        
       

     

       10
       10
        
       let diacritics =

     

       11
       11
        
         [|

     

       12
       12
       -
           0x0305; 0x030D; 0x030E; 0x0310; 0x0312; 0x033D; 0x033E; 0x033F;

     

       13
       13
       -
           0x0346; 0x034A; 0x034B; 0x034C; 0x0350; 0x0351; 0x0352; 0x0357;

     

       14
       14
       -
           0x035B; 0x0363; 0x0364; 0x0365; 0x0366; 0x0367; 0x0368; 0x0369;

     

       15
       15
       -
           0x036A; 0x036B; 0x036C; 0x036D; 0x036E; 0x036F; 0x0483; 0x0484;

     

       16
       16
       -
           0x0485; 0x0486; 0x0487; 0x0592; 0x0593; 0x0594; 0x0595; 0x0597;

     

       17
       17
       -
           0x0598; 0x0599; 0x059C; 0x059D; 0x059E; 0x059F; 0x05A0; 0x05A1;

     

       18
       18
       -
           0x05A8; 0x05A9; 0x05AB; 0x05AC; 0x05AF; 0x05C4; 0x0610; 0x0611;

     

       19
       19
       -
           0x0612; 0x0613; 0x0614; 0x0615; 0x0616; 0x0617; 0x0657; 0x0658;

     

       20
       20
       -
           0x0659; 0x065A; 0x065B; 0x065D; 0x065E; 0x06D6; 0x06D7; 0x06D8;

     

       21
       21
       -
           0x06D9; 0x06DA; 0x06DB; 0x06DC; 0x06DF; 0x06E0; 0x06E1; 0x06E2;

     

       22
       22
       -
           0x06E4; 0x06E7; 0x06E8; 0x06EB; 0x06EC; 0x0730; 0x0732; 0x0733;

     

       23
       23
       -
           0x0735; 0x0736; 0x073A; 0x073D; 0x073F; 0x0740; 0x0741; 0x0743;

     

       24
       24
       -
           0x0745; 0x0747; 0x0749; 0x074A; 0x07EB; 0x07EC; 0x07ED; 0x07EE;

     

       25
       25
       -
           0x07EF; 0x07F0; 0x07F1; 0x07F3; 0x0816; 0x0817; 0x0818; 0x0819;

     

       26
       26
       -
           0x081B; 0x081C; 0x081D; 0x081E; 0x081F; 0x0820; 0x0821; 0x0822;

     

       27
       27
       -
           0x0823; 0x0825; 0x0826; 0x0827; 0x0829; 0x082A; 0x082B; 0x082C;

     

       28
       28
       -
           0x082D; 0x0951; 0x0953; 0x0954; 0x0F82; 0x0F83; 0x0F86; 0x0F87;

     

       29
       29
       -
           0x135D; 0x135E; 0x135F; 0x17DD; 0x193A; 0x1A17; 0x1A75; 0x1A76;

     

       30
       30
       -
           0x1A77; 0x1A78; 0x1A79; 0x1A7A; 0x1A7B; 0x1A7C; 0x1B6B; 0x1B6D;

     

       31
       31
       -
           0x1B6E; 0x1B6F; 0x1B70; 0x1B71; 0x1B72; 0x1B73; 0x1CD0; 0x1CD1;

     

       32
       32
       -
           0x1CD2; 0x1CDA; 0x1CDB; 0x1CE0; 0x1DC0; 0x1DC1; 0x1DC3; 0x1DC4;

     

       33
       33
       -
           0x1DC5; 0x1DC6; 0x1DC7; 0x1DC8; 0x1DC9; 0x1DCB; 0x1DCC; 0x1DD1;

     

       34
       34
       -
           0x1DD2; 0x1DD3; 0x1DD4; 0x1DD5; 0x1DD6; 0x1DD7; 0x1DD8; 0x1DD9;

     

       35
       35
       -
           0x1DDA; 0x1DDB; 0x1DDC; 0x1DDD; 0x1DDE; 0x1DDF; 0x1DE0; 0x1DE1;

     

       36
       36
       -
           0x1DE2; 0x1DE3; 0x1DE4; 0x1DE5; 0x1DE6; 0x1DFE; 0x20D0; 0x20D1;

     

       37
       37
       -
           0x20D4; 0x20D5; 0x20D6; 0x20D7; 0x20DB; 0x20DC; 0x20E1; 0x20E7;

     

       38
       38
       -
           0x20E9; 0x20F0; 0xA66F; 0xA67C; 0xA67D; 0xA6F0; 0xA6F1; 0xA8E0;

     

       39
       39
       -
           0xA8E1; 0xA8E2; 0xA8E3; 0xA8E4; 0xA8E5; 0xA8E6; 0xA8E7; 0xA8E8;

     

       40
       40
       -
           0xA8E9; 0xA8EA; 0xA8EB; 0xA8EC; 0xA8ED; 0xA8EE; 0xA8EF; 0xA8F0;

     

       41
       41
       -
           0xA8F1; 0xAAB0; 0xAAB2; 0xAAB3; 0xAAB7; 0xAAB8; 0xAABE; 0xAABF;

     

       42
       42
       -
           0xAAC1; 0xFE20; 0xFE21; 0xFE22; 0xFE23; 0xFE24; 0xFE25; 0xFE26;

     

       43
       43
       -
           0x10A0F; 0x10A38; 0x1D185; 0x1D186; 0x1D187; 0x1D188; 0x1D189;

     

       44
       44
       -
           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;

     

       45
       274
        
         |]

     

       46
       275
        
       

     

       47
       276
        
       let diacritic n = Uchar.of_int diacritics.(n mod Array.length diacritics)

     
···

       53
       282
        
         let rec gen () =

     

       54
       283
        
           let id = Random.int32 Int32.max_int |> Int32.to_int in

     

       55
       284
        
           (* Ensure high byte and middle bytes are non-zero *)

     

       56
       56
       -
           if id land 0xFF000000 = 0 || id land 0x00FFFF00 = 0 then gen ()

     

       57
       57
       -
           else id

     

       285
       285
       +
           if id land 0xFF000000 = 0 || id land 0x00FFFF00 = 0 then gen () else id

     

       58
       286
        
         in

     

       59
       287
        
         gen ()

     

       60
       288
        
       

     
···

       84
       312
        
         (* Optional placement ID in underline color *)

     

       85
       313
        
         placement_id

     

       86
       314
        
         |> Option.iter (fun pid ->

     

       87
       87
       -
                Printf.bprintf buf "\027[58:2:%d:%d:%dm"

     

       88
       88
       -
                  ((pid lsr 16) land 0xFF)

     

       89
       89
       -
                  ((pid lsr 8) land 0xFF)

     

       90
       90
       -
                  (pid land 0xFF));

     

       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));

     

       91
       319
        
         (* High byte diacritic - always written, even when 0 *)

     

       92
       320
        
         let high_byte = (image_id lsr 24) land 0xFF in

     

       93
       321
        
         let id_diac = id_high_byte_diacritic high_byte in

+8 -6

lib/kgp_unicode.mli

···

       5
       5
        
       

     

       6
       6
        
       (** Kitty Graphics Protocol Unicode Placeholders

     

       7
       7
        
       

     

       8
       8
       -
           Support for invisible Unicode placeholder characters that encode

     

       9
       9
       -
           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
        
       

     
···

       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

     

       31
       31
       -
           work correctly. Uses [Random] internally. *)

     

       30
       30
       +
           This ensures the foreground color encoding and diacritic encoding work

     

       31
       31
       +
           correctly. Uses [Random] internally. *)

     

       32
       32
        
       

     

       33
       33
        
       val write :

     

       34
       34
        
         Buffer.t ->

     
···

       40
       40
        
         unit

     

       41
       41
        
       (** Write placeholder characters to a buffer.

     

       42
       42
        
       

     

       43
       43
       -
           @param image_id Should be generated with {!next_image_id} for correct rendering.

     

       44
       44
       -
           @param placement_id Optional placement ID for multiple placements of same image.

     

       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.

     

       45
       47
        
           @param rows Number of rows in the placeholder grid.

     

       46
       48
        
           @param cols Number of columns in the placeholder grid. *)

     

       47
       49