(*---------------------------------------------------------------------------
   Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
   SPDX-License-Identifier: ISC
  ---------------------------------------------------------------------------*)

(** Tmux Passthrough Support

    Support for passing graphics protocol escape sequences through tmux to the
    underlying terminal emulator.

    {2 Background}

    When running inside tmux, graphics protocol escape sequences need to be
    wrapped in a DCS (Device Control String) passthrough sequence so that tmux
    forwards them to the actual terminal (kitty, wezterm, ghostty, etc.) rather
    than interpreting them itself.

    The passthrough format is:
    - Prefix: [ESC P tmux ;]
    - Content with all ESC characters doubled
    - Suffix: [ESC]

    {2 Requirements}

    For tmux passthrough to work:
    {ul
     {- tmux version 3.3 or later }
     {- [allow-passthrough] must be enabled in tmux.conf:
        {v set -g allow-passthrough on v}
     }
    }

    {2 Usage}

    {[
      if Kgp.Tmux.is_active () then
        let wrapped = Kgp.Tmux.wrap graphics_command in
        print_string wrapped
      else print_string graphics_command
    ]} *)

val is_active : unit -> bool
(** Detect if we are running inside tmux.

    Returns [true] if the [TMUX] environment variable is set, indicating the
    process is running inside a tmux session. *)

val wrap : string -> string
(** Wrap an escape sequence for tmux passthrough.

    Takes a graphics protocol escape sequence and wraps it in the tmux DCS
    passthrough format:
    - Adds [ESC P tmux ;] prefix
    - Doubles all ESC characters in the content
    - Adds [ESC] suffix

    If not running inside tmux, returns the input unchanged. *)

val wrap_always : string -> string
(** Wrap an escape sequence for tmux passthrough unconditionally.

    Like {!wrap} but always applies the wrapping, regardless of whether we are
    inside tmux. Useful when you want to pre-generate tmux-compatible output. *)

val write_wrapped : Buffer.t -> string -> unit
(** Write a wrapped escape sequence directly to a buffer.

    More efficient than {!wrap_always} when building output in a buffer, as it
    avoids allocating an intermediate string. *)