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.

Skip content hashing and cache retention for streaming frames

RoversX866e3a8ee307
diff --git a/term/src/terminalstate/image.rs b/term/src/terminalstate/image.rs
index 04ac85e2..572cffcd 100644
--- a/term/src/terminalstate/image.rs
+++ b/term/src/terminalstate/image.rs
@@ -259,10 +259,18 @@ impl TerminalState {
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) {
Ok(Arc::clone(item))
} else {
- // swap_out preserves the hash byte-for-byte (Rgba8/AnimRgba8
+ // 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
@@ -322,3 +330,64 @@ fn one_or_zero<T: Zero + One>(b: bool) -> T {
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);
+ }
+}
diff --git a/term/src/terminalstate/kitty.rs b/term/src/terminalstate/kitty.rs
index a55a6bbe..eb0db83a 100644
--- a/term/src/terminalstate/kitty.rs
+++ b/term/src/terminalstate/kitty.rs
@@ -487,7 +487,7 @@ impl TerminalState {
drop(dest);
- *hash = ImageDataType::hash_bytes(data);
+ *hash = ImageDataType::content_key(data);
}
ImageDataType::AnimRgba8 {
width,
@@ -530,7 +530,7 @@ impl TerminalState {
)?;
drop(dest);
- hashes[target_frame - 1] = ImageDataType::hash_bytes(&frames[target_frame - 1]);
+ hashes[target_frame - 1] = ImageDataType::content_key(&frames[target_frame - 1]);
}
}
@@ -639,7 +639,7 @@ impl TerminalState {
blit(&mut anim_img, &img, x, y, frame.composition_mode)?;
drop(anim_img);
- *hash = ImageDataType::hash_bytes(data);
+ *hash = ImageDataType::content_key(data);
}
Some(2) | None => {
// Create a second frame
@@ -653,7 +653,7 @@ impl TerminalState {
blit(&mut new_frame, &img, x, y, frame.composition_mode)?;
let new_frame_data = new_frame.into_vec();
- let new_frame_hash = ImageDataType::hash_bytes(&new_frame_data);
+ let new_frame_hash = ImageDataType::content_key(&new_frame_data);
let frames = vec![std::mem::take(data), new_frame_data];
let durations = vec![Duration::from_millis(0), frame_gap];
@@ -701,7 +701,7 @@ impl TerminalState {
blit(&mut new_frame, &img, x, y, frame.composition_mode)?;
let new_frame_data = new_frame.into_vec();
- let new_frame_hash = ImageDataType::hash_bytes(&new_frame_data);
+ let new_frame_hash = ImageDataType::content_key(&new_frame_data);
frames.push(new_frame_data);
hashes.push(new_frame_hash);
@@ -732,7 +732,7 @@ impl TerminalState {
blit(&mut anim_img, &img, x, y, frame.composition_mode)?;
drop(anim_img);
- hashes[frame_no - 1] = ImageDataType::hash_bytes(&frames[frame_no - 1]);
+ hashes[frame_no - 1] = ImageDataType::content_key(&frames[frame_no - 1]);
}
}
}
diff --git a/wezterm-cell/src/image.rs b/wezterm-cell/src/image.rs
index 19be8933..b9a5805b 100644
--- a/wezterm-cell/src/image.rs
+++ b/wezterm-cell/src/image.rs
@@ -266,9 +266,34 @@ impl std::fmt::Debug for ImageDataType {
}
}
+/// Decoded pixel payloads larger than this skip content hashing: their
+/// identity key is a process-unique nonce instead of a SHA-256. Content
+/// dedup never hits for video-like kitty streams (every frame differs),
+/// while hashing tens of MB per frame dominated the pty read thread; small
+/// images keep real content hashes so repeated logos still dedup for free.
+pub const CONTENT_HASH_MAX: usize = 1024 * 1024;
+
+/// First 8 bytes of every nonce key, so debug checks and the dedup cache
+/// can tell identity-only keys apart from content hashes. A real SHA-256
+/// starting with these exact bytes is a ~2^-64 coincidence.
+const NONCE_KEY_MARKER: [u8; 8] = [0x54, 0x54, 0x4e, 0x43, 0x9d, 0x1b, 0x7a, 0xe4];
+
impl ImageDataType {
pub fn new_single_frame(width: u32, height: u32, data: Vec<u8>) -> Self {
+ let hash = Self::content_key(&data);
+ Self::new_single_frame_with_hash(width, height, data, hash)
+ }
+
+ /// Like `new_single_frame` but always content-hashed, for callers that
+ /// rely on "equal pixels => equal key" across reconstructions (e.g. the
+ /// background layer reload reusing textures by hash) and only construct
+ /// occasionally.
+ pub fn new_single_frame_content_hashed(width: u32, height: u32, data: Vec<u8>) -> Self {
let hash = Self::hash_bytes(&data);
+ Self::new_single_frame_with_hash(width, height, data, hash)
+ }
+
+ fn new_single_frame_with_hash(width: u32, height: u32, data: Vec<u8>, hash: [u8; 32]) -> Self {
assert_eq!(
width * height * 4,
data.len() as u32,
@@ -285,6 +310,64 @@ impl ImageDataType {
}
}
+ /// Identity key for an image payload: a real content hash for small
+ /// payloads, a process-unique nonce for large ones. The key is opaque
+ /// everywhere it travels — mux peers, caches and the GPU only store and
+ /// compare it — so the two kinds coexist freely.
+ pub fn content_key(bytes: &[u8]) -> [u8; 32] {
+ if bytes.len() > CONTENT_HASH_MAX {
+ Self::nonce_key()
+ } else {
+ Self::hash_bytes(bytes)
+ }
+ }
+
+ /// A key that is unique rather than content-derived:
+ /// 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] {
+ use std::sync::atomic::{AtomicU64, Ordering};
+ use std::sync::OnceLock;
+ static SALT: OnceLock<[u8; 16]> = OnceLock::new();
+ static COUNTER: AtomicU64 = AtomicU64::new(0);
+ let salt = SALT.get_or_init(|| {
+ // wasm32-unknown-unknown has no process id and SystemTime::now()
+ // traps there. A wasm client is single-instance, so it needs no
+ // cross-process entropy of its own, and colliding with a peer's
+ // randomly-salted nonces would require matching all 16 salt
+ // bytes AND the counter.
+ #[cfg(target_arch = "wasm32")]
+ {
+ [
+ 0x9c, 0x3f, 0x51, 0xe8, 0x27, 0xb4, 0x6a, 0xd1, 0x08, 0xf5, 0x72, 0xc9, 0x3e,
+ 0x84, 0x1b, 0x67,
+ ]
+ }
+ #[cfg(not(target_arch = "wasm32"))]
+ {
+ let mut seed = Vec::new();
+ seed.extend_from_slice(&std::process::id().to_ne_bytes());
+ if let Ok(t) = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH) {
+ seed.extend_from_slice(&t.as_nanos().to_ne_bytes());
+ }
+ Self::hash_bytes(&seed)[..16]
+ .try_into()
+ .expect("16-byte slice")
+ }
+ });
+ let n = COUNTER.fetch_add(1, Ordering::Relaxed);
+ let mut key = [0u8; 32];
+ key[..8].copy_from_slice(&NONCE_KEY_MARKER);
+ key[8..24].copy_from_slice(salt);
+ key[24..].copy_from_slice(&n.to_be_bytes());
+ key
+ }
+
+ pub fn is_nonce_key(key: &[u8; 32]) -> bool {
+ key[..8] == NONCE_KEY_MARKER
+ }
+
/// Black pixels
pub fn placeholder() -> Self {
let mut data = vec![];
@@ -309,25 +392,34 @@ impl ImageDataType {
ImageDataType::EncodedFile(data) => hasher.update(data),
ImageDataType::EncodedLease(lease) => return lease.content_id().as_hash_bytes(),
ImageDataType::Rgba8 { data, hash, .. } => {
- // The stored hash IS hash_bytes(data): the only constructor
- // computes it and every in-place pixel edit refreshes it
- // (see terminalstate/kitty.rs), so full-frame payloads are
- // not re-hashed here — at video-like kitty frame rates that
- // second SHA-256 dominated the pty read thread. The debug
- // assert turns any future forgotten refresh into a loud
- // test failure instead of a stale-image glitch.
- debug_assert_eq!(
- *hash,
- Self::hash_bytes(data),
- "Rgba8 hash field is stale; a pixel mutation forgot to refresh it"
- );
+ // 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
+ // re-hashed here — at video-like kitty frame rates that
+ // second SHA-256 dominated the pty read thread. For
+ // content-hashed (small) payloads the debug assert turns any
+ // 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"
+ );
+ }
return *hash;
}
ImageDataType::AnimRgba8 {
- frames, durations, ..
+ hashes, durations, ..
} => {
- for data in frames {
- hasher.update(data);
+ // 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
+ // frame is microseconds where the old full re-hash was the
+ // remaining full-payload SHA-256 on the pty thread.
+ for hash in hashes {
+ hasher.update(hash);
}
for d in durations {
let d = d.as_secs_f32();
@@ -483,7 +575,7 @@ impl ImageDataType {
width = w;
height = h;
let data = image.into_vec();
- hashes.push(Self::hash_bytes(&data));
+ hashes.push(Self::content_key(&data));
frames.push(data);
}
Self::AnimRgba8 {
@@ -502,7 +594,7 @@ impl ImageDataType {
let image = image.to_rgba8();
let (width, height) = image.dimensions();
let data = image.into_vec();
- let hash = Self::hash_bytes(&data);
+ let hash = Self::content_key(&data);
Self::Rgba8 {
width,
height,
@@ -604,3 +696,51 @@ impl ImageData {
self.hash
}
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn small_payloads_get_stable_content_hashes() {
+ let data = vec![7u8; 64];
+ let a = ImageDataType::content_key(&data);
+ let b = ImageDataType::content_key(&data);
+ assert_eq!(a, b);
+ assert!(!ImageDataType::is_nonce_key(&a));
+ assert_eq!(a, ImageDataType::hash_bytes(&data));
+ }
+
+ #[test]
+ fn large_payloads_get_unique_nonce_keys() {
+ let data = vec![7u8; CONTENT_HASH_MAX + 1];
+ let a = ImageDataType::content_key(&data);
+ let b = ImageDataType::content_key(&data);
+ assert_ne!(a, b, "identical large payloads must get distinct keys");
+ assert!(ImageDataType::is_nonce_key(&a));
+ assert!(ImageDataType::is_nonce_key(&b));
+ }
+
+ #[test]
+ fn anim_identity_folds_frame_keys_without_reading_pixels() {
+ let mk = |frames: Vec<Vec<u8>>, hashes: Vec<[u8; 32]>| ImageDataType::AnimRgba8 {
+ width: 1,
+ height: 1,
+ durations: vec![Duration::from_millis(10); frames.len()],
+ frames,
+ hashes,
+ };
+ let hashes = vec![[1u8; 32], [2u8; 32]];
+ let a = mk(vec![vec![0, 0, 0, 0xff]; 2], hashes.clone());
+ // Different pixels but identical per-frame keys: the identity must
+ // not change, which proves frames are no longer re-hashed.
+ let b = mk(vec![vec![0xff, 0, 0, 0xff]; 2], hashes.clone());
+ assert_eq!(a.compute_hash(), b.compute_hash());
+ // Different per-frame keys must change the identity.
+ let c = mk(
+ vec![vec![0, 0, 0, 0xff]; 2],
+ vec![[1u8; 32], [3u8; 32]],
+ );
+ assert_ne!(a.compute_hash(), c.compute_hash());
+ }
+}
diff --git a/wezterm-gui/src/glyphcache.rs b/wezterm-gui/src/glyphcache.rs
index 011b74c1..d241f960 100644
--- a/wezterm-gui/src/glyphcache.rs
+++ b/wezterm-gui/src/glyphcache.rs
@@ -1156,6 +1156,32 @@ impl GlyphCache {
) -> anyhow::Result<(Sprite, Option<Instant>, LoadState)> {
let hash = image_data.hash();
+ // A nonce key marks a one-shot streaming frame (video-like kitty
+ // content): it can never be requested again under the same key, so
+ // caching the DecodedImage would only pin the multi-MB frame long
+ // after it scrolled away — 256 retained frames is gigabytes. Loading
+ // is a cheap wrap for decoded pixels, and the sprite in frame_cache
+ // still prevents re-uploading the frame to the GPU between paints.
+ //
+ // Only single-frame Rgba8 gets the bypass: a large image later
+ // promoted to AnimRgba8 keeps its original nonce as the outer key,
+ // and recreating the DecodedImage every paint would reset the
+ // animation clock so it never advances. Animations are single
+ // persistent objects, so caching them cannot accumulate.
+ if ImageDataType::is_nonce_key(&hash)
+ && matches!(&*image_data.data(), ImageDataType::Rgba8 { .. })
+ {
+ let decoded = DecodedImage::load(image_data);
+ return Self::cached_image_impl(
+ &mut self.frame_cache,
+ &mut self.atlas,
+ &decoded,
+ padding,
+ self.min_frame_duration,
+ allow_image,
+ );
+ }
+
if let Some(decoded) = self.image_cache.get(&hash) {
Self::cached_image_impl(
&mut self.frame_cache,
diff --git a/wezterm-gui/src/termwindow/background.rs b/wezterm-gui/src/termwindow/background.rs
index 8d38ca7c..37890869 100644
--- a/wezterm-gui/src/termwindow/background.rs
+++ b/wezterm-gui/src/termwindow/background.rs
@@ -141,9 +141,12 @@ impl CachedGradient {
}
let data = imgbuf.into_vec();
- let image = Arc::new(ImageData::with_data(ImageDataType::new_single_frame(
- width, height, data,
- )));
+ // Content-hashed on purpose: reload_background_image reuses textures
+ // and animation state by hash equality across config reloads, and a
+ // window-sized gradient exceeds the nonce threshold.
+ let image = Arc::new(ImageData::with_data(
+ ImageDataType::new_single_frame_content_hashed(width, height, data),
+ ));
Ok(image)
}
@@ -323,9 +326,12 @@ fn load_background_layer(
*pixel = src_pixel;
}
let data = imgbuf.into_vec();
- Arc::new(ImageData::with_data(ImageDataType::new_single_frame(
- size, size, data,
- )))
+ // Content-hashed like the gradient above: reload_background_image
+ // reuses layers by hash equality, and the generated square can
+ // exceed the nonce threshold on large windows.
+ Arc::new(ImageData::with_data(
+ ImageDataType::new_single_frame_content_hashed(size, size, data),
+ ))
}
BackgroundSource::File(source) => CachedImage::load(&source.path, source.speed)?,
};