Image Rendering and Terminal Challenges

Image Rendering & Terminal Graphics Guide

Mastui supports displaying inline image attachments, post previews, and user avatars directly inside your terminal or web browser.

Displaying graphics inside terminal emulators is historically challenging due to competing standards and varying emulator capabilities. This guide explains how Mastui renders images, compares available rendering protocols, highlights known terminal quirks, and provides troubleshooting steps.

---

🖼️ Supported Image Renderers

Mastui leverages Pillow and textual-image to support four distinct rendering modes:

Renderer	Option Key	How It Works	Fidelity	Universal Compatibility
ANSI Halfcell (Default)	ansi	Converts pixels to Unicode upper/lower half-block characters (▀, ▄) with 24-bit TrueColor foreground and background ANSI escape codes.	Standard / Low-Res	100% (Works everywhere, including SSH, tmux, Windows Terminal, and Web)
Kitty Graphics Protocol	tgp	Uses Kitty's high-performance Terminal Graphics Protocol (\x1b_G...) to stream compressed pixel data directly to the terminal GPU buffer.	Pixel-Perfect	Supported by Kitty, WezTerm, Ghostty
Sixel Graphics	sixel	Uses the legacy DEC Sixel raster bitmap protocol (\x1bPq...) to paint 6-pixel tall bitmap slices.	High Resolution	Supported by Foot, WezTerm, Ghostty, XTerm
Auto Detection	auto	Probes terminal capabilities and selects the highest fidelity protocol supported by the active emulator.	Adaptive	Varies

---

🖥️ Terminal Emulator Compatibility Matrix

Terminal Emulator	ANSI Halfcell (ansi)	Kitty Graphics (tgp)	Sixel (sixel)	TrueColor Support	Recommended Renderer
Ghostty	✅ Full	✅ Full	✅ Full	✅ Yes	tgp / auto
Kitty	✅ Full	✅ Full	❌ No	✅ Yes	tgp / auto
WezTerm	✅ Full	✅ Full	✅ Full	✅ Yes	tgp / auto
Foot (Wayland)	✅ Full	❌ No	✅ Full	✅ Yes	sixel
iTerm2 (macOS)	✅ Full	⚠️ Partial	✅ Full	✅ Yes	sixel / ansi
Alacritty	✅ Full	❌ No	❌ No	✅ Yes	ansi
Windows Terminal	✅ Full	❌ No	❌ No	✅ Yes	ansi
GNOME Terminal / Ptyxis	✅ Full	❌ No	❌ No	✅ Yes	ansi
Mastui Web (--web)	✅ Full	❌ No	❌ No	✅ Yes	ansi

---

⚠️ Known Challenges & Terminal Quirks

1. Terminal Multiplexers (tmux & screen)

By default, tmux strips or alters passthrough escape sequences like Kitty Graphics and Sixel. If you run Mastui inside tmux:

• Recommended Fix: Use the ansi halfcell renderer (works out-of-the-box in tmux).
• For Kitty/Sixel Passthrough in tmux (v3.3+): Add the following to your ~/.tmux.conf:

  set -g allow-passthrough on
  set -ga update-environment TERM
  set -ga update-environment TERM_PROGRAM

---

2. Character Cell Aspect Ratios & Geometry

Terminal character cells are not square—they are typically twice as tall as they are wide (~1:2 aspect ratio).

• In Halfcell mode (ansi), Mastui splits each character cell into an upper and lower block, creating near-square pixel blocks and eliminating image distortion.
• In Pixel modes (tgp/sixel), the terminal font size and cell padding can cause subtle alignment shifts when resizing terminal windows. Mastui handles this by debouncing resize events and triggering dynamic redraws.

---

3. Escape Sequence Bleeding

If a terminal emulator does not support Sixel or Kitty graphics but receives those control codes, it may print garbled ASCII characters (e.g. _Ga=T,f=100... or random garbage).

• Mastui's Safeguard: Mastui defaults to ansi (Halfcell), ensuring safe, crash-free operation on any terminal by default. Only enable tgp or sixel if you know your emulator supports it.

---

4. SSH Remote Sessions & Latency

Streaming raw pixel bitmaps over slow SSH connections can saturate bandwidth.

• Halfcell images are lightweight ANSI text strings that stream efficiently even over high-latency remote connections.
• Mastui uses asynchronous, non-blocking image downloading with retry backoff (MAX_IMAGE_RETRIES = 3) to prevent network stalls from freezing the UI.

---

⚙️ Configuring Image Rendering

You can toggle images on/off and switch renderers at any time:

In the UI:

1. Press o to open Mastui Options.
2. Expand the Image Settings section.
3. Toggle Enable Images on or off.
4. Select your preferred Image Renderer (ansi, tgp, sixel, auto).
5. Click Save Options.

In .env:

IMAGE_SUPPORT=on
IMAGE_RENDERER=tgp
AUTO_PRUNE_CACHE=on