From 8b2870de46b331f55c83ca6916943b1e0fe522e4 Mon Sep 17 00:00:00 2001 From: cashmere Date: Sun, 26 Apr 2026 23:03:11 +0200 Subject: chore: bump version to 0.5.0 + write 0.5.0 changelog Bumps `;; Version:' header from 0.4.0 to 0.5.0 and AGENTS.md `Current version' to match (it was still 0.3.0; missed at the 0.4.0 bump). Per AGENTS.md versioning rules, minor (0.x.0) is the right step for new features, and 0.5.0 collects: - Typst inline equation preview (#5) - Configurable Sixel encoder + per-invocation timeout (refs #4) - Sixel inside tmux >= 3.4 (refs #2) - Windows Terminal detection + GIF routing (closes #6) - Inline mpv video playback on the Kitty backend - Loud warning when the Sixel backend cannot find an encoder on PATH Plus assorted fixes (ECH erase + pre-erase, heading folded-line skip, Sixel parity, text sizing column guard / CPU / preview-mode), the new `justfile' task runner, and documentation that hard-states img2sixel as the recommended Sixel encoder. CHANGELOG.org gets a new top-level section with the full feature write-ups, bench numbers for the encoder swap, credits to @timfel (encoder timeout pattern + Windows Terminal patch + ongoing Sixel collaboration), and a reworded "what comes next" paragraph that reflects the Sixel-in-tmux side as done while leaving Kitty APC passthrough on the roadmap. --- AGENTS.md | 4 +- CHANGELOG.org | 144 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- kitty-graphics.el | 2 +- 3 files changed, 142 insertions(+), 8 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 91c3644..647f61b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,8 +8,8 @@ Sixel, with automatic protocol detection. Also renders org-mode headings at scaled font sizes using the Kitty text sizing protocol (OSC 66). Integrates with org-mode, image-mode, shr/eww/mu4e/gnus, dired, and dirvish. -Language: **Emacs Lisp** (`lexical-binding: t`). Single source file (~1876 lines). -Current version: **0.3.0** (see Versioning section). +Language: **Emacs Lisp** (`lexical-binding: t`). Single source file (~3300 lines). +Current version: **0.5.0** (see Versioning section). ## Build / Validate diff --git a/CHANGELOG.org b/CHANGELOG.org index 82e8c5b..0437da9 100644 --- a/CHANGELOG.org +++ b/CHANGELOG.org @@ -1,5 +1,136 @@ * Changelog +** kitty-graphics 0.5.0 + +A feature-heavy follow-up to =0.4.0=: typst inline equations, a much +more robust Sixel encoder pipeline, Sixel inside tmux, and inline mpv +video playback. =0.4.0= already shipped the Sixel backend and the +text-sizing protocol; =0.5.0= builds on that foundation. + +*** Features + +**** Typst inline equation preview + +New autoloaded commands =kitty-gfx-typst-preview= and +=kitty-gfx-typst-clear-preview= scan the current buffer (or active +region) for ~$...$~ math fragments, compile each one via the =typst= +CLI, and replace it with a rendered PNG using the existing +kitty-graphics overlay pipeline. Works on both the Kitty and Sixel +backends. Customs: =kitty-gfx-typst-command=, =kitty-gfx-typst-ppi=, +=kitty-gfx-typst-text-size=, =kitty-gfx-typst-preamble=. Default +preamble auto-converts the current Emacs foreground colour to the hex +form typst's =rgb()= requires. Cached PNGs land under +=/tmp/kitty-gfx-typst/= keyed by SHA-1 of the source. Closes #5. + +**** Configurable Sixel encoder + per-invocation timeout + +The Sixel encoder pipeline used to be hard-wired to ImageMagick with +no timeout, so a malformed image or a hung encoder could freeze +Emacs. Three new customs and two helpers fix that: + +- =kitty-gfx-sixel-encoder-program= (nil = auto-detect). Auto-detect + order: =img2sixel= (libsixel) > =magick= (ImageMagick 7) > =convert= + (ImageMagick 6, deprecated). Set to a string to pin a specific + binary. +- =kitty-gfx-sixel-encoder-args= -- extra arguments slotted before + the per-invocation size flags. +- =kitty-gfx-sixel-encoder-timeout= -- float seconds, default =5.0=, + =nil= for no timeout. + +Internally =kitty-gfx--sixel-resolve-encoder= returns a +=(KIND . PATH)= cons so the encode pipeline can build the right +argv (=-w/-h = for img2sixel, =-geometry WxH sixel:-= for +ImageMagick), and =kitty-gfx--sixel-run-encoder= drives the child via +=make-process= with a separate stderr buffer and a =run-at-time= +watchdog that kills the process on timeout. Failures and timeouts +surface as a logged =nil= instead of a frozen Emacs. + +#+begin_QUOTE +*Bench*: =tests/test-image.png= encoded at 20×10 cells (160×160 px) on +my workstation -- =img2sixel= produced =2631=-byte payloads in +~5 ms, =magick= produced =5831=-byte payloads in ~58 ms. About =2.2x= +smaller payload and =~10x= faster. This matters most inside tmux, +where every refresh re-emits the full DCS payload. +#+end_QUOTE + +Pattern adapted from [[https://github.com/timfel/sixel-graphics.el][@timfel's =sixel-graphics.el= fork]]; co-authored +on the commit. Refs #4. + +**** Sixel inside tmux >= 3.4 + +The Sixel detector used to hard-disable the moment =$TMUX= was set -- +that comment in the code predated tmux =3.4= (released =2024-02-13=), +which ships native Sixel rendering. Drop the hard guard, gate on a +parsed =tmux -V=, and let users opt out via +=kitty-gfx-tmux-allow-sixel= (default =t=). New helpers +=kitty-gfx--tmux-version= (cached) and +=kitty-gfx--tmux-sixel-supported-p= centralise the in-tmux + opt-in + +version-check logic. The =sixel-detect= debug log gained =tmux-ver== +and =tmux-ok== fields. + +Caveat: tmux's cell buffer is not pixel-aware, so images may stick to +their old position after scrolling until the affected cells are +overwritten. That's an upstream tmux limitation, not something this +package can fix. The Kitty graphics protocol still does not work +inside tmux because we do not yet wrap APC sequences with the +=\ePtmux;...\e\\= passthrough envelope -- separate piece of work. +Refs #2. + +**** Inline mpv video playback (Kitty backend) + +The Kitty backend grew video support via mpv IPC. New commands: +=kitty-gfx-play-video=, =kitty-gfx-stop-video=, +=kitty-gfx-toggle-video=, =kitty-gfx-seek-video=. Limited to the +Kitty backend (Sixel re-emit cost makes video impractical there). + +**** Loud warning on missing Sixel encoder + +When the Sixel backend is selected but no encoder is on =PATH=, the +mode-enable now fires a =display-warning= pointing at +img2sixel/ImageMagick instead of silently dropping every image. + +**** Windows Terminal detection + GIF routing + +Windows Terminal does not advertise a stable =TERM= value, so the old +detector missed it. Accept the =WT_SESSION=, =WT_PROFILE_ID= and +=WT_WINDOWID= environment markers it injects and the Sixel backend +engages correctly. =gif= is also now routed through the image +pipeline (still first-frame only -- no animation support in the +terminal -- but no longer silently dropped). Closes #6. + +Thanks again to [[https://github.com/timfel][Tim Felgentreff]] for the patch and the Windows-side +testing. + +*** Fixes + +- ECH-erase + pre-erase pattern for cleaner column clearing. Credit + to [[https://github.com/mdfried][mdfried]] for the approach. +- Skip heading rendering when folded to the same visual line. +- Sixel backend parity with the Kitty backend across the refresh + cycle. +- Text sizing rendering: column guard, CPU optimisation, preview-mode + behaviour. + +*** Tooling + +- New top-level =justfile= task runner with byte-compile, load, and + per-feature interactive recipes (=test-org=, =test-typst=, + =test-image=, =test-sixel-image=, =test-sixel-tmux=, ...) plus + headless probes (=sixel-encoder=, =sixel-encode [ENCODER]=, + =sixel-timeout-test=, =typst-render=). + +*** Documentation + +- =README.org= and =AGENTS.md= now hard-state img2sixel as the + recommended Sixel encoder, with the bench numbers above and a + pointer to =just sixel-encoder= as the first step when diagnosing + Sixel rendering bugs. + +*** Credits + +Thanks to [[https://github.com/timfel][Tim Felgentreff]] for the encoder + timeout pattern and the +ongoing collaboration on the Sixel side via his fork. + ** kitty-graphics 0.4.0 - HUGE updates *** Features @@ -51,11 +182,14 @@ I will keep on improving this feature. I think it is actually great eyecandy, an **** tmux support -The Sixel side is now unlocked: starting in =0.5.0=, =kitty-graphics= no longer hard-disables the Sixel backend when =$TMUX= is set. tmux 3.4 (released 2024-02-13) ships native Sixel rendering, so running Emacs inside =tmux new-session= under foot/Konsole/mintty/mlterm/WezTerm just works. The detector probes =tmux -V= once per session and only engages on tmux >= 3.4. A new option =kitty-gfx-tmux-allow-sixel= (default =t=) lets you opt out if your tmux build lacks =--enable-sixel=. - -Caveat: tmux's cell buffer is not pixel-aware, so images may stick to their old position after scrolling until the affected cells are overwritten. That is an upstream tmux limitation, not something this package can fix. - -The Kitty graphics protocol still does not work inside tmux because we do not yet wrap APC sequences with the =\ePtmux;...\e\\= passthrough envelope. There is also an in-progress branch adding [[https://github.com/tmux/tmux/tree/ta/kitty-img][native Kitty image protocol support to tmux]]. Until either lands, if you already use Kitty directly I would stick with it -- the Kitty protocol gives you stateful image management, truecolor rendering, and a smoother overall experience. +tmux support is in progress. The Sixel side is unlocked in =0.5.0= -- +see the entry above. Native Kitty graphics passthrough inside tmux is +still pending: we do not yet wrap APC sequences with the +=\ePtmux;...\e\\= envelope, and there's also an in-progress branch +adding [[https://github.com/tmux/tmux/tree/ta/kitty-img][native Kitty image protocol support to tmux]]. Until either +lands, if you already use Kitty directly I would stick with it -- +the Kitty protocol gives you stateful image management, truecolor +rendering, and a smoother overall experience. **** Package renaming? diff --git a/kitty-graphics.el b/kitty-graphics.el index 430818a..d1514df 100644 --- a/kitty-graphics.el +++ b/kitty-graphics.el @@ -3,7 +3,7 @@ ;; Copyright (C) 2025-2026 ;; ;; Author: cashmere -;; Version: 0.4.0 +;; Version: 0.5.0 ;; URL: https://github.com/cashmeredev/kitty-graphics.el ;; Keywords: terminals, images, multimedia ;; Package-Requires: ((emacs "27.1")) -- cgit v1.3.1