#15 - tui: image rendering — protocol auto-detection at startup - charles/loom

charles commented

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

Owner

User story

As a user launching loom-tui in any terminal, I want the best available image protocol chosen automatically, so that I never have to configure rendering manually.

Acceptance criteria

Detection order

Order: Kitty → sixel → chafa → halfblock
Kitty detection: $TERM == xterm-kitty, $TERM_PROGRAM == kitty, or a successful APC query (\x1b_Gi=31,s=1,v=1,a=q,t=d,f=24;AAAA\x1b\\) within a 200 ms timeout
Sixel detection: send \x1b[c (DA1), parse response, require attribute 4 to be present, 200 ms timeout
Chafa detection: which chafa succeeds
Halfblock always available as the terminal fallback

API

loom_tui::image::detect_renderer() -> Box<dyn ImageRenderer> implements the ordered probe
Respects [tui] image_protocol config override (auto, kitty, sixel, chafa, halfblock, none); none disables image rendering entirely, returning a no-op renderer
On startup the chosen protocol name is logged at info and displayed in the Settings → Appearance section

Tests

Unit tests mock a fake terminal with each capability combination and assert the correct renderer is selected
Unit test asserts explicit config override wins over auto-detection

Out of scope

Implementing any individual renderer (separate tickets)
tui.toml config file loading (separate ticket — consumes this API)

References

Spec §2.2 (1) "Auto-detect the best available protocol"
Spec §7.1 image_protocol config key

## User story As a user launching loom-tui in any terminal, I want the best available image protocol chosen automatically, so that I never have to configure rendering manually. ## Acceptance criteria ### Detection order - [ ] Order: **Kitty → sixel → chafa → halfblock** - [ ] Kitty detection: `$TERM == xterm-kitty`, `$TERM_PROGRAM == kitty`, or a successful APC query (`\x1b_Gi=31,s=1,v=1,a=q,t=d,f=24;AAAA\x1b\\`) within a 200 ms timeout - [ ] Sixel detection: send `\x1b[c` (DA1), parse response, require attribute `4` to be present, 200 ms timeout - [ ] Chafa detection: `which chafa` succeeds - [ ] Halfblock always available as the terminal fallback ### API - [ ] `loom_tui::image::detect_renderer() -> Box<dyn ImageRenderer>` implements the ordered probe - [ ] Respects `[tui] image_protocol` config override (`auto`, `kitty`, `sixel`, `chafa`, `halfblock`, `none`); `none` disables image rendering entirely, returning a no-op renderer - [ ] On startup the chosen protocol name is logged at `info` and displayed in the Settings → Appearance section ### Tests - [ ] Unit tests mock a fake terminal with each capability combination and assert the correct renderer is selected - [ ] Unit test asserts explicit config override wins over auto-detection ## Out of scope - Implementing any individual renderer (separate tickets) - `tui.toml` config file loading (separate ticket — consumes this API) ## References - Spec §2.2 (1) "Auto-detect the best available protocol" - Spec §7.1 `image_protocol` config key

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

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

charles added the

area:image

type:user-story

labels

2026-04-11 13:01:31 +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