termgfx

package
v0.121.1 Latest Latest
Warning

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

Go to latest
Published: Oct 5, 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.

A daemon session splits the two halves across machines: the probe runs in the child on the daemon host, while the terminal — and any multiplexer wrapped around it — is on the client. The client names its multiplexer for the child; see RemoteMultiplexerEnv.

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

Index

Constants

View Source
const (
	// MultiplexerTmux is tmux, which drops graphics escapes unless
	// allow-passthrough is on and the sequence is wrapped for it.
	MultiplexerTmux = "tmux"
	// MultiplexerScreen is GNU screen, which drops them outright. tmux's
	// own default TERM also names screen, so this covers a tmux that was
	// not otherwise identified.
	MultiplexerScreen = "screen"
	// MultiplexerZellij is zellij, which forwards graphics but strips the
	// combining marks Unicode placeholders are built from.
	MultiplexerZellij = "zellij"
)

The multiplexers detection knows by name. They are the values carried by RemoteMultiplexerEnv and returned by LocalMultiplexer.

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)
View Source
const RemoteMultiplexerEnv = "KIT_REMOTE_MULTIPLEXER"

RemoteMultiplexerEnv names the multiplexer the CLIENT of a daemon session runs inside, as one of the Multiplexer constants, or is unset when the client owns a bare terminal.

A daemon session's child renders on the daemon host while the terminal, and any multiplexer around it, lives on the client machine. TMUX and ZELLIJ describe a process's own pane, so they never cross the wire, and the child therefore cannot see what will handle the escape sequences it writes. Left to itself it probes a terminal that answers through tmux, believes the answer, and draws Kitty graphics that tmux discards — leaving the empty placeholder cells the image should have filled. The client names its multiplexer instead and the daemon plants it here, so the child reaches the decision the client would have reached locally.

Variables

This section is empty.

Functions

func LocalMultiplexer added in v0.102.0

func LocalMultiplexer() string

LocalMultiplexer reports the multiplexer this process runs inside, named by the Multiplexer constants, or "" when it talks to a terminal directly.

It reads only this process's own environment, so a daemon session client calls it to describe itself and the child reads RemoteMultiplexerEnv instead; see multiplexer.

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