Markdown documents reference images, and tread currently shows the alt text
and nothing else. In a docs corpus with diagrams that is exactly where the
reader gives up and you go open the file somewhere else.
The cheap part
The two widely-supported inline-image protocols accept encoded image data and
decode it themselves:
- kitty graphics protocol — takes PNG directly (
f=100). kitty, Ghostty,
WezTerm, recent Konsole.
- iTerm2 —
OSC 1337 File=, takes PNG/JPEG/GIF. iTerm2, WezTerm.
So tread can read the file, base64 it (already hand-written for OSC 52) and
hand the bytes over. No image decoder, and therefore no dependencies — the
terminal does the work.
The expensive part, deliberately out of scope for a first pass
- Sixel (xterm, foot, Windows Terminal) needs us to decode and quantise
ourselves — a PNG decoder, which means writing inflate first.
- A block-character fallback (what
chafa does) needs the same decoder.
Terminals without kitty/iTerm2 support keep showing alt text. That is an honest
degradation; a wrong-looking picture would be worse than none.
The actual work
Not the protocol — the pager. Images have to be placed, cleared and re-placed as
the viewport scrolls, and tread repaints whole frames. kitty addresses this
with placement ids that can be deleted and re-issued; it is tractable, but it is
where the time goes.
Also to settle:
- Detecting support.
TERM/TERM_PROGRAM sniffing is unreliable; querying the
terminal and waiting for a reply is correct but needs a timeout.
- Reserving rows in the layout for the image and letting the terminal scale into
that box, so no image dimensions have to be parsed.
--plain, piped output and the non-interactive dump path must never emit
image escapes.- Only local relative paths.
tread does not fetch over the network and should
not start here.
Acceptance
Markdown documents reference images, and
treadcurrently shows the alt textand nothing else. In a docs corpus with diagrams that is exactly where the
reader gives up and you go open the file somewhere else.
The cheap part
The two widely-supported inline-image protocols accept encoded image data and
decode it themselves:
f=100). kitty, Ghostty,WezTerm, recent Konsole.
OSC 1337 File=, takes PNG/JPEG/GIF. iTerm2, WezTerm.So
treadcan read the file, base64 it (already hand-written for OSC 52) andhand the bytes over. No image decoder, and therefore no dependencies — the
terminal does the work.
The expensive part, deliberately out of scope for a first pass
ourselves — a PNG decoder, which means writing inflate first.
chafadoes) needs the same decoder.Terminals without kitty/iTerm2 support keep showing alt text. That is an honest
degradation; a wrong-looking picture would be worse than none.
The actual work
Not the protocol — the pager. Images have to be placed, cleared and re-placed as
the viewport scrolls, and
treadrepaints whole frames. kitty addresses thiswith placement ids that can be deleted and re-issued; it is tractable, but it is
where the time goes.
Also to settle:
TERM/TERM_PROGRAMsniffing is unreliable; querying theterminal and waiting for a reply is correct but needs a timeout.
that box, so no image dimensions have to be parsed.
--plain, piped output and the non-interactive dump path must never emitimage escapes.
treaddoes not fetch over the network and shouldnot start here.
Acceptance