Skip to content

fix: render Kitty graphics reliably inside tmux (issue #84) - #124

Closed
yaroslavsavateykin wants to merge 1 commit into
freref:masterfrom
yaroslavsavateykin:fix/tmux-kitty-graphics-84
Closed

yaroslavsavateykin wants to merge 1 commit into
freref:masterfrom
yaroslavsavateykin:fix/tmux-kitty-graphics-84

Conversation

@yaroslavsavateykin

Copy link
Copy Markdown

Summary

Fixes #84 for a single tmux layer with a terminal supporting Kitty Unicode placeholders. This is a real graphics transport/placement implementation, not a bypass of NoGraphicsCapability.

Related: #107 and rockorager/libvaxis#260. I saw the existing experimental branch and the reports of blank Kitty output / residual images; this implementation uses tmux-owned placeholder cells rather than terminal-owned direct placements.

Graphics path

  • Require an OK response to a valid 1x1 RGB capability query through the same tmux DCS route used by image data.
  • Wrap each <=4096-byte base64 chunk independently in DCS passthrough, doubling inner ESC bytes.
  • Parse protocol replies with image IDs and success/error status; acknowledge and retry image transmissions and virtual placements when tmux drops passthrough around redraws.
  • Render Unicode placeholders as ordinary vaxis/tmux text cells, not passthrough. Indexed foreground plus a high-byte diacritic avoids image-ID corruption from tmux truecolour conversion; underline colour binds placement ID 1.
  • Use tmux client cell geometry if TIOCGWINSZ lacks pixel dimensions.
  • Defer graphics updates while the pane is inactive (tmux routes terminal replies to the active pane); retransmit on focus return. Transient delivery failures do not exit the viewer.
  • Invalidate rasterisation on resize / PDF filewatch. Coalesce resize events after 150ms of quiet, retaining the previous grid during a drag. Delete the old image only after the new grid has been flushed.
  • Refresh the tmux client after a successful draw to accommodate older Ghostty's in-place placeholder rendering behaviour.

Technical reference: gominimal/kittyview, particularly its DCS transport, MuxSafe image-ID encoding, Unicode placeholder table and client repaint strategy.

libvaxis dependency / review point

This PR vendors the same pinned libvaxis commit previously referenced by build.zig.zon, with its MIT license. The large diff is mostly unchanged dependency source, not newly written backend code. deps/vaxis/UPSTREAM.md lists the five files changed: valid query, ID/status response parsing, response event, atomic ACK slot and input-loop forwarding.

I am happy to replace vendoring with a URL/hash dependency once equivalent response hooks are available upstream. This is an explicit integration decision for maintainers, not a proposed permanent fork of the library.

Validation

  • Zig 0.15.2: zig build --release=small — successful.
  • zig build test — 3 tests passed (DCS escaping, complete MuxSafe ID-space uniqueness, positive/negative protocol reply parsing).
  • zig fmt --check on changed Zig files and git diff --check — passed.
  • Real Ghostty 1.3.0-dev + tmux 3.6 in an isolated Xvfb display: PDF first/next pages, window switching, horizontal split, pane resizing, rapid resize bursts, replacement PDF while hidden and returning to the window. Screenshots and red/blue/green pixel counts checked.
  • Direct non-tmux rendering still works; disabled allow-passthrough produces a capability failure instead of pretending graphics are available.
  • Locally installed and used interactively; resize lag/flicker prompted the debounce and deferred deletion follow-up.

Requirements and current limits

set -g allow-passthrough on
  • The outer terminal must implement Kitty Unicode placeholders, not only basic APC transmission.
  • Start in an active, attached pane; inactive-pane updates wait for focus.
  • Single local tmux layer only; nested tmux/screen and multiple simultaneous clients with independent image stores are not covered.
  • Placeholder dimensions are limited to the protocol table's 297 cells.
  • Blocking ACK waits remain bounded; the visibility ticker checks tmux every 250ms. Further asynchronous integration/performance tuning is possible.
  • Physical Kitty, WezTerm and macOS have not been tested here. In particular, the original issue's Kitty/macOS combination still needs validation before assuming this resolves every reported environment.

Details are in docs/tmux.md. Local screenshots/build artifacts and installed binaries are deliberately excluded from this PR.

@yaroslavsavateykin

Copy link
Copy Markdown
Author

Follow-up in 3d4554f: repeated recompilation can unlink/recreate the PDF and stop the inode-based file watcher. The tmux ticker now also polls inode/size/mtime by path and reloads after stable metadata, retaining the previous page during temporary absence. Watcher errors no longer terminate the tmux viewer, and status-path realpath tolerates FileNotFound. Verified three consecutive unlink/recreate cycles (600ms missing output each), with red/blue/green page content visibly updated on every cycle. ReleaseSmall build and 3/3 graphics tests pass.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Tmux - error: NoGraphicsCapability

1 participant