Performance

How fast caretline is, where the limits are, and how to go faster. The numbers come from release builds on an Apple-silicon Mac. caretline bench reproduces the engine and protocol numbers; the stress figures came from driving a live caretline FILE --listen editor over its socket from a script, and the animation figures from the Rust demo client (examples/scenes.rs).

Summary

The engine is not the bottleneck for anything a person or a terminal does. An edit costs 1–2 µs, a caret move 2–10 µs, a socket round trip about 13 µs and a typical frame about 0.13 ms. Document size barely matters: a million-line document edits and scrolls as fast as a hundred-line one. The practical ceilings are outside caretline: how fast the terminal paints and how fast a client can produce input.

Engine and protocol (caretline bench)

After 3,000 separate edits (each its own undo step):

Without the history, a state read costs what the text costs: 30× smaller and 20× faster on a 1,000-line document. On a 100,000-line document the text dominates; use render and events.

Typing runs (one insert_text per character, no clock) cost about 10 µs per character at any length: 16,000 characters take 0.15 s and 64,000 take 0.6 s. Before the wrap cache and undo-run caps this was quadratic (8.1 s for 16,000 characters).

Why keys "<down>" looked 3× slower than msgs

It wasn’t the key script. Parsing a script and running it through the keymap costs well under a microsecond, and keys and msgs with the same edit cost the same (1.5 µs in process). The bench compared a <down> at the bottom of the view with an edit at the top: every message ends by keeping the caret in view, which counts the rows between the top of the view and the caret, and that count looked each line up in the rope and walked its chars. Now plain text walks the lines with one iterator and places a line on one row from its byte length (no char but a tab is wider than its UTF-8 bytes), formatting only lines that might wrap. A motion at the bottom of the view went from 28 µs to 9 µs in process, and keys "<down>" over a socket is now the same as the msgs it becomes and about 1.5× a one-edit msgs at the top of the document (the remaining difference is the view walk the bottom of the view still needs). Keeping the caret in view at the very end of a document also walks up from the end, so the last screen of a document costs a few microseconds more than the middle.

Stress test (live editor, driven over the socket)

Animation

Six full-screen ASCII scenes (124×65 text cells, 8–11 KB per frame, highlighted cells drawn in the selection’s colour) were precomputed and pushed into a live editor with the frame op by the Rust demo client (cargo run --release -p caretline-app --example scenes), paced against absolute deadlines. The editor ran in a 124×66 pseudo-terminal whose output was read and thrown away, so these are the editor’s numbers, not a terminal’s paint rate. Each scene played 3 s at each rate.

Paced frames left their deadline 0 µs late at the median and under 0.1 ms at p99 (a few milliseconds on a busy machine). Before the frame op and repaint coalescing, the same scenes pushed as state.set from a script ran at 835–1,674 states per second, with a repaint after every one. Now a frame costs the editor 30–100 µs, repaints happen at most once per refresh, and the rest of the frames are applied (and traced) without being drawn.

How the live editor paints

• One repaint per refresh. The runtime applies input as it arrives and repaints at most once per slot of a fixed 1/max_fps grid (--max-fps, default 120; 0 repaints after every batch of input). A change in a slot that has already painted waits for the next slot’s start. A fixed grid, rather than a gap after each paint, keeps frames arriving at the display rate with a little jitter from colliding: 120 fps in gave 119.2 repaints a second.
• Only changed cells. ratatui keeps the last frame and writes only the cells that differ.
• Synchronized output. Each repaint is wrapped in DEC private mode 2026 (CSI ? 2026 h … CSI ? 2026 l) and written through one 64 KB buffer, so a terminal that supports it (WezTerm, kitty, Ghostty, iTerm2, foot, Alacritty) shows whole frames, never a torn one; others ignore the sequence.
• A frame clock, off by default. Msg::FrameClock { fps } (or --frame-clock FPS) asks the runtime for a Msg::Frame { now_ms } at that rate, on absolute deadlines. The request is view state (frame_clock in the state), so update stays pure and a replay sees the same frames. Plain editing sends none; with the clock at 120, an idle editor applied 120 frames a second.
• --stats prints the repaint count and mean repaint time on exit.

Where the limits really are

• The terminal’s frame rate. WezTerm paints at most max_fps frames per second, 60 by default; raise it with config.max_fps = 120. The display limits it too: a 60 Hz monitor can’t look smoother than 60 fps, a 120 Hz panel can show 120.
• Multiplexers. A multiplexer between the editor and the terminal re-reads and repaints the pane at its own pace, adding a cap and a copy. Measure in a plain terminal window.
• Clients. A paced client that sleeps 1/fps − work drifts and lands below its target. Schedule against absolute deadlines (start + k/fps), sleeping until about 1 ms before each and spinning the rest. Sleep in short steps (the demo uses at most 2 ms): macOS lets a timer fire late by a share of its length, and one long sleep overshot a 1 ms spin by 2–3 ms.
• Frame shape. Push frames with frame, not state.set: it parses no state and rebuilds nothing.

Outline derivation

After an edit the outline is derived again only around the change: the document keeps the outline it had and the chars that changed since, re-reads from the block before the change (outside any fence) until the text runs in step with the old outline again, and reuses the rest shifted. Block ids and attributes are read from the marks for every block. A change the reuse can’t follow (a block that started only by its mark loses it, a mark on a reused line that isn’t a block start) falls back to a whole derivation. Debug builds check every incremental result against the whole derivation. Document::take_touched gives a host the same changed range, so a host mirroring blocks re-reads only those.

Known gaps

Toward 120 fps and beyond

In the Elm model, animation is state that advances with time, and the pieces are now in place:

1. The runtime sends Msg::Frame { now_ms } while the view asks for a frame clock. Time stays an input, so animation stays pure and replayable.
2. update advances animation state from now_ms; view draws the frame for that time, so a dropped frame never causes stutter.
3. The runtime repaints once per refresh inside a synchronized update, writing only changed cells.

With that, a 120 Hz display at max_fps = 120 shows 120 fps: measured above, 119.2 repaints a second from 120 frames a second in. Rates above the display’s refresh are only useful headless (replay, tests, recording), where the editor applies 10,000–30,000 frames a second.

Sub-cell graphics

A terminal cell can show several “pixels” using Unicode block characters, with 24-bit foreground and background colours per cell:

notcurses, ratatui’s Canvas, chafa and timg use these. caretline’s frame has three roles today (text, selection, status); pixel graphics would be a separate canvas surface with true colour and a choice of these “blitters”, driven by the same frame clock.

Reproducing

$ caretline bench                       # engine and protocol (release build)
$ caretline notes.md --listen           # a live editor to drive from another process

Drive the live editor with caretline send or any JSON-lines client; see protocol.md.

This page on GitHub: docs/caretline/performance.md