Kitty Graphics Protocol in OCaml
anil.recoil.org
terminal
graphics
ocaml
1(** Tmux Passthrough Support
2
3 Support for passing graphics protocol escape sequences through tmux
4 to the underlying terminal emulator.
5
6 {2 Background}
7
8 When running inside tmux, graphics protocol escape sequences need to be
9 wrapped in a DCS (Device Control String) passthrough sequence so that
10 tmux forwards them to the actual terminal (kitty, wezterm, ghostty, etc.)
11 rather than interpreting them itself.
12
13 The passthrough format is:
14 - Prefix: [ESC P tmux ;]
15 - Content with all ESC characters doubled
16 - Suffix: [ESC]
17
18 {2 Requirements}
19
20 For tmux passthrough to work:
21 - tmux version 3.3 or later
22 - [allow-passthrough] must be enabled in tmux.conf:
23 {v set -g allow-passthrough on v}
24
25 {2 Usage}
26
27 {[
28 if Kgp.Tmux.is_active () then
29 let wrapped = Kgp.Tmux.wrap graphics_command in
30 print_string wrapped
31 else
32 print_string graphics_command
33 ]} *)
34
35val is_active : unit -> bool
36(** Detect if we are running inside tmux.
37
38 Returns [true] if the [TMUX] environment variable is set,
39 indicating the process is running inside a tmux session. *)
40
41val wrap : string -> string
42(** Wrap an escape sequence for tmux passthrough.
43
44 Takes a graphics protocol escape sequence and wraps it in the
45 tmux DCS passthrough format:
46 - Adds [ESC P tmux ;] prefix
47 - Doubles all ESC characters in the content
48 - Adds [ESC] suffix
49
50 If not running inside tmux, returns the input unchanged. *)
51
52val wrap_always : string -> string
53(** Wrap an escape sequence for tmux passthrough unconditionally.
54
55 Like {!wrap} but always applies the wrapping, regardless of
56 whether we are inside tmux. Useful when you want to pre-generate
57 tmux-compatible output. *)
58
59val write_wrapped : Buffer.t -> string -> unit
60(** Write a wrapped escape sequence directly to a buffer.
61
62 More efficient than {!wrap_always} when building output in a buffer,
63 as it avoids allocating an intermediate string. *)