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

(** Terminal Environment Detection

    Detect terminal capabilities and environment for graphics protocol support.

    {2 Supported Terminals}

    The following terminals support the Kitty Graphics Protocol:
    - Kitty (the original implementation)
    - WezTerm
    - Ghostty
    - Konsole (partial support)

    {2 Environment Detection}

    Detection is based on environment variables:
    - [KITTY_WINDOW_ID] - set by Kitty
    - [WEZTERM_PANE] - set by WezTerm
    - [GHOSTTY_RESOURCES_DIR] - set by Ghostty
    - [TERM_PROGRAM] - may contain terminal name
    - [TERM] - may contain "kitty"
    - [TMUX] - set when inside tmux
    - [PAGER] / output to non-tty - indicates pager mode *)

(** {1 Graphics Mode} *)

type graphics_mode = [ `Auto | `Enabled | `Disabled | `Tmux ]
(** Graphics output mode.

    - [`Auto] - Auto-detect based on environment
    - [`Enabled] - Force graphics enabled
    - [`Disabled] - Force graphics disabled (use placeholders)
    - [`Tmux] - Force tmux passthrough mode *)

(** {1 Detection} *)

val is_kitty : unit -> bool
(** Detect if running in Kitty terminal. *)

val is_wezterm : unit -> bool
(** Detect if running in WezTerm terminal. *)

val is_ghostty : unit -> bool
(** Detect if running in Ghostty terminal. *)

val is_graphics_terminal : unit -> bool
(** Detect if running in any terminal that supports the graphics protocol. *)

val is_tmux : unit -> bool
(** Detect if running inside tmux. *)

val is_pager : unit -> bool
(** Detect if output is likely going to a pager.

    Returns [true] if:
    - stdout is not a tty, or
    - [PAGER] environment variable is set and we're not in a known
      graphics-capable terminal *)

val is_interactive : unit -> bool
(** Detect if running interactively (stdout is a tty). *)

(** {1 Mode Resolution} *)

val resolve_mode : graphics_mode -> [ `Graphics | `Tmux | `Placeholder ]
(** Resolve a graphics mode to the actual output method.

    - [`Graphics] - use direct graphics protocol
    - [`Tmux] - use graphics protocol with tmux passthrough
    - [`Placeholder] - use text placeholders (block characters)

    For [Auto] mode:
    - If in a pager or non-interactive: [`Placeholder]
    - If in tmux with graphics terminal: [`Tmux]
    - If in graphics terminal: [`Graphics]
    - Otherwise: [`Placeholder] *)

val supports_graphics : graphics_mode -> bool
(** Check if the resolved mode supports graphics output.

    Returns [true] for [`Graphics] and [`Tmux], [false] for [`Placeholder]. *)