1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
# kitty-graphics.el -- developer task runner
#
# Requires: just, emacs, typst (for typst tests), imagemagick (for sixel).
# Run `just` to list recipes.
set shell := ["bash", "-cu"]
EMACS := env_var_or_default("EMACS", "emacs")
TERM_ := env_var_or_default("KGFX_TERM", "xterm-256color")
SRC := "kitty-graphics.el"
# Default: list recipes
default:
@just --list --unsorted
# --- Build / lint -----------------------------------------------------------
# Byte-compile (primary lint check)
compile:
rm -f {{SRC}}c
{{EMACS}} -Q -batch -f batch-byte-compile {{SRC}}
# Byte-compile, treat warnings as errors
lint:
rm -f {{SRC}}c
{{EMACS}} -Q -batch --eval '(setq byte-compile-error-on-warn t)' \
-f batch-byte-compile {{SRC}}
# Load-test: file evaluates without error
load:
{{EMACS}} -Q -batch -l {{SRC}} -f kill-emacs
# Remove generated artifacts
clean:
rm -f {{SRC}}c
rm -rf /tmp/kitty-gfx-typst /tmp/kitty-gfx-sixel-*.six /tmp/kitty-gfx.log
# --- Interactive tests (open terminal Emacs) --------------------------------
# Test typst inline equations (M-x kitty-gfx-typst-preview after open)
test-typst:
@echo ">> M-x kitty-gfx-typst-preview to render"
@echo ">> M-x kitty-gfx-typst-clear-preview to clear"
TERM={{TERM_}} {{EMACS}} -nw -Q -l {{SRC}} \
--eval "(kitty-graphics-mode 1)" \
--eval "(setq kitty-gfx-debug t)" \
tests/test-typst.typ
# Test org-mode inline images -- C-c C-x C-v after open
test-org:
TERM={{TERM_}} {{EMACS}} -nw -Q -l {{SRC}} \
--eval "(kitty-graphics-mode 1)" \
tests/test-kitty-gfx.org
# Test text sizing protocol (OSC 66) on org headings
test-headings:
TERM={{TERM_}} {{EMACS}} -nw -Q -l {{SRC}} \
--eval "(setq kitty-gfx-heading-sizes-auto t)" \
--eval "(kitty-graphics-mode 1)" \
tests/test-kitty-gfx.org
# Test image-mode rendering
test-image:
TERM={{TERM_}} {{EMACS}} -nw -Q -l {{SRC}} \
--eval "(kitty-graphics-mode 1)" \
tests/test-image.png
# Test doc-view / PDF rendering
test-pdf:
TERM={{TERM_}} {{EMACS}} -nw -Q -l {{SRC}} \
--eval "(kitty-graphics-mode 1)" \
tests/test-document.pdf
# Test markdown-overlays integration
test-markdown:
TERM={{TERM_}} {{EMACS}} -nw -Q -l {{SRC}} \
--eval "(kitty-graphics-mode 1)" \
tests/test-markdown.md
# Test LaTeX fragment preview in org-mode (C-c C-x C-l on a fragment)
test-latex:
TERM={{TERM_}} {{EMACS}} -nw -Q -l {{SRC}} \
--eval "(kitty-graphics-mode 1)" \
tests/test-kitty-gfx.org
# --- Headless typst checks --------------------------------------------------
# Compile a typst fragment headlessly, print the PNG path
typst-render fragment="$x^2 + y^2 = z^2$":
{{EMACS}} -Q -batch -L . -l {{SRC}} --eval '(progn \
(setq kitty-gfx-debug t) \
(let ((png (kitty-gfx--typst-render "{{fragment}}"))) \
(princ (format "png=%s exists=%s\n" png (and png (file-exists-p png))))))'
# Render fragment and open PNG with xdg-open
typst-show fragment="$integral_(-oo)^(+oo) e^(-x^2) dif x = sqrt(pi)$":
@png=$({{EMACS}} -Q -batch -L . -l {{SRC}} --eval '(princ (kitty-gfx--typst-render "{{fragment}}"))' 2>/dev/null); \
echo "png=$png"; \
[ -n "$png" ] && xdg-open "$png"
# --- Headless sixel checks --------------------------------------------------
# Show resolved sixel encoder (auto-detect: img2sixel > magick > convert)
sixel-encoder:
{{EMACS}} -Q -batch -L . -l {{SRC}} --eval '(princ (format "%S\n" (kitty-gfx--sixel-resolve-encoder)))'
# Encode tests/test-image.png to sixel headlessly, report payload size.
# Override encoder with: just sixel-encode "img2sixel"
sixel-encode encoder="":
{{EMACS}} -Q -batch -L . -l {{SRC}} --eval '(progn \
(setq kitty-gfx-debug t) \
(when (> (length "{{encoder}}") 0) \
(setq kitty-gfx-sixel-encoder-program "{{encoder}}")) \
(princ (format "encoder=%S\n" (kitty-gfx--sixel-resolve-encoder))) \
(let ((d (kitty-gfx--sixel-encode "tests/test-image.png" 20 10))) \
(princ (format "bytes=%s\n" (and d (length d))))))'
@echo "--- log tail ---"
@tail -3 /tmp/kitty-gfx.log 2>/dev/null || true
# Verify timeout watchdog kills a hung encoder within `kitty-gfx-sixel-encoder-timeout'
sixel-timeout-test:
@printf '#!/usr/bin/env bash\nsleep 60\n' > /tmp/kgfx-fake-encoder.sh
@chmod +x /tmp/kgfx-fake-encoder.sh
time {{EMACS}} -Q -batch -L . -l {{SRC}} --eval '(progn \
(setq kitty-gfx-debug t \
kitty-gfx-sixel-encoder-program "/tmp/kgfx-fake-encoder.sh" \
kitty-gfx-sixel-encoder-timeout 1.0) \
(with-temp-buffer \
(set-buffer-multibyte nil) \
(princ (format "ok=%S\n" (kitty-gfx--sixel-run-encoder \
"/tmp/kgfx-fake-encoder.sh" 1.0 \
(current-buffer) nil)))))'
@echo "--- log tail ---"
@tail -3 /tmp/kitty-gfx.log 2>/dev/null || true
@rm -f /tmp/kgfx-fake-encoder.sh
# --- Interactive sixel tests (run inside a sixel-capable terminal) ----------
# Open test-image.png with sixel backend forced (foot/Konsole/mintty/WezTerm)
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)" \
--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 with sixel backend forced.
# Outer terminal must be sixel-capable (foot, Konsole, mintty, mlterm, WezTerm).
# Requires tmux >= 3.4 built with --enable-sixel.
# When already inside tmux, runs emacs directly (no nesting).
test-sixel-tmux encoder="":
#!/usr/bin/env bash
set -eu
if [ -n "${TMUX:-}" ]; then
echo ">> Already inside tmux -- running emacs directly in this pane."
exec env 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
else
echo ">> Outer terminal must be sixel-capable; spawning fresh tmux session."
exec 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"
fi
# --- Logs -------------------------------------------------------------------
# Tail the kitty-gfx debug log (set kitty-gfx-debug to t to populate)
log:
tail -f /tmp/kitty-gfx.log
|
