kitty-graphics/AGENTS.md, branch master

chore: bump version to 0.5.0 + write 0.5.0 changelog

2026-04-26T21:03:11Z

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.

fix(sixel): detect Windows Terminal and route GIFs through image pipeline

2026-04-26T21:01:59Z

Windows Terminal does not expose a stable `TERM' value, so the previous sixel-detect check missed it. Accept the `WT_SESSION', `WT_PROFILE_ID' and `WT_WINDOWID' environment markers it injects into every session. Also add `gif' to `kitty-gfx--image-file-p' so GIF files are routed through the image pipeline. Animation is still not supported -- only the first frame is rendered -- but that is better than dropping them on the floor. AGENTS.md: list Windows Terminal under supported sixel terminals and soften the GIF wording from "not supported" to "first frame only". Closes #6. Co-authored-by: Tim Felgentreff

docs(sixel): hard-state img2sixel as the recommended encoder + warn loudly when none is on PATH

2026-04-26T19:33:26Z

Users hit a silent-failure mode where `kitty-gfx--sixel-detect' returned true (terminal supports Sixel) but no encoder was on `PATH', so every `sixel-place' logged `no encoder found' and produced no image. The echo-area `message' from `sixel-encode' was easy to miss inside tmux, which made the issue look like a refresh / tmux passthrough bug. - README.org: Requirements section now explicitly lists a Sixel encoder as required and recommends `img2sixel' (libsixel) over ImageMagick, with the concrete numbers from PR #10's bench (~2.2x smaller payload, ~10x faster) and a note that this matters most inside tmux because every refresh re-emits the full DCS payload. Known-Limitations reworded: missing encoder = silent failure surfaced via the debug log. - AGENTS.md: Dependencies block reorganised the same way; adds a pointer to `just sixel-encoder' as the first step when diagnosing Sixel rendering bugs. - kitty-graphics.el: when the active backend is Sixel and `kitty-gfx--sixel-resolve-encoder' returns nil at mode-enable time, fire a `display-warning' (`*Warnings*' buffer + visible message) pointing at img2sixel/ImageMagick, so the failure is no longer buried in /tmp/kitty-gfx.log.

feat(tmux): unlock Sixel backend inside tmux >= 3.4

2026-04-26T19:14:50Z

Sixel detection used to hard-disable the moment `$TMUX' was set. That guard predates tmux 3.4 (released 2024-02-13), which ships native Sixel rendering, so we were rejecting a working configuration. Drop the hard guard, gate on a parsed `tmux -V' >= 3.4, and let users opt out via a new custom var. - `kitty-gfx-tmux-allow-sixel' (default t). Set to nil if your tmux build lacks `--enable-sixel' or if you want to avoid the upstream scroll artifact (tmux's cell buffer is not pixel-aware, so images may persist after scrolling). - `kitty-gfx--tmux-version' parses `tmux -V' once per session and caches the result in `kitty-gfx--tmux-version-cache' (with an `unset' sentinel so we can distinguish "not probed" from "no tmux"). - `kitty-gfx--tmux-sixel-supported-p' centralises the (in-tmux + opt-in + version >= 3.4) check. - `kitty-gfx--sixel-detect' now uses the helper instead of `(not in-tmux)'. Debug log gained `tmux-ver=' and `tmux-ok='. - AGENTS.md / README.org / CHANGELOG.org: limitation reworded from "no tmux support" to a partial entry that explains exactly what works and what the remaining caveats are (Kitty APC passthrough is still unimplemented; scroll artifacts are upstream). - justfile: new `test-sixel-tmux' recipe wraps `test-sixel-image' in `tmux new-session' for one-command interactive verification, and the sibling `test-sixel-image' recipe was switched from a fragile shell conditional to an elisp `when' so passing an encoder argument no longer breaks the parse. Refs #2.

feat(sixel): configurable encoder + per-invocation timeout

2026-04-26T18:54:34Z

Sixel encoding was hard-coded to ImageMagick (`magick'/`convert') with no timeout, so a malformed image or hung encoder could freeze Emacs and users could not switch to libsixel's faster `img2sixel'. - New customs: `kitty-gfx-sixel-encoder-program' (nil = auto-detect: prefer img2sixel, then magick, then convert), `-encoder-args' (extra args list), `-encoder-timeout' (float seconds, default 5.0, nil = no timeout). - New helper `kitty-gfx--sixel-resolve-encoder' returns (KIND . ABS-PATH) where KIND is `img2sixel' or `imagemagick' so the encode pipeline can build the right argv (`-w/-h ' vs `-geometry WxH sixel:-'). - New helper `kitty-gfx--sixel-run-encoder' runs the encoder via `make-process' with a separate stderr buffer and a `run-at-time' watchdog that kills the process on timeout; failures and timeouts are logged and surface as nil from `kitty-gfx--sixel-encode' rather than freezing Emacs. - Existing magick/convert path preserved and still chosen automatically when img2sixel is absent. - AGENTS.md: dependency note updated to mention img2sixel and the new customs. Inspired by and co-authored with @timfel's sixel-graphics.el fork (https://github.com/timfel/sixel-graphics.el), which introduced the configurable encoder + timeout pattern. Refs #4. Co-authored-by: Tim Felgentreff

feat: add typst inline equation preview

2026-04-26T18:36:04Z

Mirrors the existing LaTeX fragment integration but uses the `typst` CLI to compile `$...$' math fragments into PNGs that are then displayed inline through the existing kitty-graphics overlay pipeline. - New section in kitty-graphics.el: customs (typst-command, ppi, text-size, preamble), SHA-1 cached PNGs under /tmp/kitty-gfx-typst, Emacs face-foreground -> typst rgb() hex conversion. - Two autoloaded commands: `kitty-gfx-typst-preview' and `kitty-gfx-typst-clear-preview', region-aware. - Regex skips backslash-escaped dollars (\\$not math\\$). - justfile with recipes: compile/lint/load + per-feature test-* and headless typst-render / typst-show. - tests/test-typst.typ fixture with inline, display, mixed and edge-case fragments. - AGENTS.md updated: test instructions, dependency note, issue marked done. Closes #7. Parent #5.

docs: update AGENTS.md for Sixel backend architecture

2026-03-20T15:41:38Z

- Document backend dispatch system (alist-based, detect-protocol) - Update architecture section with Kitty vs Sixel pipeline - Add Sixel-compatible terminals to testing/dependencies - Note Sixel limitations (256 colors, stateless) - Track org-mode misplacement bug as WIP - Bump documented version to 0.3.0