Skip to content

Report terminal pixel size so Kitty/icat pixel probes succeed#138

Merged
phall1 merged 1 commit into
mainfrom
fix/terminal-pixel-size-reporting
Jun 17, 2026
Merged

Report terminal pixel size so Kitty/icat pixel probes succeed#138
phall1 merged 1 commit into
mainfrom
fix/terminal-pixel-size-reporting

Conversation

@phall1

@phall1 phall1 commented Jun 17, 2026

Copy link
Copy Markdown
Owner

Problem

kitty +kitten icat aborts before sending any image with:

Terminal does not support reporting screen sizes in pixels, use a terminal such as kitty, WezTerm, Konsole, etc.

icat preflights the terminal for PIXEL dimensions. A phux pane reported 0x0: the PTY winsize ws_xpixel/ws_ypixel and the XTWINOPS CSI 14 t reply both derived their pixels from a per-cell size that stayed (0, 0) until a client announced a viewport with usable pixel metrics. Most clients report cells but not pixels, so the geometry stayed zero and the probe failed.

Fix (pixel-size REPORTING only)

Seed a fallback per-cell pixel size DEFAULT_CELL_PX = 8x16 so the derived pixel geometry is never zero. Cells (cols/rows) remain authoritative; pixels are always cells x cell size. A real client's reported cell size still wins and stays sticky across pixel-less resizes (e.g. an agent TERMINAL_RESIZE).

Applied at the three reporting sites in phux-server:

  • spawn-time openpty winsize — a child that reads TIOCGWINSZ before any client resize (icat preflighting at shell startup) now sees nonzero pixels.
  • initial size_report shared with libghostty's on_size callback — CSI 14 t answers nonzero even before the first resize.
  • handle_resize — already derives the winsize ioctl and size reports from the sticky cell size, now nonzero.

The in-band CSI 14 t / CSI 16 t / CSI 18 t path is already wired through libghostty's on_size callback (exercised by xtwinops_size_queries_answered_from_resized_geometry); it simply needed a nonzero cell size to report, which this change guarantees.

Server-local; no wire change — no spec update or version bump required.

Scope

This is the pixel-size REPORTING fix only. Full Kitty graphics RENDERING is a separate deferred item with its own ADR and is not attempted here.

Tests

  • New winsize_pixels_default_when_no_client_reports_metrics: with no client ever reporting pixel metrics, asserts spawn-time winsize is 80x24 cells -> 640x384 px and a pixel-less resize tracks 100x40 -> 800x640 px.
  • Existing resize_with_cell_px_updates_pty_winsize_pixels and xtwinops_size_queries_answered_from_resized_geometry continue to pass (client-reported cell size still wins).

just ci green locally.

🤖 Generated with Claude Code

A pane's PTY winsize and XTWINOPS size reports carried 0x0 pixel
dimensions until a client announced a viewport with usable pixel
metrics. Most clients report cells but not pixels, so the geometry
stayed zero and pixel-aware programs refused to run: `kitten icat`
preflights with "Terminal does not support reporting screen sizes in
pixels" and aborts before sending any image.

Seed a fallback per-cell pixel size (DEFAULT_CELL_PX = 8x16) so the
derived pixel geometry is never zero. Cells (cols/rows) stay
authoritative; pixels are always cells x cell size. A real client's
reported cell size still wins and remains sticky across pixel-less
resizes. Applied at three reporting sites:

- spawn-time openpty winsize (a child reading TIOCGWINSZ before any
  resize now sees nonzero pixels),
- the initial size_report cell shared with libghostty's on_size
  callback (so CSI 14 t answers nonzero before the first resize),
- handle_resize, which already derives winsize and size reports from
  the now-nonzero sticky cell size.

This is the pixel-size REPORTING fix only; full Kitty graphics
rendering is a separate deferred item. No wire change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@phall1 phall1 merged commit c4fd1ab into main Jun 17, 2026
3 checks passed
@phall1 phall1 deleted the fix/terminal-pixel-size-reporting branch June 17, 2026 20:20
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.

1 participant