#14 - tui: image rendering — chafa / block-art fallback renderer - charles/loom

charles commented

2026-04-11 13:01:19 +00:00

Owner

User story

As a user on a terminal without Kitty or sixel support (e.g. gnome-terminal, tmux without passthrough), I want loom-tui to still show recognisable image previews, so that gallery and model-browser screens remain useful.

Acceptance criteria

Chafa backend

ChafaRenderer struct implements ImageRenderer
Shells out to chafa --format=symbols --size=WxH --colors=256 (or truecolor when $COLORTERM is truecolor/24bit)
Output is captured as a text block and painted via a ratatui Paragraph / Text widget inside the rect
Gracefully reports ChafaNotFound if the chafa binary is absent from $PATH, so auto-detect can fall through to the pure-Unicode half-block path
protocol_name() returns "chafa"

Pure-Unicode fallback

HalfBlockRenderer struct also implements ImageRenderer and is always available
Uses U+2580 (▀) half-blocks with ANSI 24-bit foreground/background colours derived from downsampled RGB pixels via the image crate
protocol_name() returns "halfblock"

Tests

Unit test asserts half-block renderer produces deterministic output for a fixed 4×4 RGB fixture
Unit test asserts chafa branch returns ChafaNotFound when PATH is cleared

Out of scope

Kitty and sixel backends (separate tickets)
Selecting between backends at runtime (separate auto-detection ticket)

References

Spec §2.2 "Image Rendering Subsystem"

## User story As a user on a terminal without Kitty or sixel support (e.g. gnome-terminal, tmux without passthrough), I want loom-tui to still show recognisable image previews, so that gallery and model-browser screens remain useful. ## Acceptance criteria ### Chafa backend - [ ] `ChafaRenderer` struct implements `ImageRenderer` - [ ] Shells out to `chafa --format=symbols --size=WxH --colors=256` (or `truecolor` when `$COLORTERM` is `truecolor`/`24bit`) - [ ] Output is captured as a text block and painted via a ratatui `Paragraph` / `Text` widget inside the rect - [ ] Gracefully reports `ChafaNotFound` if the `chafa` binary is absent from `$PATH`, so auto-detect can fall through to the pure-Unicode half-block path - [ ] `protocol_name()` returns `"chafa"` ### Pure-Unicode fallback - [ ] `HalfBlockRenderer` struct also implements `ImageRenderer` and is always available - [ ] Uses U+2580 (▀) half-blocks with ANSI 24-bit foreground/background colours derived from downsampled RGB pixels via the `image` crate - [ ] `protocol_name()` returns `"halfblock"` ### Tests - [ ] Unit test asserts half-block renderer produces deterministic output for a fixed 4×4 RGB fixture - [ ] Unit test asserts chafa branch returns `ChafaNotFound` when `PATH` is cleared ## Out of scope - Kitty and sixel backends (separate tickets) - Selecting between backends at runtime (separate auto-detection ticket) ## References - Spec §2.2 "Image Rendering Subsystem"

charles added this to the loom-tui v0.1.0 milestone

2026-04-11 13:01:19 +00:00

charles added the

area:image

type:user-story

labels

2026-04-11 13:01:19 +00:00

charles referenced this issue

2026-04-11 13:07:50 +00:00

tui: tracking — loom-tui v0.1.0 roadmap & implementation order #47

charles referenced this issue

2026-04-11 15:22:44 +00:00