diff options
| author | Can Celik <ogulcancelik@gmail.com> | 2026-09-10 21:51:57 +0300 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2026-09-10 21:51:57 +0300 |
| commit | 425c86179791cd32e2d4ce0ae7f269940b4b0663 (patch) | |
| tree | e52c4383a6d69216cbe2a32638bf90841d7e2189 /vendor/libghostty-vt/src/terminal/kitty/graphics_storage.zig | |
| parent | 90e947a6e26e02f10ec7f1694c4eb5b78a86406b (diff) | |
chore: upgrade libghostty and preserve terminal behavior (#3906)
Diffstat (limited to 'vendor/libghostty-vt/src/terminal/kitty/graphics_storage.zig')
| -rw-r--r-- | vendor/libghostty-vt/src/terminal/kitty/graphics_storage.zig | 3843 |
1 files changed, 3453 insertions, 390 deletions
diff --git a/vendor/libghostty-vt/src/terminal/kitty/graphics_storage.zig b/vendor/libghostty-vt/src/terminal/kitty/graphics_storage.zig index ba82ea40..897c8944 100644 --- a/vendor/libghostty-vt/src/terminal/kitty/graphics_storage.zig +++ b/vendor/libghostty-vt/src/terminal/kitty/graphics_storage.zig @@ -6,6 +6,8 @@ const ArenaAllocator = std.heap.ArenaAllocator; const terminal = @import("../main.zig"); const point = @import("../point.zig"); const size = @import("../size.zig"); +const animation = @import("graphics_animation.zig"); +const pixel = @import("graphics_pixel.zig"); const command = @import("graphics_command.zig"); const PageList = @import("../PageList.zig"); const Screen = @import("../Screen.zig"); @@ -32,8 +34,8 @@ var generation_counter: GenerationCounter = .{}; /// Returns the next generation stamp. Stamps are unique and strictly /// monotonically increasing process-wide, starting at 1 (0 is reserved /// to mean "never stamped"). -pub fn nextGeneration() u64 { - return generation_counter.next(); +pub fn nextGeneration(io: std.Io) u64 { + return generation_counter.next(io); } /// Backing implementation for the generation counter. We use a @@ -48,16 +50,17 @@ pub fn nextGeneration() u64 { const GenerationCounter = if (@bitSizeOf(usize) >= 64) struct { value: std.atomic.Value(u64) = .init(0), - fn next(self: *@This()) u64 { + fn next(self: *@This(), io: std.Io) u64 { + _ = io; return self.value.fetchAdd(1, .monotonic) + 1; } } else struct { - mutex: std.Thread.Mutex = .{}, + mutex: std.Io.Mutex = .init, value: u64 = 0, - fn next(self: *@This()) u64 { - self.mutex.lock(); - defer self.mutex.unlock(); + fn next(self: *@This(), io: std.Io) u64 { + self.mutex.lockUncancelable(io); + defer self.mutex.unlock(io); self.value += 1; return self.value; } @@ -100,11 +103,10 @@ pub const ImageStorage = struct { /// This field must only be written via markMutated. generation: u64 = 0, - /// This is the next automatically assigned image ID. We start mid-way - /// through the u32 range to avoid collisions with buggy programs. - /// TODO: This isn't good enough, it's perfectly legal for programs - /// to use IDs in the latter half of the range and collisions - /// are not gracefully handled. + /// This is the next automatically assigned image ID for images + /// transmitted without an ID or number. We start mid-way through + /// the u32 range to stay clear of the low IDs client programs + /// typically pick. See nextImageId. next_image_id: u32 = 2147483647, /// This is the next automatically assigned placement ID. This is never @@ -131,6 +133,38 @@ pub const ImageStorage = struct { total_bytes: usize = 0, total_limit: usize = 320 * 1000 * 1000, // 320MB + /// Identifies one exact pending image transmission. The generation is + /// assigned by this storage when the pending image is inserted, so a + /// later replacement of the same ID cannot consume stale payload bytes. + pub const PendingImage = struct { + id: u32, + generation: u64, + + /// Attach owned decoded bytes if this exact pending transmission is + /// still resident. On true, storage owns `data`; on false, the caller + /// retains ownership. Completion preserves the image generation (and + /// therefore eviction age) while marking storage content as mutated. + pub fn complete( + self: PendingImage, + storage: *ImageStorage, + io: std.Io, + data: []const u8, + ) bool { + const img = storage.images.getPtr(self.id) orelse return false; + if (img.generation != self.generation) return false; + + const expected_len = switch (img.data) { + .complete => return false, + .pending => |len| len, + }; + if (data.len != expected_len) return false; + + img.data = .{ .complete = data }; + storage.markMutated(io); + return true; + } + }; + pub fn deinit( self: *ImageStorage, alloc: Allocator, @@ -138,12 +172,12 @@ pub const ImageStorage = struct { ) void { if (self.loading) |loading| loading.destroy(alloc); + self.clearPlacements(s); + self.placements.deinit(alloc); + var it = self.images.iterator(); while (it.next()) |kv| kv.value_ptr.deinit(alloc); self.images.deinit(alloc); - - self.clearPlacements(s); - self.placements.deinit(alloc); } /// Kitty image protocol is enabled if we have a non-zero limit. @@ -153,15 +187,16 @@ pub const ImageStorage = struct { /// Record a content mutation: marks the storage dirty and assigns a /// fresh generation stamp. Must be called by anything that changes - /// the set of images or placements (or image contents). + /// the set of images or placements (or image contents), including + /// the animation command handlers in graphics_exec.zig. /// /// Do NOT call this for geometry-only events (scrolling, resizing, /// screen switches); those must set only the dirty flag directly. /// Bumping the generation for geometry changes would break the /// contract that an unchanged generation means unchanged contents. - fn markMutated(self: *ImageStorage) void { + pub fn markMutated(self: *ImageStorage, io: std.Io) void { self.dirty = true; - self.generation = nextGeneration(); + self.generation = nextGeneration(io); } /// Sets the limit in bytes for the total amount of image data that @@ -170,23 +205,24 @@ pub const ImageStorage = struct { /// be disabled. pub fn setLimit( self: *ImageStorage, + io: std.Io, alloc: Allocator, s: *terminal.Screen, limit: usize, - ) !void { + ) void { // Special case disabling by quickly deleting all if (limit == 0) { const image_limits = self.image_limits; self.deinit(alloc, s); self.* = .{ .image_limits = image_limits }; - self.markMutated(); + self.markMutated(io); } // If we re lowering our limit, check if we need to evict. if (limit < self.total_bytes) { const req_bytes = self.total_bytes - limit; log.info("evicting images to lower limit, evicting={}", .{req_bytes}); - if (!try self.evictImage(alloc, req_bytes)) { + if (!self.evictImage(io, alloc, s, req_bytes)) { log.warn("failed to evict enough images for required bytes", .{}); } } @@ -194,54 +230,137 @@ pub const ImageStorage = struct { self.total_limit = limit; } - /// Add an already-loaded image to the storage. This will automatically - /// free any existing image with the same ID. - pub fn addImage(self: *ImageStorage, alloc: Allocator, img: Image) Allocator.Error!void { + /// Returns the next ID to automatically assign to an image that + /// was transmitted without an explicit ID (i=). The result is + /// never zero (zero means "no ID") and never an ID currently in + /// use, so an automatic ID never replaces an existing image. + pub fn nextImageId( + self: *ImageStorage, + mode: enum { explicit, implicit }, + ) u32 { + // Starting ID depends on mode. + var id: u32 = switch (mode) { + // Yeah, starting from 1 is wasteful. This matches what Kitty + // does. In the future we can probably cache a low-water-mark + // based on delete behavior. + .explicit => 1, + .implicit => self.next_image_id, + }; + + // Go through all possible images. We have +2 because we can + // exceed the total by 1 (new ID). + const count: usize = self.images.count(); + for (0..count + 2) |_| { + if (id != 0 and !self.images.contains(id)) break; + id +%= 1; + } + + // Zero is never allowed. + if (id == 0) id = 1; + + // Keep track of our next image id for implicit to speed that up. + if (mode == .implicit) self.next_image_id = id +% 1; + + return id; + } + + /// Add an image to the storage. This will automatically free any existing + /// image with the same ID. Prefer addPendingImage for pending data so the + /// caller receives a completion token. + pub fn addImage( + self: *ImageStorage, + io: std.Io, + alloc: Allocator, + s: *terminal.Screen, + img: Image, + ) Allocator.Error!void { + const new_len = img.data.len(); + // If the image itself is over the limit, then error immediately - if (img.data.len > self.total_limit) return error.OutOfMemory; + if (new_len > self.total_limit) return error.OutOfMemory; + + // Credit an existing image's reservation before calculating the + // replacement size. In particular, a completed live transmission + // replacing pending snapshot metadata must be able to reuse the + // reservation without evicting its own ID. + const old_len = if (self.images.get(img.id)) |old| + old.storageSize() + else + 0; + assert(old_len <= self.total_bytes); + + // Reserve map capacity before evicting anything so allocation failure + // cannot leave storage partially evicted. Existing keys need no room. + if (!self.images.contains(img.id)) { + try self.images.ensureUnusedCapacity(alloc, 1); + } // If this would put us over the limit, then evict. - const total_bytes = self.total_bytes + img.data.len; + const total_bytes = self.total_bytes - old_len + new_len; if (total_bytes > self.total_limit) { const req_bytes = total_bytes - self.total_limit; log.info("evicting images to make space for {} bytes", .{req_bytes}); - if (!try self.evictImage(alloc, req_bytes)) { + if (!self.evictImageExcept(io, alloc, s, req_bytes, img.id)) { log.warn("failed to evict enough images for required bytes", .{}); return error.OutOfMemory; } } - // Do the gop op first so if it fails we don't get a partial state - const gop = try self.images.getOrPut(alloc, img.id); + const gop = self.images.getOrPutAssumeCapacity(img.id); - log.debug("addImage image={}", .{img: { - var copy = img; - copy.data = ""; - break :img copy; - }}); + log.debug("addImage image={}", .{img.withoutData()}); - // Write our new image if (gop.found_existing) { - self.total_bytes -= gop.value_ptr.data.len; + // Retransmitting a specific image ID replaces the old image and all + // of its placements, as required by the Kitty graphics protocol. + self.removePlacementsByImageId(s, img.id); + + // Relative placements parented to the removed placements go too. + _ = self.removeOrphans(s, null); + + // Replacing an image drops its animation frames with it, + // implementing the protocol rule that retransmitting the + // base image resets the animation. + self.total_bytes -= gop.value_ptr.storageSize(); gop.value_ptr.deinit(alloc); } gop.value_ptr.* = img; - self.total_bytes += img.data.len; + gop.value_ptr.metadata.placement_count = 0; + self.total_bytes += new_len; // Stamp the stored image with a fresh generation. This gives // every add/replace a unique stamp even when the same image ID // is retransmitted with identical dimensions, so consumers // (e.g. renderer texture caches) can detect content changes. - self.markMutated(); + self.markMutated(io); gop.value_ptr.generation = self.generation; } + /// Add an image whose decoded payload bytes have not arrived yet. + /// Returns the token required to complete this exact transmission. + pub fn addPendingImage( + self: *ImageStorage, + io: std.Io, + alloc: Allocator, + s: *terminal.Screen, + img: Image, + ) Allocator.Error!PendingImage { + assert(img.data == .pending); + try self.addImage(io, alloc, s, img); + const stored = self.images.get(img.id).?; + return .{ .id = stored.id, .generation = stored.generation }; + } + /// Add a placement for a given image. The caller must verify in advance - /// the image exists to prevent memory corruption. + /// the image exists to prevent memory corruption. On success, storage + /// owns `p`; on error, the caller retains ownership. The screen must own + /// any tracked pin in `p` and in the placement it replaces. pub fn addPlacement( self: *ImageStorage, + io: std.Io, alloc: Allocator, + s: *terminal.Screen, image_id: u32, placement_id: u32, p: Placement, @@ -253,6 +372,12 @@ pub const ImageStorage = struct { p, }); + // When we add a placement, take this opportunity to reap garbage. + // Garbage are placements that disappeared off scrollback (were + // pruned). We don't clear Kitty state in the hot path so we do + // this opportunistically here. + self.reapGarbagePlacements(io, s); + // The important piece here is that the placement ID needs to // be marked internal if it is zero. This allows multiple placements // to be added for the same image. If it is non-zero, then it is @@ -273,9 +398,227 @@ pub const ImageStorage = struct { }; const gop = try self.placements.getOrPut(alloc, key); + if (gop.found_existing) { + gop.value_ptr.deinit(s); + } else { + const img = self.images.getPtr(image_id).?; + img.metadata.placement_count = std.math.add( + @TypeOf(img.metadata.placement_count), + img.metadata.placement_count, + 1, + ) catch { + self.placements.removeByPtr(gop.key_ptr); + return error.OutOfMemory; + }; + } gop.value_ptr.* = p; - self.markMutated(); + // This always mutates + self.markMutated(io); + } + + /// How the row operation behind a scrollMarginsBegin/end pair moves + /// tracked pins, which determines how much repositioning work the + /// placements need. + pub const ScrollOp = enum { + /// The operation shifts the entire active window down (it + /// creates scrollback), so every placement anchored in the + /// active area changes active position and must be restored. + window_shift, + + /// The operation moves rows in place within the scrolling + /// region: pins anchored outside the region rows keep their + /// active position without help, so only placements anchored + /// inside the region rows need handling. This is the common + /// case (e.g. a status bar image beside a scrolling pane + /// costs almost nothing per scroll). + in_place, + }; + + /// Adjust placements for a scroll of the terminal's scrolling region + /// by `delta` rows (negative moves content up). This implements the + /// Kitty graphics protocol behavior for scrolls bounded by margins: + /// placements entirely inside the scrolling region move with the content + /// and are clipped when the move would extend them past a margin (deleted + /// when fully clipped), while every other placement (straddling a margin, + /// outside the region, or in the scrollback) must not move at all. + /// + /// This is split into two phases around the row operation because + /// the various scroll implementations move tracked pins in + /// inconsistent ways (some shift the active area so every pin moves, + /// some rotate rows in place and adjust only pins inside the + /// region). We record the desired final position of every placement + /// up front in the returned state, whose end() repositions the pins + /// once the rows have settled, making the result independent of the + /// path taken. Every call must be paired with exactly one end(). + /// + /// Callers must skip this entirely when the scrolling region is the + /// full screen: a full-screen scroll moves placements with their + /// anchored rows (possibly into the scrollback) via pin tracking, + /// which already matches kitty's marginless scroll behavior. + pub fn scrollMarginsBegin( + self: *ImageStorage, + io: std.Io, + t: *terminal.Terminal, + delta: isize, + op: ScrollOp, + ) ScrollMargins { + const s: *terminal.Screen = t.screens.active; + assert(self == &s.kitty_images); + var result: ScrollMargins = .{ .screen = s }; + + const top: i64 = t.scrolling_region.top; + const bottom: i64 = t.scrolling_region.bottom; + + var mutated = false; + var it = self.placements.iterator(); + while (it.next()) |entry| { + const p: *Placement = entry.value_ptr; + + // Virtual placements follow their placeholder cells and + // relative placements follow their parents, so neither is + // ever adjusted by scrolls, matching kitty. + const pin: *PageList.Pin = switch (p.location) { + .pin => |pin| pin, + .virtual, .relative => continue, + }; + + // Pruned placements are reaped by reapGarbagePlacements. + if (pin.garbage) continue; + + // Placements anchored outside the active area (scrollback) + // are never touched by a scroll within the margins. + const coord = (s.pages.pointFromPin( + .active, + pin.*, + ) orelse continue).coord(); + const y: i64 = coord.y; + + // An in-place operation doesn't touch pins anchored outside + // the region rows, and a placement anchored there can never + // be entirely inside the region, so it needs no work at all. + if (op == .in_place and (y < top or y > bottom)) continue; + + // The final position defaults to unmoved; restoring the pin + // to this exact spot afterwards is what stops the row + // operations from dragging the placement around. + var final_y: i64 = y; + + inside: { + const image = self.images.get(entry.key_ptr.image_id) orelse break :inside; + const grid = p.gridSize(image, t); + + // Unknown geometry (e.g. pixel sizes not yet reported) + // means we can't know the extent, so we can't consider + // the placement contained. + if (grid.rows == 0 or grid.cols == 0) break :inside; + + // Only placements entirely within the scrolling region + // move. Kitty only has top/bottom margins so it only + // checks rows; the column check is our generalization + // for left/right margins and is trivially true for + // full-width regions. + if (y < top or y + grid.rows - 1 > bottom) break :inside; + const x: i64 = coord.x; + if (x < t.scrolling_region.left or + @min(x + grid.cols - 1, @as(i64, t.cols) - 1) > t.scrolling_region.right) break :inside; + + const new_y: i64 = y + delta; + const rows: i64 = grid.rows; + const top_clip: i64 = @max(0, top - new_y); + const bottom_clip: i64 = @max(0, new_y + rows - 1 - bottom); + const visible: bool = clip: { + if (top_clip >= rows or bottom_clip >= rows) break :clip false; + + if (top_clip > 0) { + if (!p.clipTop( + image, + t, + @intCast(top_clip), + grid.rows, + )) break :clip false; + mutated = true; + final_y = top; + break :clip true; + } + + if (bottom_clip > 0) { + if (!p.clipBottom( + image, + t, + @intCast(bottom_clip), + grid.rows, + )) break :clip false; + mutated = true; + } + + final_y = new_y; + break :clip true; + }; + + // Scrolled or clipped entirely out of the region: the + // placement is deleted, like kitty. The image itself is + // retained for future placements. + if (!visible) { + self.removePlacement(s, entry); + mutated = true; + continue; + } + } + + result.restores.append(s.alloc, .{ + .pin = pin, + .x = pin.x, + .y = @intCast(final_y), + }) catch { + // OOM: this placement is left to the whims of the + // generic pin tracking. Degraded, but safe. + log.warn("OOM adjusting image placement for scroll", .{}); + continue; + }; + } + + if (mutated) { + // Placements deleted by clipping may orphan relative placements. + // Orphans have no pins so this never touches the restores. + _ = self.removeOrphans(s, null); + self.markMutated(io); + } + + return result; + } + + /// Reap pin-backed placements whose tracked content has been pruned + /// from history, along with any relative placements orphaned by + /// that, marking the content mutation. + /// + /// Virtual and relative placements have no tracked screen location and + /// are never pruned themselves. Kitty removes placements once they + /// scroll out of retained history. + fn reapGarbagePlacements( + self: *ImageStorage, + io: std.Io, + s: *terminal.Screen, + ) void { + var removed = false; + var it = self.placements.iterator(); + while (it.next()) |entry| { + const pin = switch (entry.value_ptr.location) { + .pin => |pin| pin, + .virtual, .relative => continue, + }; + if (!pin.garbage) continue; + + self.removePlacement(s, entry); + removed = true; + } + if (!removed) return; + + // If we removed a placement, then also remove any orphan + // children if this was a parent. + _ = self.removeOrphans(s, null); + + self.markMutated(io); } fn clearPlacements(self: *ImageStorage, s: *terminal.Screen) void { @@ -284,6 +627,290 @@ pub const ImageStorage = struct { self.placements.clearRetainingCapacity(); } + fn removePlacementsByImageId( + self: *ImageStorage, + s: *terminal.Screen, + image_id: u32, + ) void { + var it = self.placements.iterator(); + while (it.next()) |entry| { + if (entry.key_ptr.image_id != image_id) continue; + self.removePlacement(s, entry); + } + } + + /// Remove a placement by its map entry, releasing any tracked pin + /// and keeping the image's placement count in sync. The entry must + /// point into the placements map (via iteration or getEntry). + fn removePlacement( + self: *ImageStorage, + s: *terminal.Screen, + entry: PlacementMap.Entry, + ) void { + entry.value_ptr.deinit(s); + const img = self.images.getPtr(entry.key_ptr.image_id).?; + assert(img.metadata.placement_count > 0); + img.metadata.placement_count -= 1; + self.placements.removeByPtr(entry.key_ptr); + } + + /// Remove relative placements whose parent placement no longer + /// exists, keeping a relative placement's lifetime tied to its + /// parent chain. Chains can be several links deep, so this loops + /// until a pass removes nothing to take out entire orphaned + /// subtrees. Returns true if anything was removed. + /// + /// If `delete_unused` is non-null, an image left without placements + /// by the reap is freed using it. This matches uppercase delete + /// semantics; every other removal path retains image data and + /// passes null. + /// + /// This must be called, outside of any placements iteration, after + /// every operation that removes placements. Kitty gets the same + /// effect lazily by dropping unresolvable placements while drawing; + /// we do it eagerly because our renderer never mutates terminal + /// state. + fn removeOrphans( + self: *ImageStorage, + s: *terminal.Screen, + delete_unused: ?Allocator, + ) bool { + var removed_any = false; + var removed = true; + while (removed) { + removed = false; + var it = self.placements.iterator(); + while (it.next()) |entry| { + const rel = switch (entry.value_ptr.location) { + .relative => |rel| rel, + .pin, .virtual => continue, + }; + if (self.placements.contains(rel.parent)) continue; + + // Parent is gone, remove this placement. + const image_id = entry.key_ptr.image_id; + self.removePlacement(s, entry); + removed = true; + removed_any = true; + + if (delete_unused) |alloc| self.deleteIfUnused( + alloc, + image_id, + ); + } + } + + return removed_any; + } + + /// Maximum number of parent links in a relative placement chain, + /// matching the minimum specified in the spec and the actual + /// limit defined by Kitty at the time of authoring. + pub const parent_chain_limit = 8; + + pub const ParentError = error{ + /// The parent image (P=) does not exist. + ParentImageNotFound, + /// The parent image exists but the requested placement (Q=, or + /// any placement when Q is omitted) does not. + ParentPlacementNotFound, + /// The placement refers to itself as its own parent. + SelfParent, + /// The parent chain loops back to the placement being created. + Cycle, + /// The parent chain exceeds parent_chain_limit links. + TooDeep, + /// An ancestor in the chain no longer exists. This should not + /// happen since removeOrphans keeps chains intact, but we + /// check anyway rather than trusting the invariant. + AncestorNotFound, + }; + + /// Resolve and validate the parent reference (P=/Q=) of a relative + /// placement, returning the concrete key of the parent placement. + /// `child` is the key of the placement being created when it is + /// addressable (an explicit placement ID); null for placements that + /// will receive a fresh internal ID, which nothing can refer to yet. + /// + /// Checks: the parent must exist, the placement must not + /// parent itself, and the resulting ancestor chain must be acyclic + /// and within parent_chain_limit. + pub fn resolveParent( + self: *ImageStorage, + io: std.Io, + s: *terminal.Screen, + child: ?PlacementKey, + parent_image_id: u32, + parent_placement_id: u32, + ) ParentError!PlacementKey { + // Reap placements whose content has been pruned from history + // before resolving: a pruned parent must be reported as missing, + // not accepted and then immediately reaped by addPlacement's own + // sweep, which would store an orphan. + self.reapGarbagePlacements(io, s); + + // If the parent doesn't exist we're already failed. + if (!self.images.contains(parent_image_id)) { + return error.ParentImageNotFound; + } + + // Find the parent + const parent: PlacementKey = parent: { + // An explicit parent placement ID (Q=) selects exactly that + // placement. + if (parent_placement_id > 0) { + const key: PlacementKey = .{ + .image_id = parent_image_id, + .placement_id = .{ + .tag = .external, + .id = parent_placement_id, + }, + }; + if (!self.placements.contains(key)) { + return error.ParentPlacementNotFound; + } + break :parent key; + } + + // No Q: pick a placement of the parent image. Kitty picks + // the oldest surviving placement; our placement map doesn't + // track creation order so we pick by PlacementId.preferredOver + // instead. This is unspecified so any behavior here is fine. + // In practice the parent image has a single placement, and + // clients use Q when it doesn't. + const best: PlacementId = best: { + var best: ?PlacementId = null; + var it = self.placements.keyIterator(); + while (it.next()) |key| { + if (key.image_id != parent_image_id) continue; + const id = key.placement_id; + const b = best orelse { + best = id; + continue; + }; + if (id.preferredOver(b)) best = id; + } + break :best best orelse return error.ParentPlacementNotFound; + }; + + break :parent .{ + .image_id = parent_image_id, + .placement_id = best, + }; + }; + + // A placement cannot be its own parent. This must be checked + // before the chain walk so it reports EINVAL, not ECYCLE. + if (child) |c| if (parent.eql(c)) return error.SelfParent; + + // Walk the would-be ancestor chain. `depth` counts parent links, + // starting at one for the link we are about to create. + var depth: usize = 1; + var key = parent; + while (true) { + if (child) |c| if (key.eql(c)) return error.Cycle; + const p = self.placements.get(key) orelse return error.AncestorNotFound; + const rel = switch (p.location) { + .relative => |rel| rel, + // A pin or virtual placement is the chain root. + .pin, .virtual => break, + }; + if (depth >= parent_chain_limit) return error.TooDeep; + depth += 1; + key = rel.parent; + } + + return parent; + } + + /// The result of resolving a relative placement's parent chain: + /// the chain's root placement (always pin or virtual, never + /// relative) and the total cell offset from the root's origin. + pub const ResolvedChain = struct { + root_key: PlacementKey, + root: Placement, + horizontal_offset: i32, + vertical_offset: i32, + }; + + /// Resolve a relative placement's parent chain to its root, + /// accumulating the cell offsets (H=/V=) of every link on the way. + /// The placement's position is the root's origin plus the accumulated + /// offsets. + /// + /// Returns null when the chain is broken or too deep. Neither can + /// normally happen for stored placements (resolveParent validates + /// chains and removeOrphans removes broken ones), with one kitty + /// quirk: replacing an ancestor placement can deepen the chains + /// below it beyond parent_chain_limit after the fact. + pub fn resolveChain( + self: *const ImageStorage, + rel: Placement.Relative, + ) ?ResolvedChain { + var horizontal = rel.horizontal_offset; + var vertical = rel.vertical_offset; + var key = rel.parent; + var depth: usize = 1; + while (true) { + const p = self.placements.get(key) orelse return null; + switch (p.location) { + .relative => |parent_rel| { + if (depth >= parent_chain_limit) return null; + depth += 1; + horizontal +|= parent_rel.horizontal_offset; + vertical +|= parent_rel.vertical_offset; + key = parent_rel.parent; + }, + + .pin, .virtual => return .{ + .root_key = key, + .root = p, + .horizontal_offset = horizontal, + .vertical_offset = vertical, + }, + } + } + } + + /// Returns the placement that a unicode placeholder cell referencing + /// this image/placement ID pair targets, or null if there is none. A + /// zero placement ID targets one of the image's virtual placements, + /// chosen by PlacementId.preferredOver so the choice is stable (an + /// image rarely has more than one). This is the shared lookup used + /// both for sizing placeholder runs and for positioning relative + /// placements whose chain roots at a virtual placement. + pub fn placeholderTarget( + self: *const ImageStorage, + image_id: u32, + placement_id: u32, + ) ?struct { key: PlacementKey, placement: Placement } { + if (placement_id > 0) { + const key: PlacementKey = .{ + .image_id = image_id, + .placement_id = .{ .tag = .external, .id = placement_id }, + }; + const p = self.placements.get(key) orelse return null; + return .{ .key = key, .placement = p }; + } + + var best: ?PlacementKey = null; + var it = self.placements.iterator(); + while (it.next()) |entry| { + if (entry.key_ptr.image_id != image_id) continue; + if (entry.value_ptr.location != .virtual) continue; + const b = best orelse { + best = entry.key_ptr.*; + continue; + }; + if (entry.key_ptr.placement_id.preferredOver(b.placement_id)) { + best = entry.key_ptr.*; + } + } + + const key = best orelse return null; + return .{ .key = key, .placement = self.placements.get(key).? }; + } + /// Get an image by its ID. If the image doesn't exist, null is returned. pub fn imageById(self: *const ImageStorage, image_id: u32) ?Image { return self.images.get(image_id); @@ -307,46 +934,285 @@ pub const ImageStorage = struct { return newest; } + /// Get a mutable pointer to a stored image, by ID or (newest by) + /// number, following the protocol's id/number addressing. Used by + /// the animation commands, which mutate images in place. The + /// pointer is invalidated by any operation that adds or removes + /// images. + pub fn imagePtrByIdOrNumber( + self: *const ImageStorage, + image_id: u32, + image_number: u32, + ) ?*Image { + if (image_id != 0) return self.images.getPtr(image_id); + + var newest: ?*Image = null; + var it = self.images.iterator(); + while (it.next()) |kv| { + if (kv.value_ptr.number != image_number) continue; + if (newest == null or + kv.value_ptr.generation > newest.?.generation) + { + newest = kv.value_ptr; + } + } + + return newest; + } + + /// Record that the displayed content of an image changed without + /// the image being re-added: marks the storage mutated and stamps + /// the image with the fresh generation so consumers (e.g. the + /// renderer's texture cache) replace what they hold. Used when an + /// animation changes which frame is current or edits the current + /// frame's pixels. + pub fn markImageContentChanged( + self: *ImageStorage, + io: std.Io, + img: *Image, + ) void { + self.markMutated(io); + img.generation = self.generation; + } + + /// Convert a stored image's base data to RGBA in place, adjusting + /// byte accounting. All animation composition happens in RGBA; + /// this is called before the first composition into an image. + /// + /// The pixels are unchanged visually but the stored representation + /// changed, so the image is stamped with a fresh generation. + pub fn convertImageToRgba( + self: *ImageStorage, + io: std.Io, + alloc: Allocator, + img: *Image, + ) Allocator.Error!void { + if (img.format == .rgba) return; + const old = img.data.bytes() orelse return; + + const rgba = try pixel.rgbaFromFormat(alloc, img.format, old); + self.total_bytes -= old.len; + self.total_bytes += rgba.len; + img.data.deinit(alloc); + img.data = .{ .complete = rgba }; + img.format = .rgba; + self.markImageContentChanged(io, img); + } + + /// Reserve `bytes` of storage for animation frame data belonging + /// to `image_id`, evicting other images if needed, mirroring how + /// image transmission reserves space. + /// + /// Errors if the space cannot be made available. On success the caller + /// owns the reservation and must either attach the frame data to the + /// image or call releaseAnimationBytes. + pub fn reserveAnimationBytes( + self: *ImageStorage, + io: std.Io, + alloc: Allocator, + s: *terminal.Screen, + image_id: u32, + bytes: usize, + ) Allocator.Error!void { + if (bytes > self.total_limit) return error.OutOfMemory; + + const total_bytes = self.total_bytes + bytes; + if (total_bytes > self.total_limit) { + const req_bytes = total_bytes - self.total_limit; + // Excess this large cannot be recovered by evicting other + // images (evictImageExcept also requires it). + if (req_bytes > self.total_limit) return error.OutOfMemory; + log.info("evicting images for animation frame, evicting={}", .{req_bytes}); + if (!self.evictImageExcept( + io, + alloc, + s, + req_bytes, + image_id, + )) { + log.warn("failed to evict enough images for animation frame", .{}); + return error.OutOfMemory; + } + } + + self.total_bytes += bytes; + } + + /// Release a reservation made by reserveAnimationBytes, or credit + /// bytes freed by deleting animation frame data. + pub fn releaseAnimationBytes(self: *ImageStorage, bytes: usize) void { + assert(bytes <= self.total_bytes); + self.total_bytes -= bytes; + } + + /// Advance every running animation to the frame that should be + /// displayed at `now_ms` and report when the next frame change is + /// due, as a delay in milliseconds relative to `now_ms`. Null + /// means no running animation needs a future tick. + /// + /// `now_ms` is a monotonic timestamp on a clock of the caller's + /// choosing. The same clock must be used for every call. The + /// caller is expected to be the renderer, ticking once per frame + /// build and scheduling a wakeup for the returned delay. + pub fn animationTick(self: *ImageStorage, io: std.Io, now_ms: u64) ?u64 { + var min_delay: ?u64 = null; + + var it = self.images.iterator(); + while (it.next()) |entry| { + const img: *Image = entry.value_ptr; + + // The gates below mirror Kitty's image_is_animatable. + + // No animation state was ever attached (plain image). + const anim = img.animation orelse continue; + + // Stopped is the initial state of every animation: frames + // then only change client-driven (a=a c=N), never by time. + if (anim.state == .stopped) continue; + + // Only the root frame exists; there is nothing to advance + // to yet even in the running state. + if (anim.frames.items.len == 0) continue; + + // Unplaced images don't animate. This is our simpler + // approximation of Kitty's "is actually drawn" visibility + // gate; it is what stops an image that was transmitted but + // never placed from waking the renderer forever. + if (img.metadata.placement_count == 0) continue; + + // The base pixel data hasn't arrived yet (e.g. an image + // restored from a snapshot); nothing can be displayed. + if (img.data.isPending()) continue; + + // A zero total duration means every frame is gapless and + // no frame can ever be displayed, so the animation can + // never advance. This also guards the gapless-skip loop + // below from never terminating. + if (anim.durationMs() == 0) continue; + + // A finite loop budget (a=a v=N) that ran out on an + // earlier tick froze playback on the last frame for good. + if (anim.max_loops > 0 and anim.current_loop >= anim.max_loops) continue; + + const shown_at: u64 = shown_at: { + // First tick since playback started (or since the + // current frame changed through another path, e.g. + // a=a c=N): the frame is considered shown as of now, + // and its gap starts counting from here. + const at = anim.frame_shown_at_ms orelse break :shown_at now_ms; + + // A timestamp from the future means the caller's clock + // restarted; re-anchor rather than stalling until the + // old timestamp comes around again. + if (at > now_ms) break :shown_at now_ms; + + break :shown_at at; + }; + anim.frame_shown_at_ms = shown_at; + + // The current frame is replaced once its gap has elapsed. + // We advance at most one displayed frame per tick with no + // catch-up, exactly like Kitty: if ticks lag behind the + // gaps, the animation slows down rather than skipping. + var next_at: u64 = shown_at +| anim.gapAt(anim.current_index); + if (now_ms >= next_at) advance: { + // Walk forward to the next displayable frame. This is + // a loop only because gapless (gap=0) frames are never + // displayed and are stepped over; the durationMs gate + // above guarantees a displayable frame exists. + const count: u32 = anim.frameCount(); + var idx = anim.current_index; + while (true) { + const next = (idx + 1) % count; + if (next == 0) { + // Wrapping past the last frame back to the + // root. A loading-state (a=a s=2) animation + // refuses the wrap: it parks on the last frame + // awaiting more frames from the client. + if (anim.state == .loading) break :advance; + + // Each wrap completes a loop; a finite budget + // that just ran out parks on the last frame. + anim.current_loop += 1; + if (anim.max_loops > 0 and + anim.current_loop >= anim.max_loops) break :advance; + } + idx = next; + if (anim.gapAt(idx) != 0) break; + } + + // Show the chosen frame: restart its gap timer and + // stamp a fresh generation so consumers (the renderer + // texture cache, the C API) pick up the new pixels. + anim.current_index = idx; + anim.frame_shown_at_ms = now_ms; + self.markImageContentChanged(io, img); + next_at = now_ms +| anim.gapAt(idx); + } + + // Schedule the next tick. A parked animation left next_at + // in the past and so never schedules one; it is woken by + // its trigger instead (a new frame arriving, or an a=a + // command changing the state). + if (next_at > now_ms) { + const delay = next_at - now_ms; + min_delay = if (min_delay) |m| @min(m, delay) else delay; + } + } + + return min_delay; + } + + /// Clear placements intersecting the active screen, then reclaim every + /// image with no remaining placement. Unlike protocol d=A, a terminal + /// clear also reclaims images that were already unplaced. + pub fn clearScreen( + self: *ImageStorage, + io: std.Io, + alloc: Allocator, + t: *terminal.Terminal, + ) void { + const placements_before = self.placements.count(); + const images_before = self.images.count(); + + // Delete unused placements and images. Orphaned relative + // placements must be reaped before the image sweep so that + // their images are reclaimable too. + self.deleteVisiblePlacements(alloc, t, true); + _ = self.removeOrphans(t.screens.active, null); + var image_it = self.images.iterator(); + while (image_it.next()) |entry| { + self.deleteIfUnused(alloc, entry.key_ptr.*); + } + + // Mark mutated only if things changed. + if (self.placements.count() != placements_before or + self.images.count() != images_before) self.markMutated(io); + } + /// Delete placements, images. pub fn delete( self: *ImageStorage, + io: std.Io, alloc: Allocator, t: *terminal.Terminal, - cmd: command.Delete, + cmd: command.Delete.Action, ) void { // Deletes only ever remove placements/images, so comparing counts // before and after tells us whether anything actually changed. - // Only then do we mark a mutation. This matters because a - // delete-all runs on every screen clear (e.g. `ESC [ 2 J`), and - // we don't want empty clears to dirty the image state or bump - // the generation. + // Only then do we mark a mutation, so a delete that matches nothing + // doesn't dirty the image state or bump the generation. const placements_before = self.placements.count(); const images_before = self.images.count(); defer if (self.placements.count() != placements_before or - self.images.count() != images_before) self.markMutated(); + self.images.count() != images_before) self.markMutated(io); switch (cmd) { - .all => |delete_images| { - var it = self.placements.iterator(); - while (it.next()) |entry| { - // Skip virtual placements - switch (entry.value_ptr.location) { - .pin => {}, - .virtual => continue, - } - - // Deinit the placement and remove it - const image_id = entry.key_ptr.image_id; - entry.value_ptr.deinit(t.screens.active); - self.placements.removeByPtr(entry.key_ptr); - if (delete_images) self.deleteIfUnused(alloc, image_id); - } - - if (delete_images) { - var image_it = self.images.iterator(); - while (image_it.next()) |kv| self.deleteIfUnused(alloc, kv.key_ptr.*); - } - }, + .all => |delete_images| self.deleteVisiblePlacements( + alloc, + t, + delete_images, + ), .id => |v| self.deleteById( alloc, @@ -435,8 +1301,7 @@ pub const ImageStorage = struct { const img = self.imageById(entry.key_ptr.image_id) orelse continue; const rect = entry.value_ptr.rect(img, t) orelse continue; if (rect.top_left.x <= x and rect.bottom_right.x >= x) { - entry.value_ptr.deinit(t.screens.active); - self.placements.removeByPtr(entry.key_ptr); + self.removePlacement(t.screens.active, entry); if (v.delete) self.deleteIfUnused(alloc, img.id); } } @@ -464,8 +1329,7 @@ pub const ImageStorage = struct { var target_pin_copy = target_pin; target_pin_copy.x = rect.top_left.x; if (target_pin_copy.isBetween(rect.top_left, rect.bottom_right)) { - entry.value_ptr.deinit(t.screens.active); - self.placements.removeByPtr(entry.key_ptr); + self.removePlacement(t.screens.active, entry); if (v.delete) self.deleteIfUnused(alloc, img.id); } } @@ -475,7 +1339,9 @@ pub const ImageStorage = struct { var it = self.placements.iterator(); while (it.next()) |entry| { switch (entry.value_ptr.location) { - .pin => {}, + // Relative placements carry their own z value and + // are matched by z deletes just like kitty does. + .pin, .relative => {}, // Virtual placeholders cannot delete by z according // to the spec. @@ -484,37 +1350,99 @@ pub const ImageStorage = struct { if (entry.value_ptr.z == v.z) { const image_id = entry.key_ptr.image_id; - entry.value_ptr.deinit(t.screens.active); - self.placements.removeByPtr(entry.key_ptr); + self.removePlacement(t.screens.active, entry); if (v.delete) self.deleteIfUnused(alloc, image_id); } } }, .range => |v| range: { - if (v.first <= 0 or v.last <= 0) { - log.warn("delete range values must be greater than zero", .{}); - break :range; - } - if (v.first > v.last) { - log.warn("delete range 'x' ({}) must be less than or equal to 'y' ({})", .{ v.first, v.last }); - break :range; + // Both bounds default to zero when omitted. An inverted range + // or a zero upper bound is not an error, it just selects + // nothing: image IDs are always non-zero. + if (v.last == 0 or v.first > v.last) break :range; + + // Remove matching placements in one pass. + var placement_it = self.placements.iterator(); + while (placement_it.next()) |entry| { + if (entry.key_ptr.image_id < v.first or + entry.key_ptr.image_id > v.last) continue; + + self.removePlacement(t.screens.active, entry); } - var it = self.placements.iterator(); - while (it.next()) |entry| { - if (entry.key_ptr.image_id >= v.first or entry.key_ptr.image_id <= v.last) { - const image_id = entry.key_ptr.image_id; - entry.value_ptr.deinit(t.screens.active); - self.placements.removeByPtr(entry.key_ptr); - if (v.delete) self.deleteIfUnused(alloc, image_id); + // Uppercase deletion also frees matching images that are now + // unused, including images that had no placements initially. + if (!v.delete) break :range; + var image_it = self.images.iterator(); + while (image_it.next()) |entry| { + const image_id = entry.key_ptr.*; + if (image_id >= v.first and image_id <= v.last) { + self.deleteIfUnused(alloc, image_id); } } }, - // We don't support animation frames yet so they are successfully - // deleted! - .animation_frames => {}, + .animation_frames => |v| self.deleteAnimationFrame( + io, + alloc, + t.screens.active, + v, + ), + } + + // Deleting placements orphans any relative placements parented + // to them (transitively). Their lifetime is tied to the parent + // so they are removed as well, and an uppercase delete also + // frees any image the cascade leaves without placements (the + // per-branch deleteIfUnused calls above ran while the orphans + // still counted as placements). + const delete_unused: bool = switch (cmd) { + .all, .intersect_cursor => |v| v, + inline else => |v| v.delete, + }; + _ = self.removeOrphans( + t.screens.active, + if (delete_unused) alloc else null, + ); + } + + /// Delete only non-virtual placements that intersect the active screen. + /// The protocol defines d=a/A in terms of visible placements, and an + /// uppercase delete only frees data for images selected by those + /// placements. + fn deleteVisiblePlacements( + self: *ImageStorage, + alloc: Allocator, + t: *terminal.Terminal, + delete_unused: bool, + ) void { + var it = self.placements.iterator(); + while (it.next()) |entry| { + const pin = switch (entry.value_ptr.location) { + .pin => |pin| pin, + // Virtual placements are never selected by visible + // deletes per the protocol. Relative placements are + // removed with their parents instead (removeOrphans). + .virtual, .relative => continue, + }; + if (pin.garbage) continue; + + // Placements anchored in the active area are necessarily visible. + // Only compute their extent when the anchor is already in history + // and the bottom edge may still intersect the active area. + if (t.screens.active.pages.pointFromPin( + .active, + pin.*, + ) == null) { + const image = self.imageById(entry.key_ptr.image_id) orelse continue; + const rect = entry.value_ptr.rect(image, t) orelse continue; + if (t.screens.active.pages.pointFromPin(.active, rect.bottom_right) == null) continue; + } + + const image_id = entry.key_ptr.image_id; + self.removePlacement(t.screens.active, entry); + if (delete_unused) self.deleteIfUnused(alloc, image_id); } } @@ -526,47 +1454,124 @@ pub const ImageStorage = struct { placement_id: u32, delete_unused: bool, ) void { + var matched = placement_id == 0; + // If no placement, we delete all placements with the ID - if (placement_id == 0) { - var it = self.placements.iterator(); - while (it.next()) |entry| { - if (entry.key_ptr.image_id == image_id) { - entry.value_ptr.deinit(s); - self.placements.removeByPtr(entry.key_ptr); - } - } - } else { - if (self.placements.getEntry(.{ - .image_id = image_id, - .placement_id = .{ .tag = .external, .id = placement_id }, - })) |entry| { - entry.value_ptr.deinit(s); - self.placements.removeByPtr(entry.key_ptr); - } + if (placement_id == 0) self.removePlacementsByImageId( + s, + image_id, + ) else if (self.placements.getEntry(.{ + .image_id = image_id, + .placement_id = .{ + .tag = .external, + .id = placement_id, + }, + })) |entry| { + self.removePlacement(s, entry); + matched = true; } - // If this is specified, then we also delete the image - // if it is no longer in use. - if (delete_unused) self.deleteIfUnused(alloc, image_id); + // A placement ID narrows the selection to that exact placement, so an + // unmatched selector must not free otherwise-unreferenced image data. + // https://sw.kovidgoyal.net/kitty/graphics-protocol/#deleting-images + if (delete_unused and matched) self.deleteIfUnused(alloc, image_id); } - /// Delete an image if it is unused. - fn deleteIfUnused(self: *ImageStorage, alloc: Allocator, image_id: u32) void { - var it = self.placements.iterator(); - while (it.next()) |kv| { - if (kv.key_ptr.image_id == image_id) { - return; - } + /// Delete an animation frame (d=f/F). Deletes never produce + /// responses, so all failures are only logged. Kitty behaviors + /// implemented here: on an image without extra frames a lowercase + /// delete is a no-op while an uppercase delete removes the entire + /// image, placements included; the frame number is clamped to the + /// last frame and zero selects the root frame; deleting the root + /// frame promotes frame 2 to be the new root. + fn deleteAnimationFrame( + self: *ImageStorage, + io: std.Io, + alloc: Allocator, + s: *terminal.Screen, + v: command.Delete.Action.AnimationFrames, + ) void { + if (v.image_id == 0 and v.image_number == 0) { + log.warn("delete animation frames requires image id or number", .{}); + return; } + const img = self.imagePtrByIdOrNumber( + v.image_id, + v.image_number, + ) orelse { + log.warn( + "delete animation frames for unknown image id={} number={}", + .{ v.image_id, v.image_number }, + ); + return; + }; + + const anim: *animation.Animation = anim: { + if (img.animation) |anim| { + if (anim.frames.items.len > 0) break :anim anim; + } - // If we get here, we can delete the image. - if (self.images.getEntry(image_id)) |entry| { - self.total_bytes -= entry.value_ptr.data.len; + // The image is not (or no longer) an animation. The + // uppercase delete removes the entire image, even when it + // still has placements. + if (!v.delete) return; + self.removePlacementsByImageId(s, img.id); + const entry = self.images.getEntry(img.id).?; + self.total_bytes -= entry.value_ptr.storageSize(); entry.value_ptr.deinit(alloc); self.images.removeByPtr(entry.key_ptr); + return; + }; + + // Clamp the frame number: zero selects the root frame and + // values past the end select the last frame. + const count: u32 = anim.frameCount(); + var number: u32 = @min(v.frame, count); + if (number == 0) number = 1; + + if (number == 1) { + // Deleting the root frame promotes frame 2 to root. The + // promoted frame's bytes stay reserved; only the old root + // data is freed. + self.releaseAnimationBytes(img.data.len()); + img.data.deinit(alloc); + const promoted = anim.frames.orderedRemove(0); + img.data = .{ .complete = promoted.data }; + anim.root_gap_ms = promoted.gap_ms; + } else { + const removed = anim.frames.orderedRemove(number - 2); + self.releaseAnimationBytes(removed.data.len); + alloc.free(removed.data); + } + + // Fix up the current frame. + const removed_idx: u32 = if (number == 1) 0 else number - 2; + const remaining: u32 = @intCast(anim.frames.items.len); + if (anim.current_index > remaining) { + anim.current_index = remaining; + anim.frame_shown_at_ms = null; + self.markImageContentChanged(io, img); + return; + } + if (removed_idx == anim.current_index) { + anim.frame_shown_at_ms = null; + self.markImageContentChanged(io, img); + } else { + if (removed_idx < anim.current_index) anim.current_index -= 1; + self.markMutated(io); } } + /// Delete an image if it is unused. + fn deleteIfUnused(self: *ImageStorage, alloc: Allocator, image_id: u32) void { + const entry = self.images.getEntry(image_id) orelse return; + if (entry.value_ptr.metadata.placement_count > 0) return; + + self.total_bytes -= entry.value_ptr.storageSize(); + entry.value_ptr.deinit(alloc); + self.images.removeByPtr(entry.key_ptr); + } + /// Deletes all placements intersecting a screen point. fn deleteIntersecting( self: *ImageStorage, @@ -584,133 +1589,173 @@ pub const ImageStorage = struct { while (it.next()) |entry| { const img = self.imageById(entry.key_ptr.image_id) orelse continue; const rect = entry.value_ptr.rect(img, t) orelse continue; - if (target_pin.isBetween(rect.top_left, rect.bottom_right)) { + if (rect.contains(target_pin)) { if (filter) |f| if (!f(filter_ctx, entry.value_ptr.*)) continue; - entry.value_ptr.deinit(t.screens.active); - self.placements.removeByPtr(entry.key_ptr); + self.removePlacement(t.screens.active, entry); if (delete_unused) self.deleteIfUnused(alloc, img.id); } } } /// Evict image to make space. This will evict the oldest image, - /// prioritizing unused images first, as recommended by the published - /// Kitty spec. + /// prioritizing transient images and unused images as recommended by the + /// published Kitty spec. /// /// This will evict as many images as necessary to make space for /// req bytes. - fn evictImage(self: *ImageStorage, alloc: Allocator, req: usize) !bool { + fn evictImage( + self: *ImageStorage, + io: std.Io, + alloc: Allocator, + s: *terminal.Screen, + req: usize, + ) bool { + return self.evictImageExcept(io, alloc, s, req, null); + } + + /// Evict images while preserving `exclude_id`, used when replacing an + /// existing image whose old reservation has already been credited. + fn evictImageExcept( + self: *ImageStorage, + io: std.Io, + alloc: Allocator, + s: *terminal.Screen, + req: usize, + exclude_id: ?u32, + ) bool { assert(req <= self.total_limit); - // Ironically we allocate to evict. We should probably redesign the - // data structures to avoid this but for now allocating a little - // bit is fine compared to the megabytes we're looking to save. const Candidate = struct { id: u32, generation: u64, - used: bool, - }; - var candidates: std.ArrayList(Candidate) = .empty; - defer candidates.deinit(alloc); + // Lower values are evicted first: + // 0: transient, unused + // 1: not transient, unused + // 2: transient, used + // 3: not transient, used + priority: u2, - var it = self.images.iterator(); - while (it.next()) |kv| { - const img = kv.value_ptr; - - // This is a huge waste. See comment above about redesigning - // our data structures to avoid this. Eviction should be very - // rare though and we never have that many images/placements - // so hopefully this will last a long time. - const used = used: { - var p_it = self.placements.iterator(); - while (p_it.next()) |p_kv| { - if (p_kv.key_ptr.image_id == img.id) { - break :used true; - } - } - - break :used false; - }; - - try candidates.append(alloc, .{ - .id = img.id, - .generation = img.generation, - .used = used, - }); - } + fn init(img: *const Image) @This() { + return .{ + .id = img.id, + .generation = img.generation, + .priority = (if (img.metadata.transient) @as(u2, 0) else @as(u2, 1)) + + (if (img.metadata.placement_count > 0) @as(u2, 2) else @as(u2, 0)), + }; + } - // Sort - std.mem.sortUnstable( - Candidate, - candidates.items, - {}, - struct { - fn lessThan( - ctx: void, - lhs: Candidate, - rhs: Candidate, - ) bool { - _ = ctx; - - // If their usage matches, then it's based on the - // generation stamp, which orders by transmit time. - // (Stamps are unique but tie-break by ID anyway to - // stay deterministic for hand-built test images.) - if (lhs.used == rhs.used) return if (lhs.generation == rhs.generation) - lhs.id < rhs.id - else - lhs.generation < rhs.generation; - - // If not used, then its a better candidate - return !lhs.used; - } - }.lessThan, - ); + fn lessThan(lhs: @This(), rhs: @This()) bool { + if (lhs.priority != rhs.priority) + return lhs.priority < rhs.priority; + if (lhs.generation != rhs.generation) + return lhs.generation < rhs.generation; + return lhs.id < rhs.id; + } + }; // Evicting anything is a content mutation. This matters for the // setLimit path in particular, which doesn't otherwise mark it. - var any_evicted = false; - defer if (any_evicted) self.markMutated(); + // Evicted placements can also orphan relative placements of + // other images, which must be reaped along with them. + const images_before = self.images.count(); + defer if (self.images.count() != images_before) { + _ = self.removeOrphans(s, null); + self.markMutated(io); + }; - // They're in order of best to evict. var evicted: usize = 0; - for (candidates.items) |c| { - // Delete all the placements for this image and the image. + while (evicted < req) { + const c = candidate: { + var best: ?Candidate = null; + var it = self.images.iterator(); + while (it.next()) |kv| { + const img = kv.value_ptr; + if (exclude_id != null and img.id == exclude_id.?) continue; + + const current = Candidate.init(img); + if (best == null or current.lessThan(best.?)) best = current; + } + break :candidate best orelse return false; + }; + var p_it = self.placements.iterator(); while (p_it.next()) |entry| { if (entry.key_ptr.image_id == c.id) { - self.placements.removeByPtr(entry.key_ptr); - any_evicted = true; + self.removePlacement(s, entry); } } - if (self.images.getEntry(c.id)) |entry| { - log.info("evicting image id={} bytes={}", .{ c.id, entry.value_ptr.data.len }); + const entry = self.images.getEntry(c.id).?; + const image_len = entry.value_ptr.storageSize(); + log.info("evicting image id={} bytes={}", .{ c.id, image_len }); - evicted += entry.value_ptr.data.len; - self.total_bytes -= entry.value_ptr.data.len; + evicted += image_len; + self.total_bytes -= image_len; - entry.value_ptr.deinit(alloc); - self.images.removeByPtr(entry.key_ptr); - any_evicted = true; - - if (evicted > req) return true; - } + entry.value_ptr.deinit(alloc); + self.images.removeByPtr(entry.key_ptr); } - return false; + return true; } + /// State returned by scrollMarginsBegin: the final active-area + /// position every surviving placement pin must be restored to once + /// the scrolled rows have settled. Every begin must be paired with + /// exactly one end() call after the scroll's row operations + /// complete. + pub const ScrollMargins = struct { + screen: *terminal.Screen, + restores: std.ArrayListUnmanaged(Restore) = .empty, + + const Restore = struct { + pin: *PageList.Pin, + x: size.CellCountInt, + y: u32, + }; + + /// Reposition every recorded placement pin to its post-scroll + /// position and release the state. Must be called exactly + /// once, after the scroll's row operations complete. + pub fn end(self: *ScrollMargins) void { + for (self.restores.items) |restore| { + restore.pin.* = self.screen.pages.pin(.{ .active = .{ + .x = restore.x, + .y = restore.y, + } }) orelse continue; + } + self.restores.deinit(self.screen.alloc); + } + }; + /// Every placement is uniquely identified by the image ID and the /// placement ID. If an image ID isn't specified it is assumed to be 0. /// Likewise, if a placement ID isn't specified it is assumed to be 0. pub const PlacementKey = struct { image_id: u32, - placement_id: packed struct { - tag: enum(u1) { internal, external }, - id: u32, - }, + placement_id: PlacementId, + + pub fn eql(self: PlacementKey, other: PlacementKey) bool { + return std.meta.eql(self, other); + } + }; + + /// Internal placement IDs are assigned by us for placements created + /// without an explicit ID (p=0); external IDs are client-specified. + /// The two are separate namespaces, hence the tag. + pub const PlacementId = packed struct { + tag: enum(u1) { internal, external }, + id: u32, + + /// Deterministic preference order used when an operation must + /// pick a single placement out of several (kitty uses creation + /// order, which our map doesn't track): external IDs win over + /// internal ones, and lower IDs win within a tag. + pub fn preferredOver(self: PlacementId, other: PlacementId) bool { + if (self.tag != other.tag) return self.tag == .external; + return self.id < other.id; + } }; pub const Placement = struct { @@ -739,7 +1784,27 @@ pub const ImageStorage = struct { pin: *PageList.Pin, /// Virtual placement (U=1) for unicode placeholders. - virtual: void, + virtual, + + /// Placed relative to a parent placement (P=/Q=). The + /// placement has no screen position of its own; it is + /// positioned at render time by resolving the parent chain + /// to its root (see resolveChain) and therefore follows the + /// parent through scrolls automatically. Its lifetime is + /// tied to the parent: removing any ancestor removes it + /// too (see removeOrphans). + relative: Relative, + }; + + pub const Relative = struct { + /// The parent placement. Resolved to a concrete key when + /// the placement is created, so the parent is guaranteed + /// to exist at that point. + parent: PlacementKey, + + /// Cell offsets from the parent's origin (H=/V=). + horizontal_offset: i32 = 0, + vertical_offset: i32 = 0, }; pub fn deinit( @@ -748,10 +1813,80 @@ pub const ImageStorage = struct { ) void { switch (self.location) { .pin => |p| s.pages.untrackPin(p), - .virtual => {}, + .virtual, .relative => {}, } } + /// Multiply two protocol-controlled values without allowing them to + /// wrap. Placement geometry is exposed as u32, so values larger than + /// that are represented by the largest possible value. + fn saturatingMul(lhs: u32, rhs: u32) u32 { + return std.math.mul(u32, lhs, rhs) catch std.math.maxInt(u32); + } + + /// Scale a dimension by an aspect ratio and round to the nearest + /// integer. The u64 intermediate can hold the product of two u32s as + /// well as the rounding adjustment. + fn scaleDimension(value: u32, numerator: u32, denominator: u32) u32 { + if (denominator == 0) return 0; + + const rounded = (@as(u64, value) * @as(u64, numerator) + + @as(u64, denominator) / 2) / @as(u64, denominator); + return std.math.cast(u32, rounded) orelse std.math.maxInt(u32); + } + + pub const SourceRect = struct { + x: u32, + y: u32, + width: u32, + height: u32, + }; + + /// Returns the requested source rectangle intersected with the image. + /// A zero width or height requests the full corresponding image + /// dimension before intersection, as defined by the Kitty protocol. + pub fn sourceRect(self: Placement, image: Image) SourceRect { + const x = @min(self.source_x, image.width); + const y = @min(self.source_y, image.height); + return .{ + .x = x, + .y = y, + .width = @min( + if (self.source_width > 0) self.source_width else image.width, + image.width - x, + ), + .height = @min( + if (self.source_height > 0) self.source_height else image.height, + image.height - y, + ), + }; + } + + /// Returns the placement offset clamped within the first cell. Pixel + /// geometry may temporarily be unavailable, in which case there is no + /// valid offset within the cell. + pub fn cellOffset( + self: Placement, + t: *const terminal.Terminal, + ) struct { + x: u32, + y: u32, + } { + const cell_width: u32 = t.width_px / t.cols; + const cell_height: u32 = t.height_px / t.rows; + + return .{ + .x = if (cell_width > 0) + @min(self.x_offset, cell_width - 1) + else + 0, + .y = if (cell_height > 0) + @min(self.y_offset, cell_height - 1) + else + 0, + }; + } + /// Returns the size of this placement's image in pixels, /// taking into account the source rectangle, specified /// rows/columns, and aspect ratio. @@ -763,9 +1898,9 @@ pub const ImageStorage = struct { width: u32, height: u32, } { - // Height / width of the image in px. - const width = if (self.source_width > 0) self.source_width else image.width; - const height = if (self.source_height > 0) self.source_height else image.height; + const source = self.sourceRect(image); + const width = source.width; + const height = source.height; // If we don't have any specified cols or rows then the placement // should be the native size of the image, and doesn't need to be @@ -782,20 +1917,18 @@ pub const ImageStorage = struct { // count and the height by the row count, because it should be. const cell_width: u32 = t.width_px / t.cols; const cell_height: u32 = t.height_px / t.rows; - - const width_f64: f64 = @floatFromInt(width); - const height_f64: f64 = @floatFromInt(height); + const cell_offset = self.cellOffset(t); // If we have a specified cols AND rows then we calculate // the width and height from them directly, we don't need // to adjust for aspect ratio. if (self.columns > 0 and self.rows > 0) { - const calc_width = cell_width * self.columns; - const calc_height = cell_height * self.rows; + const calc_width = saturatingMul(cell_width, self.columns); + const calc_height = saturatingMul(cell_height, self.rows); return .{ - .width = calc_width, - .height = calc_height, + .width = calc_width -| cell_offset.x, + .height = calc_height -| cell_offset.y, }; } @@ -805,11 +1938,11 @@ pub const ImageStorage = struct { // If only the columns were specified, we determine // the height of the image based on the aspect ratio. if (self.columns > 0) { - const aspect = height_f64 / width_f64; - const calc_width: u32 = cell_width * self.columns; - const calc_height: u32 = @intFromFloat(@round( - @as(f64, @floatFromInt(calc_width)) * aspect, - )); + const calc_width = saturatingMul( + cell_width, + self.columns, + ) -| cell_offset.x; + const calc_height = scaleDimension(calc_width, height, width); return .{ .width = calc_width, @@ -820,11 +1953,11 @@ pub const ImageStorage = struct { // Otherwise, only the rows were specified, so we // determine the width based on the aspect ratio. { - const aspect = width_f64 / height_f64; - const calc_height: u32 = cell_height * self.rows; - const calc_width: u32 = @intFromFloat(@round( - @as(f64, @floatFromInt(calc_height)) * aspect, - )); + const calc_height = saturatingMul( + cell_height, + self.rows, + ) -| cell_offset.y; + const calc_width = scaleDimension(calc_height, width, height); return .{ .width = calc_width, @@ -851,15 +1984,16 @@ pub const ImageStorage = struct { // Otherwise we calculate the pixel size, divide by // cell size, and round up to the nearest integer. const calc_size = self.pixelSize(image, t); + const cell_offset = self.cellOffset(t); return .{ .cols = std.math.divCeil( u32, - calc_size.width + self.x_offset, + calc_size.width +| cell_offset.x, t.width_px / t.cols, ) catch 0, .rows = std.math.divCeil( u32, - calc_size.height + self.y_offset, + calc_size.height +| cell_offset.y, t.height_px / t.rows, ) catch 0, }; @@ -867,9 +2001,82 @@ pub const ImageStorage = struct { // in such a case it seems safe to return 0 for this. } + /// Permanently clip `count` rows off the top of this placement, + /// which currently spans `span` grid rows, by shrinking the + /// source rectangle (the requested source rect is materialized + /// into explicit values in the process). Used when a scroll + /// within margins pushes the placement past the top margin. + /// Requires 0 < count < span. Returns false if no visible + /// source pixels would remain, in which case the placement is + /// unmodified and should be deleted. + fn clipTop( + self: *Placement, + image: Image, + t: *const terminal.Terminal, + count: u32, + span: u32, + ) bool { + assert(count > 0 and count < span); + const src = self.sourceRect(image); + const crop: u32 = if (self.rows > 0) + // Scaled placement: each grid row shows an equal + // fraction of the source. + @intCast(@as(u64, src.height) * count / span) + else + // Native size: each grid row shows one cell height of + // source pixels (kitty does the same). + saturatingMul(t.height_px / t.rows, count); + if (crop >= src.height) return false; + self.source_x = src.x; + self.source_y = src.y + crop; + self.source_width = src.width; + self.source_height = src.height - crop; + if (self.rows > 0) self.rows -= count; + return true; + } + + /// clipTop, but clipping `count` rows off the bottom. + fn clipBottom( + self: *Placement, + image: Image, + t: *const terminal.Terminal, + count: u32, + span: u32, + ) bool { + assert(count > 0 and count < span); + const src = self.sourceRect(image); + // An empty source can never be clipped smaller. This also + // guarantees we never store an explicit zero source height, + // which would be reinterpreted as "full image". + if (src.height == 0) return false; + if (self.rows > 0) { + const crop: u32 = @intCast(@as(u64, src.height) * count / span); + if (crop >= src.height) return false; + self.source_height = src.height - crop; + self.rows -= count; + } else { + // The remaining rows can show this many source pixels, + // with the first cell losing cellOffset pixels to the + // placement's y offset. + const visible = saturatingMul(t.height_px / t.rows, span - count); + const offset = self.cellOffset(t).y; + if (visible <= offset) return false; + self.source_height = @min(src.height, visible - offset); + } + self.source_x = src.x; + self.source_y = src.y; + self.source_width = src.width; + return true; + } + /// Returns a selection of the entire rectangle this placement - /// occupies within the screen. This can return null if the placement - /// doesn't have an associated rect (i.e. a virtual placement). + /// occupies within the screen. This can return null for a virtual + /// placement or when unavailable pixel geometry makes it empty. + /// + /// Relative placements also return null: they have no screen + /// position of their own, so geometric queries (delete by + /// intersection, row, column, etc.) never match them directly. + /// They are instead removed when their parent chain is removed. pub fn rect( self: Placement, image: Image, @@ -878,20 +2085,25 @@ pub const ImageStorage = struct { const grid_size = self.gridSize(image, t); const pin = switch (self.location) { .pin => |p| p, - .virtual => return null, + .virtual, .relative => return null, }; + if (pin.garbage) return null; + + // A zero pixel-sized placement can produce a zero grid size when + // pixel geometry is unavailable. It occupies no rectangle. + if (grid_size.cols == 0 or grid_size.rows == 0) return null; var br = switch (pin.downOverflow(grid_size.rows - 1)) { .offset => |v| v, .overflow => |v| v.end, }; - br.x = @min( + br.x = @intCast(@min( // We need to sub one here because the x value is // one width already. So if the image is width "1" // then we add zero to X because X itself is width 1. - pin.x + (grid_size.cols - 1), - t.cols - 1, - ); + @as(u32, pin.x) +| (grid_size.cols - 1), + @as(u32, t.cols) - 1, + )); return .{ .top_left = pin.*, @@ -914,17 +2126,18 @@ fn trackPin( test "storage: add placement with zero placement id" { const testing = std.testing; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .cols = 100, .rows = 100 }); + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 100, .rows = 100 }); defer t.deinit(alloc); t.width_px = 100; t.height_px = 100; var s: ImageStorage = .{}; defer s.deinit(alloc, t.screens.active); - try s.addImage(alloc, .{ .id = 1, .width = 50, .height = 50 }); - try s.addImage(alloc, .{ .id = 2, .width = 25, .height = 25 }); - try s.addPlacement(alloc, 1, 0, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 25, .y = 25 }) } }); - try s.addPlacement(alloc, 1, 0, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 25, .y = 25 }) } }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1, .width = 50, .height = 50 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2, .width = 25, .height = 25 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 0, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 25, .y = 25 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 1, 0, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 25, .y = 25 }) } }); try testing.expectEqual(@as(usize, 2), s.placements.count()); try testing.expectEqual(@as(usize, 2), s.images.count()); @@ -940,25 +2153,124 @@ test "storage: add placement with zero placement id" { }) != null); } -test "storage: delete all placements and images" { +test "storage: replacing placement releases tracked pin" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 3, .rows = 3 }); + defer t.deinit(alloc); + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + + const tracked = t.screens.active.pages.countTrackedPins(); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) }, + }); + try testing.expectEqual( + tracked + 1, + t.screens.active.pages.countTrackedPins(), + ); + + const replacement_pin = try trackPin(&t, .{ .x = 2, .y = 2 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .pin = replacement_pin }, + }); + try testing.expectEqual(@as(usize, 1), s.placements.count()); + try testing.expectEqual( + tracked + 1, + t.screens.active.pages.countTrackedPins(), + ); + try testing.expectEqual( + replacement_pin, + s.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }).?.location.pin, + ); +} + +test "storage: adding placement reclaims garbage placements" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 3, .rows = 3 }); + defer t.deinit(alloc); + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + + const tracked = t.screens.active.pages.countTrackedPins(); + const old_pin = try trackPin(&t, .{ .x = 0, .y = 0 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 0, .{ + .location = .{ .pin = old_pin }, + }); + old_pin.garbage = true; + + const new_pin = try trackPin(&t, .{ .x = 1, .y = 1 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 0, .{ + .location = .{ .pin = new_pin }, + }); + + try testing.expectEqual(@as(usize, 1), s.placements.count()); + try testing.expectEqual( + tracked + 1, + t.screens.active.pages.countTrackedPins(), + ); + try testing.expectEqual( + new_pin, + s.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .internal, .id = 1 }, + }).?.location.pin, + ); +} + +test "storage: placement count limit permits replacement" { const testing = std.testing; + const io = testing.io; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 3, .cols = 3 }); + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); + defer t.deinit(alloc); + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .virtual = {} } }); + + const img = s.images.getPtr(1).?; + img.metadata.placement_count = std.math.maxInt(@TypeOf(img.metadata.placement_count)); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .virtual = {} } }); + try testing.expectError( + error.OutOfMemory, + s.addPlacement(io, alloc, t.screens.active, 1, 2, .{ .location = .{ .virtual = {} } }), + ); + try testing.expectEqual(@as(usize, 1), s.placements.count()); +} + +test "storage: delete all visible placements and matching images" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); defer t.deinit(alloc); const tracked = t.screens.active.pages.countTrackedPins(); var s: ImageStorage = .{}; defer s.deinit(alloc, t.screens.active); - try s.addImage(alloc, .{ .id = 1 }); - try s.addImage(alloc, .{ .id = 2 }); - try s.addImage(alloc, .{ .id = 3 }); - try s.addPlacement(alloc, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); - try s.addPlacement(alloc, 2, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 3 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 2, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); s.dirty = false; - s.delete(alloc, &t, .{ .all = true }); + s.delete(io, alloc, &t, .{ .all = true }); try testing.expect(s.dirty); - try testing.expectEqual(@as(usize, 0), s.images.count()); + try testing.expectEqual(@as(usize, 1), s.images.count()); + try testing.expect(s.images.contains(3)); try testing.expectEqual(@as(usize, 0), s.placements.count()); try testing.expectEqual(tracked, t.screens.active.pages.countTrackedPins()); } @@ -966,45 +2278,133 @@ test "storage: delete all placements and images" { test "storage: delete all placements and images preserves limit" { const testing = std.testing; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 3, .cols = 3 }); + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); defer t.deinit(alloc); const tracked = t.screens.active.pages.countTrackedPins(); var s: ImageStorage = .{}; defer s.deinit(alloc, t.screens.active); s.total_limit = 5000; - try s.addImage(alloc, .{ .id = 1 }); - try s.addImage(alloc, .{ .id = 2 }); - try s.addImage(alloc, .{ .id = 3 }); - try s.addPlacement(alloc, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); - try s.addPlacement(alloc, 2, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 3 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 2, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); s.dirty = false; - s.delete(alloc, &t, .{ .all = true }); + s.delete(io, alloc, &t, .{ .all = true }); try testing.expect(s.dirty); - try testing.expectEqual(@as(usize, 0), s.images.count()); + try testing.expectEqual(@as(usize, 1), s.images.count()); + try testing.expect(s.images.contains(3)); try testing.expectEqual(@as(usize, 0), s.placements.count()); try testing.expectEqual(@as(usize, 5000), s.total_limit); try testing.expectEqual(tracked, t.screens.active.pages.countTrackedPins()); } +test "storage: delete all visible placements preserves scrollback" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ + .rows = 2, + .cols = 2, + .max_scrollback_bytes = 4096, + }); + defer t.deinit(alloc); + t.width_px = 2; + t.height_px = 2; + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1, .width = 1, .height = 1 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .y = 0 }) }, + }); + try t.scrollUp(1); + + const history_key: ImageStorage.PlacementKey = .{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }; + try testing.expect(t.screens.active.pages.pointFromPin( + .active, + s.placements.get(history_key).?.location.pin.*, + ) == null); + + try s.addPlacement(io, alloc, t.screens.active, 1, 2, .{ + .location = .{ .pin = try trackPin(&t, .{ .y = 0 }) }, + }); + + s.delete(io, alloc, &t, .{ .all = true }); + try testing.expectEqual(@as(usize, 1), s.placements.count()); + try testing.expect(s.placements.contains(history_key)); + try testing.expectEqual(@as(usize, 1), s.images.count()); + try testing.expect(s.images.contains(1)); +} + +test "storage: delete all includes placements spanning into active area" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ + .rows = 2, + .cols = 2, + .max_scrollback_bytes = 4096, + }); + defer t.deinit(alloc); + t.width_px = 2; + t.height_px = 2; + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + try s.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .width = 1, + .height = 2, + }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .y = 0 }) }, + }); + try t.scrollUp(1); + + const placement = s.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }).?; + try testing.expect(t.screens.active.pages.pointFromPin( + .active, + placement.location.pin.*, + ) == null); + const rect = placement.rect(s.imageById(1).?, &t).?; + try testing.expect(t.screens.active.pages.pointFromPin( + .active, + rect.bottom_right, + ) != null); + + s.delete(io, alloc, &t, .{ .all = true }); + try testing.expectEqual(@as(usize, 0), s.placements.count()); + try testing.expectEqual(@as(usize, 0), s.images.count()); +} + test "storage: delete all placements" { const testing = std.testing; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 3, .cols = 3 }); + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); defer t.deinit(alloc); const tracked = t.screens.active.pages.countTrackedPins(); var s: ImageStorage = .{}; defer s.deinit(alloc, t.screens.active); - try s.addImage(alloc, .{ .id = 1 }); - try s.addImage(alloc, .{ .id = 2 }); - try s.addImage(alloc, .{ .id = 3 }); - try s.addPlacement(alloc, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); - try s.addPlacement(alloc, 2, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 3 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 2, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); s.dirty = false; - s.delete(alloc, &t, .{ .all = false }); + s.delete(io, alloc, &t, .{ .all = false }); try testing.expect(s.dirty); try testing.expectEqual(@as(usize, 0), s.placements.count()); try testing.expectEqual(@as(usize, 3), s.images.count()); @@ -1014,20 +2414,21 @@ test "storage: delete all placements" { test "storage: delete all placements by image id" { const testing = std.testing; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 3, .cols = 3 }); + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); defer t.deinit(alloc); const tracked = t.screens.active.pages.countTrackedPins(); var s: ImageStorage = .{}; defer s.deinit(alloc, t.screens.active); - try s.addImage(alloc, .{ .id = 1 }); - try s.addImage(alloc, .{ .id = 2 }); - try s.addImage(alloc, .{ .id = 3 }); - try s.addPlacement(alloc, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); - try s.addPlacement(alloc, 2, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 3 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 2, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); s.dirty = false; - s.delete(alloc, &t, .{ .id = .{ .image_id = 2 } }); + s.delete(io, alloc, &t, .{ .id = .{ .image_id = 2 } }); try testing.expect(s.dirty); try testing.expectEqual(@as(usize, 1), s.placements.count()); try testing.expectEqual(@as(usize, 3), s.images.count()); @@ -1037,20 +2438,21 @@ test "storage: delete all placements by image id" { test "storage: delete all placements by image id and unused images" { const testing = std.testing; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 3, .cols = 3 }); + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); defer t.deinit(alloc); const tracked = t.screens.active.pages.countTrackedPins(); var s: ImageStorage = .{}; defer s.deinit(alloc, t.screens.active); - try s.addImage(alloc, .{ .id = 1 }); - try s.addImage(alloc, .{ .id = 2 }); - try s.addImage(alloc, .{ .id = 3 }); - try s.addPlacement(alloc, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); - try s.addPlacement(alloc, 2, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 3 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 2, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); s.dirty = false; - s.delete(alloc, &t, .{ .id = .{ .delete = true, .image_id = 2 } }); + s.delete(io, alloc, &t, .{ .id = .{ .delete = true, .image_id = 2 } }); try testing.expect(s.dirty); try testing.expectEqual(@as(usize, 1), s.placements.count()); try testing.expectEqual(@as(usize, 2), s.images.count()); @@ -1060,21 +2462,22 @@ test "storage: delete all placements by image id and unused images" { test "storage: delete placement by specific id" { const testing = std.testing; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 3, .cols = 3 }); + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); defer t.deinit(alloc); const tracked = t.screens.active.pages.countTrackedPins(); var s: ImageStorage = .{}; defer s.deinit(alloc, t.screens.active); - try s.addImage(alloc, .{ .id = 1 }); - try s.addImage(alloc, .{ .id = 2 }); - try s.addImage(alloc, .{ .id = 3 }); - try s.addPlacement(alloc, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); - try s.addPlacement(alloc, 1, 2, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); - try s.addPlacement(alloc, 2, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 3 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 1, 2, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 2, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); s.dirty = false; - s.delete(alloc, &t, .{ .id = .{ + s.delete(io, alloc, &t, .{ .id = .{ .delete = true, .image_id = 1, .placement_id = 2, @@ -1085,10 +2488,84 @@ test "storage: delete placement by specific id" { try testing.expectEqual(tracked + 2, t.screens.active.pages.countTrackedPins()); } +test "storage: uppercase id delete preserves image when placement does not match" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); + defer t.deinit(alloc); + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + + s.dirty = false; + const generation = s.generation; + s.delete(io, alloc, &t, .{ .id = .{ + .delete = true, + .image_id = 1, + .placement_id = 7, + } }); + + try testing.expect(s.imageById(1) != null); + try testing.expect(!s.dirty); + try testing.expectEqual(generation, s.generation); +} + +test "storage: uppercase id delete frees image after placement matches" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); + defer t.deinit(alloc); + const tracked = t.screens.active.pages.countTrackedPins(); + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 9, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) }, + }); + + s.dirty = false; + s.delete(io, alloc, &t, .{ .id = .{ + .delete = true, + .image_id = 1, + .placement_id = 9, + } }); + + try testing.expectEqual(@as(usize, 0), s.placements.count()); + try testing.expectEqual(@as(usize, 0), s.images.count()); + try testing.expect(s.dirty); + try testing.expectEqual(tracked, t.screens.active.pages.countTrackedPins()); +} + +test "storage: uppercase id delete without placement frees unplaced image" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); + defer t.deinit(alloc); + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + + s.dirty = false; + s.delete(io, alloc, &t, .{ .id = .{ + .delete = true, + .image_id = 1, + } }); + + try testing.expectEqual(@as(usize, 0), s.images.count()); + try testing.expect(s.dirty); +} + test "storage: delete intersecting cursor" { const testing = std.testing; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 100, .cols = 100 }); + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 100, .cols = 100 }); defer t.deinit(alloc); t.width_px = 100; t.height_px = 100; @@ -1096,15 +2573,15 @@ test "storage: delete intersecting cursor" { var s: ImageStorage = .{}; defer s.deinit(alloc, t.screens.active); - try s.addImage(alloc, .{ .id = 1, .width = 50, .height = 50 }); - try s.addImage(alloc, .{ .id = 2, .width = 25, .height = 25 }); - try s.addPlacement(alloc, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) } }); - try s.addPlacement(alloc, 1, 2, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 25, .y = 25 }) } }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1, .width = 50, .height = 50 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2, .width = 25, .height = 25 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 1, 2, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 25, .y = 25 }) } }); t.screens.active.cursorAbsolute(12, 12); s.dirty = false; - s.delete(alloc, &t, .{ .intersect_cursor = false }); + s.delete(io, alloc, &t, .{ .intersect_cursor = false }); try testing.expect(s.dirty); try testing.expectEqual(@as(usize, 1), s.placements.count()); try testing.expectEqual(@as(usize, 2), s.images.count()); @@ -1117,10 +2594,66 @@ test "storage: delete intersecting cursor" { }) != null); } +test "storage: delete intersecting cursor checks interior row column" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 100, .cols = 100 }); + defer t.deinit(alloc); + t.width_px = 100; + t.height_px = 100; + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1, .width = 10, .height = 10 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 1, 2, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 20, .y = 0 }) } }); + + // This is inside the right placement and on an interior row shared by + // both placements, but it is outside the left placement's columns. + t.screens.active.cursorAbsolute(21, 5); + s.delete(io, alloc, &t, .{ .intersect_cursor = false }); + + try testing.expectEqual(@as(usize, 1), s.placements.count()); + try testing.expect(s.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }) != null); +} + +test "storage: delete intersecting cell checks interior row column" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 100, .cols = 100 }); + defer t.deinit(alloc); + t.width_px = 100; + t.height_px = 100; + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1, .width = 10, .height = 10 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 1, 2, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 20, .y = 0 }) } }); + + // Protocol coordinates are one-based, so this targets grid cell (21, 5). + s.delete(io, alloc, &t, .{ .intersect_cell = .{ + .x = 22, + .y = 6, + } }); + + try testing.expectEqual(@as(usize, 1), s.placements.count()); + try testing.expect(s.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }) != null); +} + test "storage: delete intersecting cursor plus unused" { const testing = std.testing; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 100, .cols = 100 }); + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 100, .cols = 100 }); defer t.deinit(alloc); t.width_px = 100; t.height_px = 100; @@ -1128,15 +2661,15 @@ test "storage: delete intersecting cursor plus unused" { var s: ImageStorage = .{}; defer s.deinit(alloc, t.screens.active); - try s.addImage(alloc, .{ .id = 1, .width = 50, .height = 50 }); - try s.addImage(alloc, .{ .id = 2, .width = 25, .height = 25 }); - try s.addPlacement(alloc, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) } }); - try s.addPlacement(alloc, 1, 2, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 25, .y = 25 }) } }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1, .width = 50, .height = 50 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2, .width = 25, .height = 25 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 1, 2, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 25, .y = 25 }) } }); t.screens.active.cursorAbsolute(12, 12); s.dirty = false; - s.delete(alloc, &t, .{ .intersect_cursor = true }); + s.delete(io, alloc, &t, .{ .intersect_cursor = true }); try testing.expect(s.dirty); try testing.expectEqual(@as(usize, 1), s.placements.count()); try testing.expectEqual(@as(usize, 2), s.images.count()); @@ -1152,7 +2685,8 @@ test "storage: delete intersecting cursor plus unused" { test "storage: delete intersecting cursor hits multiple" { const testing = std.testing; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 100, .cols = 100 }); + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 100, .cols = 100 }); defer t.deinit(alloc); t.width_px = 100; t.height_px = 100; @@ -1160,15 +2694,15 @@ test "storage: delete intersecting cursor hits multiple" { var s: ImageStorage = .{}; defer s.deinit(alloc, t.screens.active); - try s.addImage(alloc, .{ .id = 1, .width = 50, .height = 50 }); - try s.addImage(alloc, .{ .id = 2, .width = 25, .height = 25 }); - try s.addPlacement(alloc, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) } }); - try s.addPlacement(alloc, 1, 2, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 25, .y = 25 }) } }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1, .width = 50, .height = 50 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2, .width = 25, .height = 25 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 1, 2, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 25, .y = 25 }) } }); t.screens.active.cursorAbsolute(26, 26); s.dirty = false; - s.delete(alloc, &t, .{ .intersect_cursor = true }); + s.delete(io, alloc, &t, .{ .intersect_cursor = true }); try testing.expect(s.dirty); try testing.expectEqual(@as(usize, 0), s.placements.count()); try testing.expectEqual(@as(usize, 1), s.images.count()); @@ -1178,7 +2712,8 @@ test "storage: delete intersecting cursor hits multiple" { test "storage: delete by column" { const testing = std.testing; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 100, .cols = 100 }); + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 100, .cols = 100 }); defer t.deinit(alloc); t.width_px = 100; t.height_px = 100; @@ -1186,13 +2721,13 @@ test "storage: delete by column" { var s: ImageStorage = .{}; defer s.deinit(alloc, t.screens.active); - try s.addImage(alloc, .{ .id = 1, .width = 50, .height = 50 }); - try s.addImage(alloc, .{ .id = 2, .width = 25, .height = 25 }); - try s.addPlacement(alloc, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) } }); - try s.addPlacement(alloc, 1, 2, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 25, .y = 25 }) } }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1, .width = 50, .height = 50 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2, .width = 25, .height = 25 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 1, 2, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 25, .y = 25 }) } }); s.dirty = false; - s.delete(alloc, &t, .{ .column = .{ + s.delete(io, alloc, &t, .{ .column = .{ .delete = false, .x = 60, } }); @@ -1211,19 +2746,20 @@ test "storage: delete by column" { test "storage: delete by column 1x1" { const testing = std.testing; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 100, .cols = 100 }); + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 100, .cols = 100 }); defer t.deinit(alloc); t.width_px = 100; t.height_px = 100; var s: ImageStorage = .{}; defer s.deinit(alloc, t.screens.active); - try s.addImage(alloc, .{ .id = 1, .width = 1, .height = 1 }); - try s.addPlacement(alloc, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) } }); - try s.addPlacement(alloc, 1, 2, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 0 }) } }); - try s.addPlacement(alloc, 1, 3, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 2, .y = 0 }) } }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1, .width = 1, .height = 1 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 1, 2, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 0 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 1, 3, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 2, .y = 0 }) } }); - s.delete(alloc, &t, .{ .column = .{ + s.delete(io, alloc, &t, .{ .column = .{ .delete = false, .x = 2, } }); @@ -1244,7 +2780,8 @@ test "storage: delete by column 1x1" { test "storage: delete by row" { const testing = std.testing; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 100, .cols = 100 }); + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 100, .cols = 100 }); defer t.deinit(alloc); t.width_px = 100; t.height_px = 100; @@ -1252,13 +2789,13 @@ test "storage: delete by row" { var s: ImageStorage = .{}; defer s.deinit(alloc, t.screens.active); - try s.addImage(alloc, .{ .id = 1, .width = 50, .height = 50 }); - try s.addImage(alloc, .{ .id = 2, .width = 25, .height = 25 }); - try s.addPlacement(alloc, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) } }); - try s.addPlacement(alloc, 1, 2, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 25, .y = 25 }) } }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1, .width = 50, .height = 50 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2, .width = 25, .height = 25 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 1, 2, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 25, .y = 25 }) } }); s.dirty = false; - s.delete(alloc, &t, .{ .row = .{ + s.delete(io, alloc, &t, .{ .row = .{ .delete = false, .y = 60, } }); @@ -1277,19 +2814,20 @@ test "storage: delete by row" { test "storage: delete by row 1x1" { const testing = std.testing; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 100, .cols = 100 }); + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 100, .cols = 100 }); defer t.deinit(alloc); t.width_px = 100; t.height_px = 100; var s: ImageStorage = .{}; defer s.deinit(alloc, t.screens.active); - try s.addImage(alloc, .{ .id = 1, .width = 1, .height = 1 }); - try s.addPlacement(alloc, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .y = 0 }) } }); - try s.addPlacement(alloc, 1, 2, .{ .location = .{ .pin = try trackPin(&t, .{ .y = 1 }) } }); - try s.addPlacement(alloc, 1, 3, .{ .location = .{ .pin = try trackPin(&t, .{ .y = 2 }) } }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1, .width = 1, .height = 1 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .y = 0 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 1, 2, .{ .location = .{ .pin = try trackPin(&t, .{ .y = 1 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 1, 3, .{ .location = .{ .pin = try trackPin(&t, .{ .y = 2 }) } }); - s.delete(alloc, &t, .{ .row = .{ + s.delete(io, alloc, &t, .{ .row = .{ .delete = false, .y = 2, } }); @@ -1310,22 +2848,23 @@ test "storage: delete by row 1x1" { test "storage: delete images by range 1" { const testing = std.testing; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 3, .cols = 3 }); + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); defer t.deinit(alloc); const tracked = t.screens.active.pages.countTrackedPins(); var s: ImageStorage = .{}; defer s.deinit(alloc, t.screens.active); - try s.addImage(alloc, .{ .id = 1 }); - try s.addImage(alloc, .{ .id = 2 }); - try s.addImage(alloc, .{ .id = 3 }); - try s.addPlacement(alloc, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); - try s.addPlacement(alloc, 2, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 3 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 2, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); try testing.expectEqual(@as(usize, 3), s.images.count()); try testing.expectEqual(@as(usize, 2), s.placements.count()); s.dirty = false; - s.delete(alloc, &t, .{ .range = .{ .delete = false, .first = 1, .last = 2 } }); + s.delete(io, alloc, &t, .{ .range = .{ .delete = false, .first = 1, .last = 2 } }); try testing.expect(s.dirty); try testing.expectEqual(@as(usize, 3), s.images.count()); try testing.expectEqual(@as(usize, 0), s.placements.count()); @@ -1335,22 +2874,23 @@ test "storage: delete images by range 1" { test "storage: delete images by range 2" { const testing = std.testing; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 3, .cols = 3 }); + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); defer t.deinit(alloc); const tracked = t.screens.active.pages.countTrackedPins(); var s: ImageStorage = .{}; defer s.deinit(alloc, t.screens.active); - try s.addImage(alloc, .{ .id = 1 }); - try s.addImage(alloc, .{ .id = 2 }); - try s.addImage(alloc, .{ .id = 3 }); - try s.addPlacement(alloc, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); - try s.addPlacement(alloc, 2, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 3 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 2, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); try testing.expectEqual(@as(usize, 3), s.images.count()); try testing.expectEqual(@as(usize, 2), s.placements.count()); s.dirty = false; - s.delete(alloc, &t, .{ .range = .{ .delete = true, .first = 1, .last = 2 } }); + s.delete(io, alloc, &t, .{ .range = .{ .delete = true, .first = 1, .last = 2 } }); try testing.expect(s.dirty); try testing.expectEqual(@as(usize, 1), s.images.count()); try testing.expectEqual(@as(usize, 0), s.placements.count()); @@ -1360,58 +2900,237 @@ test "storage: delete images by range 2" { test "storage: delete images by range 3" { const testing = std.testing; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 3, .cols = 3 }); + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); defer t.deinit(alloc); const tracked = t.screens.active.pages.countTrackedPins(); var s: ImageStorage = .{}; defer s.deinit(alloc, t.screens.active); - try s.addImage(alloc, .{ .id = 1 }); - try s.addImage(alloc, .{ .id = 2 }); - try s.addImage(alloc, .{ .id = 3 }); - try s.addPlacement(alloc, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); - try s.addPlacement(alloc, 2, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 3 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 2, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 3, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); try testing.expectEqual(@as(usize, 3), s.images.count()); - try testing.expectEqual(@as(usize, 2), s.placements.count()); + try testing.expectEqual(@as(usize, 3), s.placements.count()); s.dirty = false; - s.delete(alloc, &t, .{ .range = .{ .delete = false, .first = 1, .last = 1 } }); + s.delete(io, alloc, &t, .{ .range = .{ .delete = false, .first = 2, .last = 2 } }); try testing.expect(s.dirty); try testing.expectEqual(@as(usize, 3), s.images.count()); - try testing.expectEqual(@as(usize, 0), s.placements.count()); - try testing.expectEqual(tracked, t.screens.active.pages.countTrackedPins()); + try testing.expectEqual(@as(usize, 2), s.placements.count()); + try testing.expect(s.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }) != null); + try testing.expect(s.placements.get(.{ + .image_id = 3, + .placement_id = .{ .tag = .external, .id = 1 }, + }) != null); + try testing.expectEqual(tracked + 2, t.screens.active.pages.countTrackedPins()); } test "storage: delete images by range 4" { const testing = std.testing; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 3, .cols = 3 }); + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); defer t.deinit(alloc); const tracked = t.screens.active.pages.countTrackedPins(); var s: ImageStorage = .{}; defer s.deinit(alloc, t.screens.active); - try s.addImage(alloc, .{ .id = 1 }); - try s.addImage(alloc, .{ .id = 2 }); - try s.addImage(alloc, .{ .id = 3 }); - try s.addPlacement(alloc, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); - try s.addPlacement(alloc, 2, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 3 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 2, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 3, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); try testing.expectEqual(@as(usize, 3), s.images.count()); - try testing.expectEqual(@as(usize, 2), s.placements.count()); + try testing.expectEqual(@as(usize, 3), s.placements.count()); s.dirty = false; - s.delete(alloc, &t, .{ .range = .{ .delete = true, .first = 1, .last = 1 } }); + s.delete(io, alloc, &t, .{ .range = .{ .delete = true, .first = 2, .last = 2 } }); try testing.expect(s.dirty); + try testing.expectEqual(@as(usize, 2), s.images.count()); + try testing.expectEqual(@as(usize, 2), s.placements.count()); + try testing.expect(s.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }) != null); + try testing.expect(s.placements.get(.{ + .image_id = 3, + .placement_id = .{ .tag = .external, .id = 1 }, + }) != null); + try testing.expectEqual(tracked + 2, t.screens.active.pages.countTrackedPins()); +} + +test "storage: uppercase range deletes unplaced image data" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); + defer t.deinit(alloc); + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 3 }); + + s.delete(io, alloc, &t, .{ + .range = .{ + .delete = true, + // Zero is the default lower bound when x is omitted. + .first = 0, + .last = 2, + }, + }); try testing.expectEqual(@as(usize, 1), s.images.count()); - try testing.expectEqual(@as(usize, 0), s.placements.count()); - try testing.expectEqual(tracked, t.screens.active.pages.countTrackedPins()); + try testing.expect(s.images.contains(3)); +} + +test "storage: delete images by empty range" { + // Ranges that select nothing are a silent no-op, matching kitty, which + // performs no validation and filters with `x <= image_id <= y`. + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); + defer t.deinit(alloc); + const tracked = t.screens.active.pages.countTrackedPins(); + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 2, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + + // Inverted range. + s.delete(io, alloc, &t, .{ .range = .{ .delete = true, .first = 5, .last = 4 } }); + try testing.expectEqual(@as(usize, 2), s.images.count()); + try testing.expectEqual(@as(usize, 2), s.placements.count()); + + // Upper bound omitted, so it defaults to zero. + s.delete(io, alloc, &t, .{ .range = .{ .delete = true, .first = 5, .last = 0 } }); + try testing.expectEqual(@as(usize, 2), s.images.count()); + try testing.expectEqual(@as(usize, 2), s.placements.count()); + + // Both bounds omitted. Image IDs are never zero so this matches nothing. + s.delete(io, alloc, &t, .{ .range = .{ .delete = true, .first = 0, .last = 0 } }); + try testing.expectEqual(@as(usize, 2), s.images.count()); + try testing.expectEqual(@as(usize, 2), s.placements.count()); + + // Both placements survive, so both of their pins are still tracked. + try testing.expectEqual(tracked + 2, t.screens.active.pages.countTrackedPins()); +} + +test "storage: erase display preserves scrollback and reclaims unplaced images" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ + .rows = 2, + .cols = 2, + .max_scrollback_bytes = 4096, + }); + defer t.deinit(alloc); + t.width_px = 2; + t.height_px = 2; + + const s = &t.screens.active.kitty_images; + try s.addImage(io, alloc, t.screens.active, .{ .id = 1, .width = 1, .height = 1 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .y = 0 }) }, + }); + try t.scrollUp(1); + + const history_key: ImageStorage.PlacementKey = .{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }; + try testing.expect(t.screens.active.pages.pointFromPin( + .active, + s.placements.get(history_key).?.location.pin.*, + ) == null); + + try s.addImage(io, alloc, t.screens.active, .{ .id = 2, .width = 1, .height = 1 }); + try s.addPlacement(io, alloc, t.screens.active, 2, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .y = 0 }) }, + }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 3, .width = 1, .height = 1 }); + + t.eraseDisplay(.complete, false); + try testing.expectEqual(@as(usize, 1), s.placements.count()); + try testing.expect(s.placements.contains(history_key)); + try testing.expectEqual(@as(usize, 1), s.images.count()); + try testing.expect(s.images.contains(1)); + try testing.expect(!s.images.contains(2)); + try testing.expect(!s.images.contains(3)); +} + +test "storage: cell offsets stay within explicit destination rectangle" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 5, .rows = 5 }); + defer t.deinit(alloc); + t.width_px = 50; // 10 px per col + t.height_px = 100; // 20 px per row + + // Explicit columns and rows describe the far cell boundaries. Offsets + // move the near edge inward without moving those far edges. + const placement: ImageStorage.Placement = .{ + .location = .{ .virtual = {} }, + .x_offset = 3, + .y_offset = 4, + .columns = 2, + .rows = 1, + }; + const actual = placement.pixelSize(.{ .width = 4, .height = 3 }, &t); + try testing.expectEqual(@as(u32, 17), actual.width); + try testing.expectEqual(@as(u32, 16), actual.height); + try testing.expectEqual(@as(u32, 2), placement.gridSize(.{ .width = 4, .height = 3 }, &t).cols); + try testing.expectEqual(@as(u32, 1), placement.gridSize(.{ .width = 4, .height = 3 }, &t).rows); +} + +test "storage: cell offsets clamp to cell bounds" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 5, .rows = 5 }); + defer t.deinit(alloc); + t.width_px = 50; // 10 px per col + t.height_px = 100; // 20 px per row + + const placement: ImageStorage.Placement = .{ + .location = .{ .virtual = {} }, + .x_offset = std.math.maxInt(u32), + .y_offset = std.math.maxInt(u32), + .columns = 1, + .rows = 1, + }; + const offset = placement.cellOffset(&t); + try testing.expectEqual(@as(u32, 9), offset.x); + try testing.expectEqual(@as(u32, 19), offset.y); + + // Even hostile offsets leave one pixel inside the requested cell. + const actual = placement.pixelSize(.{ .width = 1, .height = 1 }, &t); + try testing.expectEqual(@as(u32, 1), actual.width); + try testing.expectEqual(@as(u32, 1), actual.height); } test "storage: aspect ratio calculation when only columns or rows specified" { const testing = std.testing; const alloc = testing.allocator; + const io = testing.io; - var t = try terminal.Terminal.init(alloc, .{ .cols = 100, .rows = 100 }); + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 100, .rows = 100 }); defer t.deinit(alloc); t.width_px = 1000; // 10 px per col t.height_px = 2000; // 20 px per row @@ -1453,10 +3172,162 @@ test "storage: aspect ratio calculation when only columns or rows specified" { } } +test "storage: default source rectangle is intersected before sizing" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 5, .rows = 5 }); + defer t.deinit(alloc); + + const placement: ImageStorage.Placement = .{ + .location = .{ .virtual = {} }, + .source_x = 3, + .source_y = 1, + }; + const actual = placement.pixelSize(.{ .width = 4, .height = 3 }, &t); + try testing.expectEqual(@as(u32, 1), actual.width); + try testing.expectEqual(@as(u32, 2), actual.height); +} + +test "storage: explicit source rectangle is intersected before sizing" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 10, .rows = 10 }); + defer t.deinit(alloc); + t.width_px = 100; + t.height_px = 100; + + // The requested 8x8 rectangle intersects this 10x10 image as 2x3. + // With a two-column destination, the clipped 2:3 aspect ratio produces + // a 20x30 pixel destination. + const placement: ImageStorage.Placement = .{ + .location = .{ .virtual = {} }, + .source_x = 8, + .source_y = 7, + .source_width = 8, + .source_height = 8, + .columns = 2, + }; + const actual = placement.pixelSize(.{ .width = 10, .height = 10 }, &t); + try testing.expectEqual(@as(u32, 20), actual.width); + try testing.expectEqual(@as(u32, 30), actual.height); +} + +test "storage: placement geometry handles untrusted dimensions" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + const max = std.math.maxInt(u32); + + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 2, .rows = 2 }); + defer t.deinit(alloc); + t.width_px = max; + t.height_px = max; + + // Cell dimensions multiplied by protocol-controlled row and column + // counts saturate instead of panicking or wrapping. + { + const placement: ImageStorage.Placement = .{ + .location = .{ .virtual = {} }, + .columns = 3, + .rows = 3, + }; + const actual = placement.pixelSize(.{ .width = 1, .height = 1 }, &t); + try testing.expectEqual(max, actual.width); + try testing.expectEqual(max, actual.height); + } + + // Aspect-ratio scaling also saturates when the derived dimension does + // not fit in the public u32 geometry type. + { + const placement: ImageStorage.Placement = .{ + .location = .{ .virtual = {} }, + .columns = 3, + .source_height = max, + }; + const actual = placement.pixelSize(.{ .width = 1, .height = 1 }, &t); + try testing.expectEqual(max, actual.width); + try testing.expectEqual(max, actual.height); + } + { + const placement: ImageStorage.Placement = .{ + .location = .{ .virtual = {} }, + .rows = 3, + .source_width = max, + }; + const actual = placement.pixelSize(.{ .width = 1, .height = 1 }, &t); + try testing.expectEqual(max, actual.width); + try testing.expectEqual(max, actual.height); + } + + // Pixel offsets are protocol-controlled too. Clamp them to the cell + // before including them in grid geometry. + t.width_px = 2; + t.height_px = 2; + { + const placement: ImageStorage.Placement = .{ + .location = .{ .virtual = {} }, + .x_offset = max, + .y_offset = max, + }; + const actual = placement.gridSize(.{ .width = 1, .height = 1 }, &t); + try testing.expectEqual(@as(u32, 1), actual.cols); + try testing.expectEqual(@as(u32, 1), actual.rows); + } + + const pin = try trackPin(&t, .{ .x = 0, .y = 0 }); + defer t.screens.active.pages.untrackPin(pin); + + // Explicit maximum dimensions must clamp the rectangle to the terminal + // without overflowing its horizontal extent. + { + const placement: ImageStorage.Placement = .{ + .location = .{ .pin = pin }, + .columns = max, + .rows = 1, + }; + const rect = placement.rect(.{ .width = 1, .height = 1 }, &t).?; + try testing.expectEqual(@as(size.CellCountInt, 1), rect.bottom_right.x); + } + + // A garbage pin represents content that has been pruned from retained + // history. Its fallback location must not make the placement visible. + pin.garbage = true; + { + const placement: ImageStorage.Placement = .{ + .location = .{ .pin = pin }, + .columns = 1, + .rows = 1, + }; + try testing.expect(placement.rect(.{ .width = 1, .height = 1 }, &t) == null); + } + pin.garbage = false; + + // Terminals can temporarily have no pixel geometry. A placement whose + // computed grid is empty has no rectangle, so rect must not subtract one + // from a zero row count. + t.width_px = 0; + t.height_px = 0; + { + const placement: ImageStorage.Placement = .{ + .location = .{ .pin = pin }, + .columns = 1, + }; + const actual = placement.gridSize(.{ .width = 1, .height = 1 }, &t); + try testing.expectEqual(@as(u32, 0), actual.cols); + try testing.expectEqual(@as(u32, 0), actual.rows); + try testing.expect(placement.rect(.{ .width = 1, .height = 1 }, &t) == null); + } +} + test "storage: generation stamps on image add and replace" { const testing = std.testing; + const io = testing.io; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 3, .cols = 3 }); + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); defer t.deinit(alloc); var s: ImageStorage = .{}; @@ -1465,7 +3336,7 @@ test "storage: generation stamps on image add and replace" { // Fresh storage has generation zero (never mutated). try testing.expectEqual(@as(u64, 0), s.generation); - try s.addImage(alloc, .{ .id = 1, .width = 1, .height = 1 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1, .width = 1, .height = 1 }); const gen1 = s.generation; try testing.expect(gen1 > 0); @@ -1473,7 +3344,7 @@ test "storage: generation stamps on image add and replace" { try testing.expectEqual(gen1, img1.generation); // A second image gets a strictly greater stamp. - try s.addImage(alloc, .{ .id = 2, .width = 1, .height = 1 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2, .width = 1, .height = 1 }); const gen2 = s.generation; try testing.expect(gen2 > gen1); try testing.expectEqual(gen2, s.imageById(2).?.generation); @@ -1481,7 +3352,7 @@ test "storage: generation stamps on image add and replace" { // Retransmitting the same image ID (identical dimensions) gets a // fresh stamp: this is what makes same-sized retransmissions // detectable by renderers. - try s.addImage(alloc, .{ .id = 1, .width = 1, .height = 1 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1, .width = 1, .height = 1 }); const gen3 = s.generation; try testing.expect(gen3 > gen2); try testing.expectEqual(gen3, s.imageById(1).?.generation); @@ -1492,16 +3363,17 @@ test "storage: generation stamps on image add and replace" { test "storage: generation bumps on placement and delete" { const testing = std.testing; + const io = testing.io; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 3, .cols = 3 }); + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); defer t.deinit(alloc); var s: ImageStorage = .{}; defer s.deinit(alloc, t.screens.active); - try s.addImage(alloc, .{ .id = 1 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); const gen_add = s.generation; - try s.addPlacement(alloc, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); const gen_place = s.generation; try testing.expect(gen_place > gen_add); @@ -1510,26 +3382,32 @@ test "storage: generation bumps on placement and delete" { _ = s.imageByNumber(1); try testing.expectEqual(gen_place, s.generation); - s.delete(alloc, &t, .{ .all = true }); + s.delete(io, alloc, &t, .{ .all = true }); try testing.expect(s.generation > gen_place); } test "storage: generation bumps when setLimit evicts or disables" { const testing = std.testing; + const io = testing.io; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 3, .cols = 3 }); + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); defer t.deinit(alloc); var s: ImageStorage = .{}; defer s.deinit(alloc, t.screens.active); const data = try alloc.dupe(u8, "1234"); - try s.addImage(alloc, .{ .id = 1, .width = 1, .height = 1, .data = data }); + try s.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .width = 1, + .height = 1, + .data = .{ .complete = data }, + }); const gen_add = s.generation; // Lowering the limit evicts the image and must mark a mutation. s.dirty = false; - try s.setLimit(alloc, t.screens.active, 1); + s.setLimit(io, alloc, t.screens.active, 1); try testing.expect(s.dirty); try testing.expect(s.generation > gen_add); try testing.expectEqual(@as(usize, 0), s.images.count()); @@ -1537,15 +3415,16 @@ test "storage: generation bumps when setLimit evicts or disables" { // Disabling (limit=0) resets the storage and must mark a mutation. s.dirty = false; - try s.setLimit(alloc, t.screens.active, 0); + s.setLimit(io, alloc, t.screens.active, 0); try testing.expect(s.dirty); try testing.expect(s.generation > gen_evict); } test "storage: imageByNumber returns most recently transmitted" { const testing = std.testing; + const io = testing.io; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 3, .cols = 3 }); + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); defer t.deinit(alloc); var s: ImageStorage = .{}; @@ -1553,27 +3432,28 @@ test "storage: imageByNumber returns most recently transmitted" { // Two images sharing a number: the newest transmission wins, // regardless of insertion order or clock resolution. - try s.addImage(alloc, .{ .id = 1, .number = 7 }); - try s.addImage(alloc, .{ .id = 2, .number = 7 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1, .number = 7 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2, .number = 7 }); try testing.expectEqual(@as(u32, 2), s.imageByNumber(7).?.id); // Retransmit the first: it becomes the newest. - try s.addImage(alloc, .{ .id = 1, .number = 7 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1, .number = 7 }); try testing.expectEqual(@as(u32, 1), s.imageByNumber(7).?.id); } test "storage: nextGeneration is unique and monotonic" { const testing = std.testing; - const a = nextGeneration(); - const b = nextGeneration(); + const a = nextGeneration(testing.io); + const b = nextGeneration(testing.io); try testing.expect(b > a); try testing.expect(a > 0); } test "storage: no-op delete does not mark a mutation" { const testing = std.testing; + const io = testing.io; const alloc = testing.allocator; - var t = try terminal.Terminal.init(alloc, .{ .rows = 3, .cols = 3 }); + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); defer t.deinit(alloc); var s: ImageStorage = .{}; @@ -1581,21 +3461,1204 @@ test "storage: no-op delete does not mark a mutation" { // A delete-all on an empty storage (this runs on every screen // clear) must not dirty the state or bump the generation. - s.delete(alloc, &t, .{ .all = true }); + s.delete(io, alloc, &t, .{ .all = true }); try testing.expect(!s.dirty); try testing.expectEqual(@as(u64, 0), s.generation); // Same for a delete that matches nothing. - try s.addImage(alloc, .{ .id = 1 }); - try s.addPlacement(alloc, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }); const gen = s.generation; s.dirty = false; - s.delete(alloc, &t, .{ .id = .{ .image_id = 42 } }); + s.delete(io, alloc, &t, .{ .id = .{ .image_id = 42 } }); try testing.expect(!s.dirty); try testing.expectEqual(gen, s.generation); // But a delete that removes something does mark a mutation. - s.delete(alloc, &t, .{ .id = .{ .image_id = 1 } }); + s.delete(io, alloc, &t, .{ .id = .{ .image_id = 1 } }); try testing.expect(s.dirty); try testing.expect(s.generation > gen); } + +test "storage: evicts images in priority order" { + const testing = std.testing; + const io = testing.io; + const alloc = testing.allocator; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); + defer t.deinit(alloc); + + var s: ImageStorage = .{ .total_limit = 192 }; + defer s.deinit(alloc, t.screens.active); + + try s.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .data = .{ .complete = try alloc.dupe(u8, "*" ** 64) }, + .metadata = .{ .transient = false }, + }); + try s.addImage(io, alloc, t.screens.active, .{ + .id = 2, + .data = .{ .complete = try alloc.dupe(u8, "*" ** 64) }, + .metadata = .{ .transient = true }, + }); + try s.addImage(io, alloc, t.screens.active, .{ + .id = 3, + .data = .{ .complete = try alloc.dupe(u8, "*" ** 64) }, + .metadata = .{ .transient = true }, + }); + try s.addPlacement( + io, + alloc, + t.screens.active, + 2, + 1, + .{ .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) } }, + ); + + const gen = s.generation; + const result = s.evictImage(io, alloc, t.screens.active, 96); + try testing.expect(s.dirty); + try testing.expect(s.generation > gen); + try testing.expectEqual(true, result); + try testing.expectEqual(1, s.images.count()); + try testing.expect(!s.images.contains(1)); + try testing.expect(s.images.contains(2)); + try testing.expect(!s.images.contains(3)); +} + +test "storage: eviction releases placement pins" { + const testing = std.testing; + const io = testing.io; + const alloc = testing.allocator; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); + defer t.deinit(alloc); + + var s: ImageStorage = .{ .total_limit = 128 }; + defer s.deinit(alloc, t.screens.active); + + const tracked = t.screens.active.pages.countTrackedPins(); + try s.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .data = .{ .complete = try alloc.dupe(u8, "*" ** 64) }, + }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) }, + }); + try s.addImage(io, alloc, t.screens.active, .{ + .id = 2, + .data = .{ .complete = try alloc.dupe(u8, "*" ** 64) }, + }); + try s.addPlacement(io, alloc, t.screens.active, 2, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) }, + }); + try testing.expectEqual(tracked + 2, t.screens.active.pages.countTrackedPins()); + + // Adding a third image evicts the oldest equally-ranked image and its + // placement. The newer image's placement and tracked pin remain intact. + try s.addImage(io, alloc, t.screens.active, .{ + .id = 3, + .data = .{ .complete = try alloc.dupe(u8, "*" ** 64) }, + }); + try testing.expect(!s.images.contains(1)); + try testing.expect(s.images.contains(2)); + try testing.expect(s.images.contains(3)); + try testing.expectEqual(@as(usize, 1), s.placements.count()); + try testing.expect(s.placements.contains(.{ + .image_id = 2, + .placement_id = .{ .tag = .external, .id = 1 }, + })); + try testing.expectEqual(tracked + 1, t.screens.active.pages.countTrackedPins()); +} + +test "storage: pending image completes once and preserves age" { + const testing = std.testing; + const io = testing.io; + const alloc = testing.allocator; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); + defer t.deinit(alloc); + + var s: ImageStorage = .{ .total_limit = 16 }; + defer s.deinit(alloc, t.screens.active); + + const pending = try s.addPendingImage(io, alloc, t.screens.active, .{ + .id = 1, + .number = 7, + .width = 2, + .height = 2, + .format = .rgba, + .data = .{ .pending = 16 }, + }); + try testing.expectEqual(@as(usize, 16), s.total_bytes); + try testing.expectEqual(@as(u32, 1), s.imageByNumber(7).?.id); + try testing.expect(s.imageById(1).?.data.isPending()); + + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) }, + }); + try testing.expectEqual(@as(usize, 1), s.placements.count()); + + const wrong = try alloc.dupe(u8, "short"); + const wrong_completed = pending.complete(&s, io, wrong); + try testing.expect(!wrong_completed); + defer alloc.free(wrong); + + const storage_generation = s.generation; + s.dirty = false; + const pixels = try alloc.dupe(u8, "*" ** 16); + try testing.expect(pending.complete(&s, io, pixels)); + try testing.expect(s.dirty); + try testing.expect(s.generation > storage_generation); + try testing.expectEqual(pending.generation, s.imageById(1).?.generation); + try testing.expectEqual(@as(usize, 16), s.total_bytes); + try testing.expectEqualSlices(u8, pixels, s.imageById(1).?.data.bytes().?); + + const duplicate = try alloc.dupe(u8, "!" ** 16); + const duplicate_completed = pending.complete(&s, io, duplicate); + try testing.expect(!duplicate_completed); + defer alloc.free(duplicate); +} + +test "storage: stale pending completion loses to delete replacement and eviction" { + const testing = std.testing; + const io = testing.io; + const alloc = testing.allocator; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); + defer t.deinit(alloc); + + var s: ImageStorage = .{ .total_limit = 8 }; + defer s.deinit(alloc, t.screens.active); + + const deleted = try s.addPendingImage(io, alloc, t.screens.active, .{ + .id = 1, + .data = .{ .pending = 4 }, + }); + s.delete(io, alloc, &t, .{ .id = .{ .delete = true, .image_id = 1 } }); + const deleted_data = try alloc.dupe(u8, "gone"); + const deleted_completed = deleted.complete(&s, io, deleted_data); + try testing.expect(!deleted_completed); + defer alloc.free(deleted_data); + + const replaced = try s.addPendingImage(io, alloc, t.screens.active, .{ + .id = 2, + .data = .{ .pending = 4 }, + }); + try s.addImage(io, alloc, t.screens.active, .{ + .id = 2, + .data = .{ .complete = try alloc.dupe(u8, "live") }, + }); + const replaced_data = try alloc.dupe(u8, "late"); + const replaced_completed = replaced.complete(&s, io, replaced_data); + try testing.expect(!replaced_completed); + defer alloc.free(replaced_data); + try testing.expectEqualStrings("live", s.imageById(2).?.data.bytes().?); + + const evicted = try s.addPendingImage(io, alloc, t.screens.active, .{ + .id = 3, + .data = .{ .pending = 4 }, + }); + try s.addImage(io, alloc, t.screens.active, .{ + .id = 4, + .data = .{ .complete = try alloc.dupe(u8, "12345678") }, + }); + try testing.expect(s.imageById(3) == null); + const evicted_data = try alloc.dupe(u8, "late"); + const evicted_completed = evicted.complete(&s, io, evicted_data); + try testing.expect(!evicted_completed); + defer alloc.free(evicted_data); +} + +test "storage: replacement reuses pending reservation and removes placements" { + const testing = std.testing; + const io = testing.io; + const alloc = testing.allocator; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); + defer t.deinit(alloc); + + var s: ImageStorage = .{ .total_limit = 12 }; + defer s.deinit(alloc, t.screens.active); + const tracked = t.screens.active.pages.countTrackedPins(); + + const pending = try s.addPendingImage(io, alloc, t.screens.active, .{ + .id = 1, + .width = 2, + .height = 1, + .format = .rgba, + .data = .{ .pending = 8 }, + }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) }, + }); + try s.addImage(io, alloc, t.screens.active, .{ + .id = 2, + .data = .{ .complete = try alloc.dupe(u8, "keep") }, + }); + + try s.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .width = 2, + .height = 1, + .format = .rgba, + .data = .{ .complete = try alloc.dupe(u8, "12345678") }, + }); + try testing.expect(s.images.contains(1)); + try testing.expect(s.images.contains(2)); + try testing.expectEqual(@as(usize, 0), s.placements.count()); + try testing.expectEqual(tracked, t.screens.active.pages.countTrackedPins()); + try testing.expectEqual( + @as(u30, 0), + s.imageById(1).?.metadata.placement_count, + ); + try testing.expectEqual(@as(usize, 12), s.total_bytes); + + const stale = try alloc.dupe(u8, "snapshot"); + const stale_completed = pending.complete(&s, io, stale); + try testing.expect(!stale_completed); + defer alloc.free(stale); + + // Growing the replacement requires eviction, but the replacement ID is + // excluded. The other image supplies the needed bytes. + try s.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .data = .{ .complete = try alloc.dupe(u8, "1234567890") }, + }); + try testing.expect(s.images.contains(1)); + try testing.expect(!s.images.contains(2)); + try testing.expectEqual(@as(usize, 0), s.placements.count()); + try testing.expectEqual(@as(usize, 10), s.total_bytes); + + s.delete(io, alloc, &t, .{ .id = .{ .delete = true, .image_id = 1 } }); + try testing.expectEqual(@as(usize, 0), s.images.count()); + try testing.expectEqual(@as(usize, 0), s.placements.count()); +} + +test "storage: pending images share exact eviction ordering" { + const testing = std.testing; + const io = testing.io; + const alloc = testing.allocator; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); + defer t.deinit(alloc); + + var s: ImageStorage = .{ .total_limit = 192 }; + defer s.deinit(alloc, t.screens.active); + + _ = try s.addPendingImage(io, alloc, t.screens.active, .{ + .id = 1, + .data = .{ .pending = 64 }, + .metadata = .{ .transient = false }, + }); + _ = try s.addPendingImage(io, alloc, t.screens.active, .{ + .id = 2, + .data = .{ .pending = 64 }, + .metadata = .{ .transient = true }, + }); + try s.addImage(io, alloc, t.screens.active, .{ + .id = 3, + .data = .{ .complete = try alloc.dupe(u8, "*" ** 64) }, + .metadata = .{ .transient = true }, + }); + try s.addPlacement(io, alloc, t.screens.active, 2, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) }, + }); + + // ID 3 is transient and unused, so one exact-size eviction is enough. + try testing.expect(s.evictImage(io, alloc, t.screens.active, 64)); + try testing.expect(s.images.contains(1)); + try testing.expect(s.images.contains(2)); + try testing.expect(!s.images.contains(3)); + try testing.expectEqual(@as(usize, 128), s.total_bytes); +} + +test "storage: nextImageId number matches Kitty get_free_client_id" { + const testing = std.testing; + const io = testing.io; + const alloc = testing.allocator; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); + defer t.deinit(alloc); + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + + // Empty storage returns 1, as does Kitty. + try testing.expectEqual(@as(u32, 1), s.nextImageId(.explicit)); + + // Contiguous IDs from 1: the next ID after them. + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 3 }); + try testing.expectEqual(@as(u32, 4), s.nextImageId(.explicit)); + + // The first gap is filled, even when higher IDs exist. + try s.addImage(io, alloc, t.screens.active, .{ .id = 100 }); + s.delete(io, alloc, &t, .{ .id = .{ .image_id = 2, .delete = true } }); + try testing.expectEqual(@as(u32, 2), s.nextImageId(.explicit)); + + // 1 is reused as soon as it is free. + s.delete(io, alloc, &t, .{ .id = .{ .image_id = 1, .delete = true } }); + try testing.expectEqual(@as(u32, 1), s.nextImageId(.explicit)); +} + +test "storage: nextImageId implicit skips in-use ids and zero" { + const testing = std.testing; + const io = testing.io; + const alloc = testing.allocator; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 3, .cols = 3 }); + defer t.deinit(alloc); + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + + // A client image already sits on the counter's first two values. + try s.addImage(io, alloc, t.screens.active, .{ .id = 2147483647 }); + try s.addImage(io, alloc, t.screens.active, .{ .id = 2147483648 }); + try testing.expectEqual(@as(u32, 2147483649), s.nextImageId(.implicit)); + try testing.expectEqual(@as(u32, 2147483650), s.nextImageId(.implicit)); + + // Wrapping skips zero, which means "no ID" protocol-wide. + s.next_image_id = std.math.maxInt(u32); + try testing.expectEqual(std.math.maxInt(u32), s.nextImageId(.implicit)); + try testing.expectEqual(@as(u32, 1), s.nextImageId(.implicit)); +} + +test "storage: scroll margins placement inside region scrolls and clips at top" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 10, .rows = 6 }); + defer t.deinit(alloc); + t.width_px = 100; + t.height_px = 60; + + // 2-row image (10x10px cells) inside the region (rows 1-4). + const storage: *ImageStorage = &t.screens.active.kitty_images; + try storage.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .width = 10, + .height = 20, + }); + try storage.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 2 }) }, + }); + t.setTopAndBottomMargin(2, 5); + t.setCursorPos(5, 1); + + // Entirely inside: moves up with the content. + try t.index(); + { + const p = storage.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }).?; + const pt = t.screens.active.pages.pointFromPin(.active, p.location.pin.*).?; + try testing.expectEqual(point.Coordinate{ .x = 0, .y = 1 }, pt.coord()); + } + + // Would extend above the top margin: anchored at the top margin + // with the top cell row clipped off the source. + try t.index(); + { + const p = storage.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }).?; + const pt = t.screens.active.pages.pointFromPin(.active, p.location.pin.*).?; + try testing.expectEqual(point.Coordinate{ .x = 0, .y = 1 }, pt.coord()); + try testing.expectEqual(@as(u32, 10), p.source_y); + try testing.expectEqual(@as(u32, 10), p.source_height); + } + + // Fully clipped: deleted. + try t.index(); + try testing.expectEqual(@as(usize, 0), storage.placements.count()); + // The image itself is retained. + try testing.expectEqual(@as(usize, 1), storage.images.count()); +} + +test "storage: scroll margins placement straddling region does not move" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 10, .rows = 6 }); + defer t.deinit(alloc); + t.width_px = 100; + t.height_px = 60; + + // 3-row image anchored at the top of a 2-row region: not entirely + // within the region, so region scrolls must not move it. This + // exercises the scrollback-creating path (region top at row 0). + const storage: *ImageStorage = &t.screens.active.kitty_images; + try storage.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .width = 10, + .height = 30, + }); + try storage.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) }, + }); + t.setTopAndBottomMargin(1, 2); + t.setCursorPos(2, 1); + + try t.index(); + const p = storage.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }).?; + const pt = t.screens.active.pages.pointFromPin(.active, p.location.pin.*).?; + try testing.expectEqual(point.Coordinate{ .x = 0, .y = 0 }, pt.coord()); + try testing.expectEqual(@as(u32, 0), p.source_y); + try testing.expectEqual(@as(u32, 0), p.source_height); +} + +test "storage: scroll margins placement below region does not move" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 10, .rows = 6 }); + defer t.deinit(alloc); + t.width_px = 100; + t.height_px = 60; + + // A "status bar" image below the bottom margin must stay put while + // the region above it scrolls (scrollback-creating path). + const storage: *ImageStorage = &t.screens.active.kitty_images; + try storage.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .width = 10, + .height = 10, + }); + try storage.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 5 }) }, + }); + t.setTopAndBottomMargin(1, 4); + t.setCursorPos(4, 1); + + try t.index(); + try t.index(); + const p = storage.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }).?; + const pt = t.screens.active.pages.pointFromPin(.active, p.location.pin.*).?; + try testing.expectEqual(point.Coordinate{ .x = 0, .y = 5 }, pt.coord()); +} + +test "storage: scroll margins reverse index clips at bottom" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 10, .rows = 6 }); + defer t.deinit(alloc); + t.width_px = 100; + t.height_px = 60; + + // 2-row image at the bottom of the region (rows 1-4). + const storage: *ImageStorage = &t.screens.active.kitty_images; + try storage.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .width = 10, + .height = 20, + }); + try storage.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 3 }) }, + }); + t.setTopAndBottomMargin(2, 5); + t.setCursorPos(2, 1); + + // Moves down, with the bottom cell row clipped off the source. + t.reverseIndex(); + { + const p = storage.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }).?; + const pt = t.screens.active.pages.pointFromPin(.active, p.location.pin.*).?; + try testing.expectEqual(point.Coordinate{ .x = 0, .y = 4 }, pt.coord()); + try testing.expectEqual(@as(u32, 0), p.source_y); + try testing.expectEqual(@as(u32, 10), p.source_height); + } + + // Fully clipped: deleted. + t.reverseIndex(); + try testing.expectEqual(@as(usize, 0), storage.placements.count()); +} + +test "storage: scroll margins scaled placement clips proportionally" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 10, .rows = 6 }); + defer t.deinit(alloc); + t.width_px = 100; + t.height_px = 60; + + // A 40px-tall image scaled into 2 rows, inside a 2-row region. + const storage: *ImageStorage = &t.screens.active.kitty_images; + try storage.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .width = 10, + .height = 40, + }); + try storage.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 1 }) }, + .columns = 1, + .rows = 2, + }); + t.setTopAndBottomMargin(2, 3); + t.setCursorPos(3, 1); + + try t.index(); + const p = storage.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }).?; + const pt = t.screens.active.pages.pointFromPin(.active, p.location.pin.*).?; + try testing.expectEqual(point.Coordinate{ .x = 0, .y = 1 }, pt.coord()); + try testing.expectEqual(@as(u32, 20), p.source_y); + try testing.expectEqual(@as(u32, 20), p.source_height); + try testing.expectEqual(@as(u32, 1), p.rows); + try testing.expectEqual(@as(u32, 1), p.columns); +} + +test "storage: scroll margins left/right margins respect columns" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 10, .rows = 6 }); + defer t.deinit(alloc); + t.width_px = 100; + t.height_px = 60; + + // One placement outside the left/right margin columns, one inside. + const storage: *ImageStorage = &t.screens.active.kitty_images; + try storage.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .width = 10, + .height = 10, + }); + try storage.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 2 }) }, + }); + try storage.addPlacement(io, alloc, t.screens.active, 1, 2, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 2, .y = 2 }) }, + }); + + t.modes.set(.enable_left_and_right_margin, true); + t.setLeftAndRightMargin(2, 8); + + try t.scrollUp(1); + + // Outside the margin columns: stays. + { + const p = storage.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }).?; + const pt = t.screens.active.pages.pointFromPin(.active, p.location.pin.*).?; + try testing.expectEqual(point.Coordinate{ .x = 0, .y = 2 }, pt.coord()); + } + + // Inside: moves up. + { + const p = storage.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 2 }, + }).?; + const pt = t.screens.active.pages.pointFromPin(.active, p.location.pin.*).?; + try testing.expectEqual(point.Coordinate{ .x = 2, .y = 1 }, pt.coord()); + } +} + +test "storage: scroll margins insert/delete lines do not move placements" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 10, .rows = 6 }); + defer t.deinit(alloc); + t.width_px = 100; + t.height_px = 60; + + // Kitty does not scroll images for IL/DL, only for IND/RI/SU/SD. + const storage: *ImageStorage = &t.screens.active.kitty_images; + try storage.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .width = 10, + .height = 10, + }); + try storage.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 2 }) }, + }); + t.setTopAndBottomMargin(2, 5); + t.setCursorPos(2, 1); + + t.deleteLines(1); + { + const p = storage.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }).?; + const pt = t.screens.active.pages.pointFromPin(.active, p.location.pin.*).?; + try testing.expectEqual(point.Coordinate{ .x = 0, .y = 2 }, pt.coord()); + } + + t.insertLines(1); + { + const p = storage.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }).?; + const pt = t.screens.active.pages.pointFromPin(.active, p.location.pin.*).?; + try testing.expectEqual(point.Coordinate{ .x = 0, .y = 2 }, pt.coord()); + } +} + +test "storage: scroll without margins moves placement into scrollback" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 10, .rows = 6 }); + defer t.deinit(alloc); + t.width_px = 100; + t.height_px = 60; + + // No margins: the placement follows its anchored row into the + // scrollback via pin tracking (kitty's marginless behavior). + const storage: *ImageStorage = &t.screens.active.kitty_images; + try storage.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .width = 10, + .height = 20, + }); + try storage.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) }, + }); + t.setCursorPos(6, 1); + + try t.index(); + const p = storage.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }).?; + try testing.expect(t.screens.active.pages.pointFromPin( + .active, + p.location.pin.*, + ) == null); + const pt = t.screens.active.pages.pointFromPin(.screen, p.location.pin.*).?; + try testing.expectEqual(point.Coordinate{ .x = 0, .y = 0 }, pt.coord()); +} + +test "storage: scroll margins large scroll deletes inside placement" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 10, .rows = 6 }); + defer t.deinit(alloc); + t.width_px = 100; + t.height_px = 60; + + const storage: *ImageStorage = &t.screens.active.kitty_images; + try storage.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .width = 10, + .height = 10, + }); + try storage.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 2 }) }, + }); + t.setTopAndBottomMargin(2, 5); + + try t.scrollUp(10); + try testing.expectEqual(@as(usize, 0), storage.placements.count()); +} + +test "storage: scroll margins straddling placement pin inside region restored" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 10, .rows = 6 }); + defer t.deinit(alloc); + t.width_px = 100; + t.height_px = 60; + + // 2-row image anchored on the bottom margin row, extending below + // the region: not entirely inside, so it must not move even though + // the region scroll moves every tracked pin within the region rows. + const storage: *ImageStorage = &t.screens.active.kitty_images; + try storage.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .width = 10, + .height = 20, + }); + try storage.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 4 }) }, + }); + t.setTopAndBottomMargin(2, 5); + t.setCursorPos(5, 1); + + try t.index(); + const p = storage.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }).?; + const pt = t.screens.active.pages.pointFromPin(.active, p.location.pin.*).?; + try testing.expectEqual(point.Coordinate{ .x = 0, .y = 4 }, pt.coord()); + try testing.expectEqual(@as(u32, 0), p.source_y); + try testing.expectEqual(@as(u32, 0), p.source_height); +} + +test "storage: scroll margins multi-line scroll up with scrollback" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 10, .rows = 6 }); + defer t.deinit(alloc); + t.width_px = 100; + t.height_px = 60; + + // 1-row image inside a region whose top is the screen top, so the + // scroll pushes text into the scrollback (window shift) while the + // image moves within the region. + const storage: *ImageStorage = &t.screens.active.kitty_images; + try storage.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .width = 10, + .height = 10, + }); + try storage.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 2 }) }, + }); + t.setTopAndBottomMargin(1, 4); + + try t.scrollUp(2); + { + const p = storage.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }).?; + const pt = t.screens.active.pages.pointFromPin(.active, p.location.pin.*).?; + try testing.expectEqual(point.Coordinate{ .x = 0, .y = 0 }, pt.coord()); + } + + // Another two rows scrolls it out of the region: deleted. + try t.scrollUp(2); + try testing.expectEqual(@as(usize, 0), storage.placements.count()); +} + +test "storage: resolveChain accumulates offsets to the pin root" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 5, .cols = 5 }); + defer t.deinit(alloc); + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) }, + }); + try s.addPlacement(io, alloc, t.screens.active, 1, 2, .{ + .location = .{ .relative = .{ + .parent = .{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }, + .horizontal_offset = 2, + .vertical_offset = 1, + } }, + }); + try s.addPlacement(io, alloc, t.screens.active, 1, 3, .{ + .location = .{ .relative = .{ + .parent = .{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 2 }, + }, + .horizontal_offset = -1, + .vertical_offset = 4, + } }, + }); + + const grandchild = s.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 3 }, + }).?; + const chain = s.resolveChain(grandchild.location.relative).?; + try testing.expect(chain.root_key.eql(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + })); + try testing.expect(chain.root.location == .pin); + try testing.expectEqual(@as(i32, 1), chain.horizontal_offset); + try testing.expectEqual(@as(i32, 5), chain.vertical_offset); +} + +test "storage: resolveChain finds virtual roots" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 5, .cols = 5 }); + defer t.deinit(alloc); + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .virtual = {} }, + }); + try s.addPlacement(io, alloc, t.screens.active, 1, 2, .{ + .location = .{ .relative = .{ + .parent = .{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + }, + .horizontal_offset = 1, + } }, + }); + + const child = s.placements.get(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 2 }, + }).?; + const chain = s.resolveChain(child.location.relative).?; + try testing.expect(chain.root.location == .virtual); + try testing.expect(chain.root_key.eql(.{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + })); + try testing.expectEqual(@as(i32, 1), chain.horizontal_offset); + try testing.expectEqual(@as(i32, 0), chain.vertical_offset); +} + +test "storage: eviction removes orphaned relative placements" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 5, .cols = 5 }); + defer t.deinit(alloc); + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + s.total_limit = 8; + + // Image 1 holds most of the byte budget and has a pin placement. + try s.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .width = 2, + .height = 1, + .data = .{ .complete = try alloc.dupe(u8, &.{ 0, 0, 0, 0, 0, 0 }) }, + }); + try s.addPlacement(io, alloc, t.screens.active, 1, 1, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 1, .y = 1 }) }, + }); + + // Image 2's placement is relative to image 1's placement. + try s.addImage(io, alloc, t.screens.active, .{ .id = 2 }); + try s.addPlacement(io, alloc, t.screens.active, 2, 1, .{ + .location = .{ .relative = .{ .parent = .{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 1 }, + } } }, + }); + + // Adding image 3 exceeds the limit and evicts image 1 (oldest), + // removing its placement, which orphans image 2's placement. + try s.addImage(io, alloc, t.screens.active, .{ + .id = 3, + .width = 2, + .height = 1, + .data = .{ .complete = try alloc.dupe(u8, &.{ 0, 0, 0, 0, 0, 0 }) }, + }); + + try testing.expect(s.imageById(1) == null); + try testing.expectEqual(@as(usize, 0), s.placements.count()); + try testing.expect(s.imageById(2) != null); +} + +test "storage: placeholderTarget lookup" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .rows = 5, .cols = 5 }); + defer t.deinit(alloc); + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + try s.addImage(io, alloc, t.screens.active, .{ .id = 1 }); + try s.addPlacement(io, alloc, t.screens.active, 1, 5, .{ + .location = .{ .virtual = {} }, + }); + + // Exact external ID match. + { + const target = s.placeholderTarget(1, 5).?; + const expected: ImageStorage.PlacementKey = .{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 5 }, + }; + try testing.expectEqual(expected, target.key); + try testing.expect(target.placement.location == .virtual); + } + + // Zero placement ID falls back to the image's virtual placement. + { + const target = s.placeholderTarget(1, 0).?; + const expected: ImageStorage.PlacementKey = .{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 5 }, + }; + try testing.expectEqual(expected, target.key); + } + + try testing.expect(s.placeholderTarget(1, 9) == null); + try testing.expect(s.placeholderTarget(2, 0) == null); + + // With multiple virtual placements, the zero-ID fallback picks + // deterministically by PlacementId.preferredOver: lowest external. + try s.addPlacement(io, alloc, t.screens.active, 1, 3, .{ + .location = .{ .virtual = {} }, + }); + { + const expected: ImageStorage.PlacementKey = .{ + .image_id = 1, + .placement_id = .{ .tag = .external, .id = 3 }, + }; + try testing.expectEqual(expected, s.placeholderTarget(1, 0).?.key); + } +} + +test "storage: animation tick advances and schedules" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 10, .rows = 10 }); + defer t.deinit(alloc); + t.width_px = 100; + t.height_px = 100; + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + + // A running 1x1 RGBA image whose animation has one extra frame. + try s.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .width = 1, + .height = 1, + .format = .rgba, + .data = .{ .complete = try alloc.dupe(u8, &.{ 255, 0, 0, 255 }) }, + }); + const img = s.images.getPtr(1).?; + const anim = try alloc.create(animation.Animation); + anim.* = .{ .state = .running }; + img.animation = anim; + try anim.frames.append(alloc, .{ + .data = try alloc.dupe(u8, &.{ 0, 0, 255, 255 }), + .gap_ms = 40, + }); + + // Without a placement the animation doesn't advance (our + // approximation of Kitty's visibility gate). + try testing.expect(s.animationTick(io, 0) == null); + try testing.expectEqual(@as(u32, 0), anim.current_index); + + try s.addPlacement(io, alloc, t.screens.active, 1, 0, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) }, + }); + const gen1 = img.generation; + s.dirty = false; + + // First tick: the gapless root frame is due immediately and is + // skipped over to frame 2, which is due again in its 40ms gap. + try testing.expectEqual(@as(?u64, 40), s.animationTick(io, 0)); + try testing.expectEqual(@as(u32, 1), anim.current_index); + try testing.expect(img.generation > gen1); + try testing.expect(s.dirty); + + // Nothing due yet: no advance, and the delay counts down. + const gen2 = img.generation; + try testing.expectEqual(@as(?u64, 30), s.animationTick(io, 10)); + try testing.expectEqual(gen2, img.generation); + + // Wrapping is fine with an infinite loop budget: the gapless + // root is skipped and frame 2 is shown again. + try testing.expectEqual(@as(?u64, 40), s.animationTick(io, 40)); + try testing.expectEqual(@as(u32, 1), anim.current_index); + try testing.expectEqual(@as(u32, 1), anim.current_loop); +} + +test "storage: animation tick loading state parks on last frame" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 10, .rows = 10 }); + defer t.deinit(alloc); + t.width_px = 100; + t.height_px = 100; + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + + // A placed 1x1 RGBA image in the loading state (a=a s=2) whose + // animation has one extra frame. + try s.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .width = 1, + .height = 1, + .format = .rgba, + .data = .{ .complete = try alloc.dupe(u8, &.{ 255, 0, 0, 255 }) }, + }); + const anim = try alloc.create(animation.Animation); + anim.* = .{ .state = .loading }; + s.images.getPtr(1).?.animation = anim; + try anim.frames.append(alloc, .{ + .data = try alloc.dupe(u8, &.{ 0, 0, 255, 255 }), + .gap_ms = 40, + }); + try s.addPlacement(io, alloc, t.screens.active, 1, 0, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) }, + }); + + // Reach the last frame, then park: no wakeup is scheduled while + // waiting for more frames and the loop counter stays untouched. + try testing.expectEqual(@as(?u64, 40), s.animationTick(io, 0)); + try testing.expectEqual(@as(u32, 1), anim.current_index); + try testing.expect(s.animationTick(io, 100) == null); + try testing.expectEqual(@as(u32, 1), anim.current_index); + try testing.expectEqual(@as(u32, 0), anim.current_loop); + + // A new frame arriving un-parks playback. + try anim.frames.append(alloc, .{ + .data = try alloc.dupe(u8, &.{ 0, 255, 0, 255 }), + .gap_ms = 25, + }); + try testing.expectEqual(@as(?u64, 25), s.animationTick(io, 150)); + try testing.expectEqual(@as(u32, 2), anim.current_index); +} + +test "storage: animation tick exhausts loop budget" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 10, .rows = 10 }); + defer t.deinit(alloc); + t.width_px = 100; + t.height_px = 100; + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + + // A placed, running 1x1 RGBA image with a gapped root frame, one + // extra frame, and a one-loop budget (a=a v=2). + try s.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .width = 1, + .height = 1, + .format = .rgba, + .data = .{ .complete = try alloc.dupe(u8, &.{ 255, 0, 0, 255 }) }, + }); + const anim = try alloc.create(animation.Animation); + anim.* = .{ + .state = .running, + .root_gap_ms = 10, + .max_loops = 1, + }; + s.images.getPtr(1).?.animation = anim; + try anim.frames.append(alloc, .{ + .data = try alloc.dupe(u8, &.{ 0, 0, 255, 255 }), + .gap_ms = 40, + }); + try s.addPlacement(io, alloc, t.screens.active, 1, 0, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) }, + }); + + // Root shows for 10ms, frame 2 for 40ms, then the wrap exhausts + // the budget and playback freezes on the last frame for good. + try testing.expectEqual(@as(?u64, 10), s.animationTick(io, 0)); + try testing.expectEqual(@as(u32, 0), anim.current_index); + try testing.expectEqual(@as(?u64, 40), s.animationTick(io, 10)); + try testing.expectEqual(@as(u32, 1), anim.current_index); + try testing.expect(s.animationTick(io, 50) == null); + try testing.expectEqual(@as(u32, 1), anim.current_index); + try testing.expect(s.animationTick(io, 500) == null); +} + +test "storage: animation tick ignores ineligible animations" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 10, .rows = 10 }); + defer t.deinit(alloc); + t.width_px = 100; + t.height_px = 100; + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + + // A placed 1x1 RGBA image with one extra frame, in the default + // stopped state. + try s.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .width = 1, + .height = 1, + .format = .rgba, + .data = .{ .complete = try alloc.dupe(u8, &.{ 255, 0, 0, 255 }) }, + }); + const anim = try alloc.create(animation.Animation); + anim.* = .{}; + s.images.getPtr(1).?.animation = anim; + try anim.frames.append(alloc, .{ + .data = try alloc.dupe(u8, &.{ 0, 0, 255, 255 }), + .gap_ms = 40, + }); + try s.addPlacement(io, alloc, t.screens.active, 1, 0, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) }, + }); + + // Stopped (the default) never advances. + try testing.expect(s.animationTick(io, 0) == null); + + // An all-gapless animation can never advance either. + anim.state = .running; + anim.frames.items[0].gap_ms = 0; + try testing.expect(s.animationTick(io, 0) == null); + try testing.expectEqual(@as(u32, 0), anim.current_index); +} + +test "storage: animation tick re-anchors a restarted clock" { + const testing = std.testing; + const alloc = testing.allocator; + const io = testing.io; + var t = try terminal.Terminal.init(io, alloc, .{ .cols = 10, .rows = 10 }); + defer t.deinit(alloc); + t.width_px = 100; + t.height_px = 100; + + var s: ImageStorage = .{}; + defer s.deinit(alloc, t.screens.active); + + // A placed, running 1x1 RGBA image displaying its extra frame, + // with a shown-at timestamp far ahead of the tick clock. + try s.addImage(io, alloc, t.screens.active, .{ + .id = 1, + .width = 1, + .height = 1, + .format = .rgba, + .data = .{ .complete = try alloc.dupe(u8, &.{ 255, 0, 0, 255 }) }, + }); + const anim = try alloc.create(animation.Animation); + anim.* = .{ + .state = .running, + .current_index = 1, + .frame_shown_at_ms = 1000, + }; + s.images.getPtr(1).?.animation = anim; + try anim.frames.append(alloc, .{ + .data = try alloc.dupe(u8, &.{ 0, 0, 255, 255 }), + .gap_ms = 40, + }); + try s.addPlacement(io, alloc, t.screens.active, 1, 0, .{ + .location = .{ .pin = try trackPin(&t, .{ .x = 0, .y = 0 }) }, + }); + + // A timestamp in the future relative to now means the caller's + // clock restarted; the animation must not stall until the old + // timestamp comes around again. + try testing.expectEqual(@as(?u64, 40), s.animationTick(io, 5)); + try testing.expectEqual(@as(?u64, 5), anim.frame_shown_at_ms); +} |
