From b4e12512a0db4ce8823e2265faf020bb222875a7 Mon Sep 17 00:00:00 2001
From: cashmere <cashmere@autistici.org>
Date: Sun, 26 Apr 2026 21:14:50 +0200
Subject: feat(tmux): unlock Sixel backend inside tmux >= 3.4

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.
---
 justfile | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

(limited to 'justfile')

diff --git a/justfile b/justfile
index 22fe756..008f4ad 100644
--- a/justfile
+++ b/justfile
@@ -141,10 +141,20 @@ test-sixel-image encoder="":
     @echo ">> Run inside foot, Konsole, mintty, mlterm, or WezTerm."
     TERM={{TERM_}} {{EMACS}} -nw -Q -l {{SRC}} \
         --eval "(setq kitty-gfx-debug t kitty-gfx-preferred-protocol 'sixel)" \
-        $(if [ -n "{{encoder}}" ]; then echo "--eval (setq\\ kitty-gfx-sixel-encoder-program\\ \"{{encoder}}\")"; fi) \
+        --eval '(when (> (length "{{encoder}}") 0) (setq kitty-gfx-sixel-encoder-program "{{encoder}}"))' \
         --eval "(kitty-graphics-mode 1)" \
         tests/test-image.png
 
+# Open test-image.png inside `tmux new-session', sixel backend forced
+# (run on a sixel-capable outer terminal, requires tmux >= 3.4)
+test-sixel-tmux encoder="":
+    @echo ">> Outer terminal must be sixel-capable (foot, Konsole, mintty, ...)."
+    @echo ">> tmux >= 3.4 with --enable-sixel required."
+    tmux new-session -As kgfx-sixel-test "TERM={{TERM_}} {{EMACS}} -nw -Q -l {{SRC}} \
+        --eval '(setq kitty-gfx-debug t kitty-gfx-preferred-protocol (quote sixel))' \
+        --eval '(when (> (length \"{{encoder}}\") 0) (setq kitty-gfx-sixel-encoder-program \"{{encoder}}\"))' \
+        --eval '(kitty-graphics-mode 1)' tests/test-image.png"
+
 # --- Logs -------------------------------------------------------------------
 
 # Tail the kitty-gfx debug log (set kitty-gfx-debug to t to populate)
-- 
cgit v1.3.1