Skip to content

Render local images in the Kitty TUI - #309

Closed
FelixZhang wants to merge 2 commits into
RivoLink:mainfrom
FelixZhang:feat/kitty-tui-images
Closed

FelixZhang wants to merge 2 commits into
RivoLink:mainfrom
FelixZhang:feat/kitty-tui-images

Conversation

@FelixZhang

Copy link
Copy Markdown

Summary

Adds optional local image rendering to the interactive TUI using Kitty's graphics protocol. Rendering is disabled by default and can be enabled through configuration, environment, or an in-session hotkey.

Changes

  • Add kitty-images configuration with LEAF_KITTY_IMAGES override; both default to disabled.
  • Add an i / I session toggle with status feedback and help entry.
  • Parse ![alt](source) into image blocks only when image rendering is enabled.
  • Render local PNG, JPEG, GIF, and WebP images in the Kitty TUI using ratatui-image.
  • Decode and encode visible images on a background worker, with cancellation and retry handling.
  • Size image blocks from the source image aspect ratio and clamp the reserved height to 12–40 rows.
  • Keep disabled mode on the existing upstream Markdown path: only alt text is shown, with no image border or reserved rows.
  • Preserve readable fallbacks for missing, oversized, remote, SVG, unsupported, table, and footnote images.
  • Leave --inline output unchanged and free of Kitty control sequences.

Notes

  • Local paths resolve relative to the Markdown file; stdin paths resolve relative to the current working directory.
  • HTTP(S), data: URLs, and SVG files are not downloaded or rendered.
  • Images are bounded to 20 MiB, 16,384 pixels per dimension, and 128 MiB decode allocation.

Testing

  • cargo fmt --all -- --check
  • cargo test (540 tests)
  • cargo clippy --all-targets --all-features -- -D warnings
  • cargo build --release
  • Verified --inline contains no Kitty APC sequences
  • Manual Kitty visual verification: see the Kitty Images section in TESTING.md

Xiaofei Zhang added 2 commits September 28, 2026 17:11
Add aspect-aware Markdown image blocks, background decoding, bounded caching, and Kitty graphics rendering. Preserve readable fallbacks for unsupported images and non-Kitty terminals.
Add a default-disabled kitty-images setting and i/I session toggle. Disabled mode follows upstream text layout, while enabled mode reparses image blocks and cancels background workers safely.
@FelixZhang
FelixZhang force-pushed the feat/kitty-tui-images branch from ce7970f to b89c0d4 Compare September 28, 2026 09:12
@RivoLink

Copy link
Copy Markdown
Owner

Duplicate of #200

Hi,
As I mentioned in #295, I’m sorry, but I’m not planning to add image preview support to leaf.

@RivoLink RivoLink closed this Sep 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants