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.
Rust agentagent-orchestrationaiai-agentsclaude-codecodexcoding-agentlinuxmacosmultiplayermultiplexerrustterminalterminal-emulatorterminal-multiplexertmuxtuiweztermwindows
use crate::{Position, StableRowIndex, TerminalState};
use anyhow::Context;
use humansize::{SizeFormatter, DECIMAL};
use num_traits::{One, Zero};
use ordered_float::NotNan;
use std::sync::Arc;
use wezterm_cell::image::{ImageCell, ImageDataType};
use wezterm_cell::Cell;
use wezterm_surface::change::ImageData;
use wezterm_surface::TextureCoordinate;
#[cfg_attr(
feature = "use_serde",
derive(serde::Serialize, serde::Deserialize)
)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PlacementInfo {
pub first_row: StableRowIndex,
pub rows: usize,
pub cols: usize,
/// Which screen the cells live on. Removal must target that screen:
/// the budget sweep can fire while the other one is active, and
/// detaching rows on the wrong screen frees nothing while the picture
/// comes back with the screen switch.
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
pub image_width: u32,
pub image_height: u32,
/// Dimensions of the area of the image to be displayed, in pixels
pub source_width: Option<u32>,
pub source_height: Option<u32>,
/// Origin of the source data region, top left corner in pixels
pub source_origin_x: u32,
pub source_origin_y: u32,
/// When rendering in the cell, use this offset from the top left
/// of the cell. This is only used in the Kitty image protocol.
/// This should be smaller than the size of the cell. Larger values will
/// be truncated.
pub cell_padding_left: u16,
pub cell_padding_top: u16,
/// Plane on which to display the image
pub z_index: i32,
/// Desired number of cells to span.
/// If None, then compute based on source_width and source_height
pub columns: Option<usize>,
pub rows: Option<usize>,
pub image_id: Option<u32>,
pub placement_id: Option<u32>,
pub placement_tag: u64,
pub style: ImageAttachStyle,
pub do_not_move_cursor: bool,
pub data: Arc<ImageData>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ImageAttachStyle {
Sixel,
Iterm,
Kitty,
}
impl TerminalState {
pub(crate) fn assign_image_to_cells(
&mut self,
params: ImageAttachParams,
) -> anyhow::Result<ImagePlacement> {
let seqno = self.seqno;
let physical_cols = self.screen().physical_cols;
let physical_rows = self.screen().physical_rows;
// A pane can be asked to show an image before anything has told it how
// many pixels it has: the tmux and mux-server paths never report a pixel
// size at all, and the GUI only corrects one after the window has laid
// the pane out. Every division below would then be by zero.
let cell_pixel_width = self.pixel_width.checked_div(physical_cols).unwrap_or(0);
let cell_pixel_height = self.pixel_height.checked_div(physical_rows).unwrap_or(0);
anyhow::ensure!(
cell_pixel_width > 0 && cell_pixel_height > 0,
"no usable cell geometry: {}x{} pixels across {}x{} cells",
self.pixel_width,
self.pixel_height,
physical_cols,
physical_rows
);
let cell_padding_left = params
.cell_padding_left
.min(cell_pixel_width.saturating_sub(1) as u16);
let cell_padding_top = params
.cell_padding_top
.min(cell_pixel_height.saturating_sub(1) as u16);
//NOTE: review conflicting origin vs drawing going over image
let image_max_width = params.image_width.saturating_sub(params.source_origin_x);
let image_max_height = params.image_height.saturating_sub(params.source_origin_y);
let draw_width = params
.source_width
.unwrap_or(image_max_width)
.min(image_max_width);
let draw_height = params
.source_height
.unwrap_or(image_max_height)
.min(image_max_height);
// w=0/h=0, or an x=/y= origin at or past the edge of the image, leaves
// nothing to draw and divides by zero further down.
anyhow::ensure!(
draw_width > 0 && draw_height > 0,
"source rectangle is empty: origin {},{} extent {:?}x{:?} within a {}x{} image",
params.source_origin_x,
params.source_origin_y,
params.source_width,
params.source_height,
params.image_width,
params.image_height
);
let (fullcells_width, remainder_width_cell, x_delta_divisor) = params
.columns
.map(|cols| {
(
cols,
0,
(cols * cell_pixel_width) as u32 * params.image_width / draw_width,
)
})
.unwrap_or_else(|| {
(
draw_width as usize / cell_pixel_width,
draw_width as usize % cell_pixel_width,
params.image_width,
)
});
let (fullcells_height, remainder_height_cell, y_delta_divisor) = params
.rows
.map(|rows| {
(
rows,
0,
(rows * cell_pixel_height) as u32 * params.image_height / draw_height,
)
})
.unwrap_or_else(|| {
(
draw_height as usize / cell_pixel_height,
draw_height as usize % cell_pixel_height,
params.image_height,
)
});
let target_pixel_width = fullcells_width * cell_pixel_width + remainder_width_cell;
let target_pixel_height = fullcells_height * cell_pixel_height + remainder_height_cell;
let first_row = self.screen().visible_row_to_stable_row(self.cursor.y);
let mut ypos = NotNan::new(params.source_origin_y as f32 / params.image_height as f32)
.with_context(|| format!("computing ypos {params:#?}"))?;
let start_xpos = NotNan::new(params.source_origin_x as f32 / params.image_width as f32)
.context("computing xpos")?;
let cursor_x = self.cursor.x;
let width_in_cells = fullcells_width + one_or_zero::<usize>(remainder_width_cell > 0);
let height_in_cells = fullcells_height + one_or_zero::<usize>(remainder_height_cell > 0);
let height_in_cells = if params.do_not_move_cursor {
height_in_cells.min(self.screen().physical_rows - self.cursor.y as usize)
} else {
height_in_cells
};
log::debug!(
"image is {}x{} cells (cell is {}x{}), target pixel dims {}x{}, {:?}, (term is {}x{}@{}x{})",
width_in_cells,
height_in_cells,
cell_pixel_width,
cell_pixel_height,
target_pixel_width,
target_pixel_height,
params,
physical_cols,
physical_rows,
self.pixel_width,
self.pixel_height
);
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;
remain_y = remain_y.saturating_sub(cell_pixel_height);
let mut xpos = start_xpos;
let cursor_y = if params.do_not_move_cursor {
self.cursor.y + y as i64
} else {
self.cursor.y
};
log::debug!(
"setting cells for y={} x=[{}..{}]",
cursor_y,
cursor_x,
cursor_x + fullcells_width
);
let mut remain_x = target_pixel_width;
for x in 0..width_in_cells {
let padding_right = cell_pixel_width.saturating_sub(remain_x) as u16;
let x_delta = (remain_x.min(cell_pixel_width) as f32) / x_delta_divisor as f32;
remain_x = remain_x.saturating_sub(cell_pixel_width);
log::debug!(
"x_delta {} ({} px), y_delta {} ({} px), padding_right={}, padding_bottom={}",
x_delta,
x_delta * x_delta_divisor as f32,
y_delta,
y_delta * y_delta_divisor as f32,
padding_right,
padding_bottom
);
let mut cell = self
.screen_mut()
.get_cell(cursor_x + x, cursor_y)
.cloned()
.unwrap_or_else(Cell::blank);
let img = Box::new(ImageCell::with_z_index(
TextureCoordinate::new(xpos, ypos),
TextureCoordinate::new(xpos + x_delta, ypos + y_delta),
params.data.clone(),
params.z_index,
cell_padding_left,
cell_padding_top,
padding_right,
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 => {
cell.attrs_mut().set_image(img)
}
};
self.screen_mut()
.set_cell(cursor_x + x, cursor_y, &cell, seqno);
xpos += x_delta;
}
ypos += y_delta;
if !params.do_not_move_cursor && y < height_in_cells - 1 {
self.new_line(false);
}
}
// adjust cursor position if the drawn cells move beyond current cell
let x_padding_shift: i64 = one_or_zero(
draw_width as usize + cell_padding_left as usize > cell_pixel_width * width_in_cells,
);
let y_padding_shift: i64 = one_or_zero(
draw_height as usize + cell_padding_top as usize > cell_pixel_height * height_in_cells,
);
if !params.do_not_move_cursor {
// Sixel places the cursor under the left corner of the image,
// unless sixel_scrolls_right is enabled.
// iTerm places it after the bottom right corner.
let bottom_right = match params.style {
ImageAttachStyle::Kitty | ImageAttachStyle::Iterm => true,
ImageAttachStyle::Sixel => self.sixel_scrolls_right,
};
if bottom_right {
self.set_cursor_pos(
&Position::Relative(width_in_cells as i64 + x_padding_shift),
&Position::Relative(y_padding_shift),
);
}
}
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),
}),
})
}
/// cache recent images and avoid assigning a new id for repeated data!
pub(crate) fn raw_image_to_image_data(
&mut self,
data: ImageDataType,
) -> Result<Arc<ImageData>, termwiz::error::InternalError> {
let key = data.compute_hash();
// A nonce key means the payload was too large to content-hash: it
// can never match a cached entry, and inserting it would evict the
// dedup entries that do work — so streaming frames bypass the cache
// entirely.
if ImageDataType::is_nonce_key(&key) {
let data = data.swap_out()?;
return Ok(Arc::new(ImageData::with_data_and_hash(data, key)));
}
if let Some(item) = self.image_cache.get(&key).and_then(std::sync::Weak::upgrade) {
Ok(item)
} else {
// swap_out preserves the key byte-for-byte (Rgba8/AnimRgba8
// pass through; EncodedFile becomes an EncodedLease whose
// ContentId is the same SHA-256 of the same bytes), so the key
// computed for the cache lookup above is reused instead of
// hashing the full payload a second time.
let data = data.swap_out()?;
let image_data = Arc::new(ImageData::with_data_and_hash(data, key));
self.image_cache.put(key, Arc::downgrade(&image_data));
Ok(image_data)
}
}
}
/// The largest decoded image we are willing to hold, in bytes of RGBA.
pub(crate) const MAX_IMAGE_SIZE: u32 = 100_000_000;
pub(crate) fn check_image_dimensions(width: u32, height: u32) -> anyhow::Result<()> {
let size = width.saturating_mul(height).saturating_mul(4);
if size > MAX_IMAGE_SIZE {
anyhow::bail!(
"Ignoring image data for image with dimensions {}x{} \
because required RAM {} > max allowed {}",
width,
height,
SizeFormatter::new(size, DECIMAL),
SizeFormatter::new(MAX_IMAGE_SIZE, DECIMAL),
);
}
if size == 0 {
anyhow::bail!("Ignoring image with 0x0 dimensions");
}
Ok(())
}
#[derive(Debug)]
pub(crate) struct ImageInfo {
pub width: u32,
pub height: u32,
pub format: image::ImageFormat,
}
pub(crate) fn dimensions(data: &[u8]) -> anyhow::Result<ImageInfo> {
let reader = image::ImageReader::new(std::io::Cursor::new(data)).with_guessed_format()?;
let format = reader
.format()
.ok_or_else(|| anyhow::anyhow!("unknown format!?"))?;
let (width, height) = reader.into_dimensions()?;
Ok(ImageInfo {
width,
height,
format,
})
}
/// Returns `1` if `b` is true, else `0`,
fn one_or_zero<T: Zero + One>(b: bool) -> T {
if b {
T::one()
} else {
T::zero()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[derive(Debug)]
struct Cfg;
impl crate::TerminalConfiguration for Cfg {
fn color_palette(&self) -> crate::color::ColorPalette {
Default::default()
}
}
fn test_term() -> crate::Terminal {
crate::Terminal::new(
wezterm_term_size(),
Arc::new(Cfg),
"ThinkTerm",
"test",
Box::new(Vec::new()),
)
}
fn wezterm_term_size() -> crate::TerminalSize {
crate::TerminalSize {
rows: 24,
cols: 80,
pixel_width: 640,
pixel_height: 384,
dpi: 0,
}
}
fn frame(width: u32, height: u32, fill: u8) -> ImageDataType {
ImageDataType::new_single_frame(width, height, vec![fill; (width * height * 4) as usize])
}
#[test]
fn nonce_keyed_images_bypass_the_dedup_cache() {
let mut term = test_term();
// 640x512x4 = 1.25 MiB: over the content-hash threshold.
let a = term.raw_image_to_image_data(frame(640, 512, 0)).unwrap();
let b = term.raw_image_to_image_data(frame(640, 512, 0)).unwrap();
assert_ne!(
a.hash(),
b.hash(),
"streaming frames are identity-keyed, never content-deduped"
);
assert_eq!(
term.image_cache.len(),
0,
"nonce-keyed frames must not occupy dedup cache slots"
);
// Small images keep content dedup: same pixels, same Arc.
let s1 = term.raw_image_to_image_data(frame(4, 4, 1)).unwrap();
let s2 = term.raw_image_to_image_data(frame(4, 4, 1)).unwrap();
assert!(Arc::ptr_eq(&s1, &s2));
assert_eq!(term.image_cache.len(), 1);
}
#[test]
fn the_dedup_cache_keeps_no_pixels_alive() {
let mut term = test_term();
let first = term.raw_image_to_image_data(frame(4, 4, 7)).unwrap();
let key = first.hash();
let released = Arc::downgrade(&first);
drop(first);
assert!(released.upgrade().is_none(), "unused pixels are freed at once");
// The same content arriving later gets the same key, and dedups
// again while it is in use.
let again = term.raw_image_to_image_data(frame(4, 4, 7)).unwrap();
let repeat = term.raw_image_to_image_data(frame(4, 4, 7)).unwrap();
assert_eq!(again.hash(), key);
assert!(Arc::ptr_eq(&again, &repeat));
}
}