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

(** Cmdliner Support for Kitty Graphics Protocol

    This module provides Cmdliner terms for configuring graphics output mode in
    CLI applications. It allows users to override auto-detection with
    command-line flags.

    {2 Usage}

    Add the graphics term to your command:

    {[
      let cmd =
        let graphics = Kgp_cli.graphics_term in
        let my_args = ... in
        Cmd.v info Term.(const my_run $ graphics $ my_args)
    ]}

    Then use the resolved mode in your application:

    {[
      let my_run graphics_mode args =
        if Kgp.Terminal.supports_graphics graphics_mode then
          (* render with graphics *)
        else
          (* use text fallback *)
    ]} *)

(** {1 Terms} *)

val graphics_term : Kgp.Terminal.graphics_mode Cmdliner.Term.t
(** Cmdliner term for graphics mode selection.

    Provides the following command-line options:

    - [--graphics] / [-g]: Force graphics output enabled
    - [--no-graphics]: Force graphics output disabled (use placeholders)
    - [--tmux]: Force tmux passthrough mode
    - (default): Auto-detect based on terminal environment

    The term evaluates to a {!Kgp.Terminal.graphics_mode} value which can be
    passed to {!Kgp.Terminal.supports_graphics} or {!Kgp.Terminal.resolve_mode}.
*)

val graphics_docs : string
(** Section name for graphics options in help output ("GRAPHICS OPTIONS").

    Use this when grouping graphics options in a separate help section. *)