Package org.aesh.terminal.detect

Class TerminalCapabilities

java.lang.Object
org.aesh.terminal.detect.TerminalCapabilities
public final class TerminalCapabilities extends Object
Lightweight terminal capability detection.

Detects terminal features using environment variables and heuristics without requiring a terminal connection or any external dependencies.

Usage: 

 // Fast heuristic detection (~1-2ms)
 TerminalCapabilities caps = TerminalCapabilities.detect();

 // Async detection with background color queries
 TerminalCapabilities caps = TerminalCapabilities.detectAsync();
 // ... do other startup work ...
 caps.awaitColors(500, TimeUnit.MILLISECONDS);
 int[] bg = caps.backgroundRGB(); // available once query completes

  • Method Details

    • getInstance

      public static TerminalCapabilities getInstance()
      Get the shared instance, creating it lazily via detect().

      Use setInstance(TerminalCapabilities) to inject a pre-built instance from early startup (e.g., Quarkus bootstrap). For example, call setInstance(detectAsync()) to enable background color queries before other modules initialize.

      Returns:
      the shared capabilities instance

    • setInstance

      public static void setInstance(TerminalCapabilities caps)
      Set the shared instance. Call this early in application startup to make pre-detected capabilities available to all later consumers.
      Parameters:
      caps - the pre-detected capabilities

    • detect

      public static TerminalCapabilities detect()
      Detect terminal capabilities from environment variables only. Fast (~1-2ms), no subprocess calls on Linux/macOS.
      Returns:
      the detected capabilities

    • detectFull

      public static TerminalCapabilities detectFull()
      Detect terminal capabilities with full platform theme probing.

      Same as detect() but when the theme cannot be determined from environment variables, also checks platform-specific sources:

      • macOS: defaults read -g AppleInterfaceStyle
      • Linux: gsettings (GNOME) or kreadconfig5 (KDE)
      • Windows: Apps dark mode registry key
      This may take 10-50ms due to subprocess calls.
      Returns:
      the detected capabilities with resolved theme

    • detectAsync

      public static TerminalCapabilities detectAsync()
      Detect terminal capabilities and query actual colors in the background.

      Returns immediately with heuristic results (~1-2ms). A daemon thread queries the terminal for foreground/background colors via OSC escape sequences. Use awaitColors(long, TimeUnit) to wait for the query to complete, or check backgroundRGB() / foregroundRGB() which return null until the query finishes.

      On platforms where terminal queries are not possible (Windows, pipes, containers, tmux without passthrough), the background thread completes immediately with no results and falls back to platform theme detection.

      Returns:
      the detected capabilities with background color query running

    • awaitColors

      public boolean awaitColors(long timeout, TimeUnit unit) throws InterruptedException
      Wait for the background color query to complete.

      Only relevant when created via detectAsync(). For other factory methods, this returns true immediately.

      Parameters:
      timeout - the maximum time to wait
      unit - the time unit
      Returns:
      true if the query completed, false if timed out
      Throws:
      InterruptedException - if interrupted while waiting

    • supportsTrueColor

      public boolean supportsTrueColor()
      Check if the terminal supports 24-bit true color (16 million colors).

      When created via detectAsync(), this may upgrade to true after the color query confirms true color support (terminals that respond to OSC color queries support true color).

      Returns:
      true if true color is supported

    • supports256Colors

      public boolean supports256Colors()
      Check if the terminal supports at least 256 colors. Always true when supportsTrueColor() is true.

      When created via detectAsync(), this may upgrade to true after the color query confirms 256-color support.

      Returns:
      true if 256 colors are supported

    • supportsColor

      public boolean supportsColor()
      Check if the terminal supports any color output.
      Returns:
      true if color is supported

    • imageProtocol

      public ImageProtocol imageProtocol()
      Get the image display protocol supported by this terminal.

      When created via detectAsync(), this may upgrade from NONE to SIXEL after the DA1 query confirms Sixel support.

      Returns:
      the image protocol, or ImageProtocol.NONE

    • theme

      public TerminalTheme theme()
      Get the terminal background theme.

      When created via detectAsync(), this may return a more accurate result after the color query completes (derived from the actual background RGB).

      Returns:
      the theme (DARK, LIGHT, or UNKNOWN)

    • foregroundRGB

      public int[] foregroundRGB()
      Get the queried foreground color.

      Only available after a successful color query via detectAsync().

      Returns:
      RGB array [r, g, b] (0-255 each), or null if not queried

    • backgroundRGB

      public int[] backgroundRGB()
      Get the queried background color.

      Only available after a successful color query via detectAsync().

      Returns:
      RGB array [r, g, b] (0-255 each), or null if not queried

    • paletteColors

      public Map<Integer,int[]> paletteColors()
      Get the queried base 16 palette colors (ANSI colors 0-15).

      Only available after a successful color query via detectAsync().

      Returns:
      map from color index (0-15) to RGB array [r, g, b], or empty map if not queried

    • paletteColor

      public int[] paletteColor(int index)
      Get a palette color by ANSI index (0-15).
      Parameters:
      index - the ANSI color index
      Returns:
      RGB array [r, g, b] (0-255 each), or null if not queried

    • black

      public int[] black()

    • red

      public int[] red()

    • green

      public int[] green()

    • yellow

      public int[] yellow()

    • blue

      public int[] blue()

    • magenta

      public int[] magenta()

    • cyan

      public int[] cyan()

    • white

      public int[] white()

    • brightBlack

      public int[] brightBlack()

    • brightRed

      public int[] brightRed()

    • brightGreen

      public int[] brightGreen()

    • brightYellow

      public int[] brightYellow()

    • brightBlue

      public int[] brightBlue()

    • brightMagenta

      public int[] brightMagenta()

    • brightCyan

      public int[] brightCyan()

    • brightWhite

      public int[] brightWhite()

    • terminalName

      public String terminalName()
      Get the detected terminal name.
      Returns:
      terminal name (e.g., "kitty", "ghostty", "iterm2", "unknown")

    • toString

      public String toString()
      Overrides:
      toString in class Object