diff options
| author | Gabriel Schneider <[email protected]> | 2026-10-28 21:03:48 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-10-28 21:23:53 -0300 |
| commit | b250eb6135475699a945324c005890e8e1b4dd0b (patch) | |
| tree | c32f06f89cdbd501ba5d75dc8ba80ecebbe3c278 /src | |
| parent | a48a825b06cc45947adaecf42073ed86af8b7a2d (diff) | |
| download | pardes-b250eb6135475699a945324c005890e8e1b4dd0b.tar.gz pardes-b250eb6135475699a945324c005890e8e1b4dd0b.zip | |
kitty graphics conformance for terminal panes: a core suite (test/kitty.zig, `zig build kitty-test`, in unit-test) and an end-to-end harness (`zig build kitty-harness`, tty and gui); four gaps it found fixed, one left
The core suite feeds a pane's output as pty reads do and checks what the program reads back, ghostty's image storage and the ImagePlaces a frame draws: queries and their errors, q=0/1/2, f=24/32/100 and o=z, chunked m=1 split at every read size, t=f/t=t/t=s, a=T and C=1 cursor movement, a=p by placement id with source rects and re-puts, image numbers, every d= delete (a/A i/I n/N c/C p/P q/Q x/X y/Y z/Z r/R) and a delete abandoning a chunked load, Unicode placeholders over two rows with implicit columns and a placement named in the underline colour, scroll/resize/reflow, the alternate screen, clear (ED 2 + ED 3), replies per pane and never in the cells, many replies from one read, kitty before DA, CAN/SUB, an oversized image, 300 images against the storage limit, animations and relative placements.
The harness runs test/kitty_client.zig in a pane's bash (query, a 16-chunk 8x4-cell place, the three media, quiet levels, CAN, show then delete) and kitten icat (stream and detect) and chafa when installed. Outside, the tty arm is a kitty terminal (a ghostty-vt emulator): the image pardes re-emits lands at the cell after ANCHOR>, 8x4 cells a row at a time, the client's own commands and replies never pass through, and d=I frees what was sent. The gui arm reads the GPU capture.
Fixed: kitty file, temporary-file and shared-memory media (libghostty defaults to direct only; now allWithTempDir like ghostty and kitty); replies past 256 bytes of one read were cut mid-sequence (4 KiB now, an answer that does not fit dropped whole and counted); animations never played (TerminalImages draws renderData(), ticks ImageStorage.animationTick on the core clock, nextWake wakes for the next frame); relative placements (P=/Q=/H=/V=) were not drawn (resolveChain, as ghostty's renderer). image.decode no longer jumps through stb_image's null allocator before image.start.
Known gap (a knownGap test): no z-index; every image is drawn over the cells in storage order.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Diffstat (limited to 'src')
| -rw-r--r-- | src/CHANGELOG.md | 10 | ||||
| -rw-r--r-- | src/TerminalImages.zig | 35 | ||||
| -rw-r--r-- | src/image.zig | 3 | ||||
| -rw-r--r-- | src/pardes.zig | 10 | ||||
| -rw-r--r-- | src/terminal.zig | 45 |
5 files changed, 92 insertions, 11 deletions
diff --git a/src/CHANGELOG.md b/src/CHANGELOG.md index 2144f710..7aab597d 100644 --- a/src/CHANGELOG.md +++ b/src/CHANGELOG.md @@ -2,6 +2,16 @@ ## Unreleased +- Kitty graphics in a terminal pane take every medium kitty and ghostty + do: a file (`t=f`), a temporary file (`t=t`) and shared memory (`t=s`) + beside direct data, so `kitten icat` no longer falls back to base64 + through the pty. A program asking about many images in one write + hears every answer, where answers past 256 bytes of one read were cut + off mid-sequence (now 4 KiB, and an answer that does not fit is dropped + whole). Animations (`a=f`, `a=a`) play, frame by frame, where only the + first frame was drawn; and an image placed relative to another + (`P=`, `Q=`, `H=`, `V=`) is drawn beside it. `zig build kitty-test` and + `zig build kitty-harness` check the protocol through a terminal pane. - ghostty moves to its 1.4.0 release (from a main commit six days before it; libvaxis and uucode stay on the commits it pins). A terminal's `clear` (ED 3) now takes away the kitty images placed on the history it diff --git a/src/TerminalImages.zig b/src/TerminalImages.zig index 4140813f..f3333460 100644 --- a/src/TerminalImages.zig +++ b/src/TerminalImages.zig @@ -29,6 +29,9 @@ petscii: bool = false, converted: std.AutoHashMapUnmanaged(u32, Converted) = .empty, /// Glyph art for the fragments drawn as cells, kept while on screen. glyphs: std.AutoHashMapUnmanaged(GlyphKey, Glyphs) = .empty, +/// When the next frame of a playing animation (a=a) is due, in ms on the +/// core's clock (`Pardes.stepped_ns`): the core wakes for it (nextWake). +animation_due_ms: ?u64 = null, const Converted = struct { generation: u64, rgba: []u8, used: bool = true }; const Glyphs = struct { cells: []GlyphArt.Cell, used: bool = true }; @@ -147,6 +150,11 @@ pub fn draw( const screen = vt.screens.active; const storage = &screen.kitty_images; + // Animations step on the core's clock, as this frame shows them; the + // shown frame is `renderData()` (a new `generation` each step, which + // the caches key on). + const now_ms = p.stepped_ns / std.time.ns_per_ms; + ti.animation_due_ms = if (storage.animationTick(vt.io(), now_ms)) |delay| now_ms +| delay else null; const pages = &screen.pages; const top = pages.getTopLeft(.viewport); const bottom = pages.getBottomRight(.viewport) orelse return; @@ -187,10 +195,25 @@ pub fn draw( var it = storage.placements.iterator(); while (it.next()) |entry| { const placed = entry.value_ptr.*; + // A placement relative to another (P=/Q=) sits at its chain's root + // plus the chain's cell offsets (H=/V=), as ghostty's renderer puts it. + var dx: i64 = 0; + var dy: i64 = 0; const pin = switch (placed.location) { .pin => |pin| pin, - // ponytail: a placement relative to another (P=/Q=, new in ghostty) is not drawn; resolve its chain if a program needs it. - .virtual, .relative => continue, + .virtual => continue, + .relative => |rel| root: { + const chain = storage.resolveChain(rel) orelse continue; + dx = chain.horizontal_offset; + dy = chain.vertical_offset; + break :root switch (chain.root.location) { + .pin => |pin| pin, + // ponytail: a chain rooted on a virtual placement (shown + // through placeholders) is not drawn; ghostty anchors it at + // the placeholder run. + .virtual, .relative => continue, + }; + }, }; const img = storage.images.get(entry.key_ptr.image_id) orelse continue; const at = pages.pointFromPin(.screen, pin.*) orelse continue; @@ -201,8 +224,8 @@ pub fn draw( const sh = if (placed.source_height > 0) @min(placed.source_height, img.height - sy) else img.height - sy; if (size.width == 0 or size.height == 0 or sw == 0 or sh == 0) continue; ctx.place(img, .{ .x = sx, .y = sy, .w = sw, .h = sh }, .{ - .x = @as(i64, at.screen.x) * cw + placed.x_offset, - .y = (@as(i64, at.screen.y) - @as(i64, origin.screen.y)) * ch + placed.y_offset, + .x = (@as(i64, at.screen.x) + dx) * cw + placed.x_offset, + .y = (@as(i64, at.screen.y) - @as(i64, origin.screen.y) + dy) * ch + placed.y_offset, .w = size.width, .h = size.height, }); @@ -289,7 +312,7 @@ const Ctx = struct { fn pixelsOf(ti: *TerminalImages, gpa: std.mem.Allocator, img: gfx.Image) ?[]const u8 { const n = @as(usize, img.width) * img.height; if (n == 0) return null; - const data = img.data.bytes() orelse return null; + const data = img.renderData().bytes() orelse return null; if (img.format == .rgba) return if (data.len == n * 4) data else null; const gop = ti.converted.getOrPut(gpa, img.id) catch return null; if (gop.found_existing) { @@ -316,7 +339,7 @@ fn convert(gpa: std.mem.Allocator, img: gfx.Image, n: usize) ?[]u8 { .gray => 1, else => return null, }; - const data = img.data.bytes() orelse return null; + const data = img.renderData().bytes() orelse return null; if (data.len != n * depth) return null; const out = gpa.alloc(u8, n * 4) catch return null; for (0..n) |i| { diff --git a/src/image.zig b/src/image.zig index 19dbb9e4..5ceadd76 100644 --- a/src/image.zig +++ b/src/image.zig @@ -771,6 +771,9 @@ pub fn readable(bytes: []const u8) bool { const Decoded = struct { rgba: []u8, w: usize, h: usize }; pub fn decode(gpa: std.mem.Allocator, bytes: []const u8) ?Decoded { + // stb_image allocates through what `start` gave it: before that, a call + // jumps through a null pointer (a terminal's PNG in a core no shell set up). + if (!started) return null; if (bytes.len == 0 or bytes.len > std.math.maxInt(c_int)) return null; // Bounded before decoding: a few KB of PNG can name gigapixels. var iw: c_int = 0; diff --git a/src/pardes.zig b/src/pardes.zig index 3721cc32..c7ae6704 100644 --- a/src/pardes.zig +++ b/src/pardes.zig @@ -7813,6 +7813,16 @@ pub const Pardes = struct { const wait = @max(1, (pane.repl_enter_due_ns -| p.stepped_ns + animation.frame_ns - 1) / animation.frame_ns); frames = if (frames) |soonest| @min(soonest, wait) else wait; }; + // A terminal's kitty animation, at its next frame. Only a time still + // ahead counts: a pane not drawn keeps the last one it was given, + // and a past one would wake every frame for nothing. + if (comptime terminal_panes) for (p.panes) |slot| if (slot) |pane| if (panes.terminal.animationDueMs(pane)) |due_ms| { + const due = due_ms *| std.time.ns_per_ms; + if (due > p.stepped_ns) { + const wait = @max(1, (due - p.stepped_ns + animation.frame_ns - 1) / animation.frame_ns); + frames = if (frames) |soonest| @min(soonest, wait) else wait; + } + }; return if (frames) |n| p.stepped_ns + n * animation.frame_ns else null; } diff --git a/src/terminal.zig b/src/terminal.zig index 77ee9b44..ce41bd95 100644 --- a/src/terminal.zig +++ b/src/terminal.zig @@ -146,8 +146,14 @@ pub const MarkedHandler = if (enabled) struct { pub const State = struct { vt: VtSlot, stream: StreamSlot, - reply: [256]u8 = undefined, + /// The emulator's answers to its program (DSR, DA, kitty graphics, ...) + /// from one read of its output, written to its pty after it. Room for + /// a read's worth of kitty answers (yazi or `kitten icat` asking about + /// a batch of images in one write); an answer that does not fit whole + /// is dropped whole, never cut short (`reply_dropped` counts them). + reply: [4096]u8 = undefined, reply_len: u16 = 0, + reply_dropped: u32 = 0, /// The grid cell the program last heard the mouse at, so motion is /// reported once per cell. mouse_cell: if (enabled) ?ghostty_vt.Coordinate else void = if (enabled) null else {}, @@ -315,6 +321,16 @@ pub fn deinitPendingCommand(pane: *Pane) void { pane.pending_command = .{}; } +/// Where a kitty client puts its temporary files: `$TMPDIR`, else /tmp +/// (which ghostty accepts whatever this says). The environment block lives +/// as long as the process and pardes never edits it (ChildEnv.exportVar). +fn tempDir() []const u8 { + if (comptime !pardes.hosted) return "/tmp"; + const dir = std.c.getenv("TMPDIR") orelse return "/tmp"; + const path = std.mem.span(dir); + return if (path.len > 0 and path[0] == '/') path else "/tmp"; +} + pub fn terminalIo() std.Io { return if (comptime !pardes.hosted) std.Io.failing @@ -606,6 +622,13 @@ pub fn create(gpa: std.mem.Allocator, cols: u16, rows: u16) !*Pane { .rows = rows, .max_scrollback_bytes = 16 * 1024 * 1024, .kitty_image_storage_limit = if (images_enabled) TerminalImages.storage_limit else 0, + // Every kitty medium, as ghostty and kitty take them: a file (t=f), + // a temporary file it then deletes (t=t, in the temp directory and + // named as one) and shared memory (t=s), beside direct data. libghostty + // defaults to direct alone, which `kitten icat` and timg detect and + // fall back from, base64 through the pty. What the program can read + // it could send itself: it runs as the user, under pardes. + .kitty_image_loading_limits = if (images_enabled) .allWithTempDir(tempDir()) else .direct, }); state.stream = .init(.{ .handler = .{ .inner = state.vt.vtHandler() }, .allocator = gpa }); state.reply_len = 0; @@ -677,7 +700,6 @@ fn ingest(pane: *Pane, bytes: []const u8) void { pane.terminal.?.stream.nextSlice(bytes); } - test "replay ownership is terminal-only and construction rolls back on allocation failure" { const Case = struct { fn run(gpa: std.mem.Allocator, terminal: bool) !void { @@ -2808,9 +2830,14 @@ pub fn redo(p: *Pardes, pane: *Pane) void { pub fn ptyReport(handler: *ghostty_vt.TerminalStream.Handler, data: []const u8) void { const state: *State = @alignCast(@fieldParentPtr("vt", handler.terminal)); const room = state.reply.len - state.reply_len; - const n = @min(room, data.len); - @memcpy(state.reply[state.reply_len..][0..n], data[0..n]); - state.reply_len += @intCast(n); + // A cut answer is worse than none: the program would read the start of + // a sequence and wait, or misparse what follows. + if (data.len > room) { + state.reply_dropped +|= 1; + return; + } + @memcpy(state.reply[state.reply_len..][0..data.len], data); + state.reply_len += @intCast(data.len); } const DeviceAttrs = @typeInfo(@typeInfo(@typeInfo( @@ -2838,6 +2865,14 @@ fn syncPixels(p: *const Pardes, pane: *Pane) void { vt.height_px = @as(u32, vt.rows) * p.cell_pixels.h; } +/// When the pane's next kitty animation frame is due (ms on the core's +/// clock), as its last drawn frame left it; null when nothing plays. +pub fn animationDueMs(pane: *const Pane) ?u64 { + if (comptime !images_enabled) return null; + const state = pane.terminal orelse return null; + return state.images.animation_due_ms; +} + /// The Petscii builtin on a terminal: its kitty graphics as glyph art, /// or back to pixels where the shell draws pixels. pub fn togglePetscii(pane: *Pane) void { |
