Documentation
¶
Index ¶
- func CellSize() (width, height int, ok bool)
- func CreateVirtualPlacement(id uint32, cols, rows int) string
- func DeletePlacement(id uint32) string
- func InlinePlacement(id uint32, cols, rows int) string
- func InsideTmux() bool
- func IsSupported() bool
- func PlaceholderBlock(id uint32, cols, rows int) string
- func PlaceholderFill(index, cols, rows int) string
- func ReplacePlaceholders(rendered string, placements []Placement) string
- func Transmit(id uint32, data []byte, cols, rows int) string
- func TransmitOnly(id uint32, data []byte) string
- type Placement
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CellSize ¶ added in v0.8.0
CellSize reports the pixel dimensions of a single terminal cell by sending the xterm "report cell size" CSI (`CSI 16 t`) and parsing the `CSI 6 ; H ; W t` response from stdin. Must be called BEFORE bubbletea starts — once bubbletea captures stdin we can't reliably read the response without racing the renderer.
Runs with a short deadline so non-conforming terminals don't hang the startup path; returns zeros on any error or timeout, signalling the caller to fall back to heuristic defaults.
func CreateVirtualPlacement ¶ added in v0.8.0
CreateVirtualPlacement registers a virtual placement of (cols × rows) for an already-transmitted image. The placement is virtual: it occupies no cells on its own; Unicode placeholders emitted later reference it by image ID (encoded in the FG color) to render the image.
func DeletePlacement ¶ added in v0.8.0
DeletePlacement removes all placements for the given image ID (virtual and real). Call on reader exit to avoid "ghost" images on subsequent screens. Using d=I restricts deletion to this image's placements only.
func InlinePlacement ¶ added in v0.8.0
InlinePlacement returns an APC that creates a real placement of an already-transmitted image at the cursor's CURRENT position, sized to (cols × rows). C=1 prevents Kitty from moving the cursor; we then emit `rows` newlines so the next text starts below the image. This is the alternative to virtual placement+Unicode placeholders: the image is bound to the current screen buffer, so it survives bubbletea's alt-screen (where virtual placements made in main-screen disappear).
Pair with TransmitOnly (image upload) done once per article. Each View() emits InlinePlacement(id, c, r) at the spot where each image should appear.
func InsideTmux ¶ added in v0.8.0
func InsideTmux() bool
InsideTmux reports whether we're running under a tmux session. tmux strips unknown terminal escape sequences unless `set -g allow-passthrough on` is configured, which blocks Kitty Graphics Protocol APCs. Callers can use this to surface a hint when images mysteriously fail to render.
func IsSupported ¶
func IsSupported() bool
IsSupported reports whether the current terminal speaks the Kitty Graphics Protocol. Covers Kitty, Ghostty, and WezTerm.
func PlaceholderBlock ¶
PlaceholderBlock returns a text block of Unicode placeholders with the foreground color encoding the low 24 bits of the image ID. The block is wrapped with SGR reset so surrounding text is not affected. Each cell carries two diacritics (row, col); callers with image IDs whose high byte is non-zero also need to emit a third diacritic — not supported here because rdr uses small IDs derived from hashes.
func PlaceholderFill ¶ added in v0.8.0
PlaceholderFill renders a block of cols × rows cells, terminated by a trailing newline. The first cell of the first row is a marker rune encoding `index` (0-based); the rest are fill runes. Call this for each image in article order, passing index 0, 1, 2, ...
The same index must be used when building the []Placement slice passed to ReplacePlaceholders so the N-th block is paired with the N-th placement.
func ReplacePlaceholders ¶ added in v0.8.0
ReplacePlaceholders scans the rendered frame for first-row placeholder markers (runes in [U+E800, U+E8FF]) and substitutes each one with an inline delete-then-place APC for the corresponding Placement. Each line independently carries both `a=d,d=i` (delete prior placements of this image) and `a=p` (create new placement at the cursor). The subsequent rows of the block are left as fill runes — the image drawn by Kitty covers those cells visually.
Leading bytes before the marker on the same line (ANSI SGR colours and whitespace introduced by lipgloss padding) are preserved so the cursor arrives at the correct column when Kitty parses the APC.
Callers are responsible for a parallel cleanup path: when a marker scrolls off-screen its line is no longer emitted by viewport, so the delete APC never reaches Kitty through this function. The rdr reader writes explicit `DeletePlacement` APCs to os.Stdout from its Update() handler on scroll events to clear those orphans — that path bypasses bubbletea's frame-diff renderer, which otherwise skips unchanged lines and would swallow any prefix-level cleanup we try to emit here.
func Transmit ¶
Transmit returns the escape sequence(s) that upload the given PNG bytes to the terminal under the given ID and create a virtual placement of (cols × rows) terminal cells. Large payloads are split into 4096-byte base64 chunks. Matches the canonical form used by Kitty's own icat kitten with `--unicode-placeholder`.
Callers must pair this with PlaceholderBlock to draw the image.
func TransmitOnly ¶ added in v0.8.0
TransmitOnly uploads the PNG under the given ID without creating any placement. Pair with CreateVirtualPlacement + placeholder text (or with placeholders alone if a placement was already made). Using a=t (lowercase) avoids the a=T+U=1 one-shot form, which has proved fragile inside TUI renderers — splitting the upload from the placement lets us emit the payload out-of-band (before bubbletea takes over stdout) and keep only the cheap placement bytes flowing through View().
Source Files