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.

perf(term): reuse cells for CSI erase and repeat operations

RoversX25c76fc8b4d6
diff --git a/docs/thinkterm/parser-throughput-followup-results.json b/docs/thinkterm/parser-throughput-followup-results.json
new file mode 100644
index 00000000..43e20443
--- /dev/null
+++ b/docs/thinkterm/parser-throughput-followup-results.json
@@ -0,0 +1,176 @@
+{
+ "baseline_commit": "e791e310a72915ed7f9a03208437ec34166263cb",
+ "candidate_code_patch_sha256": "098e81d761c98d597d4813e10c4d9dd6ab3bb6fecf8c534124ee39a4313238a7",
+ "binary_sha256": {
+ "baseline": "654e2917ad8e23951c7bacd0b66ea0bd23f9f203d7f78393f2fdb465aff05ac2",
+ "candidate": "bd654e038fe43f2d55d834bbc56154316eca7cc81f913ba36d3a486339703936"
+ },
+ "platform": "macOS arm64",
+ "date": "2026-09-23",
+ "kitten_version": "0.49.0",
+ "size": [
+ 120,
+ 32
+ ],
+ "scrollback_lines": 3500,
+ "repetitions": 100,
+ "renderer": "none (isolated PTY/mux server)",
+ "order": [
+ "baseline",
+ "candidate",
+ "candidate",
+ "baseline",
+ "baseline",
+ "candidate"
+ ],
+ "runs": {
+ "baseline": [
+ {
+ "rates_mib_per_second": {
+ "Only ASCII chars": 43.1,
+ "Unicode chars": 47.6,
+ "Unique multi-codepoint Unicode cells": 69.1,
+ "CSI codes with few chars": 20.2,
+ "Long escape codes": 200.0,
+ "Images": 261.9
+ },
+ "peak_rss_bytes": 459210752,
+ "elapsed_seconds": 22.483098708005855
+ },
+ {
+ "rates_mib_per_second": {
+ "Only ASCII chars": 43.2,
+ "Unicode chars": 47.3,
+ "Unique multi-codepoint Unicode cells": 69.0,
+ "CSI codes with few chars": 20.2,
+ "Long escape codes": 203.5,
+ "Images": 241.0
+ },
+ "peak_rss_bytes": 463077376,
+ "elapsed_seconds": 22.542637292004656
+ },
+ {
+ "rates_mib_per_second": {
+ "Only ASCII chars": 43.2,
+ "Unicode chars": 47.6,
+ "Unique multi-codepoint Unicode cells": 69.2,
+ "CSI codes with few chars": 20.2,
+ "Long escape codes": 203.2,
+ "Images": 239.2
+ },
+ "peak_rss_bytes": 459505664,
+ "elapsed_seconds": 22.539257084019482
+ }
+ ],
+ "candidate": [
+ {
+ "rates_mib_per_second": {
+ "Only ASCII chars": 69.3,
+ "Unicode chars": 47.1,
+ "Unique multi-codepoint Unicode cells": 68.5,
+ "CSI codes with few chars": 25.0,
+ "Long escape codes": 210.0,
+ "Images": 229.5
+ },
+ "peak_rss_bytes": 463405056,
+ "elapsed_seconds": 19.874922916002106
+ },
+ {
+ "rates_mib_per_second": {
+ "Only ASCII chars": 69.3,
+ "Unicode chars": 47.2,
+ "Unique multi-codepoint Unicode cells": 68.7,
+ "CSI codes with few chars": 25.0,
+ "Long escape codes": 209.3,
+ "Images": 244.1
+ },
+ "peak_rss_bytes": 461225984,
+ "elapsed_seconds": 19.736880499986
+ },
+ {
+ "rates_mib_per_second": {
+ "Only ASCII chars": 70.0,
+ "Unicode chars": 47.2,
+ "Unique multi-codepoint Unicode cells": 68.7,
+ "CSI codes with few chars": 25.2,
+ "Long escape codes": 203.0,
+ "Images": 239.7
+ },
+ "peak_rss_bytes": 461176832,
+ "elapsed_seconds": 19.82980612499523
+ }
+ ]
+ },
+ "median_rates_mib_per_second": {
+ "baseline": {
+ "Only ASCII chars": 43.2,
+ "Unicode chars": 47.6,
+ "Unique multi-codepoint Unicode cells": 69.1,
+ "CSI codes with few chars": 20.2,
+ "Long escape codes": 203.2,
+ "Images": 241.0
+ },
+ "candidate": {
+ "Only ASCII chars": 69.3,
+ "Unicode chars": 47.2,
+ "Unique multi-codepoint Unicode cells": 68.7,
+ "CSI codes with few chars": 25.0,
+ "Long escape codes": 209.3,
+ "Images": 239.7
+ }
+ },
+ "allocation_probe": {
+ "operation": "fill 100000 already styled RGB cells four times",
+ "baseline_allocations": 400000,
+ "candidate_allocations": 4,
+ "construction_live_bytes_unchanged": true,
+ "serialized_attribute_fixture_byte_identical": true
+ },
+ "rejected_cow_prototype": {
+ "reason": "Each independent extended attribute allocation gains a 16-byte reference-count header",
+ "independent_rgb_attribute_count": 100000,
+ "baseline_requested_live_bytes": 11200096,
+ "prototype_requested_live_bytes": 12800112
+ },
+ "validation": {
+ "vtparse_tests": 26,
+ "escape_parser_tests": 82,
+ "cell_tests": 14,
+ "surface_tests": 48,
+ "terminal_tests": 129,
+ "mux_tests": 202,
+ "gui_tests": 909,
+ "existing_ignored_gui_tests": 1,
+ "release_gui_and_mux_build": true,
+ "wasm_core_check": true,
+ "integration_note": "GUI and mux suites passed during integration; core suites reran after the final UTF-8 and inlining adjustments.",
+ "foreground_gui_qa": false,
+ "native_windows_qa": false,
+ "long_duration_leak_test": false
+ },
+ "notes": [
+ "Kitten randomizes input, so paired workloads are comparable but not byte-identical.",
+ "No build or tests ran during measured benchmark pairs.",
+ "No unexpected parser or image-decoding errors appeared in benchmark logs.",
+ "Expected sandbox SSH-agent and existing-daemon handoff refusal messages occurred at startup.",
+ "Peak RSS includes the mux process; this is not a GUI/GPU memory measurement."
+ ],
+ "scrollback_check": {
+ "baseline": {
+ "rates_mib_per_second": {
+ "Only ASCII chars": 43.3,
+ "CSI codes with few chars": 20.3
+ },
+ "peak_rss_bytes": 451461120,
+ "repetitions": 200
+ },
+ "candidate": {
+ "rates_mib_per_second": {
+ "Only ASCII chars": 69.7,
+ "CSI codes with few chars": 25.2
+ },
+ "peak_rss_bytes": 451674112,
+ "repetitions": 200
+ }
+ }
+}
diff --git a/docs/thinkterm/parser-throughput-followup.md b/docs/thinkterm/parser-throughput-followup.md
new file mode 100644
index 00000000..49c81500
--- /dev/null
+++ b/docs/thinkterm/parser-throughput-followup.md
@@ -0,0 +1,113 @@
+# Parser throughput follow-up
+
+This follow-up starts at `e791e31`, after the earlier screen-write batching and
+Kitty Base64 compatibility fixes. It evaluates the parser boundary, CSI row
+updates, and repeated extended-attribute allocation separately from rendering.
+
+## Implementation
+
+`VTActor::print_ascii` has a scalar default. The terminal and mux opt into
+`Parser::parse_print_runs`; existing `parse`, `parse_first`, and
+`parse_first_as_vec` keep their action granularity. Adjacent `Print` and
+`PrintString` actions coalesce before grapheme segmentation, including an ASCII
+base followed by a Unicode combining sequence. Runs are owned strings, so they
+cannot retain a PTY input buffer. UTF-8, control codes, and character-set handling
+keep their original state-machine semantics.
+
+OSC, APC, and DCS string payloads finish the current input chunk in the original
+byte loop. This avoids adding a run-detection check to every image/payload byte.
+Text following a terminator in that same chunk uses ordinary print actions;
+batching resumes on a later input chunk. The payload limits and decoding logic
+are unchanged.
+
+Default-blank tail erasure can truncate a vector-backed row after resolving the
+left wide-character boundary and invalidating implicit links and semantic zones.
+All-blank vector rows keep their historical length; compact rows, styled blanks,
+and unsupported boundaries keep their existing behavior. Bulk erasure uses slice
+fill. REP can reuse destination cells when there are no image attachments, and
+keeps the previous image-placement merge path otherwise.
+
+`Cell::clone_from` and `CellAttributes::clone_from` reuse an existing extended
+attribute allocation. Attributes remain independently owned, with the same
+16-byte attribute and 24-byte cell layouts on this 64-bit target. No interning
+table, new persistent cache, unsafe production code, or serialization change is
+introduced.
+
+## Why shared attributes were not retained
+
+An `Arc<FatAttributes>` copy-on-write prototype passed isolation tests and helped
+repeated styles. However, 100,000 independently allocated RGB attributes increased
+from 11,200,096 to 12,800,112 requested live heap bytes. The 16-byte reference-count
+header is a real cost for each independent allocation, including decoded styles
+that have no sharing opportunity. The final implementation keeps `Box` ownership
+and instead reuses allocations during overwrites.
+
+An isolated counting-allocator probe overwrote 100,000 already styled RGB cells
+four times using slice fill. Allocations fell from 400,000 to 4. The ordinary
+attribute construction/clone cases retained the baseline allocation counts and
+requested live bytes; all allocations in each construction case were released
+after dropping the values. This is an allocation microbenchmark, not a
+long-running process leak test. A serialized attribute fixture was byte-identical
+to the baseline and round-tripped successfully.
+
+## PTY/mux measurements
+
+Measured on macOS arm64 with kitten 0.49.0, release builds, a 120x32 PTY, and
+3,500 scrollback lines. Three pairs used 100 repetitions per workload, in order
+baseline/candidate, candidate/baseline, baseline/candidate. Each mux server used
+a private temporary socket and a sandbox preventing writes to existing settings
+and sessions. Builds and tests did not run during the measured pairs. Kitten
+randomizes input, so these are comparable workloads, not byte-identical replays.
+
+Median throughput in MiB/s (kitten labels the rates MB/s):
+
+| Workload | Baseline | Candidate | Change |
+| --- | ---: | ---: | ---: |
+| ASCII | 43.2 | 69.3 | +60.4% |
+| Unicode | 47.6 | 47.2 | -0.8% |
+| Unique multi-codepoint cells | 69.1 | 68.7 | -0.6% |
+| CSI with few characters | 20.2 | 25.0 | +23.8% |
+| Long escape codes | 203.2 | 209.3 | +3.0% |
+| Images | 241.0 | 239.7 | -0.5% |
+
+Median peak mux RSS was 438.2 MiB versus 439.9 MiB (+0.4%); the individual ranges
+overlapped. An additional 200-repetition, scrollback-enabled pair measured
+43.3/69.7 MiB/s ASCII and 20.3/25.2 MiB/s CSI, with peak RSS 430.5/430.8 MiB
+(baseline/candidate). These are bounded observations, not a guarantee of equal
+memory use for every workload.
+
+The [individual runs and binary hashes](parser-throughput-followup-results.json)
+include the full results. In particular, Images varied from 239.2 to 261.9 MiB/s
+in the baseline and 229.5 to 244.1 MiB/s in the candidate; the median alone does
+not establish a small image speed change. There were no unexpected parser or
+image-decoding errors. Expected sandbox SSH-agent and existing-daemon handoff
+refusal messages occurred at startup. Successful decoding here does not test
+foreground image rendering: no GUI client was attached.
+
+To reproduce the workloads inside each binary's own isolated PTY:
+
+```sh
+kitten __benchmark__ --repetitions 100
+kitten __benchmark__ --repetitions 200 --with-scrollback ascii csi
+```
+
+## Validation boundaries
+
+Differential tests cover fragmented and invalid UTF-8, control/parser states,
+Unicode combining sequences, title accumulation, DEC/UK character sets, custom
+widths, wide-cell boundaries, semantic zones, hyperlinks, image placements,
+compact storage, snapshots, wrapping, scrolling, and the existing oversized REP
+cap. Clone tests check allocation reuse and independently mutable values.
+
+The native parser tests need shared-memory access; denying `shm_open` in a test
+sandbox prevents the existing cleanup test from running. The integration feature
+set enables serialization through `wezterm-term/use_serde`.
+
+Integration suites passed 202 mux tests and 909 GUI tests (one existing ignored
+test). After the final UTF-8 and clone-inlining adjustments, the affected suites
+passed again: 26 VT parser, 82 escape parser, 14 cell, 48 surface, and 129 terminal
+tests. Release GUI/mux builds and the `wasm32-unknown-unknown` core check passed.
+
+Foreground GUI visual QA, input latency under load, native Windows execution,
+and long-duration memory behavior remain unmeasured. No installed application
+was replaced or restarted.
diff --git a/docs/thinkterm/parser-throughput.md b/docs/thinkterm/parser-throughput.md
index e582ce0c..0fefe87e 100644
--- a/docs/thinkterm/parser-throughput.md
+++ b/docs/thinkterm/parser-throughput.md
@@ -1,5 +1,9 @@
# Parser throughput: ASCII and CSI batching
+The subsequent [parser and allocation follow-up](parser-throughput-followup.md)
+measures the next optimizations against a newer baseline. The results below
+describe the earlier screen-write batching change.
+
Measured on 2026-09-23 with an Apple M1 Pro (16 GiB RAM), macOS, and kitten
0.49.0. The baseline is commit `06bdaa4`, before the parser optimizations. Both
binaries were built locally with the same Cargo release profile. The measured
diff --git a/wezterm-surface/src/line/line.rs b/wezterm-surface/src/line/line.rs
index 62f765ca..d3fc394d 100644
--- a/wezterm-surface/src/line/line.rs
+++ b/wezterm-surface/src/line/line.rs
@@ -1045,12 +1045,36 @@ impl Line {
}
}
- pub fn fill_range(&mut self, cols: Range<usize>, cell: &Cell, seqno: SequenceNo) {
+ pub fn fill_range(&mut self, mut cols: Range<usize>, cell: &Cell, seqno: SequenceNo) {
if self.len() == 0 && *cell == Cell::blank() {
// We would be filling it with blanks only to prune
// them all away again before we return; NOP
return;
}
+ if !cols.is_empty()
+ && cols.start < self.len()
+ && cols.end >= self.len()
+ && *cell == Cell::blank()
+ && matches!(&self.cells, CellStorage::V(_))
+ {
+ // Resolve a wide grapheme crossing the start and invalidate links
+ // before deciding which prefix can remain. The erased tail will
+ // be pruned, so don't first construct a blank Cell for every column.
+ let start = cols.start;
+ self.set_cell_impl(start, cell.clone(), true, seqno);
+ if let CellStorage::V(cells) = &mut self.cells {
+ if let Some(last) = cells[..start]
+ .iter()
+ .rposition(|c| c.str() != " " || c.attrs() != cell.attrs())
+ {
+ cells.truncate(last + 1);
+ return;
+ }
+ }
+ // Vec storage historically retains the length of all-blank lines.
+ // Preserve that behavior, including styled wide-cell padding.
+ cols.start += 1;
+ }
self.set_cell_range_impl(cols, cell, true, seqno);
self.prune_trailing_blanks(seqno);
}
@@ -1084,8 +1108,12 @@ impl Line {
// Every preceding cell in this run has just been written with
// width one, so subsequent writes cannot overlap a wide cell
// on their left. Keep VecStorage's image-placement semantics.
- for x in cols {
- cells.set_cell(x, cell.clone(), clear_image_placements);
+ if clear_image_placements {
+ cells[cols].fill(cell.clone());
+ } else {
+ for x in cols {
+ cells.set_cell_from(x, cell);
+ }
}
return;
}
diff --git a/wezterm-surface/src/line/test.rs b/wezterm-surface/src/line/test.rs
index adba5340..09ea506a 100644
--- a/wezterm-surface/src/line/test.rs
+++ b/wezterm-surface/src/line/test.rs
@@ -111,6 +111,17 @@ fn appending_ranges_keeps_compact_storage() {
assert!(empty.is_compressed_for_scrollback());
}
+#[test]
+fn erasing_a_default_tail_does_not_materialize_out_of_range_blanks() {
+ let mut line: Line = "prefix tail".into();
+ line.coerce_vec_storage();
+ let mut expected = line.clone();
+ scalar_range(&mut expected, 6..100, &Cell::blank(), true);
+ line.fill_range(6..usize::MAX, &Cell::blank(), 42);
+ assert_eq!(line, expected);
+ assert_eq!(line.as_str(), "prefix");
+}
+
#[cfg(feature = "use_image")]
#[test]
fn cell_ranges_preserve_or_clear_image_placements_like_scalar_writes() {
diff --git a/wezterm-surface/src/line/vecstorage.rs b/wezterm-surface/src/line/vecstorage.rs
index beb357e8..f2cfcdc1 100644
--- a/wezterm-surface/src/line/vecstorage.rs
+++ b/wezterm-surface/src/line/vecstorage.rs
@@ -34,6 +34,17 @@ impl VecStorage {
self.cells[idx] = cell;
}
+ /// Repeated writes can reuse a cell's extended-attribute allocation. Keep
+ /// the existing merge path whenever the destination has image attachments.
+ pub(crate) fn set_cell_from(&mut self, idx: usize, cell: &Cell) {
+ #[cfg(feature = "use_image")]
+ if self.cells[idx].attrs().has_images() {
+ self.set_cell(idx, cell.clone(), false);
+ return;
+ }
+ self.cells[idx].clone_from(cell);
+ }
+
pub(crate) fn scan_and_create_hyperlinks(
&mut self,
line: &str,