Skip to content

A modern terminal with a built-in multiplexer: close it and your sessions keep running. Run shells and tons of AI agents across your machines, then pick them up from desktop, browser, TUI and more. Written in Rust with no UI framework: interface drawn straight on the GPU. No Electron, GPUI or webview.

feat(term): model Kitty placeholders, relative placements and playback

RoversX57b5d58ccb65
diff --git a/term/src/kitty_animation.rs b/term/src/kitty_animation.rs
new file mode 100644
index 00000000..ce10bd75
--- /dev/null
+++ b/term/src/kitty_animation.rs
@@ -0,0 +1,471 @@
+//! A shared playback timeline. Sampling skips elapsed cycles in constant time
+//! and locates a frame by binary search; it never replays missed frames.
+
+pub use wezterm_escape_parser::apc::KittyAnimationState as Playback;
+
+#[cfg_attr(feature = "use_serde", derive(serde::Serialize, serde::Deserialize))]
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct KittyAnimation {
+ pub frame: u32,
+ pub mode: Playback,
+ /// Zero means unlimited; otherwise stop before wrapping this many times.
+ pub max_loops: u32,
+ pub completed_loops: u64,
+ pub started_at_ms: u64,
+ /// Cumulative frame ends. Equal adjacent values represent gapless frames.
+ pub frame_ends: Vec<u64>,
+}
+
+/// An optional companion to the legacy terminal snapshot.
+#[cfg_attr(feature = "use_serde", derive(serde::Serialize, serde::Deserialize))]
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct KittyPlaybackSnapshot {
+ pub captured_at_ms: u64,
+ pub selections: Vec<KittyPlaybackEntry>,
+}
+
+// The checkpoint shape deliberately omits the process-local image generation.
+#[cfg_attr(feature = "use_serde", derive(serde::Serialize, serde::Deserialize))]
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct KittyPlaybackEntry {
+ pub image_id: u32,
+ pub data_hash: [u8; 32],
+ pub animation: KittyAnimation,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Sample {
+ pub frame: u32,
+ pub started_at_ms: u64,
+ pub completed_loops: u64,
+ pub next_at_ms: Option<u64>,
+}
+
+/// The mux's monotonic clock domain. Clients translate it to their own clock;
+/// they use `sample` rather than calling this function.
+pub fn monotonic_ms() -> u64 {
+ static START: std::sync::OnceLock<std::time::Instant> = std::sync::OnceLock::new();
+ START
+ .get_or_init(std::time::Instant::now)
+ .elapsed()
+ .as_millis()
+ .min((u64::MAX - u32::MAX as u64) as u128) as u64
+ // Reserve a maximum frame gap before the origin, so a restored
+ // partially displayed frame can start before this process did.
+ + u32::MAX as u64
+}
+
+impl KittyAnimation {
+ pub fn rebase(&mut self, captured_at: u64, restored_at: u64) {
+ let sample = self.sample(captured_at);
+ let elapsed = if self.mode == Playback::Stopped {
+ 0
+ } else {
+ captured_at
+ .saturating_sub(sample.started_at_ms)
+ .min(self.gap(sample.frame as usize))
+ };
+ self.frame = sample.frame;
+ self.completed_loops = sample.completed_loops;
+ self.started_at_ms = restored_at.saturating_sub(elapsed);
+ }
+ pub fn new(gaps: impl IntoIterator<Item = u32>, now: u64) -> Self {
+ let mut end = 0;
+ let frame_ends = gaps
+ .into_iter()
+ .map(|gap| {
+ end += u64::from(gap);
+ end
+ })
+ .collect();
+ Self {
+ frame: 0,
+ mode: Playback::Stopped,
+ max_loops: 0,
+ completed_loops: 0,
+ started_at_ms: now,
+ frame_ends,
+ }
+ }
+
+ pub fn valid(&self) -> bool {
+ !self.frame_ends.is_empty()
+ && self.frame_ends.len() <= 4096
+ && (self.frame as usize) < self.frame_ends.len()
+ && self
+ .frame_ends
+ .windows(2)
+ .all(|pair| pair[0] <= pair[1] && pair[1] - pair[0] <= u32::MAX as u64)
+ && self.frame_ends[0] <= u32::MAX as u64
+ }
+
+ fn start(&self, frame: usize) -> u64 {
+ frame
+ .checked_sub(1)
+ .map_or(0, |previous| self.frame_ends[previous])
+ }
+
+ pub fn gap(&self, frame: usize) -> u64 {
+ self.frame_ends[frame] - self.start(frame)
+ }
+
+ pub fn sample(&self, now: u64) -> Sample {
+ let held = Sample {
+ frame: self.frame,
+ started_at_ms: self.started_at_ms,
+ completed_loops: self.completed_loops,
+ next_at_ms: None,
+ };
+ let cycle = self.frame_ends.last().copied().unwrap_or(0);
+ if self.mode == Playback::Stopped
+ || self.frame_ends.len() < 2
+ || cycle == 0
+ || (self.max_loops > 0 && self.completed_loops >= u64::from(self.max_loops))
+ {
+ return held;
+ }
+ let now = now.max(self.started_at_ms);
+ let position = self
+ .start(self.frame as usize)
+ .saturating_add(now - self.started_at_ms);
+ let loops = position / cycle;
+ let completed = self.completed_loops.saturating_add(loops);
+ let ended = (self.mode == Playback::Loading && loops > 0)
+ || (self.max_loops > 0 && completed >= u64::from(self.max_loops));
+ if ended {
+ // Trailing gapless frames never replace the last visible frame.
+ let frame = self.frame_ends.partition_point(|end| *end < cycle);
+ let remaining = if self.mode == Playback::Loading {
+ 1
+ } else {
+ u64::from(self.max_loops).saturating_sub(self.completed_loops)
+ };
+ let until_end = remaining
+ .saturating_mul(cycle)
+ .saturating_sub(self.start(self.frame as usize));
+ let started = self
+ .started_at_ms
+ .saturating_add(until_end)
+ .saturating_sub(self.gap(frame));
+ return Sample {
+ frame: frame as u32,
+ started_at_ms: started,
+ completed_loops: if self.mode == Playback::Loading {
+ self.completed_loops
+ } else {
+ u64::from(self.max_loops)
+ },
+ next_at_ms: None,
+ };
+ }
+ let within = position % cycle;
+ let frame = self.frame_ends.partition_point(|end| *end <= within);
+ let elapsed = within - self.start(frame);
+ let started = now.saturating_sub(elapsed);
+ Sample {
+ frame: frame as u32,
+ started_at_ms: started,
+ completed_loops: completed,
+ next_at_ms: Some(now.saturating_add(self.frame_ends[frame] - within)),
+ }
+ }
+
+ fn settle(&mut self, now: u64) -> Sample {
+ let sampled = self.sample(now);
+ self.frame = sampled.frame;
+ self.started_at_ms = sampled.started_at_ms;
+ self.completed_loops = sampled.completed_loops;
+ sampled
+ }
+
+ pub fn append(&mut self, gap: u32, now: u64) {
+ let waiting = self.mode != Playback::Stopped
+ && self.sample(now).next_at_ms.is_none()
+ && (self.mode == Playback::Loading
+ || self.frame_ends.len() < 2
+ || self.frame_ends.last() == Some(&0));
+ self.settle(now);
+ if waiting && now.saturating_sub(self.started_at_ms) >= self.gap(self.frame as usize) {
+ self.frame = self.frame_ends.len() as u32;
+ self.started_at_ms = now;
+ }
+ self.frame_ends
+ .push(self.frame_ends.last().copied().unwrap_or(0) + u64::from(gap));
+ }
+
+ pub fn set_gap(&mut self, frame: usize, gap: u32, now: u64) -> bool {
+ if frame >= self.frame_ends.len() || self.gap(frame) == u64::from(gap) {
+ return false;
+ }
+ self.settle(now);
+ let old = self.gap(frame);
+ for end in &mut self.frame_ends[frame..] {
+ *end = *end - old + u64::from(gap);
+ }
+ true
+ }
+
+ pub fn remove_frame(&mut self, frame: usize, now: u64) -> bool {
+ if self.frame_ends.len() <= 1 || frame >= self.frame_ends.len() {
+ return false;
+ }
+ self.settle(now);
+ let gap = self.gap(frame);
+ self.frame_ends.remove(frame);
+ for end in &mut self.frame_ends[frame..] {
+ *end -= gap;
+ }
+ if frame < self.frame as usize {
+ self.frame -= 1;
+ } else if frame == self.frame as usize {
+ self.frame = frame.min(self.frame_ends.len() - 1) as u32;
+ self.started_at_ms = now;
+ }
+ true
+ }
+
+ pub fn control(
+ &mut self,
+ control: &wezterm_escape_parser::apc::KittyImageAnimationControl,
+ now: u64,
+ ) -> bool {
+ let current = control
+ .current_frame
+ .filter(|frame| *frame > 0 && (*frame as usize) <= self.frame_ends.len());
+ let gap = control
+ .frame_number
+ .filter(|frame| *frame > 0 && (*frame as usize) <= self.frame_ends.len())
+ .zip(control.gap_ms.filter(|gap| *gap != 0));
+ let loops = control.loops.filter(|loops| *loops > 0);
+ if current.is_none() && gap.is_none() && control.state.is_none() && loops.is_none() {
+ return false;
+ }
+ let header = |a: &Self| {
+ (
+ a.frame,
+ a.mode,
+ a.max_loops,
+ a.completed_loops,
+ a.started_at_ms,
+ )
+ };
+ let before = header(self);
+ self.settle(now);
+ let changed_gap = gap
+ .is_some_and(|(frame, gap)| self.set_gap(frame as usize - 1, gap.max(0) as u32, now));
+ if let Some(frame) = current {
+ if self.frame != frame - 1 {
+ self.frame = frame - 1;
+ self.started_at_ms = now;
+ }
+ }
+ if let Some(mode) = control.state {
+ if self.mode == Playback::Stopped && mode != Playback::Stopped {
+ self.started_at_ms = now;
+ }
+ self.mode = mode;
+ self.completed_loops = 0;
+ }
+ if let Some(loops) = loops {
+ self.max_loops = loops - 1;
+ }
+ changed_gap || header(self) != before
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use wezterm_escape_parser::apc::KittyImageAnimationControl;
+
+ fn control() -> KittyImageAnimationControl {
+ KittyImageAnimationControl {
+ image_id: None,
+ image_number: None,
+ current_frame: None,
+ frame_number: None,
+ state: None,
+ loops: None,
+ gap_ms: None,
+ }
+ }
+
+ #[test]
+ fn frame_deletion_preserves_playback_position_and_removes_the_gap() {
+ let mut animation = KittyAnimation::new([20, 30, 40], 100);
+ animation.mode = Playback::Running;
+ assert!(animation.remove_frame(0, 130));
+ assert_eq!(animation.frame_ends, [30, 70]);
+ assert_eq!(animation.sample(130).frame, 0);
+ assert_eq!(animation.sample(130).next_at_ms, Some(150));
+ assert!(animation.remove_frame(0, 140));
+ assert_eq!(animation.frame_ends, [40]);
+ assert_eq!(animation.started_at_ms, 140);
+ assert!(animation.valid());
+ assert!(!animation.remove_frame(0, 150));
+
+ let mut stopped = KittyAnimation::new([0, 30, 0], 100);
+ stopped.frame = 2;
+ assert!(stopped.remove_frame(2, 120));
+ assert_eq!(stopped.frame, 1);
+ assert_eq!(stopped.frame_ends, [0, 30]);
+ assert!(stopped.valid());
+ }
+
+ #[test]
+ fn elapsed_cycles_are_skipped_and_gapless_frames_are_never_presented() {
+ let mut timeline = KittyAnimation::new([0, 40, 0, 60, 0], 100);
+ timeline.mode = Playback::Running;
+ assert_eq!(timeline.sample(100).frame, 1);
+ assert_eq!(timeline.sample(139).next_at_ms, Some(140));
+ assert_eq!(timeline.sample(140).frame, 3);
+ assert_eq!(timeline.sample(200).frame, 1);
+ let sampled = timeline.sample(1_000_000_140);
+ assert_eq!(sampled.frame, 3);
+ assert_eq!(sampled.completed_loops, 10_000_000);
+ assert_eq!(sampled.next_at_ms, Some(1_000_000_200));
+ }
+
+ #[test]
+ fn finite_loops_hold_the_last_visible_frame() {
+ let mut timeline = KittyAnimation::new([0, 40, 60, 0], 100);
+ timeline.mode = Playback::Running;
+ timeline.max_loops = 2;
+ assert_eq!(timeline.sample(299).frame, 2);
+ let end = timeline.sample(10_000);
+ assert_eq!(end.frame, 2);
+ assert_eq!(end.completed_loops, 2);
+ assert_eq!(end.next_at_ms, None);
+ assert_eq!(end.started_at_ms, 240);
+ }
+
+ #[test]
+ fn loading_waits_and_a_new_frame_starts_when_it_arrives() {
+ let mut timeline = KittyAnimation::new([0, 40], 100);
+ timeline.mode = Playback::Loading;
+ assert_eq!(timeline.sample(5000).frame, 1);
+ assert_eq!(timeline.sample(5000).next_at_ms, None);
+ timeline.append(70, 5000);
+ assert_eq!(timeline.sample(5000).frame, 2);
+ assert_eq!(timeline.sample(5069).next_at_ms, Some(5070));
+ assert_eq!(timeline.sample(5070).next_at_ms, None);
+ }
+
+ #[test]
+ fn stopping_freezes_the_sample_and_resuming_restarts_its_gap() {
+ let mut timeline = KittyAnimation::new([20, 40], 100);
+ timeline.mode = Playback::Running;
+ timeline.control(
+ &KittyImageAnimationControl {
+ state: Some(Playback::Stopped),
+ ..control()
+ },
+ 125,
+ );
+ assert_eq!(timeline.sample(5000).frame, 1);
+ assert_eq!(timeline.sample(5000).next_at_ms, None);
+ timeline.control(
+ &KittyImageAnimationControl {
+ state: Some(Playback::Running),
+ loops: Some(2),
+ ..control()
+ },
+ 5000,
+ );
+ assert_eq!(timeline.sample(5039).next_at_ms, Some(5040));
+ assert_eq!(timeline.sample(5040).next_at_ms, None);
+ }
+
+ #[test]
+ fn all_gapless_and_single_frame_images_do_not_spin() {
+ for gaps in [vec![0, 0, 0], vec![40]] {
+ let mut timeline = KittyAnimation::new(gaps, 100);
+ timeline.mode = Playback::Running;
+ assert_eq!(timeline.sample(u64::MAX).next_at_ms, None);
+ }
+ let mut timeline = KittyAnimation::new([0], 100);
+ timeline.mode = Playback::Running;
+ timeline.append(40, 5000);
+ assert_eq!(timeline.sample(5000).frame, 1);
+ assert_eq!(timeline.sample(5000).next_at_ms, Some(5040));
+ }
+
+ #[test]
+ fn appending_before_the_current_gap_expires_keeps_its_remaining_time() {
+ let mut timeline = KittyAnimation::new([40], 100);
+ timeline.mode = Playback::Running;
+ timeline.append(70, 110);
+ assert_eq!(timeline.sample(110).frame, 0);
+ assert_eq!(timeline.sample(110).next_at_ms, Some(140));
+ assert_eq!(timeline.sample(140).frame, 1);
+ }
+
+ #[test]
+ fn clock_mapping_before_the_anchor_does_not_advance_its_deadline() {
+ let mut timeline = KittyAnimation::new([40, 70], 100);
+ timeline.mode = Playback::Running;
+ assert_eq!(timeline.sample(90).started_at_ms, 100);
+ assert_eq!(timeline.sample(90).next_at_ms, Some(140));
+ }
+
+ #[test]
+ fn restoring_preserves_remaining_gap_and_completed_loops_in_a_new_clock() {
+ let mut timeline = KittyAnimation::new([40, 60], 100);
+ timeline.mode = Playback::Running;
+ timeline.max_loops = 3;
+ timeline.rebase(255, 5000);
+ assert_eq!(timeline.frame, 1);
+ assert_eq!(timeline.completed_loops, 1);
+ assert_eq!(timeline.sample(5000).next_at_ms, Some(5045));
+ assert_eq!(timeline.sample(5045).frame, 0);
+ assert_eq!(timeline.sample(5145).next_at_ms, None);
+ }
+
+ #[test]
+ fn restoring_loading_wait_and_completed_animation_does_not_restart_them() {
+ for mode in [Playback::Loading, Playback::Running] {
+ let mut timeline = KittyAnimation::new([40, 60], 100);
+ timeline.mode = mode;
+ timeline.max_loops = 1;
+ timeline.rebase(10_000, 5000);
+ assert_eq!(timeline.sample(5000).frame, 1);
+ assert_eq!(timeline.sample(5000).next_at_ms, None);
+ if mode == Playback::Loading {
+ timeline.append(70, 5100);
+ assert_eq!(timeline.sample(5100).frame, 2);
+ assert_eq!(timeline.sample(5100).next_at_ms, Some(5170));
+ }
+ }
+ }
+
+ #[test]
+ fn sampling_matches_a_stepwise_player_for_every_anchor_and_gap_pattern() {
+ for gaps in [[0, 1, 3, 0], [4, 0, 2, 5], [1, 1, 1, 1]] {
+ for anchor in 0..gaps.len() {
+ let mut timeline = KittyAnimation::new(gaps, 100);
+ timeline.frame = anchor as u32;
+ timeline.mode = Playback::Running;
+ let (mut frame, mut start, mut loops) = (anchor, 100, 0);
+ for now in 100..1000 {
+ while now - start >= u64::from(gaps[frame]) {
+ start += u64::from(gaps[frame]);
+ frame += 1;
+ if frame == gaps.len() {
+ frame = 0;
+ loops += 1;
+ }
+ }
+ assert_eq!(
+ timeline.sample(now),
+ Sample {
+ frame: frame as u32,
+ started_at_ms: start,
+ completed_loops: loops,
+ next_at_ms: Some(start + u64::from(gaps[frame])),
+ }
+ );
+ }
+ }
+ }
+ }
+}
diff --git a/term/src/kitty_placeholder.rs b/term/src/kitty_placeholder.rs
new file mode 100644
index 00000000..fd01c6d6
--- /dev/null
+++ b/term/src/kitty_placeholder.rs
@@ -0,0 +1,348 @@
+//! Kitty Unicode placeholder decoding for terminal cores and renderers.
+//! The protocol table is independent of the host's Unicode/font version.
+
+use crate::color::ColorAttribute;
+use crate::Line;
+
+pub const PLACEHOLDER: char = '\u{10eeee}';
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct Placeholder {
+ pub image_id: u32,
+ pub placement_id: u32,
+ pub row: u32,
+ pub column: u32,
+}
+
+/// One decoder per physical text row. Only the immediately preceding cell can
+/// supply missing coordinates; a gap, ordinary text or a color change breaks it.
+#[derive(Default)]
+pub struct Decoder {
+ previous: Option<(usize, Placeholder)>,
+}
+
+fn color_id(color: ColorAttribute) -> u32 {
+ match color {
+ ColorAttribute::Default => 0,
+ ColorAttribute::PaletteIndex(index) => u32::from(index),
+ ColorAttribute::TrueColorWithDefaultFallback(rgb)
+ | ColorAttribute::TrueColorWithPaletteFallback(rgb, _) => {
+ let (r, g, b, _) = rgb.to_srgb_u8();
+ (u32::from(r) << 16) | (u32::from(g) << 8) | u32::from(b)
+ }
+ }
+}
+
+fn diacritic(c: char) -> Option<u32> {
+ DIACRITICS
+ .binary_search(&(c as u32))
+ .ok()
+ .map(|index| index as u32)
+}
+
+impl Decoder {
+ pub fn push(
+ &mut self,
+ column: usize,
+ text: &str,
+ foreground: ColorAttribute,
+ underline: ColorAttribute,
+ ) -> Option<Placeholder> {
+ let mut chars = text.chars();
+ if chars.next() != Some(PLACEHOLDER) {
+ self.previous = None;
+ return None;
+ }
+ let row = chars.next().and_then(diacritic);
+ let col = chars.next().and_then(diacritic);
+ let upper = chars.next().and_then(diacritic).map(|n| n as u8);
+ let lower = color_id(foreground);
+ let placement_id = color_id(underline);
+ let previous = self
+ .previous
+ .filter(|(at, image)| {
+ at.checked_add(1) == Some(column)
+ && image.image_id & 0xffffff == lower
+ && image.placement_id == placement_id
+ && row.is_none_or(|row| row == image.row)
+ && col.is_none_or(|col| image.column.checked_add(1) == Some(col))
+ && upper.is_none_or(|upper| u32::from(upper) == image.image_id >> 24)
+ })
+ .map(|(_, image)| image);
+ let image = Placeholder {
+ image_id: lower
+ | (u32::from(
+ upper.unwrap_or_else(|| previous.map_or(0, |p| (p.image_id >> 24) as u8)),
+ ) << 24),
+ placement_id,
+ row: row.unwrap_or_else(|| previous.map_or(0, |p| p.row)),
+ column: col
+ .unwrap_or_else(|| previous.and_then(|p| p.column.checked_add(1)).unwrap_or(0)),
+ };
+ self.previous = Some((column, image));
+ Some(image)
+ }
+}
+
+/// Visit without allocating a decoded-cell list or resolving palette colors.
+pub fn visit(line: &Line, mut emit: impl FnMut(usize, Placeholder)) {
+ // Wire rows already store contiguous text. Avoid decoding their graphemes
+ // and attributes when no placeholder is present; as_str borrows this form.
+ if line.is_compressed_for_scrollback() && !line.as_str().contains(PLACEHOLDER) {
+ return;
+ }
+ let mut decoder = Decoder::default();
+ for cell in line.visible_cells() {
+ if let Some(image) = decoder.push(
+ cell.cell_index(),
+ cell.str(),
+ cell.attrs().foreground(),
+ cell.attrs().underline_color(),
+ ) {
+ emit(cell.cell_index(), image);
+ }
+ }
+}
+
+/// A single placeholder cell's piece of an aspect-preserving, centered image.
+/// `rect` is local to the cell, and `uv` is normalized to the complete image.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct Slice {
+ pub rect: [f32; 4],
+ pub uv: [f32; 4],
+}
+
+pub fn fit_cell(
+ image: (u32, u32),
+ grid: (u32, u32),
+ cell: (f32, f32),
+ row: u32,
+ column: u32,
+) -> Option<Slice> {
+ let (iw, ih) = (f64::from(image.0), f64::from(image.1));
+ let (cw, ch) = (f64::from(cell.0), f64::from(cell.1));
+ if iw == 0.0 || ih == 0.0 || !cw.is_finite() || !ch.is_finite() || cw <= 0.0 || ch <= 0.0 {
+ return None;
+ }
+ // A missing grid dimension uses the natural image size, as Kitty does.
+ let cols = if grid.0 == 0 {
+ (iw / cw).ceil()
+ } else {
+ f64::from(grid.0)
+ };
+ let rows = if grid.1 == 0 {
+ (ih / ch).ceil()
+ } else {
+ f64::from(grid.1)
+ };
+ if f64::from(column) >= cols || f64::from(row) >= rows {
+ return None;
+ }
+ let scale = (cols * cw / iw).min(rows * ch / ih);
+ let (w, h) = (iw * scale, ih * scale);
+ let (left, top) = ((cols * cw - w) / 2.0, (rows * ch - h) / 2.0);
+ let (x, y) = (f64::from(column) * cw, f64::from(row) * ch);
+ let (x1, y1, x2, y2) = (
+ x.max(left),
+ y.max(top),
+ (x + cw).min(left + w),
+ (y + ch).min(top + h),
+ );
+ if x2 <= x1 || y2 <= y1 {
+ return None;
+ }
+ Some(Slice {
+ rect: [
+ (x1 - x) as f32,
+ (y1 - y) as f32,
+ (x2 - x) as f32,
+ (y2 - y) as f32,
+ ],
+ uv: [
+ ((x1 - left) / w) as f32,
+ ((y1 - top) / h) as f32,
+ ((x2 - left) / w) as f32,
+ ((y2 - top) / h) as f32,
+ ],
+ })
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::{Cell, CellAttributes};
+
+ const P: &str = "\u{10eeee}";
+ const FG: ColorAttribute = ColorAttribute::PaletteIndex(42);
+ const DEFAULT: ColorAttribute = ColorAttribute::Default;
+
+ #[test]
+ fn explicit_and_omitted_coordinates_match_the_protocol_examples() {
+ for row in 0..2 {
+ let mut decoder = Decoder::default();
+ let first = format!("{P}{}", char::from_u32(DIACRITICS[row]).unwrap());
+ for (column, text) in [first.as_str(), P, P].into_iter().enumerate() {
+ assert_eq!(
+ decoder.push(column, text, FG, DEFAULT),
+ Some(Placeholder {
+ image_id: 42,
+ placement_id: 0,
+ row: row as u32,
+ column: column as u32,
+ })
+ );
+ }
+ }
+ }
+
+ #[test]
+ fn high_byte_inherits_only_with_compatible_row_column_and_colors() {
+ let mut decoder = Decoder::default();
+ let start = format!("{P}\u{305}\u{305}\u{30e}");
+ assert_eq!(
+ decoder.push(0, &start, FG, DEFAULT).unwrap().image_id,
+ 33554474
+ );
+ assert_eq!(
+ decoder
+ .push(1, &format!("{P}\u{305}\u{30d}"), FG, DEFAULT)
+ .unwrap()
+ .image_id,
+ 33554474
+ );
+ let broken = decoder
+ .push(2, &format!("{P}\u{30d}"), FG, DEFAULT)
+ .unwrap();
+ assert_eq!((broken.image_id, broken.row, broken.column), (42, 1, 0));
+ decoder.push(3, &start, FG, DEFAULT);
+ let broken = decoder
+ .push(4, P, FG, ColorAttribute::PaletteIndex(3))
+ .unwrap();
+ assert_eq!(
+ (broken.image_id, broken.placement_id, broken.column),
+ (42, 3, 0)
+ );
+ }
+
+ #[test]
+ fn ordinary_text_and_non_adjacent_cells_break_inheritance() {
+ let mut decoder = Decoder::default();
+ let start = format!("{P}\u{30e}\u{30e}\u{30e}");
+ decoder.push(0, &start, FG, DEFAULT);
+ assert_eq!(decoder.push(1, "x", FG, DEFAULT), None);
+ assert_eq!(decoder.push(2, P, FG, DEFAULT).unwrap().column, 0);
+ decoder.push(3, &start, FG, DEFAULT);
+ let next = decoder.push(5, P, FG, DEFAULT).unwrap();
+ assert_eq!((next.image_id, next.row, next.column), (42, 0, 0));
+ }
+
+ #[test]
+ fn raw_color_bytes_encode_ids_without_palette_resolution() {
+ let rgb = ColorAttribute::TrueColorWithDefaultFallback(crate::color::SrgbaTuple(
+ 18.0 / 255.0,
+ 52.0 / 255.0,
+ 86.0 / 255.0,
+ 1.0,
+ ));
+ let image = Decoder::default()
+ .push(0, P, rgb, ColorAttribute::PaletteIndex(7))
+ .unwrap();
+ assert_eq!((image.image_id, image.placement_id), (0x123456, 7));
+ let mut attrs = CellAttributes::default();
+ attrs.set_foreground(FG);
+ let mut line = Line::from_cells(
+ vec![
+ Cell::new_grapheme_with_width(&format!("{P}\u{305}"), 1, attrs.clone()),
+ Cell::new_grapheme_with_width(P, 1, attrs),
+ ],
+ 1,
+ );
+ for compressed in [false, true] {
+ if compressed {
+ line.compress_for_scrollback();
+ }
+ let mut seen = vec![];
+ visit(&line, |at, image| seen.push((at, image.column)));
+ assert_eq!(seen, [(0, 0), (1, 1)]);
+ }
+ }
+
+ #[test]
+ fn table_covers_high_byte_and_non_bmp_coordinates() {
+ assert!(DIACRITICS.windows(2).all(|pair| pair[0] < pair[1]));
+ assert!(DIACRITICS.len() > 256);
+ assert_eq!(&DIACRITICS[..3], &[0x305, 0x30d, 0x30e]);
+ for (index, &code) in DIACRITICS.iter().enumerate() {
+ assert_eq!(diacritic(char::from_u32(code).unwrap()), Some(index as u32));
+ }
+ assert_eq!(diacritic('\u{301}'), None);
+ }
+
+ #[test]
+ fn letterboxing_clips_each_cell_without_stretching_the_image() {
+ let upper = fit_cell((200, 100), (2, 2), (10.0, 10.0), 0, 0).unwrap();
+ assert_eq!(upper.rect, [0.0, 5.0, 10.0, 10.0]);
+ assert_eq!(upper.uv, [0.0, 0.0, 0.5, 0.5]);
+ let lower = fit_cell((200, 100), (2, 2), (10.0, 10.0), 1, 1).unwrap();
+ assert_eq!(lower.rect, [0.0, 0.0, 10.0, 5.0]);
+ assert_eq!(lower.uv, [0.5, 0.5, 1.0, 1.0]);
+ assert!(fit_cell((200, 10), (2, 4), (10.0, 10.0), 0, 0).is_none());
+ assert!(fit_cell((200, 100), (2, 2), (10.0, 10.0), 2, 0).is_none());
+ }
+
+ #[test]
+ fn natural_grid_and_extreme_geometry_remain_finite() {
+ assert_eq!(
+ fit_cell((20, 20), (0, 0), (10.0, 10.0), 1, 1).unwrap().uv,
+ [0.5, 0.5, 1.0, 1.0]
+ );
+ for cell in [(0.0, 1.0), (1.0, f32::NAN), (f32::INFINITY, 1.0)] {
+ assert!(fit_cell((20, 20), (2, 2), cell, 0, 0).is_none());
+ }
+ assert!(fit_cell((0, 20), (2, 2), (10.0, 10.0), 0, 0).is_none());
+ if let Some(slice) = fit_cell(
+ (u32::MAX, u32::MAX),
+ (u32::MAX, u32::MAX),
+ (100.0, 100.0),
+ 100,
+ 100,
+ ) {
+ assert!(slice
+ .rect
+ .iter()
+ .chain(slice.uv.iter())
+ .all(|v| v.is_finite()));
+ assert!(slice.uv.iter().all(|v| (0.0..=1.0).contains(v)));
+ }
+ }
+}
+
+// Protocol rowcolumn-diacritics.txt, derived from Unicode 6.0 combining marks.
+// https://sw.kovidgoyal.net/kitty/graphics-protocol/#unicode-placeholders
+const DIACRITICS: &[u32] = &[
+ 0x305, 0x30d, 0x30e, 0x310, 0x312, 0x33d, 0x33e, 0x33f, 0x346, 0x34a, 0x34b, 0x34c, 0x350,
+ 0x351, 0x352, 0x357, 0x35b, 0x363, 0x364, 0x365, 0x366, 0x367, 0x368, 0x369, 0x36a, 0x36b,
+ 0x36c, 0x36d, 0x36e, 0x36f, 0x483, 0x484, 0x485, 0x486, 0x487, 0x592, 0x593, 0x594, 0x595,
+ 0x597, 0x598, 0x599, 0x59c, 0x59d, 0x59e, 0x59f, 0x5a0, 0x5a1, 0x5a8, 0x5a9, 0x5ab, 0x5ac,
+ 0x5af, 0x5c4, 0x610, 0x611, 0x612, 0x613, 0x614, 0x615, 0x616, 0x617, 0x657, 0x658, 0x659,
+ 0x65a, 0x65b, 0x65d, 0x65e, 0x6d6, 0x6d7, 0x6d8, 0x6d9, 0x6da, 0x6db, 0x6dc, 0x6df, 0x6e0,
+ 0x6e1, 0x6e2, 0x6e4, 0x6e7, 0x6e8, 0x6eb, 0x6ec, 0x730, 0x732, 0x733, 0x735, 0x736, 0x73a,
+ 0x73d, 0x73f, 0x740, 0x741, 0x743, 0x745, 0x747, 0x749, 0x74a, 0x7eb, 0x7ec, 0x7ed, 0x7ee,
+ 0x7ef, 0x7f0, 0x7f1, 0x7f3, 0x816, 0x817, 0x818, 0x819, 0x81b, 0x81c, 0x81d, 0x81e, 0x81f,
+ 0x820, 0x821, 0x822, 0x823, 0x825, 0x826, 0x827, 0x829, 0x82a, 0x82b, 0x82c, 0x82d, 0x951,
+ 0x953, 0x954, 0xf82, 0xf83, 0xf86, 0xf87, 0x135d, 0x135e, 0x135f, 0x17dd, 0x193a, 0x1a17,
+ 0x1a75, 0x1a76, 0x1a77, 0x1a78, 0x1a79, 0x1a7a, 0x1a7b, 0x1a7c, 0x1b6b, 0x1b6d, 0x1b6e, 0x1b6f,
+ 0x1b70, 0x1b71, 0x1b72, 0x1b73, 0x1cd0, 0x1cd1, 0x1cd2, 0x1cda, 0x1cdb, 0x1ce0, 0x1dc0, 0x1dc1,
+ 0x1dc3, 0x1dc4, 0x1dc5, 0x1dc6, 0x1dc7, 0x1dc8, 0x1dc9, 0x1dcb, 0x1dcc, 0x1dd1, 0x1dd2, 0x1dd3,
+ 0x1dd4, 0x1dd5, 0x1dd6, 0x1dd7, 0x1dd8, 0x1dd9, 0x1dda, 0x1ddb, 0x1ddc, 0x1ddd, 0x1dde, 0x1ddf,
+ 0x1de0, 0x1de1, 0x1de2, 0x1de3, 0x1de4, 0x1de5, 0x1de6, 0x1dfe, 0x20d0, 0x20d1, 0x20d4, 0x20d5,
+ 0x20d6, 0x20d7, 0x20db, 0x20dc, 0x20e1, 0x20e7, 0x20e9, 0x20f0, 0x2cef, 0x2cf0, 0x2cf1, 0x2de0,
+ 0x2de1, 0x2de2, 0x2de3, 0x2de4, 0x2de5, 0x2de6, 0x2de7, 0x2de8, 0x2de9, 0x2dea, 0x2deb, 0x2dec,
+ 0x2ded, 0x2dee, 0x2def, 0x2df0, 0x2df1, 0x2df2, 0x2df3, 0x2df4, 0x2df5, 0x2df6, 0x2df7, 0x2df8,
+ 0x2df9, 0x2dfa, 0x2dfb, 0x2dfc, 0x2dfd, 0x2dfe, 0x2dff, 0xa66f, 0xa67c, 0xa67d, 0xa6f0, 0xa6f1,
+ 0xa8e0, 0xa8e1, 0xa8e2, 0xa8e3, 0xa8e4, 0xa8e5, 0xa8e6, 0xa8e7, 0xa8e8, 0xa8e9, 0xa8ea, 0xa8eb,
+ 0xa8ec, 0xa8ed, 0xa8ee, 0xa8ef, 0xa8f0, 0xa8f1, 0xaab0, 0xaab2, 0xaab3, 0xaab7, 0xaab8, 0xaabe,
+ 0xaabf, 0xaac1, 0xfe20, 0xfe21, 0xfe22, 0xfe23, 0xfe24, 0xfe25, 0xfe26, 0x10a0f, 0x10a38,
+ 0x1d185, 0x1d186, 0x1d187, 0x1d188, 0x1d189, 0x1d1aa, 0x1d1ab, 0x1d1ac, 0x1d1ad, 0x1d242,
+ 0x1d243, 0x1d244,
+];
diff --git a/term/src/kitty_relative.rs b/term/src/kitty_relative.rs
new file mode 100644
index 00000000..24032f0b
--- /dev/null
+++ b/term/src/kitty_relative.rs
@@ -0,0 +1,745 @@
+//! Bounded parent relationships for Kitty relative placements.
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::convert::TryFrom;
+use wezterm_escape_parser::apc::KittyImagePlacement;
+use wezterm_cell::image::{ImageCell, TextureCoordinate};
+
+pub const MAX_RELATIVE_PLACEMENTS: usize = 65536;
+pub const MAX_PARENT_DEPTH: usize = 64;
+
+/// A stable placement identity. The wider placement key also permits distinct
+/// anonymous placements; their wire p=0 must be resolved before entering here.
+#[cfg_attr(feature = "use_serde", derive(serde::Serialize, serde::Deserialize))]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct PlacementKey {
+ pub image_id: u32,
+ pub placement_id: u64,
+}
+
+impl PlacementKey {
+ pub fn protocol_id(self) -> Option<u32> {
+ u32::try_from(self.placement_id).ok().filter(|id| *id != 0)
+ }
+}
+
+/// Recover a placement's origin from any surviving cell after scrolling.
+#[cfg_attr(feature = "use_serde", derive(serde::Serialize, serde::Deserialize))]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct CellOrigin {
+ pub source: TextureCoordinate,
+ pub step: TextureCoordinate,
+}
+
+impl CellOrigin {
+ pub fn anchor(&self, column: usize, row: i64, alternate: bool, cell: &ImageCell) -> Option<Anchor> {
+ let source = cell.top_left();
+ let x = self.step.x.into_inner();
+ let y = self.step.y.into_inner();
+ if !self.valid() { return None; }
+ let dx = ((source.x.into_inner() - self.source.x.into_inner()) / x).round() as i64;
+ let dy = ((source.y.into_inner() - self.source.y.into_inner()) / y).round() as i64;
+ Some(Anchor { column: (column as i64).checked_sub(dx)?, row: row.checked_sub(dy)?, alt_screen: alternate })
+ }
+
+ pub fn valid(&self) -> bool {
+ [self.source.x, self.source.y, self.step.x, self.step.y].iter().all(|v| v.into_inner().is_finite())
+ && self.step.x.into_inner() > 0.0 && self.step.y.into_inner() > 0.0
+ }
+}
+
+#[cfg_attr(feature = "use_serde", derive(serde::Serialize, serde::Deserialize))]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct RelativeView {
+ pub placement_id: u64,
+ /// The terminal update that established this position.
+ pub source_seqno: u64,
+ pub anchor: Anchor,
+ pub geometry: PlacementGeometry,
+ pub image_size: (u32, u32),
+}
+
+#[cfg_attr(feature = "use_serde", derive(serde::Serialize, serde::Deserialize))]
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RelativeSnapshot {
+ pub origins: Vec<(PlacementKey, CellOrigin)>,
+ pub placements: Vec<RelativePlacement>,
+}
+
+#[cfg_attr(feature = "use_serde", derive(serde::Serialize, serde::Deserialize))]
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+pub struct PlacementGeometry {
+ pub x: u32,
+ pub y: u32,
+ /// Zero uses the remaining source extent or the natural cell extent.
+ pub width: u32,
+ pub height: u32,
+ pub columns: u32,
+ pub rows: u32,
+ pub x_offset: u32,
+ pub y_offset: u32,
+ pub z_index: i32,
+}
+
+impl From<&KittyImagePlacement> for PlacementGeometry {
+ fn from(placement: &KittyImagePlacement) -> Self {
+ Self {
+ x: placement.x.unwrap_or(0),
+ y: placement.y.unwrap_or(0),
+ width: placement.w.unwrap_or(0),
+ height: placement.h.unwrap_or(0),
+ columns: placement.columns.unwrap_or(0),
+ rows: placement.rows.unwrap_or(0),
+ x_offset: placement.x_offset.unwrap_or(0),
+ y_offset: placement.y_offset.unwrap_or(0),
+ z_index: placement.z_index.unwrap_or(0),
+ }
+ }
+}
+
+/// Source UVs and destination pixel edges relative to the anchor cell. Keep
+/// double precision until clipping; large cell counts must not allocate cells.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct PlacementLayout {
+ pub rect: [f64; 4],
+ pub uv: [f64; 4],
+}
+
+impl PlacementGeometry {
+ pub fn layout(&self, image: (u32, u32), cell: (u32, u32)) -> Option<PlacementLayout> {
+ if image.0 == 0 || image.1 == 0 || cell.0 == 0 || cell.1 == 0 {
+ return None;
+ }
+ let remaining_width = image.0.saturating_sub(self.x);
+ let remaining_height = image.1.saturating_sub(self.y);
+ let width = if self.width == 0 {
+ remaining_width
+ } else {
+ self.width.min(remaining_width)
+ };
+ let height = if self.height == 0 {
+ remaining_height
+ } else {
+ self.height.min(remaining_height)
+ };
+ if width == 0 || height == 0 {
+ return None;
+ }
+ let left = f64::from(self.x_offset.min(cell.0 - 1));
+ let top = f64::from(self.y_offset.min(cell.1 - 1));
+ let aspect = f64::from(width) / f64::from(height);
+ let (right, bottom) = if self.rows > 0 {
+ let bottom = f64::from(self.rows) * f64::from(cell.1);
+ let right = if self.columns > 0 {
+ f64::from(self.columns) * f64::from(cell.0)
+ } else {
+ left + (bottom - top) * aspect
+ };
+ (right, bottom)
+ } else {
+ let right = if self.columns > 0 {
+ f64::from(self.columns) * f64::from(cell.0)
+ } else {
+ left + f64::from(width)
+ };
+ (right, top + (right - left) / aspect)
+ };
+ Some(PlacementLayout {
+ rect: [left, top, right, bottom],
+ uv: [
+ f64::from(self.x) / f64::from(image.0),
+ f64::from(self.y) / f64::from(image.1),
+ (f64::from(self.x) + f64::from(width)) / f64::from(image.0),
+ (f64::from(self.y) + f64::from(height)) / f64::from(image.1),
+ ],
+ })
+ }
+}
+
+#[cfg_attr(feature = "use_serde", derive(serde::Serialize, serde::Deserialize))]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct RelativePlacement {
+ pub key: PlacementKey,
+ pub parent: PlacementKey,
+ pub horizontal: i32,
+ pub vertical: i32,
+ pub geometry: PlacementGeometry,
+}
+
+#[cfg_attr(feature = "use_serde", derive(serde::Serialize, serde::Deserialize))]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Anchor {
+ pub column: i64,
+ /// Stable row, kept at fixed width when transferred to a 32-bit browser.
+ pub row: i64,
+ pub alt_screen: bool,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PlacementError {
+ MissingParent,
+ Cycle,
+ TooDeep,
+ Full,
+ Duplicate,
+}
+
+impl PlacementError {
+ pub fn code(self) -> &'static str {
+ match self {
+ Self::MissingParent => "ENOPARENT",
+ Self::Cycle => "ECYCLE",
+ Self::TooDeep => "ETOODEEP",
+ Self::Full => "ENOSPC",
+ Self::Duplicate => "EINVAL",
+ }
+ }
+}
+
+#[derive(Debug, Default, PartialEq, Eq)]
+pub struct RelativePlacements {
+ entries: BTreeMap<PlacementKey, RelativePlacement>,
+ children: BTreeSet<(PlacementKey, PlacementKey)>,
+}
+
+impl RelativePlacements {
+ pub fn is_empty(&self) -> bool {
+ self.entries.is_empty()
+ }
+
+ pub fn len(&self) -> usize {
+ self.entries.len()
+ }
+
+ pub fn get(&self, key: PlacementKey) -> Option<&RelativePlacement> {
+ self.entries.get(&key)
+ }
+
+ pub fn iter(&self) -> impl Iterator<Item = &RelativePlacement> {
+ self.entries.values()
+ }
+
+ /// Turning a relative into a root preserves its descendants.
+ pub fn make_root(&mut self, key: PlacementKey) -> bool {
+ if let Some(old) = self.entries.remove(&key) {
+ self.unlink(old.parent, key);
+ true
+ } else {
+ false
+ }
+ }
+
+ fn children_of(&self, key: PlacementKey) -> impl Iterator<Item = PlacementKey> + '_ {
+ let first = PlacementKey {
+ image_id: 0,
+ placement_id: 0,
+ };
+ let last = PlacementKey {
+ image_id: u32::MAX,
+ placement_id: u64::MAX,
+ };
+ self.children
+ .range((key, first)..=(key, last))
+ .map(|(_, child)| *child)
+ }
+
+ /// Validate before changing either index. A replacement also checks its
+ /// descendants: moving a short subtree deeper can exceed the depth limit.
+ pub fn insert(
+ &mut self,
+ placement: RelativePlacement,
+ parent_exists: impl Fn(PlacementKey) -> bool,
+ ) -> Result<bool, PlacementError> {
+ let old = self.entries.get(&placement.key).copied();
+ if old.is_none() && self.entries.len() == MAX_RELATIVE_PLACEMENTS {
+ return Err(PlacementError::Full);
+ }
+ let depth = self.parent_depth(placement.key, placement.parent, &parent_exists)?;
+ if old.is_none_or(|old| old.parent != placement.parent) {
+ let mut pending = vec![(placement.key, depth)];
+ while let Some((key, depth)) = pending.pop() {
+ for child in self.children_of(key) {
+ if depth == MAX_PARENT_DEPTH {
+ return Err(PlacementError::TooDeep);
+ }
+ pending.push((child, depth + 1));
+ }
+ }
+ }
+ if old == Some(placement) {
+ return Ok(false);
+ }
+ if let Some(old) = old.filter(|old| old.parent != placement.parent) {
+ self.unlink(old.parent, old.key);
+ }
+ self.children.insert((placement.parent, placement.key));
+ self.entries.insert(placement.key, placement);
+ Ok(true)
+ }
+
+ fn parent_depth(
+ &self,
+ key: PlacementKey,
+ mut parent: PlacementKey,
+ parent_exists: &impl Fn(PlacementKey) -> bool,
+ ) -> Result<usize, PlacementError> {
+ for depth in 1..=MAX_PARENT_DEPTH + 1 {
+ if parent == key {
+ return Err(PlacementError::Cycle);
+ }
+ if depth > MAX_PARENT_DEPTH {
+ return Err(PlacementError::TooDeep);
+ }
+ match self.entries.get(&parent) {
+ Some(placement) => parent = placement.parent,
+ None if parent_exists(parent) => return Ok(depth),
+ None => return Err(PlacementError::MissingParent),
+ }
+ }
+ Err(PlacementError::TooDeep)
+ }
+
+ fn unlink(&mut self, parent: PlacementKey, key: PlacementKey) {
+ self.children.remove(&(parent, key));
+ }
+
+ /// Roots may be ordinary or virtual placements outside this graph. Return
+ /// removed relatives so the image store can release now-unreferenced data.
+ pub fn remove(
+ &mut self,
+ roots: impl IntoIterator<Item = PlacementKey>,
+ ) -> Vec<RelativePlacement> {
+ let mut removed = Vec::new();
+ let mut pending: Vec<_> = roots.into_iter().collect();
+ while let Some(key) = pending.pop() {
+ loop {
+ let child = self.children_of(key).next();
+ let Some(child) = child else { break };
+ self.unlink(key, child);
+ pending.push(child);
+ }
+ if let Some(placement) = self.entries.remove(&key) {
+ self.unlink(placement.parent, key);
+ removed.push(placement);
+ }
+ }
+ removed
+ }
+
+ /// Resolve at the current terminal geometry, never at creation time. The
+ /// root provider handles ordinary cells and Unicode placeholder anchors.
+ pub fn resolve(
+ &self,
+ mut key: PlacementKey,
+ root: impl Fn(PlacementKey) -> Option<Anchor>,
+ ) -> Option<Anchor> {
+ let (mut horizontal, mut vertical) = (0i64, 0i64);
+ for _ in 0..=MAX_PARENT_DEPTH {
+ match self.entries.get(&key) {
+ Some(placement) => {
+ horizontal += i64::from(placement.horizontal);
+ vertical += i64::from(placement.vertical);
+ key = placement.parent;
+ }
+ None => {
+ let anchor = root(key)?;
+ return Some(Anchor {
+ column: anchor.column.checked_add(horizontal)?,
+ row: anchor.row.checked_add(vertical)?,
+ alt_screen: anchor.alt_screen,
+ });
+ }
+ }
+ }
+ None
+ }
+
+ pub fn restore(
+ placements: Vec<RelativePlacement>,
+ parent_exists: impl Fn(PlacementKey) -> bool,
+ ) -> Result<Self, PlacementError> {
+ if placements.len() > MAX_RELATIVE_PLACEMENTS {
+ return Err(PlacementError::Full);
+ }
+ let mut graph = Self::default();
+ for placement in placements {
+ if graph.entries.insert(placement.key, placement).is_some() {
+ return Err(PlacementError::Duplicate);
+ }
+ graph.children.insert((placement.parent, placement.key));
+ }
+ for placement in graph.entries.values() {
+ graph.parent_depth(placement.key, placement.parent, &parent_exists)?;
+ }
+ Ok(graph)
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn key(image_id: u32) -> PlacementKey {
+ PlacementKey {
+ image_id,
+ placement_id: 1,
+ }
+ }
+
+ fn placement(image_id: u32, parent: u32) -> RelativePlacement {
+ RelativePlacement {
+ key: key(image_id),
+ parent: key(parent),
+ horizontal: -2,
+ vertical: 3,
+ geometry: PlacementGeometry {
+ columns: 4,
+ rows: 2,
+ ..Default::default()
+ },
+ }
+ }
+
+ #[test]
+ fn geometry_preserves_aspect_only_when_one_or_both_cell_extents_are_omitted() {
+ for (columns, rows, rect) in [
+ (0, 0, [0.0, 0.0, 100.0, 50.0]),
+ (4, 0, [0.0, 0.0, 40.0, 20.0]),
+ (0, 4, [0.0, 0.0, 160.0, 80.0]),
+ (4, 4, [0.0, 0.0, 40.0, 80.0]),
+ ] {
+ let layout = PlacementGeometry {
+ columns,
+ rows,
+ ..Default::default()
+ }
+ .layout((100, 50), (10, 20))
+ .unwrap();
+ assert_eq!(
+ layout,
+ PlacementLayout {
+ rect,
+ uv: [0.0, 0.0, 1.0, 1.0]
+ }
+ );
+ }
+ for (columns, rows, rect) in [
+ (4, 0, [3.0, 5.0, 40.0, 23.5]),
+ (0, 4, [3.0, 5.0, 153.0, 80.0]),
+ (4, 4, [3.0, 5.0, 40.0, 80.0]),
+ ] {
+ let layout = PlacementGeometry {
+ columns,
+ rows,
+ x_offset: 3,
+ y_offset: 5,
+ ..Default::default()
+ }
+ .layout((100, 50), (10, 20))
+ .unwrap();
+ assert_eq!(layout.rect, rect);
+ }
+ }
+
+ #[test]
+ fn geometry_clips_the_source_and_handles_empty_and_extreme_inputs() {
+ for (width, height) in [(0, 0), (30, 20)] {
+ let layout = PlacementGeometry {
+ x: 90,
+ y: 40,
+ width,
+ height,
+ ..Default::default()
+ }
+ .layout((100, 50), (10, 20))
+ .unwrap();
+ assert_eq!(
+ layout,
+ PlacementLayout {
+ rect: [0.0, 0.0, 10.0, 10.0],
+ uv: [0.9, 0.8, 1.0, 1.0]
+ }
+ );
+ }
+ assert!(PlacementGeometry {
+ x: 100,
+ ..Default::default()
+ }
+ .layout((100, 50), (10, 20))
+ .is_none());
+ for (image, cell) in [
+ ((0, 1), (10, 20)),
+ ((1, 0), (10, 20)),
+ ((1, 1), (0, 20)),
+ ((1, 1), (10, 0)),
+ ] {
+ assert!(PlacementGeometry::default().layout(image, cell).is_none());
+ }
+ let layout = PlacementGeometry {
+ columns: u32::MAX,
+ rows: u32::MAX,
+ x_offset: u32::MAX,
+ y_offset: u32::MAX,
+ ..Default::default()
+ }
+ .layout((u32::MAX, u32::MAX), (10, 20))
+ .unwrap();
+ assert_eq!(&layout.rect[..2], &[9.0, 19.0]);
+ assert!(layout.rect.iter().all(|value| value.is_finite()));
+ assert_eq!(layout.rect[2], f64::from(u32::MAX) * 10.0);
+ }
+
+ #[test]
+ fn relationships_follow_current_roots_and_preserve_signed_offsets() {
+ let mut graph = RelativePlacements::default();
+ graph
+ .insert(placement(2, 1), |key| key.image_id == 1)
+ .unwrap();
+ graph
+ .insert(placement(3, 2), |key| key.image_id == 1)
+ .unwrap();
+ for (row, column, alt_screen) in [(0, 0, false), (-100, 20, true)] {
+ let root = |key: PlacementKey| {
+ (key.image_id == 1).then_some(Anchor {
+ row,
+ column,
+ alt_screen,
+ })
+ };
+ assert_eq!(
+ graph.resolve(key(3), root),
+ Some(Anchor {
+ column: column - 4,
+ row: row + 6,
+ alt_screen,
+ })
+ );
+ }
+ assert_eq!(graph.resolve(key(3), |_| None), None);
+ assert_eq!(
+ graph.resolve(key(3), |_| Some(Anchor {
+ column: i64::MIN,
+ row: 0,
+ alt_screen: false
+ })),
+ None
+ );
+ }
+
+ #[test]
+ fn invalid_replacements_leave_the_graph_and_children_unchanged() {
+ let mut graph = RelativePlacements::default();
+ let root = |key: PlacementKey| key.image_id == 1;
+ graph.insert(placement(2, 1), root).unwrap();
+ graph.insert(placement(3, 2), root).unwrap();
+ let snapshot: Vec<_> = graph.iter().copied().collect();
+ for (replacement, error) in [
+ (placement(2, 2), PlacementError::Cycle),
+ (placement(2, 3), PlacementError::Cycle),
+ (placement(2, 99), PlacementError::MissingParent),
+ ] {
+ assert_eq!(graph.insert(replacement, root), Err(error));
+ assert_eq!(
+ graph,
+ RelativePlacements::restore(snapshot.clone(), root).unwrap()
+ );
+ }
+ assert_eq!(graph.insert(placement(2, 1), root), Ok(false));
+ }
+
+ #[test]
+ fn deleting_a_root_removes_only_its_descendants_and_releases_indexes() {
+ let mut graph = RelativePlacements::default();
+ for (child, parent) in [(2, 1), (3, 2), (4, 1), (6, 5)] {
+ graph
+ .insert(placement(child, parent), |key| {
+ matches!(key.image_id, 1 | 5)
+ })
+ .unwrap();
+ }
+ // Reparenting removes the old reverse edge.
+ graph
+ .insert(placement(4, 5), |key| matches!(key.image_id, 1 | 5))
+ .unwrap();
+ let removed: BTreeSet<_> = graph
+ .remove([key(1), key(2), key(1)])
+ .into_iter()
+ .map(|p| p.key.image_id)
+ .collect();
+ assert_eq!(removed, [2, 3].into());
+ assert_eq!(
+ graph.iter().map(|p| p.key.image_id).collect::<Vec<_>>(),
+ [4, 6]
+ );
+ graph.remove([key(5)]);
+ assert_eq!(graph, RelativePlacements::default());
+ }
+
+ #[test]
+ fn deep_chains_and_reparented_subtrees_share_the_same_depth_bound() {
+ let mut graph = RelativePlacements::default();
+ let root = |key: PlacementKey| key.image_id == 1;
+ for child in 2..=MAX_PARENT_DEPTH as u32 + 1 {
+ graph.insert(placement(child, child - 1), root).unwrap();
+ }
+ assert!(MAX_PARENT_DEPTH >= 8);
+ let snapshot: Vec<_> = graph.iter().copied().collect();
+ assert_eq!(
+ graph.insert(placement(1, MAX_PARENT_DEPTH as u32 + 1), root),
+ Err(PlacementError::Cycle)
+ );
+ assert_eq!(
+ graph.insert(placement(100, MAX_PARENT_DEPTH as u32 + 1), root),
+ Err(PlacementError::TooDeep)
+ );
+ // A node itself fits at depth64, but its child would not.
+ graph.insert(placement(101, 1), root).unwrap();
+ graph.insert(placement(102, 101), root).unwrap();
+ assert_eq!(
+ graph.insert(placement(101, MAX_PARENT_DEPTH as u32), root),
+ Err(PlacementError::TooDeep)
+ );
+ assert_eq!(graph.get(key(101)), Some(&placement(101, 1)));
+ let mut reversed = snapshot.clone();
+ reversed.reverse();
+ assert_eq!(
+ RelativePlacements::restore(reversed, root)
+ .unwrap()
+ .iter()
+ .copied()
+ .collect::<Vec<_>>(),
+ snapshot
+ );
+ }
+
+ #[test]
+ fn restore_rejects_duplicate_missing_and_cyclic_parents() {
+ for placements in [
+ vec![placement(2, 1), placement(2, 1)],
+ vec![placement(2, 99)],
+ vec![placement(2, 3), placement(3, 2)],
+ ] {
+ assert!(RelativePlacements::restore(placements, |key| key.image_id == 1).is_err());
+ }
+ }
+
+ #[test]
+ fn anonymous_keys_and_maximum_ids_keep_distinct_parent_edges() {
+ let root = PlacementKey {
+ image_id: u32::MAX,
+ placement_id: u64::MAX,
+ };
+ let first = PlacementKey {
+ image_id: 7,
+ placement_id: u64::from(u32::MAX) + 1,
+ };
+ let second = PlacementKey {
+ image_id: 7,
+ placement_id: first.placement_id + 1,
+ };
+ let mut graph = RelativePlacements::default();
+ let a = RelativePlacement {
+ key: first,
+ parent: root,
+ ..placement(7, 1)
+ };
+ let b = RelativePlacement {
+ key: second,
+ parent: first,
+ ..a
+ };
+ graph.insert(a, |key| key == root).unwrap();
+ graph.insert(b, |key| key == root).unwrap();
+ assert_eq!(graph.remove([first]), [a, b]);
+ assert_eq!(graph, RelativePlacements::default());
+ }
+
+ #[test]
+ fn indexed_mutations_match_an_unindexed_parent_walk() {
+ let mut graph = RelativePlacements::default();
+ let mut reference = BTreeMap::<PlacementKey, RelativePlacement>::new();
+ let mut random = 17u32;
+ for step in 0..1000 {
+ random = random.wrapping_mul(1664525).wrapping_add(1013904223);
+ let child = key(3 + random % 40);
+ let parent = key((random >> 12) % 43);
+ if step % 3 == 0 {
+ let root = if step % 9 == 0 { key(1) } else { child };
+ // Walk each candidate's ancestors; no reverse-child index.
+ let doomed: Vec<_> = reference
+ .keys()
+ .copied()
+ .filter(|key| {
+ let mut current = *key;
+ loop {
+ if current == root {
+ return true;
+ }
+ match reference.get(&current) {
+ Some(placement) => current = placement.parent,
+ None => return false,
+ }
+ }
+ })
+ .collect();
+ for key in doomed {
+ reference.remove(&key);
+ }
+ graph.remove([root]);
+ } else {
+ let candidate = RelativePlacement {
+ key: child,
+ parent,
+ ..placement(3, 1)
+ };
+ let mut current = parent;
+ let mut visited = BTreeSet::from([child]);
+ let error = loop {
+ if !visited.insert(current) {
+ break Some(PlacementError::Cycle);
+ }
+ match reference.get(&current) {
+ Some(placement) => current = placement.parent,
+ None if matches!(current.image_id, 1 | 2) => break None,
+ None => break Some(PlacementError::MissingParent),
+ }
+ };
+ let result = graph.insert(candidate, |key| matches!(key.image_id, 1 | 2));
+ match error {
+ Some(error) => assert_eq!(result, Err(error)),
+ None => {
+ assert_eq!(result, Ok(reference.get(&child) != Some(&candidate)));
+ reference.insert(child, candidate);
+ }
+ }
+ }
+ assert_eq!(graph.entries, reference);
+ let expected_edges: BTreeSet<_> =
+ reference.values().map(|p| (p.parent, p.key)).collect();
+ assert_eq!(graph.children, expected_edges);
+ }
+ }
+
+ #[test]
+ fn placement_budget_allows_replacement_and_is_reusable_after_removal() {
+ let mut graph = RelativePlacements::default();
+ for id in 2..MAX_RELATIVE_PLACEMENTS as u32 + 2 {
+ graph
+ .insert(placement(id, 1), |key| key.image_id == 1)
+ .unwrap();
+ }
+ assert_eq!(graph.len(), MAX_RELATIVE_PLACEMENTS);
+ assert_eq!(
+ graph.insert(placement(u32::MAX, 1), |_| true),
+ Err(PlacementError::Full)
+ );
+ let mut changed = placement(2, 1);
+ changed.horizontal = i32::MIN;
+ graph.insert(changed, |_| true).unwrap();
+ graph.remove([key(2)]);
+ graph.insert(placement(u32::MAX, 1), |_| true).unwrap();
+ graph.remove([key(1)]);
+ assert!(graph.is_empty());
+ assert!(graph.children.is_empty());
+ }
+}
diff --git a/term/src/kitty_virtual.rs b/term/src/kitty_virtual.rs
new file mode 100644
index 00000000..867512c4
--- /dev/null
+++ b/term/src/kitty_virtual.rs
@@ -0,0 +1,136 @@
+//! Virtual placements describe placeholder grids without attaching desktop cells.
+
+use std::collections::BTreeMap;
+
+pub const MAX_VIRTUAL_PLACEMENTS: usize = 65536;
+
+#[cfg_attr(feature = "use_serde", derive(serde::Serialize, serde::Deserialize))]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct VirtualPlacement {
+ pub placement_id: u32,
+ /// Zero uses the natural image size in that dimension.
+ pub columns: u32,
+ pub rows: u32,
+}
+
+/// Process-independent identity for the optional handoff companion. Pixel data
+/// stays in the terminal snapshot's image table; it is not duplicated here.
+#[cfg_attr(feature = "use_serde", derive(serde::Serialize, serde::Deserialize))]
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct VirtualImage {
+ pub image_id: u32,
+ pub data_hash: [u8; 32],
+ pub placements: Vec<VirtualPlacement>,
+}
+
+pub fn find(placements: &[VirtualPlacement], id: u32) -> Option<VirtualPlacement> {
+ if id == 0 {
+ placements.first().copied()
+ } else {
+ placements.binary_search_by_key(&id, |p| p.placement_id)
+ .ok().map(|index| placements[index])
+ }
+}
+
+pub fn valid(placements: &[VirtualPlacement]) -> bool {
+ placements.len() <= MAX_VIRTUAL_PLACEMENTS
+ && placements.windows(2).all(|pair| pair[0].placement_id < pair[1].placement_id)
+}
+
+#[derive(Debug, Default)]
+pub(crate) struct VirtualPlacements {
+ entries: BTreeMap<(u32, u32), VirtualPlacement>,
+}
+
+impl VirtualPlacements {
+ pub fn contains(&self, image_id: u32, placement_id: u32) -> bool {
+ self.entries.contains_key(&(image_id, placement_id))
+ }
+
+ pub fn first(&self, image_id: u32) -> Option<VirtualPlacement> {
+ self.entries.range((image_id, 0)..=(image_id, u32::MAX)).next().map(|(_, p)| *p)
+ }
+
+ pub fn insert(&mut self, image_id: u32, placement: VirtualPlacement) -> bool {
+ let key = (image_id, placement.placement_id);
+ if self.entries.get(&key) == Some(&placement) {
+ return false;
+ }
+ if self.entries.len() == MAX_VIRTUAL_PLACEMENTS && !self.entries.contains_key(&key) {
+ log::warn!("Kitty virtual placement budget exhausted");
+ return false;
+ }
+ self.entries.insert(key, placement);
+ true
+ }
+
+ pub fn for_image(&self, image_id: u32) -> Vec<VirtualPlacement> {
+ self.entries
+ .range((image_id, 0)..=(image_id, u32::MAX))
+ .map(|(_, placement)| *placement)
+ .collect()
+ }
+
+ pub fn contains_image(&self, image_id: u32) -> bool {
+ self.entries.range((image_id, 0)..=(image_id, u32::MAX)).next().is_some()
+ }
+
+ pub fn remove(&mut self, image_id: u32, placement_id: Option<u32>) -> bool {
+ if let Some(id) = placement_id.filter(|id| *id != 0) {
+ return self.entries.remove(&(image_id, id)).is_some();
+ }
+ let before = self.entries.len();
+ // Remove only this image's range, without scanning unrelated images
+ // or allocating a temporary list of all its placement keys.
+ while let Some(key) = self.entries
+ .range((image_id, 0)..=(image_id, u32::MAX))
+ .next()
+ .map(|(key, _)| *key)
+ {
+ self.entries.remove(&key);
+ }
+ before != self.entries.len()
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn placement(id: u32) -> VirtualPlacement {
+ VirtualPlacement { placement_id: id, columns: 10, rows: 5 }
+ }
+
+ #[test]
+ fn replace_and_remove_leave_other_images_and_placements_intact() {
+ let mut store = VirtualPlacements::default();
+ assert!(store.insert(1, placement(2)));
+ assert!(!store.insert(1, placement(2)));
+ store.insert(1, placement(3));
+ store.insert(2, placement(2));
+ let resized = VirtualPlacement { columns: 20, ..placement(2) };
+ assert!(store.insert(1, resized));
+ assert_eq!(store.for_image(1), [resized, placement(3)]);
+ assert!(store.remove(1, Some(2)));
+ assert_eq!(store.for_image(1), [placement(3)]);
+ assert!(store.remove(1, Some(0)));
+ assert!(store.for_image(1).is_empty());
+ assert_eq!(store.for_image(2), [placement(2)]);
+ assert!(!store.remove(1, None));
+ assert!(store.remove(2, None));
+ assert!(store.entries.is_empty());
+ }
+
+ #[test]
+ fn global_limit_allows_replacement_and_recovers_after_deletion() {
+ let mut store = VirtualPlacements::default();
+ for id in 0..MAX_VIRTUAL_PLACEMENTS as u32 {
+ assert!(store.insert(id, placement(0)));
+ }
+ assert!(!store.insert(u32::MAX, placement(0)));
+ assert!(store.insert(0, VirtualPlacement { rows: 7, ..placement(0) }));
+ assert!(store.remove(0, None));
+ assert!(store.insert(u32::MAX, placement(0)));
+ assert_eq!(store.entries.len(), MAX_VIRTUAL_PLACEMENTS);
+ }
+}
diff --git a/term/src/lib.rs b/term/src/lib.rs
index 56d68557..d4798c5c 100644
--- a/term/src/lib.rs
+++ b/term/src/lib.rs
@@ -29,6 +29,32 @@ pub use config::TerminalConfiguration;
pub mod input;
pub use crate::input::*;
+pub mod kitty_animation;
+pub mod kitty_placeholder;
+pub mod kitty_relative;
+pub mod kitty_virtual;
+
+/// Graphics state carried alongside the unchanged legacy terminal snapshot.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct KittyGraphicsSnapshot {
+ pub playback: kitty_animation::KittyPlaybackSnapshot,
+ pub virtual_images: Vec<kitty_virtual::VirtualImage>,
+ pub image_numbers: Vec<(u32, u32)>,
+ pub placements: Option<KittyPlacementSnapshot>,
+ pub relatives: Option<kitty_relative::RelativeSnapshot>,
+}
+
+/// Web/mobile frame selection, independent of the legacy desktop animator.
+#[cfg_attr(feature = "use_serde", derive(Serialize, Deserialize))]
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct KittyFrameSelection {
+ pub image_id: u32,
+ pub data_generation: u64,
+ pub data_hash: [u8; 32],
+ pub animation: kitty_animation::KittyAnimation,
+ pub virtual_placements: Vec<kitty_virtual::VirtualPlacement>,
+ pub relative_placements: Vec<kitty_relative::RelativeView>,
+}
pub use wezterm_cell::*;
pub use wezterm_surface::line::*;
diff --git a/term/src/screen.rs b/term/src/screen.rs
index f628a90c..004c7954 100644
--- a/term/src/screen.rs
+++ b/term/src/screen.rs
@@ -249,7 +249,11 @@ impl Screen {
// real information off the top of the scrollback
let capacity = physical_rows + self.scrollback_size();
while self.lines.len() > capacity
- && self.lines.back().map(Line::is_whitespace).unwrap_or(false)
+ && self
+ .lines
+ .back()
+ .map(|line| line.is_whitespace() && !line.has_images())
+ .unwrap_or(false)
{
self.lines.pop_back();
}
@@ -286,7 +290,12 @@ impl Screen {
// maximized states.
let cursor_phys = self.phys_row(cursor.y);
for _ in cursor_phys + 1..self.lines.len() {
- if self.lines.back().map(Line::is_whitespace).unwrap_or(false) {
+ if self
+ .lines
+ .back()
+ .map(|line| line.is_whitespace() && !line.has_images())
+ .unwrap_or(false)
+ {
self.lines.pop_back();
}
}
diff --git a/term/src/terminal.rs b/term/src/terminal.rs
index 16eaecb9..6fd1528c 100644
--- a/term/src/terminal.rs
+++ b/term/src/terminal.rs
@@ -174,6 +174,7 @@ impl Terminal {
ParsedAction::Print(text) => performer.print_text(text),
});
}
+ self.state.kitty_scene_refresh();
self.trigger_unseen_output_notif();
}
@@ -191,6 +192,7 @@ impl Terminal {
performer.perform(action);
}
}
+ self.state.kitty_scene_refresh();
self.trigger_unseen_output_notif();
}
}
diff --git a/term/src/terminalstate/image.rs b/term/src/terminalstate/image.rs
index 8d5099e4..b9743bad 100644
--- a/term/src/terminalstate/image.rs
+++ b/term/src/terminalstate/image.rs
@@ -25,6 +25,22 @@ pub struct PlacementInfo {
pub alt_screen: bool,
}
+#[derive(Debug, Clone, Copy)]
+pub struct ImagePlacement {
+ pub info: PlacementInfo,
+ pub origin: Option<crate::kitty_relative::CellOrigin>,
+}
+
+/// Internal placement identities accompany the legacy handoff snapshot.
+#[cfg_attr(feature = "use_serde", derive(serde::Serialize, serde::Deserialize))]
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct KittyPlacementSnapshot {
+ pub next_id: u64,
+ pub placements: Vec<(crate::kitty_relative::PlacementKey, PlacementInfo)>,
+ /// In snapshot image-cell order, before either screen trims scrollback.
+ pub cell_tags: [Vec<u64>; 2],
+}
+
#[derive(Debug, PartialEq, Eq)]
pub struct ImageAttachParams {
/// Dimensions of the underlying ImageData, in pixels
@@ -56,6 +72,7 @@ pub struct ImageAttachParams {
pub image_id: Option<u32>,
pub placement_id: Option<u32>,
+ pub placement_tag: u64,
pub style: ImageAttachStyle,
pub do_not_move_cursor: bool,
@@ -74,7 +91,7 @@ impl TerminalState {
pub(crate) fn assign_image_to_cells(
&mut self,
params: ImageAttachParams,
- ) -> anyhow::Result<PlacementInfo> {
+ ) -> anyhow::Result<ImagePlacement> {
let seqno = self.seqno;
let physical_cols = self.screen().physical_cols;
let physical_rows = self.screen().physical_rows;
@@ -190,6 +207,13 @@ impl TerminalState {
);
let mut remain_y = target_pixel_height;
+ if params.style == ImageAttachStyle::Kitty {
+ if let (Some(image_id), Some(placement_id)) =
+ (params.image_id, params.placement_id.filter(|id| *id != 0))
+ {
+ self.kitty_replace_placement(image_id, placement_id);
+ }
+ }
for y in 0..height_in_cells {
let padding_bottom = cell_pixel_height.saturating_sub(remain_y) as u16;
let y_delta = (remain_y.min(cell_pixel_height) as f32) / y_delta_divisor as f32;
@@ -237,7 +261,7 @@ impl TerminalState {
padding_bottom,
params.image_id,
params.placement_id,
- ));
+ ).with_placement_tag(params.placement_tag));
match params.style {
ImageAttachStyle::Kitty => cell.attrs_mut().attach_image(img),
ImageAttachStyle::Sixel | ImageAttachStyle::Iterm => {
@@ -279,11 +303,19 @@ impl TerminalState {
}
}
- Ok(PlacementInfo {
- first_row,
- rows: height_in_cells,
- cols: width_in_cells,
- alt_screen: self.screen.is_alt_screen_active(),
+ Ok(ImagePlacement {
+ info: PlacementInfo {
+ first_row,
+ rows: height_in_cells,
+ cols: width_in_cells,
+ alt_screen: self.screen.is_alt_screen_active(),
+ },
+ origin: (x_delta_divisor > 0 && y_delta_divisor > 0).then(|| crate::kitty_relative::CellOrigin {
+ source: TextureCoordinate::new_f32(params.source_origin_x as f32 / params.image_width as f32,
+ params.source_origin_y as f32 / params.image_height as f32),
+ step: TextureCoordinate::new_f32(cell_pixel_width as f32 / x_delta_divisor as f32,
+ cell_pixel_height as f32 / y_delta_divisor as f32),
+ }),
})
}
diff --git a/term/src/terminalstate/iterm.rs b/term/src/terminalstate/iterm.rs
index 5dea29d2..9479108c 100644
--- a/term/src/terminalstate/iterm.rs
+++ b/term/src/terminalstate/iterm.rs
@@ -145,6 +145,7 @@ impl TerminalState {
style: ImageAttachStyle::Iterm,
image_id: None,
placement_id: None,
+ placement_tag: 0,
do_not_move_cursor: image.do_not_move_cursor,
}) {
log::error!("set iterm2 image: {:#}", err);
diff --git a/term/src/terminalstate/kitty.rs b/term/src/terminalstate/kitty.rs
index 77bc6355..8cdd4dc1 100644
--- a/term/src/terminalstate/kitty.rs
+++ b/term/src/terminalstate/kitty.rs
@@ -1,3 +1,7 @@
+use crate::kitty_animation::{monotonic_ms, KittyAnimation, KittyPlaybackSnapshot};
+use crate::kitty_relative::{PlacementKey, RelativePlacements, RelativeView};
+#[path = "kitty_scene.rs"]
+mod scene;
use crate::terminalstate::image::*;
use crate::terminalstate::{ImageAttachParams, PlacementInfo};
use crate::{StableRowIndex, TerminalState};
@@ -5,7 +9,7 @@ use ::image::{
DynamicImage, GenericImage, GenericImageView, ImageBuffer, RgbImage, Rgba, RgbaImage,
};
use anyhow::Context;
-use std::collections::{HashMap, HashSet};
+use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet};
use std::io::Write;
use std::sync::Arc;
use std::time::Duration;
@@ -24,10 +28,10 @@ use wezterm_surface::change::ImageData;
/// so that honest transfers are unaffected.
pub(crate) const MAX_ACCUM_BYTES: usize = 256 * 1024 * 1024;
pub(crate) const MAX_ACCUM_CHUNKS: usize = 65536;
+pub(crate) const MAX_PLACEMENTS: usize = 65536;
-/// An animation grows one frame at a time with no natural end, and `d=f`
-/// (drop the frames again) is not implemented, so without a ceiling a client
-/// can append until the process dies. Sized for real content: a terminal-sized
+/// An animation grows one frame at a time with no natural end. Without a
+/// ceiling, a client that never deletes frames can append until the process dies. Sized for real content: a terminal-sized
/// 640x384 frame is under a megabyte, so this is a few hundred of them.
pub(crate) const MAX_ANIM_BYTES: usize = 256 * 1024 * 1024;
@@ -55,14 +59,23 @@ pub struct KittyImageState {
/// without it the remaining fragments would be parsed without their header.
accumulator_overflowed: bool,
max_image_id: u32,
- number_to_id: HashMap<u32, u32>,
+ /// Numbered ids increase with successful transmissions. Keep older ids
+ /// until eviction so deleting the newest reveals the previous image.
+ numbered_images: BTreeSet<(u32, u32)>,
id_to_data: HashMap<u32, Arc<ImageData>>,
+ animations: HashMap<u32, KittyAnimation>,
+ virtual_placements: crate::kitty_virtual::VirtualPlacements,
+ selection_revision: u64,
/// Transmission order of each stored image, so eviction drops the
/// oldest unplaced image first. A HashMap walk would evict at random,
/// which for a frame stream means keeping stale frames over fresh ones.
id_seq: HashMap<u32, u64>,
next_seq: u64,
- placements: HashMap<(u32, Option<u32>), PlacementInfo>,
+ pub(super) placements: BTreeMap<PlacementKey, ImagePlacement>,
+ relatives: RelativePlacements,
+ relative_views: BTreeMap<u32, Vec<RelativeView>>,
+ relative_seqno: Option<wezterm_surface::SequenceNo>,
+ pub(super) next_placement_id: u64,
used_memory: usize,
/// The idle sweep's memory of `next_seq` and of the transfer in
/// progress, and how many sweeps in a row found both unchanged. Ticks,
@@ -82,6 +95,11 @@ impl TerminalState {
}
impl KittyImageState {
+ fn id_for_number(&self, number: u32) -> Option<u32> {
+ self.numbered_images.range((number, 0)..=(number, u32::MAX))
+ .next_back().map(|(_, id)| *id)
+ }
+
/// The bookkeeping, with each picture replaced by its hash in `images`.
#[cfg(feature = "use_serde")]
pub(crate) fn snapshot(
@@ -90,7 +108,8 @@ impl KittyImageState {
) -> crate::terminalstate::snapshot::KittySnapshot {
crate::terminalstate::snapshot::KittySnapshot {
max_image_id: self.max_image_id,
- number_to_id: self.number_to_id.iter().map(|(k, v)| (*k, *v)).collect(),
+ // The legacy snapshot carries only the newest id for each number.
+ number_to_id: self.numbered_images.iter().copied().collect(),
id_to_hash: self
.id_to_data
.iter()
@@ -98,7 +117,7 @@ impl KittyImageState {
.collect(),
id_seq: self.id_seq.iter().map(|(k, v)| (*k, *v)).collect(),
next_seq: self.next_seq,
- placements: self.placements.iter().map(|(k, v)| (*k, *v)).collect(),
+ placements: self.placements.iter().map(|(k, v)| ((k.image_id, k.protocol_id()), v.info)).collect(),
transmission_in_progress: !self.accumulator.is_empty(),
}
}
@@ -122,12 +141,24 @@ impl KittyImageState {
self.accumulator.clear();
self.accumulated_bytes = 0;
self.accumulator_overflowed = false;
+ if !self.animations.is_empty() {
+ self.animations = HashMap::new();
+ }
+ self.selection_revision += 1;
+ self.virtual_placements = Default::default();
+ self.relatives = Default::default();
+ self.relative_views = Default::default();
+ self.relative_seqno = None;
self.max_image_id = snapshot.max_image_id;
- self.number_to_id = snapshot.number_to_id.into_iter().collect();
+ self.numbered_images = snapshot.number_to_id.into_iter()
+ .filter(|(_, id)| id_to_data.contains_key(id)).collect();
self.id_to_data = id_to_data;
self.id_seq = snapshot.id_seq.into_iter().collect();
self.next_seq = snapshot.next_seq;
- self.placements = snapshot.placements.into_iter().collect();
+ self.placements = snapshot.placements.into_iter().map(|((image_id, placement_id), info)| {
+ (PlacementKey { image_id, placement_id: u64::from(placement_id.unwrap_or(0)) }, ImagePlacement { info, origin: None })
+ }).collect();
+ self.next_placement_id = u64::from(u32::MAX);
self.recompute_used_memory();
Ok(())
}
@@ -154,7 +185,17 @@ impl KittyImageState {
}
fn remove_data_for_id(&mut self, image_id: u32) {
- self.id_to_data.remove(&image_id);
+ if self.virtual_placements.remove(image_id, None) {
+ self.selection_revision += 1;
+ }
+ if self.animations.remove(&image_id).is_some() {
+ if self.animations.is_empty() {
+ self.animations = HashMap::new();
+ }
+ }
+ if self.id_to_data.remove(&image_id).is_some() {
+ self.selection_revision += 1;
+ }
self.id_seq.remove(&image_id);
self.recompute_used_memory();
}
@@ -164,7 +205,22 @@ impl KittyImageState {
/// fails on an id that no longer exists.
fn evict(&mut self, image_id: u32) {
self.remove_data_for_id(image_id);
- self.number_to_id.retain(|_, id| *id != image_id);
+ self.numbered_images.retain(|(_, id)| *id != image_id);
+ }
+
+ fn evict_unplaced(&mut self, ids: &HashSet<u32>) {
+ if ids.is_empty() {
+ return;
+ }
+ let before = self.id_to_data.len();
+ self.id_to_data.retain(|id, _| !ids.contains(id));
+ self.id_seq.retain(|id, _| !ids.contains(id));
+ self.animations.retain(|id, _| !ids.contains(id));
+ self.numbered_images.retain(|(_, id)| !ids.contains(id));
+ if self.id_to_data.len() != before {
+ self.selection_revision += 1;
+ self.recompute_used_memory();
+ }
}
/// The stored image that was transmitted earliest, skipping the most
@@ -202,6 +258,7 @@ impl KittyImageState {
// transmit-now-place-later.
self.remove_data_for_id(image_id);
self.id_to_data.insert(image_id, data);
+ self.selection_revision += 1;
self.recompute_used_memory();
self.next_seq += 1;
self.id_seq.insert(image_id, self.next_seq);
@@ -259,13 +316,15 @@ impl KittyImageState {
if self.used_memory <= budget {
return;
}
- let referenced: HashSet<u32> = self.placements.keys().map(|(k, _)| *k).collect();
+ let referenced: HashSet<u32> = self.placements.keys().map(|key| key.image_id)
+ .chain(self.relatives.iter().map(|p| p.key.image_id)).collect();
let newest = self.next_seq;
let before = self.used_memory;
let mut candidates: Vec<(u64, u32)> = self
.id_to_data
.keys()
- .filter(|id| !referenced.contains(id) && self.id_seq.get(id).copied() != Some(newest))
+ .filter(|id| !referenced.contains(id) && !self.virtual_placements.contains_image(**id)
+ && self.id_seq.get(id).copied() != Some(newest))
.map(|id| (self.id_seq.get(id).copied().unwrap_or(0), *id))
.collect();
candidates.sort_unstable();
@@ -301,6 +360,49 @@ mod prune_tests {
)))
}
+ #[test]
+ fn placement_limit_preserves_existing_cells_and_recovers_after_deletion() {
+ use super::{ImagePlacement, PlacementInfo, PlacementKey, MAX_PLACEMENTS};
+ use crate::{Terminal, TerminalConfiguration, TerminalSize};
+ use wezterm_cell::image::{ImageCell, TextureCoordinate};
+ #[derive(Debug)]
+ struct Config;
+ impl TerminalConfiguration for Config {
+ fn scrollback_size(&self) -> usize { 0 }
+ fn color_palette(&self) -> crate::color::ColorPalette { Default::default() }
+ fn enable_kitty_graphics(&self) -> bool { true }
+ }
+ let mut terminal = Terminal::new(TerminalSize { rows: 2, cols: 2,
+ pixel_width: 16, pixel_height: 32, dpi: 96 }, Arc::new(Config), "ThinkTerm", "test", Box::new(Vec::new()));
+ let data = image(1);
+ terminal.kitty_img.record_id_to_data(1, data.clone(), 1024);
+ let mut cell = wezterm_cell::Cell::blank();
+ for index in 0..MAX_PLACEMENTS {
+ let tag = u64::from(u32::MAX) + 1 + index as u64;
+ terminal.kitty_img.placements.insert(PlacementKey { image_id: 1, placement_id: tag },
+ ImagePlacement { info: PlacementInfo { first_row: 0, rows: 1, cols: 1, alt_screen: false }, origin: None });
+ cell.attrs_mut().attach_image(Box::new(
+ ImageCell::with_z_index(TextureCoordinate::new_f32(0.0, 0.0), TextureCoordinate::new_f32(1.0, 1.0),
+ data.clone(), index as i32, 0, 0, 0, 0, Some(1), None).with_placement_tag(tag)));
+ terminal.kitty_img.next_placement_id = tag;
+ }
+ terminal.screen_mut().set_cell(0, 0, &cell, 0);
+ drop(cell);
+ let counter = terminal.kitty_img.next_placement_id;
+ terminal.advance_bytes("\x1b_Ga=p,i=1,C=1,q=2\x1b\\");
+ assert_eq!(terminal.kitty_img.placements.len(), MAX_PLACEMENTS);
+ assert_eq!(terminal.kitty_img.next_placement_id, counter);
+ assert_eq!(terminal.screen_mut().line_mut(0).get_cell(0).unwrap().attrs().image_attachments().count(), MAX_PLACEMENTS);
+ terminal.advance_bytes("\x1b_Ga=d,d=z,z=1,q=2\x1b\\");
+ assert_eq!(terminal.kitty_img.placements.len(), MAX_PLACEMENTS - 1);
+ terminal.advance_bytes("\x1b_Ga=p,i=1,C=1,q=2\x1b\\");
+ assert_eq!(terminal.kitty_img.next_placement_id, counter + 1);
+ assert_eq!(terminal.kitty_img.placements.len(), MAX_PLACEMENTS);
+ terminal.advance_bytes("\x1b_Ga=d,d=I,i=1,q=2\x1b\\");
+ assert_eq!(terminal.kitty_image_stats(), (0, 0, 0));
+ assert!(!terminal.screen_mut().line_mut(0).has_images());
+ }
+
#[test]
fn idle_ticks_preserve_completed_images_until_budget_pressure() {
let mut state = KittyImageState::default();
@@ -371,6 +473,15 @@ mod prune_tests {
/// transfer: no action key (`a=` defaults to `t`), no identifying or format
/// keys, just `m=` and payload. `q=` is deliberately not consulted — the
/// protocol permits it on continuation fragments.
+fn placement_error(err: &anyhow::Error) -> String {
+ let message = err.to_string();
+ if ["EINVAL:", "ENOENT:", "ENOPARENT:", "ECYCLE:", "ETOODEEP:", "ENOSPC:"].iter().any(|code| message.starts_with(code)) {
+ message
+ } else {
+ format!("ERROR:{message}")
+ }
+}
+
fn is_bare_continuation(img: &KittyImage) -> bool {
match img {
KittyImage::TransmitData { transmit, .. } => {
@@ -424,6 +535,149 @@ impl TerminalState {
)
}
+ /// Only subscribers to frame control read this; desktop pixels and frame
+ /// durations remain unchanged. Static images also publish pixel versions.
+ pub fn kitty_frame_selections(&mut self, known: Option<u64>) -> Option<(u64, Vec<crate::KittyFrameSelection>)> {
+ self.kitty_scene_refresh();
+ if known == Some(self.kitty_img.selection_revision) {
+ return None;
+ }
+ Some((self.kitty_img.selection_revision, self.kitty_img.id_to_data.iter().map(|(id, data)| {
+ crate::KittyFrameSelection {
+ image_id: *id, data_hash: data.hash(), data_generation: data.generation(),
+ animation: self.kitty_img.animations.get(id).cloned().unwrap_or_else(|| KittyAnimation::new([0], 0)),
+ virtual_placements: self.kitty_img.virtual_placements.for_image(*id),
+ relative_placements: self.kitty_img.relative_views.get(id).cloned().unwrap_or_default(),
+ }
+ }).collect()))
+ }
+
+ /// The picture `image_id` holds now, whichever version a caller last saw.
+ pub fn kitty_image(&self, image_id: u32) -> Option<Arc<ImageData>> {
+ self.kitty_img.id_to_data.get(&image_id).cloned()
+ }
+
+ pub fn snapshot_kitty_playback(&self) -> KittyPlaybackSnapshot {
+ KittyPlaybackSnapshot {
+ captured_at_ms: monotonic_ms(),
+ selections: self.kitty_img.animations.iter().filter_map(|(id, animation)| {
+ self.kitty_img.id_to_data.get(id).map(|data| crate::kitty_animation::KittyPlaybackEntry {
+ image_id: *id, data_hash: data.hash(), animation: animation.clone(),
+ })
+ }).collect(),
+ }
+ }
+
+ pub fn snapshot_kitty_graphics(&self) -> crate::KittyGraphicsSnapshot {
+ crate::KittyGraphicsSnapshot {
+ playback: self.snapshot_kitty_playback(),
+ virtual_images: self.snapshot_kitty_virtual(),
+ image_numbers: self.kitty_img.numbered_images.iter().copied().collect(),
+ placements: self.snapshot_kitty_placements(),
+ relatives: self.snapshot_kitty_relatives(),
+ }
+ }
+
+ fn snapshot_kitty_placements(&self) -> Option<KittyPlacementSnapshot> {
+ if self.kitty_img.next_placement_id <= u64::from(u32::MAX) {
+ return None;
+ }
+ let mut live = HashSet::new();
+ let cell_tags = [false, true].map(|alternate| {
+ let mut tags = Vec::new();
+ self.screen_for_alt(alternate).for_each_phys_line(|_, line| {
+ if !line.has_images() { return; }
+ for cell in (0..line.len()).filter_map(|idx| line.get_cell(idx)) {
+ for image in cell.attrs().image_attachments() {
+ let tag = image.placement_tag();
+ tags.push(tag);
+ if let Some(image_id) = image.image_id() {
+ live.insert(PlacementKey { image_id, placement_id: tag });
+ }
+ }
+ }
+ });
+ tags
+ });
+ Some(KittyPlacementSnapshot {
+ next_id: self.kitty_img.next_placement_id,
+ placements: self.kitty_img.placements.iter()
+ .filter(|(key, _)| live.contains(key)).map(|(key, placement)| (*key, placement.info)).collect(),
+ cell_tags,
+ })
+ }
+
+ pub fn restore_kitty_numbers(&mut self, numbers: Vec<(u32, u32)>) -> anyhow::Result<()> {
+ anyhow::ensure!(numbers.len() <= self.kitty_img.id_to_data.len(), "too many numbered images");
+ let mut ids = HashSet::with_capacity(numbers.len());
+ let mut numbered_images = BTreeSet::new();
+ for (number, id) in numbers {
+ anyhow::ensure!(self.kitty_img.id_to_data.contains_key(&id), "number refers to an absent image");
+ anyhow::ensure!(id != 0 && ids.insert(id), "invalid or duplicate numbered image id");
+ let latest = self.kitty_img.id_for_number(number)
+ .ok_or_else(|| anyhow::anyhow!("number missing from the terminal snapshot"))?;
+ anyhow::ensure!(id <= latest, "number history is newer than the terminal snapshot");
+ numbered_images.insert((number, id));
+ }
+ anyhow::ensure!(self.kitty_img.numbered_images.is_subset(&numbered_images), "incomplete number history");
+ self.kitty_img.numbered_images = numbered_images;
+ Ok(())
+ }
+
+ pub fn snapshot_kitty_virtual(&self) -> Vec<crate::kitty_virtual::VirtualImage> {
+ let mut images: Vec<_> = self.kitty_img.id_to_data.iter().filter_map(|(id, data)| {
+ let placements = self.kitty_img.virtual_placements.for_image(*id);
+ (!placements.is_empty()).then(|| crate::kitty_virtual::VirtualImage {
+ image_id: *id, data_hash: data.hash(), placements,
+ })
+ }).collect();
+ images.sort_unstable_by_key(|image| image.image_id);
+ images
+ }
+
+ pub fn restore_kitty_virtual(&mut self, images: Vec<crate::kitty_virtual::VirtualImage>) -> anyhow::Result<()> {
+ use crate::kitty_virtual::{valid, VirtualPlacements, MAX_VIRTUAL_PLACEMENTS};
+ anyhow::ensure!(images.len() <= MAX_VIRTUAL_PLACEMENTS, "too many virtual images");
+ let count = images.iter().try_fold(0usize, |count, image| count.checked_add(image.placements.len()));
+ anyhow::ensure!(count.is_some_and(|count| count <= MAX_VIRTUAL_PLACEMENTS), "too many virtual placements");
+ let mut ids = HashSet::with_capacity(images.len());
+ let mut placements = VirtualPlacements::default();
+ for image in images {
+ let data = self.kitty_img.id_to_data.get(&image.image_id)
+ .ok_or_else(|| anyhow::anyhow!("virtual placement refers to an absent image"))?;
+ anyhow::ensure!(data.hash() == image.data_hash, "virtual placement does not match its image");
+ anyhow::ensure!(!image.placements.is_empty() && valid(&image.placements), "invalid virtual placements");
+ anyhow::ensure!(ids.insert(image.image_id), "duplicate virtual image id");
+ for placement in image.placements {
+ placements.insert(image.image_id, placement);
+ }
+ }
+ self.kitty_img.virtual_placements = placements;
+ self.kitty_img.selection_revision += 1;
+ Ok(())
+ }
+
+ pub fn restore_kitty_playback(&mut self, snapshot: KittyPlaybackSnapshot) -> anyhow::Result<()> {
+ let now = monotonic_ms();
+ let mut animations = HashMap::new();
+ for selection in snapshot.selections {
+ let data = self.kitty_img.id_to_data.get(&selection.image_id)
+ .ok_or_else(|| anyhow::anyhow!("animation refers to an absent image"))?;
+ let count = match &*data.data() {
+ ImageDataType::AnimRgba8 { frames, .. } => frames.len(),
+ _ => 1,
+ };
+ let mut animation = selection.animation;
+ anyhow::ensure!(data.hash() == selection.data_hash && animation.valid()
+ && animation.frame_ends.len() == count, "animation does not match its image");
+ animation.rebase(snapshot.captured_at_ms, now);
+ anyhow::ensure!(animations.insert(selection.image_id, animation).is_none(), "duplicate animation image id");
+ }
+ self.kitty_img.animations = animations;
+ self.kitty_img.selection_revision += 1;
+ Ok(())
+ }
+
pub(crate) fn kitty_enforce_image_budget(&mut self) {
let budget = self.config.kitty_image_memory_budget();
self.kitty_img.prune_unreferenced(budget);
@@ -448,21 +702,12 @@ impl TerminalState {
placement: KittyImagePlacement,
verbosity: KittyImageVerbosity,
) -> anyhow::Result<()> {
+ self.kitty_scene_refresh();
let image_id = match image_id {
Some(id) => id,
- None => *self
- .kitty_img
- .number_to_id
- .get(
- &image_number
- .ok_or_else(|| anyhow::anyhow!("no image_id or image_number specified!"))?,
- )
- .ok_or_else(|| {
- anyhow::anyhow!(
- "image_number has no matching image id {:?} in number_to_id",
- image_number
- )
- })?,
+ None => self.kitty_img.id_for_number(
+ image_number.ok_or_else(|| anyhow::anyhow!("no image_id or image_number specified!"))?,
+ ).ok_or_else(|| anyhow::anyhow!("no image for image_number {:?}", image_number))?,
};
log::trace!(
@@ -473,38 +718,52 @@ impl TerminalState {
verbosity
);
- // Replace any previous placement under this key before the virtual
- // check below: converting a real placement to a virtual one must
- // erase the pixels the real one painted, or they stay on screen with
- // nothing left that can remove them.
- if image_id != 0 {
- self.kitty_remove_placement(image_id, placement.placement_id);
- }
+ let placement_id = placement.placement_id.filter(|id| image_id != 0 && *id != 0);
+ let img = Arc::clone(self.kitty_img.id_to_data.get(&image_id).ok_or_else(|| {
+ anyhow::anyhow!("ENOENT: no matching image id {image_id}")
+ })?);
+ anyhow::ensure!(!placement.virtual_placement || placement.parent_image_id.unwrap_or(0) == 0,
+ "EINVAL: a virtual placement cannot have a parent");
+ if placement.parent_image_id.unwrap_or(0) != 0 {
+ let tag = match placement_id {
+ Some(id) => u64::from(id),
+ None => self.kitty_img.next_placement_id.max(u64::from(u32::MAX)).checked_add(1)
+ .ok_or_else(|| anyhow::anyhow!("ENOSPC: placement ids exhausted"))?,
+ };
+ self.kitty_place_relative(PlacementKey { image_id, placement_id: tag }, &placement, img.data().dimensions()?)?;
+ if placement_id.is_none() { self.kitty_img.next_placement_id = tag; }
+ self.kitty_img.mark_newest(image_id);
+ return Ok(());
+ }
if placement.virtual_placement {
- // A virtual placement is a promise that the image is ready; the
- // application decides where it goes by printing U+10EEEE
- // placeholder cells. Rendering those is not implemented, so draw
- // nothing rather than painting a real placement at the cursor —
- // that would put a stray image on screen, move the cursor, and
- // leave the placeholder cells rendering as tofu on top of it.
- log::trace!("ignoring virtual placement for image_id {}", image_id);
+ // Publish the grid to Web/mobile without changing the legacy
+ // cursor, cells, response or image eviction order.
+ if self.kitty_img.id_to_data.contains_key(&image_id)
+ && self.kitty_img.virtual_placements.insert(image_id, crate::kitty_virtual::VirtualPlacement {
+ placement_id: placement_id.unwrap_or(0),
+ columns: placement.columns.unwrap_or(0),
+ rows: placement.rows.unwrap_or(0),
+ })
+ {
+ if let Some(placement_id) = placement_id {
+ self.kitty_replace_placement(image_id, placement_id);
+ }
+ self.kitty_img.selection_revision += 1;
+ }
return Ok(());
}
- let img = Arc::clone(self.kitty_img.id_to_data.get(&image_id).ok_or_else(|| {
- anyhow::anyhow!(
- "no matching image id {} in id_to_data for image_number {:?}",
- image_id,
- image_number
- )
- })?);
-
let (image_width, image_height) = img.data().dimensions()?;
-
- // Kitty evicts by last use, not by transmit order: a picture sent
- // once and re-placed on every redraw must outlive frames streamed
- // after it, or the client's next `a=p` fails on a missing id.
- self.kitty_img.mark_newest(image_id);
+ let tag = match placement_id {
+ Some(id) => u64::from(id),
+ None => self.kitty_img.next_placement_id.max(u64::from(u32::MAX))
+ .checked_add(1).ok_or_else(|| anyhow::anyhow!("ENOSPC: placement ids exhausted"))?,
+ };
+ let key = PlacementKey { image_id, placement_id: tag };
+ if self.kitty_img.placements.len() >= MAX_PLACEMENTS && !self.kitty_img.placements.contains_key(&key) {
+ self.kitty_prune_placements();
+ anyhow::ensure!(self.kitty_img.placements.len() < MAX_PLACEMENTS, "ENOSPC: too many image placements");
+ }
// A placement spanning more cells than the grid has is clamped to
// the grid: cells are assigned one column at a time below, and a
// count near u32::MAX would allocate them until the process died,
@@ -526,13 +785,20 @@ impl TerminalState {
columns: placement.columns.map(|x| (x as usize).min(grid_cols)),
rows: placement.rows.map(|x| (x as usize).min(grid_rows)),
image_id: Some(image_id),
- placement_id: placement.placement_id,
+ placement_id,
+ placement_tag: if placement_id.is_none() { tag } else { 0 },
do_not_move_cursor: placement.do_not_move_cursor,
})?;
- self.kitty_img
- .placements
- .insert((image_id, placement.placement_id), info);
+ if let Some(placement_id) = placement_id {
+ if self.kitty_img.virtual_placements.remove(image_id, Some(placement_id)) {
+ self.kitty_img.selection_revision += 1;
+ }
+ }
+ self.kitty_img.mark_newest(image_id);
+ if placement_id.is_none() { self.kitty_img.next_placement_id = tag; }
+ self.kitty_img.placements.insert(key, info);
+ self.kitty_img.relative_seqno = None;
log::trace!(
"record placement for {} (image_number {:?}) {:?}",
image_id,
@@ -707,14 +973,16 @@ impl TerminalState {
// an image that may never appear.
let (image_id, image_number) =
self.kitty_img_transmit_quietly(transmit, verbosity)?;
+ let placement_id = placement.placement_id.filter(|p| *p != 0 && image_id != 0);
match self.kitty_img_place(Some(image_id), image_number, placement, verbosity) {
Ok(()) => {
if image_id != 0 || image_number.is_some() {
- self.kitty_send_response(
+ self.kitty_send_placement_response(
verbosity,
true,
Some(image_id),
image_number,
+ placement_id,
"OK".to_string(),
);
}
@@ -722,12 +990,13 @@ impl TerminalState {
}
Err(err) => {
if image_id != 0 || image_number.is_some() {
- self.kitty_send_response(
+ self.kitty_send_placement_response(
verbosity,
false,
Some(image_id),
image_number,
- format!("ERROR:{:#}", err),
+ placement_id,
+ placement_error(&err),
);
}
Err(err)
@@ -772,6 +1041,7 @@ impl TerminalState {
KittyImage::TransmitData { .. }
| KittyImage::TransmitDataAndDisplay { .. }
| KittyImage::TransmitFrame { .. }
+ | KittyImage::ControlAnimation { .. }
)
{
self.kitty_interrupt_transfer();
@@ -779,6 +1049,27 @@ impl TerminalState {
let verbosity = img.verbosity();
match img {
+ // The legacy cell-backed renderer does not consume animation
+ // controls. Keep its pixels, gaps and transfer state unchanged.
+ KittyImage::ControlAnimation { control, .. } => {
+ if let Some(id) = control.image_id.or_else(|| control.image_number.and_then(|no| self.kitty_img.id_for_number(no))) {
+ if let Some(data) = self.kitty_img.id_to_data.get(&id) {
+ let now = monotonic_ms();
+ if let Some(animation) = self.kitty_img.animations.get_mut(&id) {
+ if animation.control(&control, now) { self.kitty_img.selection_revision += 1; }
+ } else {
+ let mut animation = match &*data.data() {
+ ImageDataType::AnimRgba8 { durations, .. } => KittyAnimation::new(durations.iter().map(|gap| gap.as_millis().min(u32::MAX as u128) as u32), now),
+ _ => KittyAnimation::new([0], now),
+ };
+ if animation.control(&control, now) {
+ self.kitty_img.animations.insert(id, animation);
+ self.kitty_img.selection_revision += 1;
+ }
+ }
+ }
+ }
+ }
// `verbosity` above is `img.verbosity()`, which now reports the
// query's own `q=` rather than assuming q=0.
KittyImage::Query { transmit, .. } => match transmit.data.load_data() {
@@ -831,40 +1122,18 @@ impl TerminalState {
placement,
verbosity,
} => {
- self.kitty_img_place(image_id, image_number, placement, verbosity)?;
- }
- KittyImage::Delete {
- what:
- KittyImageDelete::ByImageId {
- image_id,
- placement_id,
- delete,
- },
- verbosity,
- } => {
- log::trace!(
- "remove a placement: image_id {} placement_id {:?} delete {} verb {:?}",
- image_id,
- placement_id,
- delete,
- verbosity
- );
-
- self.kitty_remove_placement(image_id, placement_id);
-
- if delete {
- self.kitty_img.remove_data_for_id(image_id);
- }
- }
- KittyImage::Delete {
- what: KittyImageDelete::All { delete },
- verbosity: _,
- } => {
- self.kitty_remove_all_placements(delete);
- }
- KittyImage::Delete { what, verbosity } => {
- log::warn!("unhandled KittyImage::Delete {:?} {:?}", what, verbosity);
+ let id = image_id.or_else(|| image_number.and_then(|n| self.kitty_img.id_for_number(n)));
+ let placement_id = placement.placement_id.filter(|p| *p != 0 && id != Some(0));
+ let result = if image_id.is_some() && image_number.is_some() {
+ Err(anyhow::anyhow!("EINVAL: i and I are mutually exclusive"))
+ } else {
+ self.kitty_img_place(image_id, image_number, placement, verbosity)
+ };
+ self.kitty_send_placement_response(verbosity, result.is_ok(), id, image_number, placement_id,
+ result.as_ref().map(|_| "OK".to_owned()).unwrap_or_else(placement_error));
+ result?;
}
+ KittyImage::Delete { what, .. } => self.kitty_delete(what),
KittyImage::TransmitFrame {
transmit,
frame,
@@ -901,8 +1170,8 @@ impl TerminalState {
.kitty_img
.placements
.iter()
- .filter(|((id, _), _)| *id == image_id)
- .map(|(_, info)| *info)
+ .filter(|(key, _)| key.image_id == image_id)
+ .map(|(_, placement)| placement.info)
.collect();
let seqno = self.seqno;
@@ -919,64 +1188,330 @@ impl TerminalState {
}
}
- fn kitty_remove_placement_from_model(
- &mut self,
- image_id: u32,
- placement_id: Option<u32>,
- info: PlacementInfo,
- ) {
+ fn kitty_image_for_mutation(image: &Arc<ImageData>) -> Arc<ImageData> {
+ if ImageDataType::is_nonce_key(&image.hash()) {
+ Arc::clone(image)
+ } else {
+ Arc::new(image.copy_for_mutation())
+ }
+ }
+
+ /// Install a successful first edit. Later edits keep the private identity.
+ fn kitty_commit_image_mutation(&mut self, image_id: u32, image: &Arc<ImageData>) -> bool {
+ let old = &self.kitty_img.id_to_data[&image_id];
+ if Arc::ptr_eq(old, image) {
+ return false;
+ }
+ let old = Arc::clone(old);
+ self.kitty_img.id_to_data.insert(image_id, Arc::clone(image));
+ if !self.kitty_img.placements.keys().any(|key| key.image_id == image_id) {
+ return true;
+ }
let seqno = self.seqno;
- // The recorded screen, not the active one: the sweep can run while
- // the other screen is up (a stream in one pane, btop in this one),
- // and StableRowIndex only means anything on the screen it came from.
- let screen = self.screen.screen_for_alt_mut(info.alt_screen);
- for idx in placement_phys_rows(screen, &info) {
- let line = screen.line_mut(idx);
- for c in line.cells_mut() {
- c.attrs_mut()
- .detach_image_with_placement(image_id, placement_id);
- }
- line.update_last_change_seqno(seqno);
+ // Reflow can move attachments outside their recorded placement rows.
+ // Scan only on the transition from content-shared to private pixels.
+ for alternate in [false, true] {
+ self.screen.screen_for_alt_mut(alternate).for_each_phys_line_mut(|_, line| {
+ if !line.has_images() {
+ return;
+ }
+ let references_image = line.visible_cells().any(|cell| {
+ cell.attrs().image_attachments().any(|attached| {
+ attached.image_id() == Some(image_id)
+ && Arc::ptr_eq(attached.image_data(), &old)
+ })
+ });
+ if references_image {
+ for cell in line.cells_mut_for_attr_changes_only() {
+ cell.attrs_mut().replace_image_data(image_id, &old, image);
+ }
+ line.update_last_change_seqno(seqno);
+ }
+ });
+ }
+ true
+ }
+
+ pub(super) fn kitty_prune_placements(&mut self) {
+ let mut live = HashSet::new();
+ for alternate in [false, true] {
+ self.screen_for_alt(alternate).for_each_phys_line(|_, line| {
+ if !line.has_images() { return; }
+ for cell in line.visible_cells() {
+ for image in cell.attrs().image_attachments() {
+ if let Some(image_id) = image.image_id() {
+ live.insert(PlacementKey { image_id, placement_id: image.placement_tag() });
+ }
+ }
+ }
+ });
}
+ self.kitty_img.placements.retain(|key, _| live.contains(key));
}
- fn kitty_remove_placement(&mut self, image_id: u32, placement_id: Option<u32>) {
- if placement_id.is_some() {
- if let Some(info) = self.kitty_img.placements.remove(&(image_id, placement_id)) {
- log::trace!("removed placement {} {:?}", image_id, placement_id);
- self.kitty_remove_placement_from_model(image_id, placement_id, info);
+ pub(super) fn kitty_remove_placement(&mut self, image_id: u32, placement_id: Option<u32>) {
+ let selected = self.kitty_img.placements.keys().copied()
+ .chain(self.kitty_img.relatives.iter().map(|p| p.key))
+ .chain(self.kitty_img.virtual_placements.for_image(image_id).iter().map(|p| PlacementKey {
+ image_id, placement_id: u64::from(p.placement_id),
+ })).filter(|key| {
+ key.image_id == image_id && placement_id.is_none_or(|id| key.protocol_id() == Some(id))
+ }).collect();
+ self.kitty_delete_selected_placements(selected, HashSet::new(), true);
+ }
+
+ fn kitty_delete(&mut self, what: KittyImageDelete) {
+ self.kitty_scene_refresh();
+ use KittyImageDelete::*;
+ let delete = match what {
+ ByImageId { image_id, placement_id, delete } => {
+ self.kitty_delete_image_ids(&[image_id], placement_id, delete);
+ return;
}
- } else {
- let mut to_clear = vec![];
- for (id, p) in self.kitty_img.placements.keys() {
- if *id == image_id {
- to_clear.push(*p);
+ ByImageNumber { image_number, placement_id, delete } => {
+ if let Some(id) = self.kitty_img.id_for_number(image_number) {
+ self.kitty_delete_image_ids(&[id], placement_id, delete);
+ }
+ return;
+ }
+ ByImageIdRange { first, last, delete } => {
+ let ids: Vec<_> = self.kitty_img.id_to_data.keys().copied()
+ .filter(|id| *id != 0 && first <= *id && *id <= last).collect();
+ self.kitty_delete_image_ids(&ids, None, delete);
+ return;
+ }
+ AnimationFrames { image_id, image_number, frame_number, delete } => {
+ self.kitty_delete_frame(image_id, image_number, frame_number, delete);
+ return;
+ }
+ All { delete } | AtCursorPosition { delete } | DeleteAt { delete, .. }
+ | DeleteAtZ { delete, .. } | DeleteColumn { delete, .. }
+ | DeleteRow { delete, .. } | DeleteZ { delete, .. } => delete,
+ };
+ let screen = self.screen();
+ let top = screen.phys_row(0);
+ let mut selected = HashSet::new();
+ screen.for_each_phys_line(|physical, line| {
+ if !line.has_images() {
+ return;
+ }
+ let row = physical as isize - top as isize;
+ for cell in line.visible_cells() {
+ let column = cell.cell_index();
+ let at = |x: u32, y: u32| {
+ x.checked_sub(1).is_some_and(|x| column == x as usize)
+ && y.checked_sub(1).is_some_and(|y| row == y as isize)
+ };
+ for image in cell.attrs().image_attachments() {
+ let Some(id) = image.image_id() else { continue };
+ let matches = match what {
+ All { .. } => row >= 0 && row < screen.physical_rows as isize,
+ AtCursorPosition { .. } => column == self.cursor.x && row == self.cursor.y as isize,
+ DeleteAt { x, y, .. } => at(x, y),
+ DeleteAtZ { x, y, z, .. } => at(x, y) && image.z_index() == z,
+ DeleteColumn { x, .. } => x.checked_sub(1).is_some_and(|x| column == x as usize),
+ DeleteRow { y, .. } => y.checked_sub(1).is_some_and(|y| row == y as isize),
+ DeleteZ { z, .. } => image.z_index() == z,
+ _ => false,
+ };
+ if matches {
+ selected.insert(PlacementKey { image_id: id, placement_id: image.placement_tag() });
+ }
}
}
- for p in to_clear.into_iter() {
- if let Some(info) = self.kitty_img.placements.remove(&(image_id, p)) {
- self.kitty_remove_placement_from_model(image_id, p, info);
+ });
+ let cell = ((self.pixel_width / screen.physical_cols) as u32, (self.pixel_height / screen.physical_rows) as u32);
+ if cell.0 > 0 && cell.1 > 0 {
+ for (&id, views) in &self.kitty_img.relative_views {
+ let Some(data) = self.kitty_img.id_to_data.get(&id) else { continue };
+ let Ok(size) = data.data().dimensions() else { continue };
+ for view in views {
+ if view.anchor.alt_screen != self.screen.is_alt_screen_active() { continue; }
+ let Some(layout) = view.geometry.layout(size, cell) else { continue };
+ let x0 = view.anchor.column as f64 + layout.rect[0] / f64::from(cell.0);
+ let y0 = view.anchor.row as f64 - screen.visible_row_to_stable_row(0) as f64 + layout.rect[1] / f64::from(cell.1);
+ let x1 = view.anchor.column as f64 + layout.rect[2] / f64::from(cell.0);
+ let y1 = view.anchor.row as f64 - screen.visible_row_to_stable_row(0) as f64 + layout.rect[3] / f64::from(cell.1);
+ let column = |x: f64| x < x1 && x + 1.0 > x0;
+ let row = |y: f64| y < y1 && y + 1.0 > y0;
+ let matches = match what {
+ All { .. } => x1 > 0.0 && y1 > 0.0 && x0 < screen.physical_cols as f64 && y0 < screen.physical_rows as f64,
+ AtCursorPosition { .. } => column(self.cursor.x as f64) && row(self.cursor.y as f64),
+ DeleteAt { x, y, .. } => x > 0 && y > 0 && column(f64::from(x - 1)) && row(f64::from(y - 1)),
+ DeleteAtZ { x, y, z, .. } => x > 0 && y > 0 && column(f64::from(x - 1)) && row(f64::from(y - 1)) && view.geometry.z_index == z,
+ DeleteColumn { x, .. } => x > 0 && column(f64::from(x - 1)),
+ DeleteRow { y, .. } => y > 0 && row(f64::from(y - 1)),
+ DeleteZ { z, .. } => view.geometry.z_index == z,
+ _ => false,
+ };
+ if matches { selected.insert(PlacementKey { image_id: id, placement_id: view.placement_id }); }
}
}
}
+ let release = selected.iter().filter_map(|key| (delete || key.image_id == 0).then_some(key.image_id)).collect();
+ self.kitty_delete_selected_placements(selected, release, true);
+ }
- log::trace!(
- "after remove: there are {} placements, {} images, {} memory",
- self.kitty_img.placements.len(),
- self.kitty_img.id_to_data.len(),
- self.kitty_img.used_memory,
- );
+ fn kitty_delete_image_ids(&mut self, ids: &[u32], placement: Option<u32>, delete: bool) {
+ let ids: HashSet<_> = ids.iter().copied().filter(|id| *id != 0).collect();
+ let placement = placement.filter(|id| *id != 0);
+ let mut selected: HashSet<_> = self.kitty_img.placements.keys().copied()
+ .chain(self.kitty_img.relatives.iter().map(|p| p.key))
+ .filter(|key| ids.contains(&key.image_id) && placement.is_none_or(|id| key.protocol_id() == Some(id)))
+ .collect();
+ let mut release: HashSet<_> = if delete {
+ selected.iter().map(|key| key.image_id).collect()
+ } else {
+ HashSet::new()
+ };
+ for id in ids {
+ selected.extend(self.kitty_img.virtual_placements.for_image(id).into_iter()
+ .filter(|p| placement.is_none_or(|wanted| p.placement_id == wanted))
+ .map(|p| PlacementKey { image_id: id, placement_id: u64::from(p.placement_id) }));
+ let removed = self.kitty_img.virtual_placements.remove(id, placement);
+ if removed {
+ self.kitty_img.selection_revision += 1;
+ }
+ if delete && (removed || placement.is_none()) {
+ release.insert(id);
+ }
+ }
+ self.kitty_delete_selected_placements(selected, release, true);
}
- pub(crate) fn kitty_remove_all_placements(&mut self, delete: bool) {
- for ((image_id, p), info) in std::mem::take(&mut self.kitty_img.placements).into_iter() {
- self.kitty_remove_placement_from_model(image_id, p, info);
+ fn kitty_delete_selected_placements(
+ &mut self,
+ selected: HashSet<PlacementKey>,
+ mut release: HashSet<u32>,
+ cascade: bool,
+ ) {
+ if selected.is_empty() && release.is_empty() {
+ return;
+ }
+ // Placement coordinates can be stale after reflow. Select by actual
+ // cells, then detach every piece of each selected placement in one pass.
+ let scan = !selected.is_empty()
+ || self.kitty_img.placements.keys().any(|key| release.contains(&key.image_id));
+ if scan {
+ let seqno = self.seqno;
+ let mut remaining = HashSet::new();
+ let matches = |image: &wezterm_cell::image::ImageCell| {
+ image.image_id().is_some_and(|id| selected.contains(&PlacementKey { image_id: id, placement_id: image.placement_tag() }))
+ };
+ for alternate in [false, true] {
+ self.screen.screen_for_alt_mut(alternate).for_each_phys_line_mut(|_, line| {
+ if !line.has_images() {
+ return;
+ }
+ if line.visible_cells().any(|cell| cell.attrs().image_attachments().any(matches)) {
+ for cell in line.cells_mut_for_attr_changes_only() {
+ cell.attrs_mut().detach_images(matches);
+ }
+ line.update_last_change_seqno(seqno);
+ }
+ for cell in line.visible_cells() {
+ for image in cell.attrs().image_attachments() {
+ if let Some(id) = image.image_id() {
+ remaining.insert(PlacementKey { image_id: id, placement_id: image.placement_tag() });
+ }
+ }
+ }
+ });
+ }
+ self.kitty_img.placements.retain(|key, _| remaining.contains(key));
+ }
+ if cascade { self.kitty_remove_relative_dependents(selected.iter().copied()); }
+ self.kitty_img.relative_seqno = None;
+ // Uppercase deletion releases data only after the last ordinary or
+ // virtual placement disappears. Unplaced images use the ID path above.
+ if release.is_empty() {
+ return;
+ }
+ let retained: HashSet<_> = self.kitty_img.placements.keys().map(|key| key.image_id).collect();
+ release.retain(|id| !retained.contains(id) && !self.kitty_img.virtual_placements.contains_image(*id)
+ && !self.kitty_img.relatives.iter().any(|p| p.key.image_id == *id));
+ self.kitty_img.evict_unplaced(&release);
+ }
+
+ fn kitty_delete_frame(
+ &mut self,
+ image_id: Option<u32>,
+ image_number: Option<u32>,
+ frame_number: Option<u32>,
+ delete: bool,
+ ) {
+ let Some(id) = image_id.filter(|id| *id != 0).or_else(|| {
+ image_number.and_then(|number| self.kitty_img.id_for_number(number))
+ }) else { return };
+ let Some(old) = self.kitty_img.id_to_data.get(&id).cloned() else { return };
+ let data = old.data();
+ let count = match &*data {
+ ImageDataType::AnimRgba8 { frames, .. } => frames.len(),
+ _ => 1,
+ };
+ if count <= 1 {
+ drop(data);
+ if delete {
+ self.kitty_delete_image_ids(&[id], None, true);
+ }
+ return;
}
+ let index = (frame_number.unwrap_or(1).max(1) as usize).min(count) - 1;
+ let ImageDataType::AnimRgba8 { width, height, frames, hashes, durations } = &*data else { return };
+ let now = monotonic_ms();
+ let mut animation = self.kitty_img.animations.get(&id).cloned().unwrap_or_else(|| {
+ KittyAnimation::new(durations.iter().map(|gap| gap.as_millis().min(u32::MAX as u128) as u32), now)
+ });
+ if !animation.remove_frame(index, now) {
+ return;
+ }
+ // Shrinking under an existing identity leaves remote frame cursors and
+ // append-only image caches pointing at obsolete indices. Publish a new
+ // immutable payload and rebind placements; copy only surviving frames.
+ let payload = if count == 2 {
+ let kept = 1 - index;
+ ImageDataType::Rgba8 { width: *width, height: *height, data: frames[kept].clone(), hash: hashes[kept] }
+ } else {
+ ImageDataType::AnimRgba8 {
+ width: *width, height: *height,
+ frames: frames.iter().enumerate().filter(|(i, _)| *i != index).map(|(_, frame)| frame.clone()).collect(),
+ hashes: hashes.iter().enumerate().filter(|(i, _)| *i != index).map(|(_, hash)| *hash).collect(),
+ durations: durations.iter().enumerate().filter(|(i, _)| *i != index).map(|(_, gap)| *gap).collect(),
+ }
+ };
+ // A payload keyed by a surviving frame's nonce can come back under
+ // the animation's own identity, and a remote copy never takes the
+ // shorter list under the same hash.
+ let hash = Some(payload.compute_hash()).filter(|hash| *hash != old.hash());
+ let image = Arc::new(ImageData::with_data_and_hash(payload, hash.unwrap_or_else(ImageDataType::nonce_key)));
+ image.set_generation(old.generation() + 1);
+ drop(data);
+ self.kitty_commit_image_mutation(id, &image);
+ self.kitty_img.animations.insert(id, animation);
+ self.kitty_img.selection_revision += 1;
+ self.kitty_img.recompute_used_memory();
+ self.kitty_img.mark_newest(id);
+ self.kitty_enforce_image_budget();
+ }
+
+ pub(crate) fn kitty_remove_all_placements(&mut self, delete: bool) {
+ let selected = self.kitty_img.placements.keys().copied().collect();
+ self.kitty_delete_selected_placements(selected, HashSet::new(), true);
if delete {
+ self.kitty_img.relatives = Default::default();
+ self.kitty_img.relative_views = Default::default();
+ self.kitty_img.relative_seqno = None;
+ self.kitty_img.virtual_placements = Default::default();
+ if !self.kitty_img.animations.is_empty() {
+ self.kitty_img.animations = HashMap::new();
+ }
+ if !self.kitty_img.id_to_data.is_empty() {
+ self.kitty_img.selection_revision += 1;
+ }
self.kitty_img.id_to_data.clear();
self.kitty_img.id_seq.clear();
self.kitty_img.used_memory = 0;
- self.kitty_img.number_to_id.clear();
+ self.kitty_img.numbered_images.clear();
}
}
@@ -987,6 +1522,18 @@ impl TerminalState {
image_id: Option<u32>,
image_no: Option<u32>,
message: String,
+ ) {
+ self.kitty_send_placement_response(verbosity, success, image_id, image_no, None, message);
+ }
+
+ fn kitty_send_placement_response(
+ &mut self,
+ verbosity: KittyImageVerbosity,
+ success: bool,
+ image_id: Option<u32>,
+ image_no: Option<u32>,
+ placement_id: Option<u32>,
+ message: String,
) {
match verbosity {
KittyImageVerbosity::Verbose => {}
@@ -1012,24 +1559,13 @@ impl TerminalState {
.collect();
match (image_id, image_no) {
- (Some(id), Some(no)) => {
- write!(self.writer, "\x1b_GI={},i={};{}\x1b\\", no, id, message).ok();
- }
- (Some(id), None) => {
- write!(self.writer, "\x1b_Gi={};{}\x1b\\", id, message).ok();
- }
- (None, Some(no)) => {
- write!(self.writer, "\x1b_GI={};{}\x1b\\", no, message).ok();
- }
- (None, None) => {
- // The protocol says not to answer a request that identified no
- // image. There is also nothing well-formed to say: the reply
- // syntax is `<keys> ; <message>`, and with no keys this used to
- // emit `ESC _ G OK ESC \` — a reply that this crate's own
- // parser rejects, because every comma-separated token before
- // the `;` has to contain an `=`.
- }
+ (Some(id), Some(no)) => { write!(self.writer, "\x1b_GI={},i={}", no, id).ok(); }
+ (Some(id), None) => { write!(self.writer, "\x1b_Gi={}", id).ok(); }
+ (None, Some(no)) => { write!(self.writer, "\x1b_GI={}", no).ok(); }
+ (None, None) => return,
}
+ if let Some(id) = placement_id { write!(self.writer, ",p={}", id).ok(); }
+ write!(self.writer, ";{}\x1b\\", message).ok();
self.writer.flush().ok();
}
@@ -1039,8 +1575,8 @@ impl TerminalState {
verbosity: KittyImageVerbosity,
) -> anyhow::Result<()> {
let image_id = match frame.image_number {
- Some(no) => match self.kitty_img.number_to_id.get(&no) {
- Some(id) => *id,
+ Some(no) => match self.kitty_img.id_for_number(no) {
+ Some(id) => id,
None => {
self.kitty_send_response(
verbosity,
@@ -1085,7 +1621,7 @@ impl TerminalState {
anyhow::anyhow!("missing target frame")
})? as usize;
- let image = Arc::clone(
+ let image = Self::kitty_image_for_mutation(
self.kitty_img
.id_to_data
.get(&image_id)
@@ -1185,6 +1721,12 @@ impl TerminalState {
// generation together sees them agree.
image.bump_generation();
drop(img);
+ if self.kitty_commit_image_mutation(image_id, &image) {
+ self.kitty_img.recompute_used_memory();
+ self.kitty_img.mark_newest(image_id);
+ self.kitty_enforce_image_budget();
+ }
+ self.kitty_img.selection_revision += 1;
self.kitty_touch_placements_for_image(image_id);
Ok(())
@@ -1196,18 +1738,19 @@ impl TerminalState {
frame: KittyImageFrame,
verbosity: KittyImageVerbosity,
) -> anyhow::Result<()> {
- if let Some(no) = transmit.image_number.take() {
- match self.kitty_img.number_to_id.get(&no) {
- Some(id) => {
- transmit.image_id.replace(*id);
- }
- None => {
- transmit.image_number.replace(no);
- }
+ let image_number = transmit.image_number;
+ if transmit.image_id.is_none() {
+ if let Some(no) = image_number {
+ let Some(id) = self.kitty_img.id_for_number(no) else {
+ self.kitty_send_response(verbosity, false, None, Some(no), "ENOENT".to_string());
+ anyhow::bail!("no such image_number {}", no);
+ };
+ transmit.image_number = None;
+ transmit.image_id = Some(id);
}
}
- let (image_id, image_number, img) = self.kitty_img_transmit_inner(transmit, verbosity)?;
+ let (image_id, _, img) = self.kitty_img_transmit_inner(transmit, verbosity)?;
let img = match img.decode() {
ImageDataType::Rgba8 {
@@ -1229,7 +1772,7 @@ impl TerminalState {
]);
let image = match self.kitty_img.id_to_data.get(&image_id) {
- Some(anim) => Arc::clone(anim),
+ Some(anim) => Self::kitty_image_for_mutation(anim),
None => {
self.kitty_send_response(
verbosity,
@@ -1247,6 +1790,17 @@ impl TerminalState {
};
let mut anim = image.data();
+ let count = match &*anim { ImageDataType::AnimRgba8 { frames, .. } => frames.len(), _ => 1 };
+ let target = frame.frame_number.unwrap_or(count as u32 + 1) as usize;
+ let explicit_gap = if frame.gapless { Some(0) } else { frame.duration_ms.filter(|gap| *gap > 0) };
+ let new_timeline = if !self.kitty_img.animations.contains_key(&image_id)
+ && (target == count + 1 || explicit_gap.is_some())
+ {
+ Some(match &*anim {
+ ImageDataType::AnimRgba8 { durations, .. } => KittyAnimation::new(durations.iter().map(|gap| gap.as_millis().min(u32::MAX as u128) as u32), monotonic_ms()),
+ _ => KittyAnimation::new([0], monotonic_ms()),
+ })
+ } else { None };
let x = frame.x.unwrap_or(0);
let y = frame.y.unwrap_or(0);
let frame_gap = Duration::from_millis(match frame.duration_ms {
@@ -1434,6 +1988,21 @@ impl TerminalState {
image.bump_generation();
drop(anim);
+ self.kitty_commit_image_mutation(image_id, &image);
+ if let Some(animation) = new_timeline {
+ self.kitty_img.animations.insert(image_id, animation);
+ }
+ if let Some(animation) = self.kitty_img.animations.get_mut(&image_id) {
+ let now = monotonic_ms();
+ if target == count + 1 {
+ animation.append(explicit_gap.unwrap_or(40), now);
+ } else if let Some(gap) = explicit_gap {
+ animation.set_gap(target - 1, gap, now);
+ }
+ }
+ // Subscribers also track pixel generations: an edit with no
+ // timing change still needs a new metadata snapshot.
+ self.kitty_img.selection_revision += 1;
// Frames are appended behind the Mutex, so the total measured when
// the image was transmitted is stale the moment an animation grows.
@@ -1471,15 +2040,8 @@ impl TerminalState {
}
(Some(id), None) => (id, None),
(None, Some(no)) => {
- // Claim the id here rather than leaving it to the caller. Only
- // `kitty_img_transmit` used to advance the counter, so an
- // `a=f` naming an unknown image number handed out an id that
- // the next allocation would hand out again.
- //
- // Checked, because the counter follows the largest client
- // chosen i=: after i=4294967295 a plain `+ 1` panics the
- // parser thread in debug builds, and in release it wraps
- // onto 0 — the anonymous-transmission slot.
+ // Publish this allocation only after decoding and storing the
+ // image succeeds; failures must retain the previous mapping.
let id = match self.kitty_img.max_image_id.checked_add(1) {
Some(id) => id,
None => {
@@ -1493,8 +2055,6 @@ impl TerminalState {
anyhow::bail!("image id space exhausted");
}
};
- self.kitty_img.max_image_id = id;
- self.kitty_img.number_to_id.insert(no, id);
(id, Some(no))
}
};
@@ -1505,11 +2065,6 @@ impl TerminalState {
// A client that counts one answer per transmission (q=0, or
// a stream pacing itself on ACKs) would otherwise wait on a
// reply that never comes; kitty answers a failed read too.
- // The number allocated above must not outlive the image it
- // never got.
- if let Some(no) = no {
- self.kitty_img.number_to_id.remove(&no);
- }
self.kitty_send_response(verbosity, false, Some(id), no, format!("EBADF:{err}"));
return Err(anyhow::Error::new(err)
.context("data should have been materialized in coalesce_kitty_accumulation"));
@@ -1596,13 +2151,16 @@ impl TerminalState {
verbosity: KittyImageVerbosity,
) -> anyhow::Result<(u32, Option<u32>)> {
let (image_id, image_number, img) = self.kitty_img_transmit_inner(transmit, verbosity)?;
- self.kitty_img.max_image_id = self.kitty_img.max_image_id.max(image_id);
-
let img = self
.raw_image_to_image_data(img)
.context("storing image data")?;
+ if image_id != 0 { self.kitty_delete_image_ids(&[image_id], None, false); }
self.kitty_img
.record_id_to_data(image_id, img, self.config.kitty_image_memory_budget());
+ self.kitty_img.max_image_id = self.kitty_img.max_image_id.max(image_id);
+ if let Some(number) = image_number {
+ self.kitty_img.numbered_images.insert((number, image_id));
+ }
self.kitty_enforce_image_budget();
Ok((image_id, image_number))
diff --git a/term/src/terminalstate/kitty_scene.rs b/term/src/terminalstate/kitty_scene.rs
new file mode 100644
index 00000000..66c91b76
--- /dev/null
+++ b/term/src/terminalstate/kitty_scene.rs
@@ -0,0 +1,212 @@
+//! Relative relationships and their current positions in the terminal model.
+
+use super::*;
+use crate::kitty_relative::{Anchor, PlacementGeometry, RelativePlacement, RelativeSnapshot};
+
+impl TerminalState {
+ fn kitty_root_exists(&self, key: PlacementKey) -> bool {
+ self.kitty_img.placements.contains_key(&key)
+ || (key.placement_id <= u64::from(u32::MAX)
+ && self.kitty_img.virtual_placements.contains(key.image_id, key.placement_id as u32))
+ }
+
+ fn kitty_parent_key(&self, image_id: u32, placement_id: u32) -> Option<PlacementKey> {
+ if placement_id != 0 {
+ let key = PlacementKey { image_id, placement_id: u64::from(placement_id) };
+ return (self.kitty_root_exists(key) || self.kitty_img.relatives.get(key).is_some()).then_some(key);
+ }
+ self.kitty_img.placements.keys().copied()
+ .chain(self.kitty_img.relatives.iter().map(|p| p.key))
+ .filter(|key| key.image_id == image_id)
+ .chain(self.kitty_img.virtual_placements.first(image_id).map(|p| PlacementKey {
+ image_id, placement_id: u64::from(p.placement_id),
+ }))
+ .min()
+ }
+
+ pub(super) fn kitty_place_relative(
+ &mut self,
+ key: PlacementKey,
+ placement: &KittyImagePlacement,
+ image_size: (u32, u32),
+ ) -> anyhow::Result<()> {
+ anyhow::ensure!(!placement.virtual_placement, "EINVAL: a virtual placement cannot have a parent");
+ self.kitty_scene_refresh();
+ let parent = self.kitty_parent_key(placement.parent_image_id.unwrap_or(0), placement.parent_placement_id.unwrap_or(0))
+ .ok_or_else(|| anyhow::anyhow!("ENOPARENT: no matching parent placement"))?;
+ let geometry = PlacementGeometry::from(placement);
+ let cell = (self.pixel_width / self.screen().physical_cols, self.pixel_height / self.screen().physical_rows);
+ anyhow::ensure!(geometry.layout(image_size, (cell.0 as u32, cell.1 as u32)).is_some(), "EINVAL: invalid placement geometry");
+ let relative = RelativePlacement { key, parent, geometry,
+ horizontal: placement.horizontal_offset.unwrap_or(0), vertical: placement.vertical_offset.unwrap_or(0) };
+ let ordinary = &self.kitty_img.placements;
+ let virtuals = &self.kitty_img.virtual_placements;
+ self.kitty_img.relatives.insert(relative, |key| ordinary.contains_key(&key)
+ || (key.placement_id <= u64::from(u32::MAX) && virtuals.contains(key.image_id, key.placement_id as u32)))
+ .map_err(|err| anyhow::anyhow!("{}: invalid placement ancestry", err.code()))?;
+ // A valid conversion keeps descendants referring to this identity.
+ self.kitty_delete_selected_placements([key].into(), HashSet::new(), false);
+ if let Some(id) = key.protocol_id() {
+ self.kitty_img.virtual_placements.remove(key.image_id, Some(id));
+ }
+ self.kitty_img.relative_seqno = None;
+ self.kitty_img.selection_revision += 1;
+ Ok(())
+ }
+
+ pub(in crate::terminalstate) fn kitty_replace_placement(&mut self, image_id: u32, placement_id: u32) {
+ let key = PlacementKey { image_id, placement_id: u64::from(placement_id) };
+ self.kitty_delete_selected_placements([key].into(), HashSet::new(), false);
+ if self.kitty_img.relatives.make_root(key) {
+ self.kitty_img.selection_revision += 1;
+ }
+ self.kitty_img.relative_seqno = None;
+ }
+
+ fn kitty_relative_roots(&self) -> BTreeMap<PlacementKey, Anchor> {
+ let wanted: BTreeSet<_> = self.kitty_img.relatives.iter().map(|p| p.parent)
+ .filter(|key| self.kitty_img.relatives.get(*key).is_none()).collect();
+ let virtuals: BTreeSet<_> = wanted.iter().copied().filter(|key| {
+ key.placement_id <= u64::from(u32::MAX)
+ && self.kitty_img.virtual_placements.contains(key.image_id, key.placement_id as u32)
+ }).collect();
+ let mut roots = BTreeMap::new();
+ let mut first_source = BTreeMap::new();
+ for alternate in [false, true] {
+ let screen = self.screen_for_alt(alternate);
+ screen.for_each_phys_line(|physical, line| {
+ let row = screen.phys_to_stable_row_index(physical) as i64;
+ if line.has_images() {
+ for cell in line.visible_cells() {
+ for image in cell.attrs().image_attachments() {
+ let Some(image_id) = image.image_id() else { continue };
+ let key = PlacementKey { image_id, placement_id: image.placement_tag() };
+ if !wanted.contains(&key) { continue; }
+ let uv = image.top_left();
+ let source = (uv.y, uv.x);
+ if first_source.get(&key).is_some_and(|old| *old <= source) { continue; }
+ let anchor = self.kitty_img.placements.get(&key).and_then(|p| p.origin)
+ .and_then(|origin| origin.anchor(cell.cell_index(), row, alternate, image))
+ .unwrap_or(Anchor { column: cell.cell_index() as i64, row, alt_screen: alternate });
+ roots.insert(key, anchor);
+ first_source.insert(key, source);
+ }
+ }
+ }
+ if !virtuals.is_empty() {
+ crate::kitty_placeholder::visit(line, |column, placeholder| {
+ let key = if placeholder.placement_id == 0 {
+ self.kitty_img.virtual_placements.first(placeholder.image_id)
+ .map(|p| PlacementKey { image_id: placeholder.image_id, placement_id: u64::from(p.placement_id) })
+ } else {
+ Some(PlacementKey { image_id: placeholder.image_id, placement_id: u64::from(placeholder.placement_id) })
+ };
+ let Some(key) = key.filter(|key| virtuals.contains(key)) else { return };
+ let anchor = Anchor { column: column as i64 - i64::from(placeholder.column),
+ row: row - i64::from(placeholder.row), alt_screen: alternate };
+ // The active screen's actual placeholder images supply
+ // a virtual root; the other screen retains its text.
+ if alternate != self.screen.is_alt_screen_active() { return; }
+ roots.entry(key).and_modify(|old| {
+ old.column = old.column.min(anchor.column);
+ old.row = old.row.min(anchor.row);
+ }).or_insert(anchor);
+ });
+ }
+ });
+ }
+ roots
+ }
+
+ pub(crate) fn kitty_scene_refresh(&mut self) {
+ if self.kitty_img.relatives.is_empty() {
+ if !self.kitty_img.relative_views.is_empty() {
+ self.kitty_img.relative_views = BTreeMap::new();
+ self.kitty_img.selection_revision += 1;
+ }
+ return;
+ }
+ if self.kitty_img.relative_seqno == Some(self.seqno) { return; }
+ let roots = self.kitty_relative_roots();
+ let missing: BTreeSet<_> = self.kitty_img.relatives.iter().map(|p| p.parent)
+ .filter(|key| self.kitty_img.relatives.get(*key).is_none() && !roots.contains_key(key)
+ && !(key.placement_id <= u64::from(u32::MAX)
+ && self.kitty_img.virtual_placements.contains(key.image_id, key.placement_id as u32))).collect();
+ if !missing.is_empty() {
+ self.kitty_img.placements.retain(|key, _| !missing.contains(key));
+ self.kitty_remove_relative_dependents(missing.iter().copied());
+ }
+ let mut views: BTreeMap<u32, Vec<RelativeView>> = BTreeMap::new();
+ let mut image = None;
+ let mut image_size = (0, 0);
+ for relative in self.kitty_img.relatives.iter() {
+ if image != Some(relative.key.image_id) {
+ image = Some(relative.key.image_id);
+ image_size = self.kitty_img.id_to_data.get(&relative.key.image_id)
+ .and_then(|data| data.data().dimensions().ok()).unwrap_or((0, 0));
+ }
+ if let Some(anchor) = self.kitty_img.relatives.resolve(relative.key, |key| roots.get(&key).copied()) {
+ let previous = self.kitty_img.relative_views.get(&relative.key.image_id).and_then(|views|
+ views.binary_search_by_key(&relative.key.placement_id, |view| view.placement_id).ok().map(|i| views[i]));
+ let source_seqno = previous.filter(|view| view.anchor == anchor
+ && view.geometry == relative.geometry && view.image_size == image_size)
+ .map_or(self.seqno as u64, |view| view.source_seqno);
+ views.entry(relative.key.image_id).or_default().push(RelativeView {
+ placement_id: relative.key.placement_id, source_seqno, anchor, geometry: relative.geometry, image_size,
+ });
+ }
+ }
+ if self.kitty_img.relative_views != views {
+ self.kitty_img.relative_views = views;
+ self.kitty_img.selection_revision += 1;
+ }
+ self.kitty_img.relative_seqno = Some(self.seqno);
+ }
+
+ pub(super) fn kitty_remove_relative_dependents(&mut self, roots: impl IntoIterator<Item = PlacementKey>) {
+ let removed = self.kitty_img.relatives.remove(roots);
+ if removed.is_empty() { return; }
+ let mut release: HashSet<_> = removed.iter().map(|p| p.key.image_id).collect();
+ release.retain(|id| !self.kitty_img.placements.keys().any(|p| p.image_id == *id)
+ && !self.kitty_img.virtual_placements.contains_image(*id)
+ && !self.kitty_img.relatives.iter().any(|p| p.key.image_id == *id));
+ self.kitty_img.evict_unplaced(&release);
+ self.kitty_img.relative_seqno = None;
+ self.kitty_img.selection_revision += 1;
+ }
+
+ pub(super) fn snapshot_kitty_relatives(&self) -> Option<RelativeSnapshot> {
+ let origins: Vec<_> = self.kitty_img.placements.iter().filter_map(|(key, p)| p.origin.map(|o| (*key, o))).collect();
+ if origins.is_empty() && self.kitty_img.relatives.is_empty() { return None; }
+ Some(RelativeSnapshot { origins, placements: self.kitty_img.relatives.iter().copied().collect() })
+ }
+
+ pub fn restore_kitty_relatives(&mut self, state: RelativeSnapshot) -> anyhow::Result<()> {
+ anyhow::ensure!(state.origins.len() <= MAX_PLACEMENTS, "too many placement origins");
+ let mut origins = BTreeMap::new();
+ for (key, origin) in state.origins {
+ anyhow::ensure!(self.kitty_img.id_to_data.contains_key(&key.image_id)
+ && key.placement_id <= self.kitty_img.next_placement_id.max(u64::from(u32::MAX))
+ && origin.valid() && origins.insert(key, origin).is_none(), "invalid or duplicate placement origin");
+ }
+ for p in &state.placements {
+ anyhow::ensure!(self.kitty_img.id_to_data.contains_key(&p.key.image_id), "relative image is absent");
+ anyhow::ensure!(!self.kitty_root_exists(p.key) && p.key.placement_id != 0
+ && p.key.placement_id <= self.kitty_img.next_placement_id.max(u64::from(u32::MAX)),
+ "invalid relative placement identity");
+ }
+ // An ordinary root can have been trimmed by the new history limit.
+ // Validate its carried identity before pruning its whole subtree.
+ let graph = RelativePlacements::restore(state.placements, |key| self.kitty_root_exists(key) || origins.contains_key(&key))
+ .map_err(|err| anyhow::anyhow!("{}: invalid relative snapshot", err.code()))?;
+ self.kitty_img.relatives = graph;
+ let missing: Vec<_> = origins.keys().copied().filter(|key| !self.kitty_img.placements.contains_key(key)).collect();
+ for (key, origin) in origins {
+ if let Some(p) = self.kitty_img.placements.get_mut(&key) { p.origin = Some(origin); }
+ }
+ self.kitty_remove_relative_dependents(missing);
+ self.kitty_img.relative_seqno = None;
+ self.kitty_scene_refresh();
+ Ok(())
+ }
+}
diff --git a/term/src/terminalstate/mod.rs b/term/src/terminalstate/mod.rs
index b3e0900c..31547603 100644
--- a/term/src/terminalstate/mod.rs
+++ b/term/src/terminalstate/mod.rs
@@ -38,6 +38,7 @@ mod sixel;
#[cfg(feature = "use_serde")]
mod snapshot;
use crate::terminalstate::image::*;
+pub use crate::terminalstate::image::KittyPlacementSnapshot;
use crate::terminalstate::kitty::*;
#[cfg(feature = "use_serde")]
pub use crate::terminalstate::snapshot::*;
diff --git a/term/src/terminalstate/sixel.rs b/term/src/terminalstate/sixel.rs
index f3bbc3ec..e7c3dd3d 100644
--- a/term/src/terminalstate/sixel.rs
+++ b/term/src/terminalstate/sixel.rs
@@ -149,6 +149,7 @@ impl TerminalState {
z_index: 0,
image_id: None,
placement_id: None,
+ placement_tag: 0,
do_not_move_cursor: self.sixel_display_mode,
}) {
log::error!("set sixel image: {:#}", err);
diff --git a/term/src/terminalstate/snapshot.rs b/term/src/terminalstate/snapshot.rs
index 0e398183..5045b3f7 100644
--- a/term/src/terminalstate/snapshot.rs
+++ b/term/src/terminalstate/snapshot.rs
@@ -20,7 +20,7 @@ use super::{
};
use crate::color::ColorPalette;
use crate::screen::Screen;
-use crate::terminalstate::image::PlacementInfo;
+use crate::terminalstate::image::{KittyPlacementSnapshot, PlacementInfo};
use crate::{CursorPosition, Progress, TerminalSize};
use serde::{Deserialize, Serialize};
use std::collections::{BTreeMap, HashMap};
@@ -401,6 +401,17 @@ impl TerminalState {
/// oldest end, with the stable row offset advanced to match, so stable
/// row indices keep their meaning.
pub fn restore(&mut self, snapshot: TerminalSnapshot) -> anyhow::Result<()> {
+ self.restore_with_kitty_placements(snapshot, None)
+ }
+
+ pub fn restore_with_kitty_placements(
+ &mut self,
+ snapshot: TerminalSnapshot,
+ placements: Option<KittyPlacementSnapshot>,
+ ) -> anyhow::Result<()> {
+ if let Some(placements) = &placements {
+ validate_kitty_placements(&snapshot, placements)?;
+ }
anyhow::ensure!(
snapshot.version == SNAPSHOT_VERSION,
"terminal snapshot version {} cannot be restored by a terminal that speaks version {}",
@@ -428,8 +439,10 @@ impl TerminalState {
})
.collect();
- restore_screen(&mut self.screen.screen, snapshot.screen, &images)?;
- restore_screen(&mut self.screen.alt_screen, snapshot.alt_screen, &images)?;
+ restore_screen(&mut self.screen.screen, snapshot.screen, &images,
+ placements.as_ref().map(|p| p.cell_tags[0].as_slice()))?;
+ restore_screen(&mut self.screen.alt_screen, snapshot.alt_screen, &images,
+ placements.as_ref().map(|p| p.cell_tags[1].as_slice()))?;
self.screen.alt_screen_is_active = snapshot.alt_screen_is_active;
self.pixel_width = snapshot.size.pixel_width;
@@ -509,6 +522,12 @@ impl TerminalState {
.collect();
self.kitty_img.restore(snapshot.kitty, &images)?;
+ if let Some(placements) = placements {
+ self.kitty_img.next_placement_id = placements.next_id;
+ self.kitty_img.placements = placements.placements.into_iter().map(|(key, info)|
+ (key, super::image::ImagePlacement { info, origin: None })).collect();
+ self.kitty_prune_placements();
+ }
self.seqno = snapshot.seqno;
self.lost_focus_seqno = snapshot.seqno;
@@ -520,6 +539,34 @@ impl TerminalState {
}
}
+fn validate_kitty_placements(snapshot: &TerminalSnapshot, state: &KittyPlacementSnapshot) -> anyhow::Result<()> {
+ use crate::kitty_relative::PlacementKey;
+ anyhow::ensure!(state.placements.len() <= super::kitty::MAX_PLACEMENTS, "too many Kitty placements");
+ anyhow::ensure!(state.next_id >= u64::from(u32::MAX), "invalid Kitty placement counter");
+ let mut placements = BTreeMap::new();
+ for &(key, info) in &state.placements {
+ anyhow::ensure!(key.placement_id <= state.next_id && snapshot.kitty.id_to_hash.contains_key(&key.image_id),
+ "invalid Kitty placement identity");
+ anyhow::ensure!(placements.insert(key, info).is_none(), "duplicate Kitty placement identity");
+ }
+ for (index, screen) in [&snapshot.screen, &snapshot.alt_screen].iter().enumerate() {
+ let tags = &state.cell_tags[index];
+ anyhow::ensure!(tags.len() == screen.image_cells.len(), "Kitty placement cell count mismatch");
+ for (&tag, cell) in tags.iter().zip(&screen.image_cells) {
+ let Some(image_id) = cell.image_id else {
+ anyhow::ensure!(tag == 0, "non-Kitty image has a placement identity");
+ continue;
+ };
+ let key = PlacementKey { image_id, placement_id: tag };
+ anyhow::ensure!(key.protocol_id() == cell.placement_id.filter(|id| *id != 0),
+ "Kitty placement identity does not match its protocol id");
+ let info = placements.get(&key).ok_or_else(|| anyhow::anyhow!("unknown Kitty placement identity"))?;
+ anyhow::ensure!(info.alt_screen == (index == 1), "Kitty placement is on the wrong screen");
+ }
+ }
+ Ok(())
+}
+
/// Clones the screen's lines with their pictures detached into `images`.
fn snapshot_screen(screen: &Screen, images: &mut ImageTable) -> ScreenSnapshot {
let mut lines = Vec::with_capacity(screen.lines().len());
@@ -583,6 +630,7 @@ fn restore_screen(
screen: &mut Screen,
snapshot: ScreenSnapshot,
images: &HashMap<[u8; 32], Arc<ImageData>>,
+ tags: Option<&[u64]>,
) -> anyhow::Result<()> {
anyhow::ensure!(
snapshot.physical_rows == screen.physical_rows
@@ -601,7 +649,7 @@ fn restore_screen(
);
let mut lines = snapshot.lines;
- for image_cell in snapshot.image_cells {
+ for (index, image_cell) in snapshot.image_cells.into_iter().enumerate() {
let data = images.get(&image_cell.hash).ok_or_else(|| {
anyhow::anyhow!(
"line {} cell {} refers to a picture the snapshot does not carry",
@@ -634,7 +682,10 @@ fn restore_screen(
image_cell.padding_bottom,
image_cell.image_id,
image_cell.placement_id,
- )));
+ ).with_placement_tag(tags.map_or(0, |tags| {
+ // Named placements derive their identity from their external id.
+ if tags[index] > u64::from(u32::MAX) { tags[index] } else { 0 }
+ }))));
}
// The oldest scrollback goes first when this process allows less of
diff --git a/term/src/test/graphics.rs b/term/src/test/graphics.rs
index c6bbf2eb..137887b6 100644
--- a/term/src/test/graphics.rs
+++ b/term/src/test/graphics.rs
@@ -95,17 +95,17 @@ impl Write for Tap {
impl Tap {
/// `TerminalState` hands replies to a `BufWriter<ThreadedWriter>`, so they
/// arrive on a worker thread rather than during `advance_bytes`. Wait for
- /// `needle` to show up instead of guessing at a delay: replies are written
- /// in order, so once it appears everything sent before it is here too. On
- /// deadline the buffer is returned as-is so the caller's assertion can
- /// print it.
- fn read_until(&self, needle: &str) -> String {
+ /// the requested occurrence of `needle` instead of guessing at a delay.
+ /// Replies are written in order, so everything before that barrier has
+ /// arrived too. An earlier drain's barrier cannot satisfy a later one.
+ fn read_until(&self, needle: &str, count: usize) -> String {
let deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);
loop {
let buf = String::from_utf8_lossy(&self.0.lock().unwrap()).to_string();
- if buf.contains(needle) || std::time::Instant::now() >= deadline {
+ if buf.matches(needle).count() >= count {
return buf;
}
+ assert!(std::time::Instant::now() < deadline, "terminal reply barrier timed out");
std::thread::sleep(std::time::Duration::from_millis(10));
}
}
@@ -124,11 +124,12 @@ const SENTINEL: &str = "987654321";
/// The sentinel is a Query, which aborts a chunked transfer in progress —
/// only drain once the transfer under test has completed or been abandoned.
fn drain(term: &mut Terminal, tap: &Tap) -> String {
+ let reply = format!("\x1b_Gi={SENTINEL};OK\x1b\\");
+ let count = String::from_utf8_lossy(&tap.0.lock().unwrap()).matches(&reply).count() + 1;
term.advance_bytes(format!(
"\x1b_Ga=q,i={SENTINEL},f=32,s=1,v=1;AAAAAA==\x1b\\"
));
- tap.read_until(&format!("i={SENTINEL}"))
- .replace(&format!("\x1b_Gi={SENTINEL};OK\x1b\\"), "")
+ tap.read_until(&reply, count).replace(&reply, "")
}
fn term_with_tap(pixel_width: usize, pixel_height: usize) -> (Terminal, Tap) {
@@ -210,6 +211,55 @@ fn kitty_placement_still_works_on_a_normal_pane() {
assert!(!images.is_empty());
}
+#[test]
+fn kitty_image_only_rows_survive_resizing_a_blank_bottom_margin() {
+ for alternate in [false, true] {
+ for compressed in [false, true] {
+ for columns in [90, 100] {
+ let mut terminal = term(1000, 550, true);
+ let size = TerminalSize {
+ rows: 25,
+ cols: 100,
+ pixel_width: 1000,
+ pixel_height: 550,
+ dpi: 96,
+ };
+ terminal.resize(size);
+ if alternate {
+ terminal.advance_bytes("\x1b[?1049h");
+ }
+ terminal.advance_bytes(XMIT_2X2);
+ terminal.advance_bytes("\x1b[3;5H\x1b_Ga=p,i=1,p=1,c=8,r=4,C=1,q=2\x1b\\");
+ if compressed {
+ for row in 2..6 {
+ terminal.screen_mut().line_mut(row).compress_for_scrollback();
+ }
+ }
+ let image_cells = |terminal: &Terminal| {
+ terminal
+ .screen()
+ .all_lines()
+ .iter()
+ .flat_map(|line| line.visible_cells())
+ .filter(|cell| cell.attrs().has_images())
+ .count()
+ };
+ assert_eq!(image_cells(&terminal), 32);
+ terminal.resize(TerminalSize {
+ rows: 22,
+ cols: columns,
+ pixel_width: columns * 10,
+ pixel_height: 484,
+ ..size
+ });
+ assert_eq!(image_cells(&terminal), 32, "all four image rows survive");
+ terminal.resize(size);
+ assert_eq!(image_cells(&terminal), 32, "growing preserves the image");
+ }
+ }
+ }
+}
+
#[test]
fn sixel_still_works_on_a_normal_pane() {
let mut term = term(640, 384, false);
@@ -354,6 +404,239 @@ fn a_chunked_transfer_reassembles() {
);
}
+#[test]
+fn animation_controls_leave_legacy_images_and_transfers_unchanged() {
+ let (mut term, tap) = term_with_tap(640, 384);
+ term.advance_bytes(XMIT_2X2);
+ term.advance_bytes("\x1b_Ga=f,i=1,f=32,s=2,v=2,z=70;AAAAAAAAAAAAAAAAAAAAAA==\x1b\\");
+ term.advance_bytes("\x1b_Ga=p,i=1\x1b\\");
+ let before = animation_at_origin(&mut term).unwrap();
+ let image = term.kitty_image_data_for_id(1).unwrap();
+ let generation = image.generation();
+ let cursor = term.cursor_pos();
+ term.advance_bytes(format!("\x1b_Ga=t,i=9,f=32,s=2,v=2,m=1;{HALF_2X2}\x1b\\"));
+ for control in ["c=2", "r=2,z=-1", "s=1", "s=2,v=1", "s=3,v=3"] {
+ term.advance_bytes(format!("\x1b_Ga=a,i=1,{control}\x1b\\"));
+ }
+ term.advance_bytes(format!("\x1b_Gm=0;{HALF_2X2}\x1b\\"));
+ assert_eq!(animation_at_origin(&mut term).unwrap(), before);
+ assert_eq!(image.generation(), generation);
+ assert_eq!(term.cursor_pos(), cursor);
+ assert!(term.kitty_image_data_for_id(9).is_some());
+ let reply = drain(&mut term, &tap);
+ assert!(!reply.contains("EINVAL"), "{reply}");
+ assert!(reply.contains("i=9;OK"), "{reply}");
+}
+
+#[test]
+fn frame_selections_are_validated_and_released_with_the_image() {
+ let mut term = term(640, 384, true);
+ term.advance_bytes(XMIT_2X2);
+ term.advance_bytes("\x1b_Ga=f,i=1,f=32,s=2,v=2;AAAAAAAAAAAAAAAAAAAAAA==\x1b\\");
+ term.advance_bytes("\x1b_Ga=a,i=1,c=2\x1b\\");
+ let (revision, selected) = term.kitty_frame_selections(None).unwrap();
+ assert_eq!(selected.len(), 1);
+ assert_eq!(selected[0].image_id, 1);
+ assert_eq!(selected[0].animation.frame, 1);
+ for command in ["i=1,c=2", "i=1,c=99", "i=9,c=2", "i=1,c=0"] {
+ term.advance_bytes(format!("\x1b_Ga=a,{command}\x1b\\"));
+ assert!(term.kitty_frame_selections(Some(revision)).is_none());
+ }
+ term.advance_bytes("\x1b_Ga=a,i=1,c=1\x1b\\");
+ assert_eq!(term.kitty_frame_selections(Some(revision)).unwrap().1[0].animation.frame, 0);
+ term.advance_bytes("\x1b_Ga=a,i=1,c=2\x1b\\");
+ let before_delete = term.kitty_frame_selections(None).unwrap().0;
+ term.advance_bytes("\x1b_Ga=d,d=I,i=1\x1b\\");
+ assert!(term.kitty_frame_selections(Some(before_delete)).unwrap().1.is_empty());
+ term.advance_bytes(XMIT_2X2);
+ let root = term.kitty_frame_selections(None).unwrap().1;
+ assert_eq!(root.len(), 1);
+ assert_eq!(root[0].animation.frame, 0);
+ assert_eq!(root[0].animation.frame_ends, [0]);
+ assert!(term.snapshot_kitty_playback().selections.is_empty());
+}
+
+#[test]
+fn frame_selection_resolves_image_numbers_and_reset_releases_it() {
+ let mut term = term(640, 384, true);
+ term.advance_bytes("\x1b_Ga=t,I=12,f=32,s=2,v=2;AAAAAAAAAAAAAAAAAAAAAA==\x1b\\");
+ term.advance_bytes("\x1b_Ga=f,I=12,f=32,s=2,v=2;AAAAAAAAAAAAAAAAAAAAAA==\x1b\\");
+ term.advance_bytes("\x1b_Ga=a,I=12,c=2\x1b\\");
+ assert_eq!(term.kitty_frame_selections(None).unwrap().1[0].animation.frame, 1);
+ term.advance_bytes("\x1bc");
+ assert!(term.kitty_frame_selections(None).unwrap().1.is_empty());
+}
+
+#[test]
+fn kitty_number_resolves_previous_image_after_delete_and_failed_transmissions() {
+ let (mut terminal, tap) = term_with_tap(640, 384);
+ for _ in 0..3 {
+ terminal.advance_bytes("\x1b_Ga=t,I=12,f=32,s=2,v=2;AAAAAAAAAAAAAAAAAAAAAA==\x1b\\");
+ }
+ assert_eq!(terminal.snapshot_kitty_graphics().image_numbers, [(12, 1), (12, 2), (12, 3)]);
+ // Replacing and editing an older id must not reorder numbered images.
+ terminal.advance_bytes(XMIT_2X2);
+ terminal.advance_bytes("\x1b_Ga=f,i=2,f=32,s=2,v=2;AAAAAAAAAAAAAAAAAAAAAA==\x1b\\");
+ for failed in [
+ "a=t,I=12,f=32,s=2,v=2;AA==",
+ "a=t,I=12,f=100;AAAAAA==",
+ "a=t,I=12,f=32,s=2,v=2,o=z;AAAAAA==",
+ "a=t,I=12,f=32,s=2,v=2;!",
+ "a=f,I=99,f=32,s=2,v=2;AAAAAAAAAAAAAAAAAAAAAA==",
+ ] {
+ terminal.advance_bytes(format!("\x1b_G{failed}\x1b\\"));
+ assert_eq!(terminal.snapshot_kitty_graphics().image_numbers, [(12, 1), (12, 2), (12, 3)]);
+ assert_eq!(terminal.kitty_image_stats().0, 3);
+ }
+ for id in [3, 2, 1] {
+ terminal.advance_bytes("\x1b[1;1H\x1b_Ga=p,I=12,p=7,c=2,r=2,C=1\x1b\\");
+ assert_eq!(kitty_placement_keys(&terminal, false), [(id, Some(7))].into());
+ if id == 2 {
+ terminal.advance_bytes("\x1b_Ga=a,I=12,c=2\x1b\\");
+ assert_eq!(terminal.kitty_frame_selections(None).unwrap().1.into_iter()
+ .find(|entry| entry.image_id == 2).unwrap().animation.frame, 1);
+ terminal.advance_bytes("\x1b_Ga=d,d=f,I=12,r=2\x1b\\");
+ assert_eq!(terminal.kitty_image_data_for_id(2).unwrap().len(), 16);
+ }
+ terminal.advance_bytes("\x1b_Ga=d,d=N,I=12\x1b\\");
+ assert!(terminal.kitty_image_data_for_id(id).is_none());
+ }
+ assert!(terminal.snapshot_kitty_graphics().image_numbers.is_empty());
+ terminal.advance_bytes("\x1b_Ga=t,I=99,f=32,s=2,v=2;AAAAAAAAAAAAAAAAAAAAAA==\x1b\\");
+ assert_eq!(terminal.snapshot_kitty_graphics().image_numbers, [(99, 4)]);
+ let reply = drain(&mut terminal, &tap);
+ assert!(reply.contains("I=99;ENOENT"));
+ assert!(reply.contains("I=99,i=4;OK"));
+ terminal.advance_bytes("\x1bc");
+ assert!(terminal.snapshot_kitty_graphics().image_numbers.is_empty());
+}
+
+#[test]
+fn kitty_number_history_is_released_with_evicted_images() {
+ let mut terminal = term_with_budget(640, 384, true, 32);
+ for value in 1..20u8 {
+ let pixels = base64_of(&[value; 16]);
+ terminal.advance_bytes(format!("\x1b_Ga=t,I=12,f=32,s=2,v=2;{pixels}\x1b\\"));
+ let history = terminal.snapshot_kitty_graphics().image_numbers;
+ assert!(history.len() <= 2);
+ assert_eq!(history.last(), Some(&(12, u32::from(value))));
+ assert!(history.iter().all(|(_, id)| terminal.kitty_image_data_for_id(*id).is_some()));
+ }
+ terminal.advance_bytes("\x1b_Ga=d,d=N,I=12\x1b\\");
+ assert_eq!(terminal.snapshot_kitty_graphics().image_numbers, [(12, 18)]);
+ terminal.advance_bytes("\x1b_Ga=d,d=R,x=1,y=99\x1b\\");
+ assert!(terminal.snapshot_kitty_graphics().image_numbers.is_empty());
+ assert_eq!(terminal.kitty_used_memory(), 0);
+}
+
+#[test]
+#[cfg(feature = "use_serde")]
+fn kitty_number_history_survives_restore_and_validates_before_replacing() {
+ let mut original = term(640, 384, true);
+ for _ in 0..3 {
+ original.advance_bytes("\x1b_Ga=t,I=12,f=32,s=2,v=2;AAAAAAAAAAAAAAAAAAAAAA==\x1b\\");
+ }
+ let history = original.snapshot_kitty_graphics().image_numbers;
+ let mut restored = term(640, 384, true);
+ restored.restore(original.snapshot()).unwrap();
+ assert_eq!(restored.snapshot_kitty_graphics().image_numbers, [(12, 3)]);
+ for invalid in [vec![], vec![(12, 1)], vec![(12, 3), (12, 3)],
+ vec![(13, 1), (12, 3)], vec![(12, 3), (12, 4)]] {
+ assert!(restored.restore_kitty_numbers(invalid).is_err());
+ assert_eq!(restored.snapshot_kitty_graphics().image_numbers, [(12, 3)]);
+ }
+ restored.restore_kitty_numbers(history.clone()).unwrap();
+ assert_eq!(restored.snapshot_kitty_graphics().image_numbers, history);
+ assert_eq!(restored.snapshot(), original.snapshot());
+ for id in [3, 2, 1] {
+ restored.advance_bytes("\x1b_Ga=d,d=N,I=12\x1b\\");
+ assert!(restored.kitty_image_data_for_id(id).is_none());
+ assert_eq!(restored.kitty_image_stats().0, id as usize - 1);
+ }
+}
+
+#[test]
+fn animation_pixel_edits_publish_versions_without_changing_playback() {
+ let mut term = term(640, 384, true);
+ term.advance_bytes(XMIT_2X2);
+ term.advance_bytes(FRAME_2X2);
+ for command in [
+ "\x1b_Ga=f,i=1,f=32,s=2,v=2,r=1;AAAAAAAAAAAAAAAAAAAAAA==\x1b\\",
+ "\x1b_Ga=c,i=1,r=2,c=1,w=1,h=1\x1b\\",
+ ] {
+ let (revision, before) = term.kitty_frame_selections(None).unwrap();
+ term.advance_bytes(command);
+ let (_, after) = term.kitty_frame_selections(Some(revision)).expect("pixel edit publishes metadata");
+ assert_eq!(after[0].data_hash, before[0].data_hash);
+ assert!(after[0].data_generation > before[0].data_generation);
+ assert_eq!(after[0].animation, before[0].animation);
+ }
+}
+
+#[test]
+fn static_pixel_edits_publish_versions_and_release_them_with_the_image() {
+ let mut term = term(640, 384, true);
+ let initial = term.kitty_frame_selections(None).unwrap().0;
+ term.advance_bytes(XMIT_2X2);
+ let (revision, before) = term.kitty_frame_selections(Some(initial)).unwrap();
+ term.advance_bytes("\x1b_Ga=f,i=1,f=32,s=2,v=2,r=1;AAAAAAAAAAAAAAAAAAAAAA==\x1b\\");
+ let (edited, after) = term.kitty_frame_selections(Some(revision)).unwrap();
+ assert!(after[0].data_generation > before[0].data_generation);
+ assert_eq!(after[0].animation, before[0].animation);
+ assert!(term.snapshot_kitty_playback().selections.is_empty());
+ term.advance_bytes("\x1b_Ga=d,d=I,i=1\x1b\\");
+ assert!(term.kitty_frame_selections(Some(edited)).unwrap().1.is_empty());
+}
+
+#[test]
+fn web_animation_gaps_and_controls_do_not_rewrite_legacy_frame_durations() {
+ use crate::kitty_animation::Playback;
+ use wezterm_cell::image::ImageDataType;
+ let mut term = term(640, 384, true);
+ term.advance_bytes(XMIT_2X2);
+ term.advance_bytes("\x1b_Ga=f,i=1,f=32,s=2,v=2,z=70;AAAAAAAAAAAAAAAAAAAAAA==\x1b\\");
+ term.advance_bytes("\x1b_Ga=f,i=1,f=32,s=2,v=2,z=-1;AAAAAAAAAAAAAAAAAAAAAA==\x1b\\");
+ term.advance_bytes("\x1b_Ga=a,i=1,r=1,z=30,s=2,v=3\x1b\\");
+ let state = term.kitty_frame_selections(None).unwrap().1.remove(0).animation;
+ assert_eq!(state.frame_ends, [30, 100, 100]);
+ assert_eq!(state.mode, Playback::Loading);
+ assert_eq!(state.max_loops, 2);
+ term.advance_bytes("\x1b_Ga=f,i=1,f=32,s=2,v=2,r=2;AAAAAAAAAAAAAAAAAAAAAA==\x1b\\");
+ assert_eq!(term.kitty_frame_selections(None).unwrap().1[0].animation.frame_ends, state.frame_ends);
+ let image = term.kitty_image_data_for_id(1).unwrap();
+ let data = image.data();
+ let ImageDataType::AnimRgba8 { durations, .. } = &*data else { panic!("not animated"); };
+ assert_eq!(durations.iter().map(|gap| gap.as_millis()).collect::<Vec<_>>(), [0, 70, 40]);
+}
+
+#[test]
+#[cfg(feature = "use_serde")]
+fn playback_companion_restores_selection_and_rejects_mismatched_images_atomically() {
+ let mut original = term(640, 384, true);
+ original.advance_bytes(XMIT_2X2);
+ original.advance_bytes("\x1b_Ga=f,i=1,f=32,s=2,v=2,z=70;AAAAAAAAAAAAAAAAAAAAAA==\x1b\\");
+ original.advance_bytes("\x1b_Ga=a,i=1,c=2,r=1,z=30\x1b\\");
+ let playback = original.snapshot_kitty_playback();
+ let mut copy = term(640, 384, true);
+ copy.restore(original.snapshot()).unwrap();
+ copy.restore_kitty_playback(playback.clone()).unwrap();
+ assert_eq!(copy.snapshot(), original.snapshot());
+ let (revision, selections) = copy.kitty_frame_selections(None).unwrap();
+ assert_eq!(selections[0].animation.frame, 1);
+ assert_eq!(selections[0].animation.frame_ends, [30, 100]);
+ for kind in 0..4 {
+ let mut invalid = playback.clone();
+ match kind {
+ 0 => invalid.selections[0].image_id = 999,
+ 1 => invalid.selections[0].data_hash[0] ^= 1,
+ 2 => invalid.selections[0].animation.frame_ends.pop().map(|_| ()).unwrap(),
+ _ => invalid.selections.push(invalid.selections[0].clone()),
+ }
+ assert!(copy.restore_kitty_playback(invalid).is_err());
+ assert!(copy.kitty_frame_selections(Some(revision)).is_none());
+ }
+}
+
#[test]
fn idle_sweep_keeps_a_chunked_transfer_that_is_still_arriving() {
let (mut term, tap) = term_with_tap(640, 384);
@@ -627,6 +910,90 @@ fn a_virtual_placement_draws_nothing_and_leaves_the_cursor_alone() {
);
}
+#[test]
+fn virtual_grids_publish_replace_and_delete_without_attaching_desktop_cells() {
+ use crate::kitty_virtual::VirtualPlacement;
+ let mut term = term(640, 384, true);
+ term.advance_bytes(XMIT_2X2);
+ let (before, _) = term.kitty_frame_selections(None).unwrap();
+ term.advance_bytes("\x1b_Ga=p,i=1,U=1,p=3,c=20,r=10\x1b\\");
+ let (revision, selections) = term.kitty_frame_selections(Some(before)).unwrap();
+ assert_eq!(selections[0].virtual_placements, [VirtualPlacement {
+ placement_id: 3, columns: 20, rows: 10,
+ }]);
+ term.advance_bytes("\x1b_Ga=p,i=1,U=1,p=3,c=20,r=10\x1b\\");
+ assert!(term.kitty_frame_selections(Some(revision)).is_none());
+ term.advance_bytes("\x1b_Ga=p,i=1,U=1,p=3,c=7,r=4\x1b\\");
+ let (revision, selections) = term.kitty_frame_selections(Some(revision)).unwrap();
+ assert_eq!(selections[0].virtual_placements[0].columns, 7);
+ term.advance_bytes("\x1b_Ga=d,d=a\x1b\\");
+ assert!(term.kitty_frame_selections(Some(revision)).is_none());
+ term.advance_bytes("\x1b_Ga=d,d=i,i=1,p=3\x1b\\");
+ let (_, selections) = term.kitty_frame_selections(Some(revision)).unwrap();
+ assert!(selections[0].virtual_placements.is_empty());
+ assert!(term.kitty_image_data_for_id(1).is_some());
+ assert_eq!((term.cursor_pos().x, term.cursor_pos().y), (0, 0));
+ assert!(!term.screen_mut().line_mut(0).has_images());
+}
+
+#[test]
+fn virtual_grids_cannot_survive_replaced_or_deleted_image_data() {
+ let mut term = term(640, 384, true);
+ term.advance_bytes(XMIT_2X2);
+ term.advance_bytes("\x1b_Ga=p,i=1,U=1,c=20,r=10\x1b\\");
+ term.advance_bytes(XMIT_2X2);
+ assert!(term.kitty_frame_selections(None).unwrap().1[0].virtual_placements.is_empty());
+ term.advance_bytes("\x1b_Ga=p,i=1,U=1,c=20,r=10\x1b\\");
+ term.advance_bytes("\x1b_Ga=d,d=I,i=1\x1b\\");
+ assert!(term.kitty_frame_selections(None).unwrap().1.is_empty());
+ term.advance_bytes("\x1b_Ga=p,i=1,U=1,c=20,r=10\x1b\\");
+ assert!(term.kitty_frame_selections(None).unwrap().1.is_empty());
+}
+
+#[test]
+#[cfg(feature = "use_serde")]
+fn virtual_companion_restores_grids_and_rejects_invalid_state_atomically() {
+ use crate::kitty_virtual::{VirtualImage, VirtualPlacement, MAX_VIRTUAL_PLACEMENTS};
+ let mut original = term(640, 384, true);
+ original.advance_bytes(XMIT_2X2);
+ original.advance_bytes("\x1b_Ga=p,i=1,U=1,p=3,c=20,r=10\x1b\\");
+ original.advance_bytes("\x1b_Ga=p,i=1,U=1,p=5,c=7,r=4\x1b\\");
+ original.advance_bytes("\x1b[38;5;1m\u{10eeee}\u{305}\u{305}\x1b[0m");
+ let grids = original.snapshot_kitty_virtual();
+ let snapshot = original.snapshot();
+ let mut copy = term(640, 384, true);
+ copy.restore(original.snapshot()).unwrap();
+ assert!(copy.snapshot_kitty_virtual().is_empty());
+ copy.restore_kitty_virtual(grids.clone()).unwrap();
+ assert_eq!(copy.snapshot(), snapshot);
+ assert_eq!(copy.snapshot_kitty_virtual(), grids);
+ let (revision, _) = copy.kitty_frame_selections(None).unwrap();
+ for kind in 0..7 {
+ let mut invalid = grids.clone();
+ match kind {
+ 0 => invalid[0].image_id = 999,
+ 1 => invalid[0].data_hash[0] ^= 1,
+ 2 => invalid[0].placements.clear(),
+ 3 => { let duplicate = invalid[0].placements[0]; invalid[0].placements.push(duplicate); },
+ 4 => invalid[0].placements.reverse(),
+ 5 => invalid.push(invalid[0].clone()),
+ _ => invalid[0].placements = (0..=MAX_VIRTUAL_PLACEMENTS as u32)
+ .map(|placement_id| VirtualPlacement { placement_id, columns: 1, rows: 1 }).collect(),
+ }
+ assert!(copy.restore_kitty_virtual(invalid).is_err());
+ assert!(copy.kitty_frame_selections(Some(revision)).is_none());
+ assert_eq!(copy.snapshot_kitty_virtual(), grids);
+ assert_eq!(copy.snapshot(), snapshot);
+ }
+ let oversized: Vec<VirtualImage> = std::iter::repeat(grids[0].clone())
+ .take(MAX_VIRTUAL_PLACEMENTS + 1).collect();
+ assert!(copy.restore_kitty_virtual(oversized).is_err());
+ assert!(copy.kitty_frame_selections(Some(revision)).is_none());
+ copy.restore_kitty_virtual(Vec::new()).unwrap();
+ assert!(copy.snapshot_kitty_virtual().is_empty());
+ assert_eq!(copy.snapshot(), snapshot);
+}
+
#[test]
fn an_ordinary_placement_is_unaffected_by_the_virtual_check() {
let mut term = term(640, 384, true);
@@ -945,7 +1312,7 @@ fn transmit_and_display_is_not_acknowledged_until_it_displays() {
fn converting_a_real_placement_to_virtual_erases_it() {
let mut term = term(640, 384, true);
term.advance_bytes(XMIT_2X2);
- term.advance_bytes("\x1b_Ga=p,i=1\x1b\\");
+ term.advance_bytes("\x1b_Ga=p,i=1,p=1\x1b\\");
assert!(
term.screen_mut()
.line_mut(0)
@@ -956,7 +1323,7 @@ fn converting_a_real_placement_to_virtual_erases_it() {
);
let (before_x, before_y) = (term.cursor_pos().x, term.cursor_pos().y);
- term.advance_bytes("\x1b_Ga=p,i=1,U=1,c=20,r=10\x1b\\");
+ term.advance_bytes("\x1b_Ga=p,i=1,p=1,U=1,c=20,r=10\x1b\\");
let (after_x, after_y) = (term.cursor_pos().x, term.cursor_pos().y);
assert!(
@@ -1321,6 +1688,8 @@ fn a_frame_moves_the_image_generation_but_not_its_hash() {
term.advance_bytes("\x1b[H");
term.advance_bytes(XMIT_2X2);
term.advance_bytes("\x1b_Ga=p,i=1\x1b\\");
+ // The first mutation detaches from immutable content deduplication.
+ term.advance_bytes(FRAME_2X2);
let image = term
.screen()
.lines_in_phys_range(0..1)
@@ -1411,3 +1780,673 @@ fn security_kitty_reply_filters_control_bytes_for_all_transmits() {
fn security_kitty_placement_caps_wire_cell_counts() {
kitty(640, 384, "\x1b_Ga=p,i=1,c=4294967295,r=4294967295\x1b\\");
}
+
+
+#[test]
+fn kitty_mutations_do_not_alias_other_ids_or_the_content_cache() {
+ use wezterm_cell::image::ImageDataType;
+ for alternate in [false, true] {
+ let mut terminal = term(640, 384, true);
+ terminal.advance_bytes(XMIT_2X2);
+ terminal.advance_bytes("\x1b_Ga=t,i=2,f=32,s=2,v=2;AAAAAAAAAAAAAAAAAAAAAA==\x1b\\");
+ let original = terminal.kitty_image_data_for_id(1).unwrap();
+ assert!(Arc::ptr_eq(&original, &terminal.kitty_image_data_for_id(2).unwrap()));
+ terminal.advance_bytes("\x1b_Ga=p,i=1,p=1,c=2,r=2,C=1,z=-2\x1b\\");
+ terminal.advance_bytes("\x1b_Ga=p,i=2,p=1,c=2,r=2,C=1,z=3\x1b\\");
+ let cached_row = terminal.screen().lines_in_phys_range(0..1).remove(0);
+ terminal.screen_mut().line_mut(0).compress_for_scrollback();
+ if alternate {
+ terminal.advance_bytes("\x1b[?1049h");
+ }
+ let before = terminal.current_seqno();
+ terminal.advance_bytes("\x1b_Ga=f,i=1,f=32,s=1,v=1,r=1;/////w==\x1b\\");
+ let edited = terminal.kitty_image_data_for_id(1).unwrap();
+ assert_ne!(edited.hash(), original.hash());
+ assert!(ImageDataType::is_nonce_key(&edited.hash()));
+ assert_eq!(edited.generation(), 1);
+ assert_eq!(terminal.kitty_used_memory(), 32, "detached pixels count separately");
+ {
+ let pixels = original.data();
+ let ImageDataType::Rgba8 { data, .. } = &*pixels else { panic!("static image"); };
+ assert!(data.iter().all(|byte| *byte == 0));
+ }
+ assert_eq!(original.generation(), 0);
+ assert!(Arc::ptr_eq(&original, &terminal.kitty_image_data_for_id(2).unwrap()));
+ if alternate {
+ assert!(dirty_phys_rows(terminal.screen(), before).is_empty());
+ terminal.advance_bytes("\x1b[?1049l");
+ }
+ let live_row = terminal.screen().lines_in_phys_range(0..1).remove(0);
+ let live = live_row.get_cell(0).unwrap().attrs().images().unwrap().remove(0);
+ let cached = cached_row.get_cell(0).unwrap().attrs().images().unwrap().remove(0);
+ assert!(Arc::ptr_eq(live.image_data(), &edited));
+ assert!(live_row.get_cell(0).unwrap().attrs().image_attachments()
+ .any(|im| im.image_id() == Some(2) && Arc::ptr_eq(im.image_data(), &original)));
+ assert!(Arc::ptr_eq(cached.image_data(), &original), "retained line clones are immutable");
+ assert_eq!(live.z_index(), cached.z_index());
+ assert_eq!(live.top_left(), cached.top_left());
+ assert_eq!(live.bottom_right(), cached.bottom_right());
+ assert_eq!(live.padding(), cached.padding());
+ assert_eq!(live.placement_id(), cached.placement_id());
+ assert!(live_row.current_seqno() > before);
+ // Later edits and composition reuse the private image, without copying.
+ terminal.advance_bytes("\x1b_Ga=f,i=1,f=32,s=1,v=1,r=1;AQIDBA==\x1b\\");
+ terminal.advance_bytes("\x1b_Ga=c,i=1,r=1,c=1,x=1,y=1,w=1,h=1,C=1\x1b\\");
+ assert!(Arc::ptr_eq(&edited, &terminal.kitty_image_data_for_id(1).unwrap()));
+ assert_eq!(edited.generation(), 3);
+ terminal.advance_bytes("\x1b_Ga=d,d=I,i=1\x1b\\");
+ terminal.advance_bytes("\x1b_Ga=t,i=3,f=32,s=2,v=2;AAAAAAAAAAAAAAAAAAAAAA==\x1b\\");
+ assert!(Arc::ptr_eq(&original, &terminal.kitty_image_data_for_id(3).unwrap()));
+ assert_eq!(terminal.kitty_used_memory(), 16);
+ }
+}
+
+#[test]
+fn kitty_first_composition_detaches_and_invalid_edits_do_not_change_identity() {
+ let mut terminal = term(640, 384, true);
+ terminal.advance_bytes("\x1b_Ga=t,i=1,f=32,s=2,v=1;/////wAAAAA=\x1b\\");
+ terminal.advance_bytes("\x1b_Ga=t,i=2,f=32,s=2,v=1;/////wAAAAA=\x1b\\");
+ let original = terminal.kitty_image_data_for_id(1).unwrap();
+ terminal.advance_bytes("\x1b_Ga=f,i=1,f=32,s=1,v=1,r=99;AQIDBA==\x1b\\");
+ terminal.advance_bytes("\x1b_Ga=c,i=1,r=99,c=1,w=1,h=1\x1b\\");
+ assert!(Arc::ptr_eq(&original, &terminal.kitty_image_data_for_id(1).unwrap()));
+ assert_eq!(original.generation(), 0);
+ terminal.advance_bytes("\x1b_Ga=c,i=1,r=1,c=1,x=1,w=1,h=1,C=1\x1b\\");
+ let edited = terminal.kitty_image_data_for_id(1).unwrap();
+ assert_ne!(original.hash(), edited.hash());
+ assert_eq!(edited.generation(), 1);
+ assert!(Arc::ptr_eq(&original, &terminal.kitty_image_data_for_id(2).unwrap()));
+ assert_eq!(terminal.kitty_used_memory(), 16);
+}
+
+#[test]
+fn kitty_images_with_equal_bytes_but_different_dimensions_do_not_alias() {
+ let mut terminal = term(640, 384, true);
+ terminal.advance_bytes("\x1b_Ga=t,i=1,f=32,s=2,v=1;AAAAAAAAAAA=\x1b\\");
+ terminal.advance_bytes("\x1b_Ga=t,i=2,f=32,s=1,v=2;AAAAAAAAAAA=\x1b\\");
+ let a = terminal.kitty_image_data_for_id(1).unwrap();
+ let b = terminal.kitty_image_data_for_id(2).unwrap();
+ assert_ne!(a.hash(), b.hash());
+ assert_eq!(a.data().dimensions().unwrap(), (2, 1));
+ assert_eq!(b.data().dimensions().unwrap(), (1, 2));
+}
+
+#[test]
+#[cfg(feature = "use_serde")]
+fn kitty_detached_identity_survives_snapshot_restore() {
+ let mut original = term(640, 384, true);
+ original.advance_bytes(XMIT_2X2);
+ original.advance_bytes("\x1b_Ga=t,i=2,f=32,s=2,v=2;AAAAAAAAAAAAAAAAAAAAAA==\x1b\\");
+ original.advance_bytes("\x1b_Ga=p,i=1,p=1,c=2,r=2,C=1\x1b\\");
+ original.advance_bytes("\x1b_Ga=f,i=1,f=32,s=1,v=1,r=1;/////w==\x1b\\");
+ let mut restored = term(640, 384, true);
+ restored.restore(original.snapshot()).unwrap();
+ let edited = restored.kitty_image_data_for_id(1).unwrap();
+ let other = restored.kitty_image_data_for_id(2).unwrap();
+ assert_ne!(edited.hash(), other.hash());
+ let row = restored.screen().lines_in_phys_range(0..1).remove(0);
+ assert_eq!(row.get_cell(0).unwrap().attrs().image_attachments().count(), 1);
+ assert!(row.get_cell(0).unwrap().attrs().image_attachments().all(|im| Arc::ptr_eq(im.image_data(), &edited)));
+ restored.advance_bytes(FRAME_2X2);
+ assert!(Arc::ptr_eq(&edited, &restored.kitty_image_data_for_id(1).unwrap()));
+ assert_eq!(other.len(), 16);
+ assert_eq!(restored.kitty_used_memory(), 48);
+}
+
+#[test]
+fn kitty_detaching_shared_pixels_enforces_the_image_budget() {
+ for compose in [false, true] {
+ let mut terminal = term_with_budget(640, 384, true, 16);
+ terminal.advance_bytes(XMIT_2X2);
+ terminal.advance_bytes("\x1b_Ga=t,i=2,f=32,s=2,v=2;AAAAAAAAAAAAAAAAAAAAAA==\x1b\\");
+ assert_eq!(terminal.kitty_used_memory(), 16);
+ terminal.advance_bytes(if compose {
+ "\x1b_Ga=c,i=1,r=1,c=1,w=1,h=1\x1b\\"
+ } else {
+ "\x1b_Ga=f,i=1,f=32,s=1,v=1,r=1;/////w==\x1b\\"
+ });
+ assert!(terminal.kitty_image_data_for_id(1).is_some());
+ assert!(terminal.kitty_image_data_for_id(2).is_none());
+ assert_eq!(terminal.kitty_used_memory(), 16);
+ }
+}
+
+fn kitty_placement_keys(term: &Terminal, alternate: bool) -> std::collections::BTreeSet<(u32, Option<u32>)> {
+ let mut keys = std::collections::BTreeSet::new();
+ term.screen_for_alt(alternate).for_each_phys_line(|_, line| {
+ if line.has_images() {
+ for cell in line.visible_cells() {
+ for image in cell.attrs().image_attachments() {
+ if let Some(id) = image.image_id() {
+ keys.insert((id, image.placement_id()));
+ }
+ }
+ }
+ }
+ });
+ keys
+}
+
+fn place_kitty_for_delete(term: &mut Terminal, id: u32, placement: u32, row: usize, col: usize, z: i32) {
+ term.advance_bytes(format!("\x1b[{row};{col}H\x1b_Ga=p,i={id},p={placement},c=2,r=2,C=1,z={z}\x1b\\"));
+}
+
+#[test]
+fn kitty_spatial_deletion_selects_whole_placements_from_actual_cells() {
+ let cases: &[(&str, &[u32])] = &[
+ ("a", &[1, 2, 3]), ("c", &[1, 2]), ("p,x=4,y=2", &[1, 2]),
+ ("q,x=4,y=2,z=-2", &[1]), ("x,x=9", &[3]), ("y,y=6", &[3]),
+ ("z,z=-2", &[1, 3]), ("r,x=1,y=2", &[1, 2]),
+ ("p,x=0,y=2", &[]), ("r,x=3,y=1", &[]),
+ ];
+ for &(selector, removed) in cases {
+ for uppercase in [false, true] {
+ for compressed in [false, true] {
+ let mut term = term(640, 384, true);
+ for id in 1..=3 {
+ term.advance_bytes(XMIT_2X2.replace("i=1", &format!("i={id}")));
+ }
+ place_kitty_for_delete(&mut term, 1, 1, 2, 3, -2);
+ place_kitty_for_delete(&mut term, 2, 1, 2, 4, 3);
+ place_kitty_for_delete(&mut term, 3, 1, 6, 9, -2);
+ term.advance_bytes("\x1b[2;4H");
+ if compressed {
+ term.screen_mut().for_each_phys_line_mut(|_, line| line.compress_for_scrollback());
+ }
+ let cursor = term.cursor_pos();
+ let selector = if uppercase {
+ format!("{}{}", selector[..1].to_uppercase(), &selector[1..])
+ } else { selector.to_string() };
+ term.advance_bytes(format!("\x1b_Ga=d,d={selector}\x1b\\"));
+ let expected = (1..=3).filter(|id| !removed.contains(id)).map(|id| (id, Some(1))).collect();
+ assert_eq!(kitty_placement_keys(&term, false), expected, "{selector}");
+ assert_eq!(term.cursor_pos(), cursor);
+ for id in 1..=3 {
+ assert_eq!(term.kitty_image_data_for_id(id).is_some(), !uppercase || !removed.contains(&id), "{selector} id={id}");
+ }
+ }
+ }
+ }
+}
+
+#[test]
+fn kitty_uppercase_delete_retains_virtual_and_other_placement_references() {
+ for selector in ["A", "C", "P,x=1,y=1", "Q,x=1,y=1,z=0", "X,x=1", "Y,y=1", "Z,z=0", "I,i=1,p=2"] {
+ let mut term = term(640, 384, true);
+ term.advance_bytes(XMIT_2X2);
+ place_kitty_for_delete(&mut term, 1, 2, 1, 1, 0);
+ term.advance_bytes("\x1b_Ga=p,i=1,U=1,p=3,c=2,r=2\x1b\\");
+ term.advance_bytes(format!("\x1b_Ga=d,d={selector}\x1b\\"));
+ assert!(kitty_placement_keys(&term, false).is_empty(), "{selector}");
+ assert!(term.kitty_image_data_for_id(1).is_some(), "{selector}");
+ assert_eq!(term.snapshot_kitty_virtual()[0].placements[0].placement_id, 3);
+ term.advance_bytes("\x1b_Ga=d,d=I,i=1,p=999\x1b\\");
+ assert!(term.kitty_image_data_for_id(1).is_some());
+ term.advance_bytes("\x1b_Ga=d,d=I,i=1,p=0\x1b\\");
+ assert!(term.kitty_image_data_for_id(1).is_none());
+ assert!(term.snapshot_kitty_virtual().is_empty());
+ }
+ let mut term = term(640, 384, true);
+ term.advance_bytes(XMIT_2X2);
+ place_kitty_for_delete(&mut term, 1, 2, 1, 1, 0);
+ place_kitty_for_delete(&mut term, 1, 3, 4, 1, 0);
+ term.advance_bytes("\x1b_Ga=d,d=I,i=1,p=2\x1b\\");
+ assert_eq!(kitty_placement_keys(&term, false), [(1, Some(3))].into());
+ assert!(term.kitty_image_data_for_id(1).is_some());
+}
+
+#[test]
+fn kitty_delete_all_preserves_scrollback_inactive_screen_and_unplaced_data() {
+ let mut term = term(640, 384, true);
+ for id in 1..=3 { term.advance_bytes(XMIT_2X2.replace("i=1", &format!("i={id}"))); }
+ place_kitty_for_delete(&mut term, 1, 1, 1, 1, 0);
+ term.advance_bytes("\x1b[24;1H\n\n\n");
+ place_kitty_for_delete(&mut term, 1, 2, 4, 1, 0);
+ term.advance_bytes("\x1b_Ga=d,d=A\x1b\\");
+ assert_eq!(kitty_placement_keys(&term, false), [(1, Some(1))].into());
+ assert!(term.kitty_image_data_for_id(1).is_some());
+ assert!(term.kitty_image_data_for_id(2).is_some());
+ term.advance_bytes("\x1b[?1049h");
+ place_kitty_for_delete(&mut term, 3, 1, 1, 1, 0);
+ term.advance_bytes("\x1b_Ga=d,d=A\x1b\\");
+ assert!(kitty_placement_keys(&term, true).is_empty());
+ assert_eq!(kitty_placement_keys(&term, false), [(1, Some(1))].into());
+ assert!(term.kitty_image_data_for_id(3).is_none());
+ term.advance_bytes("\x1b_Ga=d,d=R,x=1,y=2\x1b\\");
+ assert!(kitty_placement_keys(&term, false).is_empty());
+ assert_eq!(term.kitty_used_memory(), 0);
+}
+
+#[test]
+fn kitty_delete_by_id_finds_reflowed_cells_and_preserves_shared_rows() {
+ let mut term = term(640, 384, true);
+ term.advance_bytes(XMIT_2X2);
+ place_kitty_for_delete(&mut term, 1, 1, 1, 75, -2);
+ term.advance_bytes("\x1b[1;80HX");
+ let size = TerminalSize { rows: 24, cols: 20, pixel_width: 160, pixel_height: 384, dpi: 96 };
+ term.resize(size);
+ let saved: Vec<_> = (0..6).map(|row| term.screen_mut().line_mut(row).clone()).collect();
+ assert!(saved.iter().skip(2).any(|line| line.has_images()));
+ term.advance_bytes("\x1b_Ga=d,d=I,i=1\x1b\\");
+ assert!(kitty_placement_keys(&term, false).is_empty());
+ assert!(saved.iter().any(|line| line.has_images()));
+ assert!(term.kitty_image_data_for_id(1).is_none());
+}
+
+#[test]
+fn kitty_number_and_range_delete_select_virtual_and_unplaced_images() {
+ let mut term = term(640, 384, true);
+ term.advance_bytes(XMIT_2X2);
+ term.advance_bytes("\x1b_Ga=t,I=7,f=32,s=2,v=2;AAAAAAAAAAAAAAAAAAAAAA==\x1b\\");
+ let id = term.kitty_frame_selections(None).unwrap().1.iter().map(|s| s.image_id).max().unwrap();
+ term.advance_bytes("\x1b_Ga=p,I=7,U=1,p=4,c=2,r=2\x1b\\");
+ term.advance_bytes("\x1b_Ga=d,d=n,I=7,p=4\x1b\\");
+ assert!(term.snapshot_kitty_virtual().is_empty());
+ assert!(term.kitty_image_data_for_id(id).is_some());
+ term.advance_bytes("\x1b_Ga=d,d=N,I=7\x1b\\");
+ assert!(term.kitty_image_data_for_id(id).is_none());
+ assert!(term.kitty_image_data_for_id(1).is_some());
+ term.advance_bytes("\x1b_Ga=p,i=1,U=1,p=4,c=2,r=2\x1b\\");
+ term.advance_bytes("\x1b_Ga=d,d=r,x=1,y=1\x1b\\");
+ assert!(term.snapshot_kitty_virtual().is_empty());
+ assert!(term.kitty_image_data_for_id(1).is_some());
+ term.advance_bytes("\x1b_Ga=d,d=R,x=1,y=1\x1b\\");
+ assert_eq!(term.kitty_used_memory(), 0);
+}
+
+#[test]
+fn kitty_frame_deletion_replaces_identity_and_keeps_remaining_frames_and_timeline() {
+ use wezterm_cell::image::ImageDataType;
+ let mut term = term(640, 384, true);
+ term.advance_bytes("\x1b_Ga=t,i=1,f=32,s=1,v=1;/wAA/w==\x1b\\");
+ term.advance_bytes("\x1b_Ga=f,i=1,f=32,s=1,v=1,z=30;AP8A/w==\x1b\\");
+ term.advance_bytes("\x1b_Ga=f,i=1,f=32,s=1,v=1,z=40;AAD//w==\x1b\\");
+ term.advance_bytes("\x1b_Ga=a,i=1,r=1,z=20,c=3,s=1\x1b\\");
+ place_kitty_for_delete(&mut term, 1, 1, 1, 1, 0);
+ term.advance_bytes("\x1b_Ga=p,i=1,U=1,p=2,c=2,r=2\x1b\\");
+ let old = term.kitty_image_data_for_id(1).unwrap();
+ term.advance_bytes("\x1b_Ga=d,d=f,i=1,r=0\x1b\\");
+ let image = term.kitty_image_data_for_id(1).unwrap();
+ assert_ne!(old.hash(), image.hash());
+ assert_eq!(image.generation(), old.generation() + 1);
+ assert_eq!(term.kitty_used_memory(), 8);
+ assert!(matches!(&*old.data(), ImageDataType::AnimRgba8 { frames, .. } if frames.len() == 3));
+ match &*image.data() {
+ ImageDataType::AnimRgba8 { frames, .. } => assert_eq!(frames, &[vec![0, 255, 0, 255], vec![0, 0, 255, 255]]),
+ _ => panic!("expected remaining animation"),
+ }
+ let selection = &term.kitty_frame_selections(None).unwrap().1[0];
+ assert_eq!(selection.animation.frame_ends, [30, 70]);
+ assert_eq!(selection.animation.frame, 1);
+ assert_eq!(selection.virtual_placements.len(), 1);
+ assert_eq!(kitty_placement_keys(&term, false), [(1, Some(1))].into());
+ term.advance_bytes("\x1b_Ga=d,d=f,i=1,r=999\x1b\\");
+ let image = term.kitty_image_data_for_id(1).unwrap();
+ assert!(matches!(&*image.data(), ImageDataType::Rgba8 { data, .. } if data == &[0, 255, 0, 255]));
+ term.advance_bytes("\x1b_Ga=d,d=f,i=1\x1b\\");
+ assert!(Arc::ptr_eq(&image, &term.kitty_image_data_for_id(1).unwrap()));
+ term.advance_bytes("\x1b_Ga=d,d=F,i=1\x1b\\");
+ assert!(kitty_placement_keys(&term, false).is_empty());
+ assert!(term.snapshot_kitty_virtual().is_empty());
+ assert_eq!(term.kitty_used_memory(), 0);
+}
+
+#[test]
+fn kitty_frame_deletion_on_a_nonce_keyed_picture_still_changes_identity() {
+ use wezterm_cell::image::ImageDataType;
+ // Past the content-hash limit a frame is keyed by a nonce. Dropping the
+ // second frame left the first frame's nonce, which was the animation's
+ // own identity too, and a remote copy never took the shorter list.
+ let mut term = term(640, 384, true);
+ let (width, height) = (1024, 257);
+ let first = base64_of(&vec![1u8; width * height * 4]);
+ let second = base64_of(&vec![2u8; width * height * 4]);
+ term.advance_bytes(format!("\x1b_Ga=t,i=1,f=32,s={width},v={height};{first}\x1b\\"));
+ term.advance_bytes(format!("\x1b_Ga=f,i=1,f=32,s={width},v={height},z=40;{second}\x1b\\"));
+ let old = term.kitty_image_data_for_id(1).unwrap();
+ assert!(matches!(&*old.data(), ImageDataType::AnimRgba8 { frames, .. } if frames.len() == 2));
+ term.advance_bytes("\x1b_Ga=d,d=f,i=1,r=2\x1b\\");
+ let image = term.kitty_image_data_for_id(1).unwrap();
+ assert_ne!(old.hash(), image.hash());
+ assert!(matches!(&*image.data(), ImageDataType::Rgba8 { data, .. } if data.iter().all(|byte| *byte == 1)));
+}
+
+fn kitty_internal_keys(term: &Terminal, alternate: bool) -> std::collections::BTreeSet<(u32, u64)> {
+ let mut keys = std::collections::BTreeSet::new();
+ term.screen_for_alt(alternate).for_each_phys_line(|_, line| {
+ if !line.has_images() { return; }
+ for cell in line.visible_cells() {
+ for image in cell.attrs().image_attachments() {
+ if let Some(id) = image.image_id() { keys.insert((id, image.placement_tag())); }
+ }
+ }
+ });
+ keys
+}
+
+#[test]
+fn anonymous_placements_coexist_and_spatial_deletion_preserves_siblings() {
+ for p in ["", ",p=0"] {
+ for compressed in [false, true] {
+ let mut terminal = term(640, 384, true);
+ terminal.advance_bytes(XMIT_2X2);
+ for row in [2, 7] {
+ terminal.advance_bytes(format!("\x1b[{row};4H\x1b_Ga=p,i=1{p},c=2,r=2,C=1\x1b\\"));
+ }
+ place_kitty_for_delete(&mut terminal, 1, u32::MAX, 12, 4, 0);
+ let before = kitty_internal_keys(&terminal, false);
+ assert_eq!(before.len(), 3);
+ assert_eq!(before.iter().filter(|(_, tag)| *tag > u64::from(u32::MAX)).count(), 2);
+ if compressed { terminal.screen_mut().for_each_phys_line_mut(|_, line| line.compress_for_scrollback()); }
+ let retained = terminal.screen_mut().line_mut(1).clone();
+ terminal.advance_bytes("\x1b_Ga=d,d=P,x=4,y=2\x1b\\");
+ let after = kitty_internal_keys(&terminal, false);
+ assert_eq!(after.len(), 2);
+ assert!(after.is_subset(&before));
+ assert!(retained.has_images());
+ assert!(terminal.kitty_image_data_for_id(1).is_some());
+ terminal.advance_bytes("\x1b_Ga=d,d=I,i=1,p=0\x1b\\");
+ assert!(kitty_internal_keys(&terminal, false).is_empty());
+ assert_eq!(terminal.kitty_image_stats(), (0, 0, 0));
+ }
+ }
+}
+
+#[test]
+fn named_replacement_preserves_anonymous_siblings_and_invalid_replacement_keeps_pixels() {
+ let mut terminal = term(640, 384, true);
+ terminal.advance_bytes(XMIT_2X2);
+ place_kitty_for_delete(&mut terminal, 1, 0, 2, 4, 0);
+ place_kitty_for_delete(&mut terminal, 1, 8, 7, 4, 0);
+ let before = kitty_internal_keys(&terminal, false);
+ let retained = terminal.screen_mut().line_mut(6).clone();
+ terminal.advance_bytes("\x1b[12;4H\x1b_Ga=p,i=1,p=8,x=2,c=2,r=2,C=1\x1b\\");
+ assert_eq!(terminal.screen_mut().line_mut(6), &retained);
+ assert_eq!(kitty_internal_keys(&terminal, false), before);
+ place_kitty_for_delete(&mut terminal, 1, 8, 12, 4, 0);
+ assert!(!terminal.screen_mut().line_mut(6).has_images());
+ assert!(terminal.screen_mut().line_mut(11).has_images());
+ assert!(terminal.screen_mut().line_mut(1).has_images());
+ assert_eq!(kitty_internal_keys(&terminal, false), before);
+ assert!(retained.has_images());
+}
+
+#[test]
+fn anonymous_placements_survive_reflow_and_active_screen_deletion() {
+ let mut terminal = term(640, 384, true);
+ terminal.advance_bytes(XMIT_2X2);
+ place_kitty_for_delete(&mut terminal, 1, 0, 1, 75, 0);
+ terminal.advance_bytes("\x1b[1;80HX");
+ let primary = kitty_internal_keys(&terminal, false);
+ terminal.resize(TerminalSize { rows: 24, cols: 20, pixel_width: 160, pixel_height: 384, dpi: 96 });
+ assert_eq!(kitty_internal_keys(&terminal, false), primary);
+ terminal.advance_bytes("\x1b[?1049h");
+ place_kitty_for_delete(&mut terminal, 1, 0, 1, 1, 0);
+ assert_eq!(kitty_internal_keys(&terminal, true).len(), 1);
+ assert_ne!(kitty_internal_keys(&terminal, true), primary);
+ terminal.advance_bytes("\x1b_Ga=d,d=A\x1b\\");
+ assert_eq!(kitty_internal_keys(&terminal, false), primary);
+ assert!(kitty_internal_keys(&terminal, true).is_empty());
+ assert!(terminal.kitty_image_data_for_id(1).is_some());
+ terminal.advance_bytes("\x1b_Ga=d,d=I,i=1\x1b\\");
+ assert!(kitty_internal_keys(&terminal, false).is_empty());
+ assert_eq!(terminal.kitty_image_stats(), (0, 0, 0));
+}
+
+#[test]
+#[cfg(feature = "use_serde")]
+fn anonymous_handoff_restores_tags_before_trimming_and_validates_before_mutation() {
+ use serde::{Deserialize, Serialize};
+ let mut original = term(640, 384, true);
+ original.advance_bytes(XMIT_2X2);
+ place_kitty_for_delete(&mut original, 1, 0, 1, 1, 0);
+ original.advance_bytes("\x1b[24;1H\n\n\n");
+ // Equal z values and overlapping anonymous placements exercise attachment ordering.
+ for _ in 0..2 { place_kitty_for_delete(&mut original, 1, 0, 3, 1, 0); }
+ original.advance_bytes("\x1b[?1049h");
+ place_kitty_for_delete(&mut original, 1, 0, 2, 1, 0);
+ let state = original.snapshot_kitty_graphics().placements.unwrap();
+ let mut bytes = Vec::new();
+ original.snapshot().serialize(&mut varbincode::Serializer::new(&mut bytes)).unwrap();
+ let snapshot = || crate::TerminalSnapshot::deserialize(&mut varbincode::Deserializer::new(&mut &bytes[..])).unwrap();
+ let mut restored = term(640, 384, true);
+ restored.restore_with_kitty_placements(snapshot(), Some(state.clone())).unwrap();
+ for alternate in [false, true] {
+ assert_eq!(kitty_internal_keys(&restored, alternate), kitty_internal_keys(&original, alternate));
+ }
+ // A second handoff must carry the tags in the restored attachment order.
+ let again = restored.snapshot_kitty_graphics().placements.unwrap();
+ let mut second = term(640, 384, true);
+ second.restore_with_kitty_placements(restored.snapshot(), Some(again)).unwrap();
+ assert_eq!(kitty_internal_keys(&second, false), kitty_internal_keys(&original, false));
+ place_kitty_for_delete(&mut second, 1, 0, 7, 1, 0);
+ let new_tag = *kitty_internal_keys(&second, true).iter().next_back().unwrap();
+ assert!(new_tag.1 > state.next_id);
+ second.advance_bytes("\x1b_Ga=d,d=P,x=1,y=2\x1b\\");
+ assert_eq!(kitty_internal_keys(&second, true), [new_tag].into());
+ for kind in 0..6 {
+ let mut invalid = state.clone();
+ match kind {
+ 0 => invalid.cell_tags[0].pop().map(|_| ()).unwrap(),
+ 1 => invalid.cell_tags[0][0] = u64::MAX,
+ 2 => invalid.placements.push(invalid.placements[0]),
+ 3 => invalid.placements[0].1.alt_screen = true,
+ 4 => invalid.next_id = 0,
+ _ => invalid.placements[0].0.image_id = 99,
+ }
+ let before = second.snapshot();
+ assert!(second.restore_with_kitty_placements(snapshot(), Some(invalid)).is_err());
+ assert_eq!(second.snapshot(), before);
+ }
+ #[derive(Debug)]
+ struct NoHistory;
+ impl TerminalConfiguration for NoHistory {
+ fn scrollback_size(&self) -> usize { 0 }
+ fn color_palette(&self) -> ColorPalette { ColorPalette::default() }
+ fn enable_kitty_graphics(&self) -> bool { true }
+ }
+ let mut trimmed = Terminal::new(original.get_size(), Arc::new(NoHistory), "ThinkTerm", "test", Box::new(Vec::new()));
+ trimmed.restore_with_kitty_placements(snapshot(), Some(state.clone())).unwrap();
+ assert_eq!(kitty_internal_keys(&trimmed, false).len(), 2);
+ assert_eq!(trimmed.snapshot_kitty_graphics().placements.unwrap().placements.len(), 3);
+ assert_eq!(kitty_internal_keys(&trimmed, true), kitty_internal_keys(&original, true));
+ trimmed.advance_bytes("\x1b[?1049l\x1b_Ga=d,d=P,x=1,y=3\x1b\\");
+ assert!(kitty_internal_keys(&trimmed, false).is_empty());
+ assert_eq!(kitty_internal_keys(&trimmed, true).len(), 1);
+}
+
+#[test]
+fn anonymous_virtual_placement_does_not_replace_an_ordinary_placement() {
+ let mut terminal = term(640, 384, true);
+ terminal.advance_bytes(XMIT_2X2);
+ place_kitty_for_delete(&mut terminal, 1, 0, 1, 1, 0);
+ let before = kitty_internal_keys(&terminal, false);
+ terminal.advance_bytes("\x1b_Ga=p,i=1,U=1,c=20,r=10\x1b\\");
+ assert_eq!(kitty_internal_keys(&terminal, false), before);
+ assert_eq!(terminal.snapshot_kitty_virtual()[0].placements.len(), 1);
+}
+
+#[test]
+#[cfg(feature = "use_serde")]
+fn internal_placement_identity_does_not_change_image_cell_wire_bytes_or_shape() {
+ use serde::Serialize;
+ use std::hash::Hasher;
+ use wezterm_cell::image::{ImageCell, ImageData, ImageDataType, TextureCoordinate};
+ let cell = ImageCell::new(TextureCoordinate::new_f32(0.0, 0.0), TextureCoordinate::new_f32(1.0, 1.0),
+ Arc::new(ImageData::with_data(ImageDataType::new_single_frame(1, 1, vec![0; 4]))));
+ let tagged = cell.clone().with_placement_tag(u64::from(u32::MAX) + 1);
+ let mut old = Vec::new();
+ let mut new = Vec::new();
+ cell.serialize(&mut varbincode::Serializer::new(&mut old)).unwrap();
+ tagged.serialize(&mut varbincode::Serializer::new(&mut new)).unwrap();
+ assert_eq!(old, new);
+ let mut first = std::collections::hash_map::DefaultHasher::new();
+ let mut second = std::collections::hash_map::DefaultHasher::new();
+ cell.compute_shape_hash(&mut first);
+ tagged.compute_shape_hash(&mut second);
+ assert_eq!(first.finish(), second.finish());
+ // Storage equality still distinguishes them so scrollback compression
+ // cannot merge adjacent, visually identical anonymous placements.
+ assert_ne!(cell, tagged);
+}
+
+fn relative_views(terminal: &mut Terminal, id: u32) -> Vec<crate::kitty_relative::RelativeView> {
+ terminal.kitty_frame_selections(None).unwrap().1.into_iter()
+ .find(|s| s.image_id == id).map(|s| s.relative_placements).unwrap_or_default()
+}
+
+fn relative_images(terminal: &mut Terminal) {
+ for id in 1..=3 { terminal.advance_bytes(XMIT_2X2.replace("i=1", &format!("i={id}"))); }
+}
+
+#[test]
+fn relative_metadata_tracks_position_updates_without_resending_for_unrelated_text() {
+ let mut terminal = term(640, 384, true);
+ relative_images(&mut terminal);
+ place_kitty_for_delete(&mut terminal, 1, 1, 2, 4, 0);
+ terminal.advance_bytes("\x1b_Ga=p,i=2,p=5,P=1,Q=1,H=3,V=2,c=2,r=2\x1b\\");
+ let initial = relative_views(&mut terminal, 2)[0];
+ assert_eq!(initial.source_seqno, terminal.current_seqno() as u64);
+ let revision = terminal.kitty_frame_selections(None).unwrap().0;
+ terminal.advance_bytes("\x1b[20;1Hunrelated text");
+ assert_eq!(relative_views(&mut terminal, 2)[0], initial);
+ assert!(terminal.kitty_frame_selections(Some(revision)).is_none());
+ place_kitty_for_delete(&mut terminal, 1, 1, 3, 4, 0);
+ let moved = relative_views(&mut terminal, 2)[0];
+ assert_eq!(moved.source_seqno, terminal.current_seqno() as u64);
+ assert!(moved.source_seqno > initial.source_seqno);
+ assert_eq!(moved.anchor.row, initial.anchor.row + 1);
+}
+
+#[test]
+fn relative_placements_follow_named_parents_and_chains_without_moving_the_cursor() {
+ let mut terminal = term(640, 384, true);
+ relative_images(&mut terminal);
+ place_kitty_for_delete(&mut terminal, 1, 1, 2, 4, 0);
+ terminal.advance_bytes("\x1b[15;20H");
+ let cursor = terminal.cursor_pos();
+ terminal.advance_bytes("\x1b_Ga=p,i=2,p=5,P=1,Q=1,H=3,V=-1,c=4,r=2,C=0\x1b\\");
+ assert_eq!((terminal.cursor_pos().x, terminal.cursor_pos().y), (cursor.x, cursor.y));
+ assert_eq!(relative_views(&mut terminal, 2)[0].anchor, crate::kitty_relative::Anchor { column: 6, row: 0, alt_screen: false });
+ assert!(kitty_internal_keys(&terminal, false).iter().all(|(id, _)| *id == 1));
+ terminal.advance_bytes("\x1b_Ga=p,i=3,p=6,P=2,Q=5,H=-2,V=5,c=1,r=1\x1b\\");
+ assert_eq!(relative_views(&mut terminal, 3)[0].anchor, crate::kitty_relative::Anchor { column: 4, row: 5, alt_screen: false });
+ place_kitty_for_delete(&mut terminal, 1, 1, 8, 10, 0);
+ assert_eq!(relative_views(&mut terminal, 3)[0].anchor, crate::kitty_relative::Anchor { column: 10, row: 11, alt_screen: false });
+ // A cycle must retain the ordinary root and both relative placements.
+ terminal.advance_bytes("\x1b_Ga=p,i=1,p=1,P=3,Q=6,c=2,r=2\x1b\\");
+ assert_eq!(kitty_internal_keys(&terminal, false), [(1, 1)].into());
+ assert_eq!(relative_views(&mut terminal, 3)[0].anchor.column, 10);
+ terminal.advance_bytes("\x1b_Ga=d,d=i,i=1,p=1\x1b\\");
+ assert!(relative_views(&mut terminal, 2).is_empty());
+ assert!(terminal.kitty_image_data_for_id(2).is_none());
+ assert!(terminal.kitty_image_data_for_id(3).is_none());
+ assert!(terminal.kitty_image_data_for_id(1).is_some());
+}
+
+#[test]
+fn relative_parent_selection_is_stable_for_anonymous_siblings() {
+ let mut terminal = term(640, 384, true);
+ relative_images(&mut terminal);
+ place_kitty_for_delete(&mut terminal, 1, 0, 2, 4, 0);
+ place_kitty_for_delete(&mut terminal, 1, 0, 7, 4, 0);
+ terminal.advance_bytes("\x1b_Ga=p,i=2,P=1,H=2,V=1,c=2,r=2\x1b\\");
+ let view = relative_views(&mut terminal, 2);
+ assert_eq!(view[0].anchor.row, 2);
+ terminal.advance_bytes("\x1b_Ga=d,d=p,x=4,y=7\x1b\\");
+ assert_eq!(relative_views(&mut terminal, 2), view);
+ terminal.advance_bytes("\x1b_Ga=d,d=p,x=4,y=2\x1b\\");
+ assert!(terminal.kitty_image_data_for_id(2).is_none());
+}
+
+#[test]
+fn virtual_parent_can_hide_and_reappear_without_deleting_relative_children() {
+ let mut terminal = term(640, 384, true);
+ relative_images(&mut terminal);
+ terminal.advance_bytes("\x1b_Ga=p,i=1,p=5,U=1,c=1,r=1\x1b\\");
+ terminal.advance_bytes("\x1b_Ga=p,i=2,p=7,P=1,Q=5,H=-1,V=2,c=2,r=2\x1b\\");
+ assert!(relative_views(&mut terminal, 2).is_empty());
+ assert!(terminal.kitty_image_data_for_id(2).is_some());
+ terminal.advance_bytes("\x1b[4;10H\x1b[38;2;0;0;1;58;2;0;0;5m\u{10eeee}\x1b[0m");
+ assert_eq!(relative_views(&mut terminal, 2)[0].anchor, crate::kitty_relative::Anchor { column: 8, row: 5, alt_screen: false });
+ terminal.advance_bytes("\x1b[4;1H\x1b[2K");
+ assert!(relative_views(&mut terminal, 2).is_empty());
+ assert!(terminal.kitty_image_data_for_id(2).is_some());
+ terminal.advance_bytes("\x1b[2;8H\x1b[38;2;0;0;1;58;2;0;0;5m\u{10eeee}\x1b[0m");
+ assert_eq!(relative_views(&mut terminal, 2)[0].anchor.column, 6);
+ terminal.advance_bytes("\x1b_Ga=d,d=i,i=1,p=5\x1b\\");
+ assert!(terminal.kitty_image_data_for_id(2).is_none());
+}
+
+#[test]
+fn relative_deletion_selects_the_current_rectangle_and_releases_descendants() {
+ for selector in ["p,x=7,y=4", "q,x=7,y=4,z=-2", "x,x=7", "y,y=4", "z,z=-2"] {
+ let mut terminal = term(640, 384, true);
+ relative_images(&mut terminal);
+ place_kitty_for_delete(&mut terminal, 1, 1, 2, 4, 0);
+ terminal.advance_bytes("\x1b_Ga=p,i=2,p=5,P=1,Q=1,H=3,V=2,c=4,r=2,z=-2\x1b\\");
+ terminal.advance_bytes("\x1b_Ga=p,i=3,p=6,P=2,Q=5,V=4,c=2,r=2\x1b\\");
+ terminal.advance_bytes(format!("\x1b_Ga=d,d={selector}\x1b\\"));
+ assert!(terminal.kitty_image_data_for_id(2).is_none());
+ assert!(terminal.kitty_image_data_for_id(3).is_none());
+ assert_eq!(kitty_internal_keys(&terminal, false), [(1, 1)].into());
+ }
+}
+
+#[test]
+fn relative_roots_follow_reflow_and_can_stay_outside_the_viewport() {
+ let mut terminal = term(640, 384, true);
+ relative_images(&mut terminal);
+ place_kitty_for_delete(&mut terminal, 1, 1, 1, 75, 0);
+ terminal.advance_bytes("\x1b[1;80HX\x1b_Ga=p,i=2,p=5,P=1,Q=1,H=-1,V=4,c=2,r=2\x1b\\");
+ terminal.resize(TerminalSize { rows: 24, cols: 20, pixel_width: 160, pixel_height: 384, dpi: 96 });
+ let view = relative_views(&mut terminal, 2)[0];
+ assert_eq!(view.anchor.column, 13);
+ assert_eq!(view.anchor.row, 7);
+ terminal.advance_bytes("\x1b[24;1H\n\n\n\n\n");
+ assert_eq!(relative_views(&mut terminal, 2)[0], view);
+ terminal.advance_bytes("\x1b[?1049h");
+ assert!(!relative_views(&mut terminal, 2)[0].anchor.alt_screen);
+ terminal.advance_bytes("\x1b[?1049l\x1b[2J\x1b[3J");
+ assert!(terminal.kitty_image_data_for_id(2).is_none());
+}
+
+#[test]
+fn relative_errors_keep_existing_placements_and_replies_identify_the_placement() {
+ let (mut terminal, tap) = term_with_tap(640, 384);
+ relative_images(&mut terminal);
+ place_kitty_for_delete(&mut terminal, 1, 1, 2, 4, 0);
+ terminal.advance_bytes("\x1b_Ga=p,i=2,p=5,P=1,Q=1,c=2,r=2\x1b\\");
+ let view = relative_views(&mut terminal, 2);
+ drain(&mut terminal, &tap);
+ for (keys, code) in [("P=99", "ENOPARENT"), ("P=2,Q=5", "ECYCLE"), ("P=1,Q=1,U=1", "EINVAL")] {
+ terminal.advance_bytes(format!("\x1b_Ga=p,i=2,p=5,{keys},c=2,r=2\x1b\\"));
+ let reply = drain(&mut terminal, &tap);
+ assert!(reply.contains(&format!("i=2,p=5;{code}:")), "unexpected reply: {:?}", reply);
+ assert_eq!(relative_views(&mut terminal, 2), view);
+ }
+ terminal.advance_bytes("\x1b_Ga=p,i=1,I=9,p=1\x1b\\");
+ assert!(drain(&mut terminal, &tap).contains("EINVAL:"));
+}
+
+#[test]
+#[cfg(feature = "use_serde")]
+fn relative_graph_and_cell_origins_survive_repeated_restore_and_image_retransmission() {
+ let mut original = term(640, 384, true);
+ relative_images(&mut original);
+ place_kitty_for_delete(&mut original, 1, 0, 2, 4, 0);
+ original.advance_bytes("\x1b_Ga=p,i=2,P=1,H=3,V=2,c=2,r=2\x1b\\");
+ let expected = relative_views(&mut original, 2);
+ for _ in 0..2 {
+ let state = original.snapshot_kitty_graphics();
+ let mut next = term(640, 384, true);
+ next.restore_with_kitty_placements(original.snapshot(), state.placements).unwrap();
+ next.restore_kitty_relatives(state.relatives.unwrap()).unwrap();
+ assert_eq!(relative_views(&mut next, 2), expected);
+ original = next;
+ }
+ original.advance_bytes(XMIT_2X2);
+ assert!(kitty_internal_keys(&original, false).is_empty());
+ assert!(relative_views(&mut original, 2).is_empty());
+ assert!(original.kitty_image_data_for_id(2).is_none());
+}
diff --git a/term/src/test/snapshot.rs b/term/src/test/snapshot.rs
index df44d797..200a968c 100644
--- a/term/src/test/snapshot.rs
+++ b/term/src/test/snapshot.rs
@@ -117,7 +117,8 @@ fn a_restored_terminal_is_the_same_terminal() {
assert!(snapshot.alt_screen_is_active);
assert!(!snapshot.kitty.transmission_in_progress);
- let mut copy = restored(original.snapshot(), 100);
+ let mut copy = terminal(100);
+ copy.restore_with_kitty_placements(original.snapshot(), original.snapshot_kitty_graphics().placements).unwrap();
assert_eq!(copy.snapshot(), snapshot, "a snapshot of the restore");
for alt in [false, true] {
assert_eq!(
@@ -259,7 +260,8 @@ fn a_smaller_scrollback_keeps_the_newest_lines() {
let offset = snapshot.screen.stable_row_index_offset;
assert!(carried > 24 + 4, "the script scrolled {carried} lines");
- let copy = restored(snapshot, 4);
+ let mut copy = terminal(4);
+ copy.restore_with_kitty_placements(snapshot, original.snapshot_kitty_graphics().placements).unwrap();
let screen = copy.screen();
assert_eq!(screen.lines().len(), 24 + 4, "visible rows plus the allowance");
assert_eq!(
diff --git a/wezterm-cell/src/image.rs b/wezterm-cell/src/image.rs
index 3d487367..e554a507 100644
--- a/wezterm-cell/src/image.rs
+++ b/wezterm-cell/src/image.rs
@@ -98,6 +98,9 @@ pub struct ImageCell {
image_id: Option<u32>,
placement_id: Option<u32>,
+ /// Internal identity for anonymous Kitty placements; external p stays zero.
+ #[cfg_attr(feature = "use_serde", serde(skip))]
+ placement_tag: u64,
}
impl ImageCell {
@@ -145,6 +148,7 @@ impl ImageCell {
padding_bottom,
image_id,
placement_id,
+ placement_tag: 0,
}
}
@@ -164,6 +168,19 @@ impl ImageCell {
self.placement_id
}
+ pub fn placement_tag(&self) -> u64 {
+ if self.placement_tag == 0 {
+ u64::from(self.placement_id.unwrap_or(0))
+ } else {
+ self.placement_tag
+ }
+ }
+
+ pub fn with_placement_tag(mut self, tag: u64) -> Self {
+ self.placement_tag = tag;
+ self
+ }
+
pub fn top_left(&self) -> TextureCoordinate {
self.top_left
}
@@ -176,6 +193,10 @@ impl ImageCell {
&self.data
}
+ pub(crate) fn set_image_data(&mut self, data: Arc<ImageData>) {
+ self.data = data;
+ }
+
/// negative z_index is rendered beneath the text layer.
/// >= 0 is rendered above the text.
/// negative z_index < INT32_MIN/2 will be drawn under cells
@@ -401,7 +422,7 @@ impl ImageDataType {
/// marker || per-process random salt || counter. The salt keeps keys
/// minted by different processes (this GUI, every mux server) from
/// colliding in the client- and GPU-side caches that mix all sources.
- fn nonce_key() -> [u8; 32] {
+ pub fn nonce_key() -> [u8; 32] {
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::OnceLock;
static SALT: OnceLock<[u8; 16]> = OnceLock::new();
@@ -466,7 +487,7 @@ impl ImageDataType {
match self {
ImageDataType::EncodedFile(data) => hasher.update(data),
ImageDataType::EncodedLease(lease) => return lease.content_id().as_hash_bytes(),
- ImageDataType::Rgba8 { data, hash, .. } => {
+ ImageDataType::Rgba8 { data, hash, width, height } => {
// The stored key is authoritative: the constructors compute
// it and every in-place pixel edit refreshes it (see
// terminalstate/kitty.rs), so full-frame payloads are not
@@ -476,18 +497,25 @@ impl ImageDataType {
// future forgotten refresh into a loud test failure instead
// of a stale-image glitch; nonce keys are identity-only and
// have nothing to re-derive.
- if !Self::is_nonce_key(hash) {
- debug_assert_eq!(
- *hash,
- Self::hash_bytes(data),
- "Rgba8 hash field is stale; a pixel mutation forgot to refresh it"
- );
+ if Self::is_nonce_key(hash) {
+ return *hash;
}
- return *hash;
+ debug_assert_eq!(
+ *hash,
+ Self::hash_bytes(data),
+ "Rgba8 hash field is stale; a pixel mutation forgot to refresh it"
+ );
+ hasher.update(b"rgba8");
+ hasher.update(width.to_le_bytes());
+ hasher.update(height.to_le_bytes());
+ hasher.update(hash);
}
ImageDataType::AnimRgba8 {
- hashes, durations, ..
+ hashes, durations, width, height, ..
} => {
+ hasher.update(b"anim-rgba8");
+ hasher.update(width.to_le_bytes());
+ hasher.update(height.to_le_bytes());
// Fold the per-frame keys instead of re-hashing every
// frame's pixels: the keys already identify the frame
// content (or are unique nonces), and hashing 32 bytes per
@@ -743,10 +771,9 @@ impl ImageData {
Self::with_data_and_hash(ImageDataType::EncodedFile(data).decode(), hash)
}
- /// `hash` must equal `data.compute_hash()`; the caller supplies it to
- /// avoid re-hashing image payloads that were already hashed for cache
- /// lookup (a full-frame SHA-256 per kitty transmission otherwise runs
- /// twice on the pty read thread while it holds the terminal lock).
+ /// Use an existing identity without hashing the payload again. Immutable
+ /// images use `data.compute_hash()`; mutable copies and frame deltas retain
+ /// an identity independent of their current pixels.
pub fn with_data_and_hash(data: ImageDataType, hash: [u8; 32]) -> Self {
Self {
data: Mutex::new(data),
@@ -764,6 +791,14 @@ impl ImageData {
}
}
+ /// A private mutable copy with an independent, stable cache identity.
+ pub fn copy_for_mutation(&self) -> Self {
+ let data = self.data();
+ let copy = Self::with_data_and_hash(data.clone(), ImageDataType::nonce_key());
+ copy.set_generation(self.generation());
+ copy
+ }
+
/// How many in-place changes `data` has seen. See the field.
pub fn generation(&self) -> u64 {
self.generation.load(Ordering::Acquire)
@@ -865,4 +900,18 @@ mod tests {
let c = mk(vec![vec![0, 0, 0, 0xff]; 2], vec![[1u8; 32], [3u8; 32]]);
assert_ne!(a.compute_hash(), c.compute_hash());
}
+
+ #[test]
+ fn decoded_image_identity_includes_shape() {
+ let a = ImageDataType::new_single_frame(1, 2, vec![7; 8]);
+ let b = ImageDataType::new_single_frame(2, 1, vec![7; 8]);
+ assert_ne!(a.compute_hash(), b.compute_hash());
+ assert_eq!(a.compute_hash(), a.clone().compute_hash());
+ let animation = |width, height| ImageDataType::AnimRgba8 {
+ width, height, frames: vec![vec![7; 8]],
+ hashes: vec![ImageDataType::content_key(&[7; 8])],
+ durations: vec![Duration::ZERO],
+ };
+ assert_ne!(animation(1, 2).compute_hash(), animation(2, 1).compute_hash());
+ }
}
diff --git a/wezterm-cell/src/lib.rs b/wezterm-cell/src/lib.rs
index 7c58632d..4cf2f359 100644
--- a/wezterm-cell/src/lib.rs
+++ b/wezterm-cell/src/lib.rs
@@ -533,6 +533,41 @@ impl CellAttributes {
self.deallocate_fat_attributes_if_none();
}
+ /// Remove matching attachments while preserving shared rows and z order.
+ pub fn detach_images(&mut self, matches: impl Fn(&ImageCell) -> bool) -> bool {
+ if !self.image_attachments().any(&matches) {
+ return false;
+ }
+ self.update_fat(|fat| {
+ fat.update_images(|images| images.retain(|image| !matches(image)))
+ });
+ self.deallocate_fat_attributes_if_none();
+ true
+ }
+
+ /// Rebind one image's attachments without changing their order or geometry.
+ pub fn replace_image_data(
+ &mut self,
+ image_id: u32,
+ old: &Arc<image::ImageData>,
+ new: &Arc<image::ImageData>,
+ ) -> bool {
+ let matches = |image: &ImageCell| {
+ image.image_id() == Some(image_id) && Arc::ptr_eq(image.image_data(), old)
+ };
+ if !self.image_attachments().any(matches) {
+ return false;
+ }
+ self.update_fat(|fat| {
+ fat.update_images(|images| {
+ for image in images.iter_mut().filter(|image| matches(image)) {
+ image.set_image_data(Arc::clone(new));
+ }
+ });
+ });
+ true
+ }
+
/// Add an image attachement, preserving any existing attachments.
/// The list of images is maintained in z-index order
pub fn attach_image(&mut self, image: Box<ImageCell>) -> &mut Self {
@@ -638,6 +673,14 @@ impl CellAttributes {
.is_some_and(|fat| !fat.images().is_empty())
}
+ /// Borrow attachments without allocating a list or cloning their pixels' Arcs.
+ #[cfg(feature = "use_image")]
+ pub fn image_attachments(&self) -> impl Iterator<Item = &ImageCell> {
+ self.fat
+ .iter()
+ .flat_map(|fat| fat.images().iter().map(Box::as_ref))
+ }
+
pub fn underline_color(&self) -> ColorAttribute {
self.fat
.as_ref()
diff --git a/wezterm-escape-parser/src/apc.rs b/wezterm-escape-parser/src/apc.rs
index 882b0f27..8c18620a 100644
--- a/wezterm-escape-parser/src/apc.rs
+++ b/wezterm-escape-parser/src/apc.rs
@@ -959,6 +959,12 @@ pub struct KittyImagePlacement {
/// Give an explicit placement id to this placement.
/// p=...
pub placement_id: Option<u32>,
+ /// Parent image and placement, P/Q. Q=0 chooses a placement of P.
+ pub parent_image_id: Option<u32>,
+ pub parent_placement_id: Option<u32>,
+ /// Signed cell offsets from the parent's top-left cell, H/V.
+ pub horizontal_offset: Option<i32>,
+ pub vertical_offset: Option<i32>,
/// z=...
pub z_index: Option<i32>,
/// A virtual placement draws nothing by itself. It registers that the
@@ -980,6 +986,10 @@ impl KittyImagePlacement {
columns: geti(keys, "c"),
rows: geti(keys, "r"),
placement_id: geti(keys, "p"),
+ parent_image_id: geti(keys, "P"),
+ parent_placement_id: geti(keys, "Q"),
+ horizontal_offset: geti(keys, "H"),
+ vertical_offset: geti(keys, "V"),
do_not_move_cursor: match get(keys, "C") {
None | Some("0") => false,
Some("1") => true,
@@ -1004,6 +1014,10 @@ impl KittyImagePlacement {
set(keys, "c", &self.columns);
set(keys, "r", &self.rows);
set(keys, "p", &self.placement_id);
+ set(keys, "P", &self.parent_image_id);
+ set(keys, "Q", &self.parent_placement_id);
+ set(keys, "H", &self.horizontal_offset);
+ set(keys, "V", &self.vertical_offset);
if self.do_not_move_cursor {
keys.insert("C", "1".to_string());
@@ -1043,6 +1057,8 @@ pub enum KittyImageDelete {
placement_id: Option<u32>,
delete: bool,
},
+ /// d='r' or d='R', inclusive image id bounds from x and y.
+ ByImageIdRange { first: u32, last: u32, delete: bool },
/// d='c' or d='C'
/// Delete all placements that intersect with the current
@@ -1051,7 +1067,12 @@ pub enum KittyImageDelete {
/// d='f' or d='F'
/// Delete animation frames
- AnimationFrames { delete: bool },
+ AnimationFrames {
+ image_id: Option<u32>,
+ image_number: Option<u32>,
+ frame_number: Option<u32>,
+ delete: bool,
+ },
/// d='p' or d='P'
/// Delete all placements that intersect the specified
@@ -1101,8 +1122,18 @@ impl KittyImageDelete {
placement_id: geti(keys, "p"),
delete,
}),
+ 'r' | 'R' => Some(Self::ByImageIdRange {
+ first: geti(keys, "x")?,
+ last: geti(keys, "y")?,
+ delete,
+ }),
'c' | 'C' => Some(Self::AtCursorPosition { delete }),
- 'f' | 'F' => Some(Self::AnimationFrames { delete }),
+ 'f' | 'F' => Some(Self::AnimationFrames {
+ image_id: geti(keys, "i"),
+ image_number: geti(keys, "I"),
+ frame_number: geti(keys, "r"),
+ delete,
+ }),
'p' | 'P' => Some(Self::DeleteAt {
x: geti(keys, "x")?,
y: geti(keys, "y")?,
@@ -1164,8 +1195,16 @@ impl KittyImageDelete {
Self::AtCursorPosition { delete } => {
keys.insert("d", d('c', delete));
}
- Self::AnimationFrames { delete } => {
+ Self::ByImageIdRange { first, last, delete } => {
+ keys.insert("d", d('r', delete));
+ keys.insert("x", first.to_string());
+ keys.insert("y", last.to_string());
+ }
+ Self::AnimationFrames { image_id, image_number, frame_number, delete } => {
keys.insert("d", d('f', delete));
+ set(keys, "i", image_id);
+ set(keys, "I", image_number);
+ set(keys, "r", frame_number);
}
Self::DeleteAt { x, y, delete } => {
keys.insert("d", d('p', delete));
@@ -1173,7 +1212,7 @@ impl KittyImageDelete {
keys.insert("y", y.to_string());
}
Self::DeleteAtZ { x, y, z, delete } => {
- keys.insert("d", d('p', delete));
+ keys.insert("d", d('q', delete));
keys.insert("x", x.to_string());
keys.insert("y", y.to_string());
keys.insert("z", z.to_string());
@@ -1317,6 +1356,8 @@ pub struct KittyImageFrame {
/// Zero or omitted values are interpreted as 40ms.
/// z=...
pub duration_ms: Option<u32>,
+ /// A negative z, retained separately from the legacy unsigned duration.
+ pub gapless: bool,
/// Composition mode.
/// Default is AlphaBlending
@@ -1346,6 +1387,7 @@ impl KittyImageFrame {
None | Some(0) => None,
n => n,
},
+ gapless: geti::<i32>(keys, "z").is_some_and(|gap| gap < 0),
composition_mode: match geti(keys, "X") {
None | Some(0) => KittyFrameCompositionMode::AlphaBlending,
Some(1) => KittyFrameCompositionMode::Overwrite,
@@ -1361,6 +1403,7 @@ impl KittyImageFrame {
set(keys, "c", &self.base_frame);
set(keys, "r", &self.frame_number);
set(keys, "z", &self.duration_ms);
+ if self.gapless { keys.insert("z", "-1".to_string()); }
match &self.composition_mode {
KittyFrameCompositionMode::AlphaBlending => {}
KittyFrameCompositionMode::Overwrite => {
@@ -1371,6 +1414,75 @@ impl KittyImageFrame {
}
}
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[cfg_attr(feature = "use_serde", derive(serde::Serialize, serde::Deserialize))]
+pub enum KittyAnimationState {
+ Stopped,
+ Loading,
+ Running,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct KittyImageAnimationControl {
+ pub image_id: Option<u32>,
+ pub image_number: Option<u32>,
+ /// c: the one-based frame to display now.
+ pub current_frame: Option<u32>,
+ /// r: the one-based frame whose gap is being changed.
+ pub frame_number: Option<u32>,
+ pub state: Option<KittyAnimationState>,
+ /// v: 1 means infinite; otherwise the number of loops plus one.
+ pub loops: Option<u32>,
+ /// z: negative gaps skip the frame; zero leaves its gap unchanged.
+ pub gap_ms: Option<i32>,
+}
+
+impl KittyImageAnimationControl {
+ fn from_keys(keys: &BTreeMap<&str, &str>) -> Option<Self> {
+ fn number<T: core::str::FromStr>(
+ keys: &BTreeMap<&str, &str>,
+ key: &str,
+ ) -> Option<Option<T>> {
+ get(keys, key).map(str::parse).transpose().ok()
+ }
+ Some(Self {
+ image_id: number(keys, "i")?.filter(|n| *n != 0),
+ image_number: number(keys, "I")?.filter(|n| *n != 0),
+ current_frame: number(keys, "c")?.filter(|n| *n != 0),
+ frame_number: number(keys, "r")?.filter(|n| *n != 0),
+ state: match number::<u32>(keys, "s")? {
+ None | Some(0) => None,
+ Some(1) => Some(KittyAnimationState::Stopped),
+ Some(2) => Some(KittyAnimationState::Loading),
+ Some(3) => Some(KittyAnimationState::Running),
+ _ => return None,
+ },
+ loops: number(keys, "v")?.filter(|n| *n != 0),
+ gap_ms: number(keys, "z")?.filter(|n| *n != 0),
+ })
+ }
+
+ fn to_keys(&self, keys: &mut BTreeMap<&'static str, String>) {
+ set(keys, "i", &self.image_id);
+ set(keys, "I", &self.image_number);
+ set(keys, "c", &self.current_frame);
+ set(keys, "r", &self.frame_number);
+ set(keys, "v", &self.loops);
+ set(keys, "z", &self.gap_ms);
+ if let Some(state) = self.state {
+ keys.insert(
+ "s",
+ match state {
+ KittyAnimationState::Stopped => "1",
+ KittyAnimationState::Loading => "2",
+ KittyAnimationState::Running => "3",
+ }
+ .to_string(),
+ );
+ }
+ }
+}
+
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum KittyImage {
/// a='t'
@@ -1412,6 +1524,11 @@ pub enum KittyImage {
frame: KittyImageFrameCompose,
verbosity: KittyImageVerbosity,
},
+ /// a='a'
+ ControlAnimation {
+ control: KittyImageAnimationControl,
+ verbosity: KittyImageVerbosity,
+ },
}
impl KittyImage {
@@ -1425,7 +1542,10 @@ impl KittyImage {
| Self::TransmitDataAndDisplay { transmit, .. }
| Self::Query { transmit, .. }
| Self::TransmitFrame { transmit, .. } => &transmit.data,
- Self::Display { .. } | Self::Delete { .. } | Self::ComposeFrame { .. } => {
+ Self::Display { .. }
+ | Self::Delete { .. }
+ | Self::ComposeFrame { .. }
+ | Self::ControlAnimation { .. } => {
return false;
}
};
@@ -1462,7 +1582,8 @@ impl KittyImage {
| Self::TransmitFrame { .. }
| Self::Display { .. }
| Self::Delete { .. }
- | Self::ComposeFrame { .. } => None,
+ | Self::ComposeFrame { .. }
+ | Self::ControlAnimation { .. } => None,
}
}
@@ -1475,7 +1596,10 @@ impl KittyImage {
| Self::TransmitFrame { transmit, .. } => {
transmit.data.discard_external_source(reason);
}
- Self::Display { .. } | Self::Delete { .. } | Self::ComposeFrame { .. } => {}
+ Self::Display { .. }
+ | Self::Delete { .. }
+ | Self::ComposeFrame { .. }
+ | Self::ControlAnimation { .. } => {}
}
#[cfg(not(feature = "kitty-shm"))]
{
@@ -1492,7 +1616,10 @@ impl KittyImage {
| Self::TransmitDataAndDisplay { transmit, .. }
| Self::Query { transmit, .. }
| Self::TransmitFrame { transmit, .. } => transmit.data.materialized_len(),
- Self::Display { .. } | Self::Delete { .. } | Self::ComposeFrame { .. } => 0,
+ Self::Display { .. }
+ | Self::Delete { .. }
+ | Self::ComposeFrame { .. }
+ | Self::ControlAnimation { .. } => 0,
}
}
#[cfg(not(feature = "kitty-shm"))]
@@ -1513,7 +1640,10 @@ impl KittyImage {
| Self::TransmitFrame { transmit, .. } => {
transmit.data.materialize_external_source();
}
- Self::Display { .. } | Self::Delete { .. } | Self::ComposeFrame { .. } => {}
+ Self::Display { .. }
+ | Self::Delete { .. }
+ | Self::ComposeFrame { .. }
+ | Self::ControlAnimation { .. } => {}
}
}
@@ -1540,6 +1670,7 @@ impl KittyImage {
Self::Delete { verbosity, .. } => *verbosity,
Self::TransmitFrame { verbosity, .. } => *verbosity,
Self::ComposeFrame { verbosity, .. } => *verbosity,
+ Self::ControlAnimation { verbosity, .. } => *verbosity,
}
}
@@ -1590,6 +1721,10 @@ impl KittyImage {
frame: KittyImageFrame::from_keys(&keys)?,
verbosity,
}),
+ "a" => Some(Self::ControlAnimation {
+ control: KittyImageAnimationControl::from_keys(&keys)?,
+ verbosity,
+ }),
"c" => Some(Self::ComposeFrame {
frame: KittyImageFrameCompose::from_keys(&keys)?,
verbosity,
@@ -1621,7 +1756,7 @@ impl KittyImage {
verbosity,
placement,
} => {
- keys.insert("a", "Q".to_string());
+ keys.insert("a", "T".to_string());
verbosity.to_keys(keys);
placement.to_keys(keys);
transmit.to_keys(keys);
@@ -1657,6 +1792,11 @@ impl KittyImage {
frame.to_keys(keys);
verbosity.to_keys(keys);
}
+ Self::ControlAnimation { control, verbosity } => {
+ keys.insert("a", "a".to_string());
+ control.to_keys(keys);
+ verbosity.to_keys(keys);
+ }
Self::ComposeFrame { frame, verbosity } => {
keys.insert("a", "c".to_string());
frame.to_keys(keys);
@@ -1700,6 +1840,126 @@ mod test {
use super::*;
use k9::assert_equal as assert_eq;
+ #[test]
+ fn kitty_commands_keep_all_keys_when_forwarded() {
+ for command in [
+ "Ga=T,i=9,f=32,s=1,v=1,p=3,C=1;/wAA/w==",
+ "Ga=d,d=q,x=3,y=4,z=-2", "Ga=d,d=Q,x=3,y=4,z=-2",
+ "Ga=d,d=r,x=7,y=19", "Ga=d,d=R,x=7,y=19",
+ "Ga=d,d=f,i=9,I=7,r=3", "Ga=d,d=F,I=7,r=0",
+ "Ga=d,d=n,I=7,p=3", "Ga=d,d=N,I=7,p=0",
+ ] {
+ let parsed = KittyImage::parse_apc(command.as_bytes()).unwrap();
+ let encoded = parsed.to_string();
+ assert_eq!(KittyImage::parse_apc(&encoded.as_bytes()[2..]), Some(parsed), "{command}");
+ }
+ assert!(matches!(
+ KittyImage::parse_apc(b"Ga=d,d=R,x=7,y=19"),
+ Some(KittyImage::Delete { what: KittyImageDelete::ByImageIdRange { first: 7, last: 19, delete: true }, .. })
+ ));
+ assert!(matches!(
+ KittyImage::parse_apc(b"Ga=d,d=f,i=9,r=3"),
+ Some(KittyImage::Delete { what: KittyImageDelete::AnimationFrames { image_id: Some(9), frame_number: Some(3), .. }, .. })
+ ));
+ }
+
+ #[test]
+ fn kitty_relative_placements_keep_parent_and_signed_offsets() {
+ for action in ["p", "T"] {
+ let command = format!("Ga={action},i=9,p=3,P=8,Q=2,H=-2147483648,V=2147483647,C=0,x=1,y=2,w=3,h=4,X=5,Y=6,c=7,r=8,z=-9,f=32,s=1,v=1;/wAA/w==");
+ let parsed = KittyImage::parse_apc(command.as_bytes()).unwrap();
+ let placement = match &parsed {
+ KittyImage::Display { placement, .. }
+ | KittyImage::TransmitDataAndDisplay { placement, .. } => placement,
+ other => panic!("unexpected command: {:?}", other),
+ };
+ assert_eq!(placement.parent_image_id, Some(8));
+ assert_eq!(placement.parent_placement_id, Some(2));
+ assert_eq!(placement.horizontal_offset, Some(i32::MIN));
+ assert_eq!(placement.vertical_offset, Some(i32::MAX));
+ assert!(!placement.do_not_move_cursor);
+ let encoded = parsed.to_string();
+ assert_eq!(KittyImage::parse_apc(&encoded.as_bytes()[2..]), Some(parsed));
+ }
+ let Some(KittyImage::Display { placement, .. }) = KittyImage::parse_apc(b"Ga=p,i=9,P=8") else { panic!("expected placement") };
+ assert_eq!(placement.parent_image_id, Some(8));
+ assert_eq!(placement.parent_placement_id, None);
+ assert_eq!(placement.horizontal_offset, None);
+ assert_eq!(placement.vertical_offset, None);
+ }
+
+ #[test]
+ fn kitty_animation_controls_keep_signed_gaps_and_round_trip() {
+ for (state, value) in [
+ (KittyAnimationState::Stopped, 1),
+ (KittyAnimationState::Loading, 2),
+ (KittyAnimationState::Running, 3),
+ ] {
+ let parsed = KittyImage::parse_apc(
+ format!("Ga=a,i=9,I=7,c=3,r=2,s={value},v=5,z=-1,q=2").as_bytes(),
+ )
+ .unwrap();
+ assert_eq!(
+ parsed,
+ KittyImage::ControlAnimation {
+ control: KittyImageAnimationControl {
+ image_id: Some(9),
+ image_number: Some(7),
+ current_frame: Some(3),
+ frame_number: Some(2),
+ state: Some(state),
+ loops: Some(5),
+ gap_ms: Some(-1),
+ },
+ verbosity: KittyImageVerbosity::Quiet,
+ }
+ );
+ let encoded = parsed.to_string();
+ assert_eq!(
+ KittyImage::parse_apc(&encoded.as_bytes()[2..]),
+ Some(parsed.clone())
+ );
+ assert_eq!(parsed.replacing_transmit_image_id(), None);
+ assert!(!parsed.has_external_data_source());
+ assert_eq!(parsed.materialized_len(), 0);
+ }
+ }
+
+ #[test]
+ fn kitty_animation_control_zero_means_unspecified() {
+ assert_eq!(
+ KittyImage::parse_apc(b"Ga=a,i=0,I=0,c=0,r=0,s=0,v=0,z=0"),
+ KittyImage::parse_apc(b"Ga=a")
+ );
+ let Some(KittyImage::ControlAnimation { control, .. }) =
+ KittyImage::parse_apc(b"Ga=a,i=1,v=1,z=2147483647")
+ else {
+ panic!("valid animation control")
+ };
+ assert_eq!(control.loops, Some(1));
+ assert_eq!(control.gap_ms, Some(i32::MAX));
+ }
+
+ #[test]
+ fn kitty_animation_controls_reject_invalid_numbers() {
+ for field in [
+ "s=4",
+ "s=-1",
+ "v=-1",
+ "c=-1",
+ "r=4294967296",
+ "i=invalid",
+ "I=-1",
+ "z=2147483648",
+ "z=-2147483649",
+ ] {
+ assert!(
+ KittyImage::parse_apc(format!("Ga=a,{field}").as_bytes()).is_none(),
+ "{field}"
+ );
+ }
+ }
+
#[cfg(feature = "kitty-shm")]
#[test]
fn kitty_payload_accepts_optional_base64_padding() {
@@ -1855,6 +2115,7 @@ mod test {
composition_mode: KittyFrameCompositionMode::Overwrite,
background_pixel: None,
duration_ms: None,
+ gapless: false,
},
}
);