termgfx

package
v0.98.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 27, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package termgfx detects which inline-graphics protocols the attached terminal will actually honour.

Detection is empirical, not a lookup table: the probe writes a Kitty graphics query and a primary device attributes (DA1) request, then reads the replies. A terminal that understands the Kitty graphics protocol answers the query; every terminal answers DA1, so the DA1 reply is the guaranteed terminator that keeps the probe from waiting for a response that will never arrive.

Empirical detection matters because a terminal's name does not predict what it can do. It matters most under a multiplexer, where the answer can be borrowed: both tmux and zellij forward the graphics query to the terminal behind them and let that terminal answer, which makes the multiplexer look capable when it cannot place an image. The probe therefore also requires the pty to report pixel geometry, which is what a forwarding multiplexer lacks.

Measured on 2026-08-26 with kitty 0.48.2:

  • kitty: answers the query and reports a cell size. Graphics used.
  • zellij 0.45.0: answers (via kitty) and reports no pixel geometry. It also strips the combining marks that Unicode placeholders depend on, so placeholder cells draw nothing. Graphics used, placed directly at the cursor instead.
  • tmux with allow-passthrough on: answers DA1 itself while forwarding the graphics query onward, so the terminal's reply arrives after the probe has stopped reading and leaks into the input stream as visible garbage. The query is therefore not sent under a multiplexer at all.

See internal/ui/imagepreview for the two renderers this chooses between.

Index

Constants

View Source
const EnvOverride = "KIT_IMAGE_PROTOCOL"

EnvOverride is the environment variable that bypasses detection.

KIT_IMAGE_PROTOCOL=kitty      force the Kitty graphics protocol
KIT_IMAGE_PROTOCOL=halfblock  force half-block thumbnails
KIT_IMAGE_PROTOCOL=auto       probe the terminal (default)

Variables

This section is empty.

Functions

func Resolve

func Resolve()

Resolve probes the process terminal once and caches the result. Later calls are no-ops.

Call this during startup, before the TUI takes over stdin: the probe reads raw bytes from stdin, so it must not run while the event loop owns the same fd. Headless frontends should call Set instead, so no fd that does not describe their client is ever probed.

func Set

func Set(c Capabilities)

Set overrides the detected capabilities. It exists for headless frontends, which know their client's capabilities out of band, and for tests.

func SupportsKittyGraphics

func SupportsKittyGraphics() bool

SupportsKittyGraphics reports whether inline Kitty graphics reach the terminal intact.

func UseKittyGraphics

func UseKittyGraphics() bool

UseKittyGraphics reports whether image previews use the Kitty graphics protocol rather than half-block text.

Types

type Capabilities

type Capabilities struct {
	// KittyGraphics reports that the terminal answered the Kitty graphics
	// query, and therefore that graphics escape sequences reach it intact.
	KittyGraphics bool

	// Sixel reports that DA1 advertised attribute 4 (sixel graphics). It is a
	// free by-product of the probe's terminator and is not used for
	// thumbnails today.
	Sixel bool

	// CellWidth and CellHeight are the pixel dimensions of one terminal cell,
	// or zero when the terminal reports no pixel geometry.
	//
	// They are part of the graphics decision, not just a detail for scaling. A
	// multiplexer can forward the graphics query to the terminal behind it and
	// let that terminal answer, which makes the multiplexer look capable when
	// it cannot actually place an image. Pixel geometry is what such a
	// multiplexer does not report, so requiring it turns a borrowed answer into
	// a truthful one. See ptyPixelSize.
	CellWidth  int
	CellHeight int

	// TrueColor reports that the terminal accepts 24-bit colour.
	//
	// It is captured when capabilities are resolved rather than read at draw
	// time, so that the preview mode is a pure function of this struct. It
	// decides only between the two graphics modes: placeholder cells carry the
	// image id as a 24-bit foreground colour, which a smaller palette would
	// quantise into a different id, whereas a direct placement carries the id
	// in the escape sequence and does not care.
	TrueColor bool

	// UnicodePlaceholders reports that placeholder cells reach the terminal
	// intact, and therefore that an image can be drawn as view text.
	//
	// This is a separate capability from the protocol itself. Zellij 0.45
	// forwards the graphics protocol and draws real images, but discards the
	// combining marks that tell each placeholder cell which part of the image
	// it holds, so placeholders render nothing there while direct placement
	// works. Naming the capability rather than the terminal keeps the decision
	// in one place: a future release that fixes the marks changes detection,
	// not the renderer.
	UnicodePlaceholders bool
}

Capabilities records the graphics protocols the terminal accepted during the probe. A zero value means "no inline graphics", which is the safe default: callers fall back to half-block rendering.

func Current

func Current() Capabilities

Current returns the resolved capabilities, or the zero value when nothing has been resolved yet. It never probes: an unresolved value degrades to half-block rendering rather than reading stdin at render time.

func Probe

func Probe(in, out *os.File, timeout time.Duration) (Capabilities, error)

Probe queries the terminal directly, bypassing both the cache and the environment override.

in must be the terminal's input and out its output; both are put in raw mode for the duration of the call. An error means the probe could not run (not a terminal, raw mode refused, write failed), which callers should read as "no graphics support".

type Mode

type Mode int

Mode is how image previews should be drawn.

const (
	// ModeHalfBlock draws previews as coloured half-block text. It works in
	// any terminal with 256 colours and survives multiplexers untouched.
	ModeHalfBlock Mode = iota

	// ModePlaceholder draws previews with the Kitty graphics protocol using
	// Unicode placeholder cells, so the image travels with the view text.
	ModePlaceholder

	// ModeDirect draws previews with the Kitty graphics protocol using a
	// direct placement at the cursor. It is for terminals that carry the
	// protocol but drop the combining marks placeholders depend on.
	ModeDirect
)

func PreviewMode

func PreviewMode() Mode

PreviewMode reports how image previews should be drawn in this terminal.

Kitty graphics need protocol support and a reported cell size. The cell size matters because a multiplexer that merely forwards the graphics query to the terminal behind it will answer yes without being able to draw; see Capabilities.CellWidth.

The choice between the two graphics modes turns on whether placeholder cells survive to the terminal and whether it has truecolor to carry the image id in. See Capabilities.UnicodePlaceholders and Capabilities.TrueColor.

func (Mode) String

func (m Mode) String() string

String implements fmt.Stringer.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL