Cache shaped lines so unchanged rows skip CoreText typesetting

[Nico-Sanchez]

Profiling a terminal hosting an AI-agent TUI (Claude Code) put essentially all of the app's draw time inside CTLineCreateWithAttributedString: drawTerminalContents rebuilds an attributed string per visible row and runs CoreText's typesetter + OpenType shaping over it on every draw — and a terminal redraws unchanged content constantly (partial-rect exposures call it dozens of times per pass, cursor blinks, the 60 Hz tick after a single-row change, and every full repaint of an alt-screen TUI that rewrote one line).

In a 20 s sample of a real workload, 774 of 778 drawTerminalContents stacks were inside CTLineCreateWithAttributedString.

What this PR does

Shapes each line once and caches the result (ViewLineInfo + CTLines + runs). The key carries everything the shaped output depends on:

• the row and the BufferLine's identity,
• a content digest of the line (cells' rune/width/attribute + isWrapped, renderMode, image count),
• the column count and the row's selection range,
• an epoch bumped on font changes (resetCaches), palette changes (colorsChanged), and hovered-link highlight changes.

Content-keying (3rd commit) matters more than it looks: BufferLine.generation counts writes, not changes, so a TUI that repaints identical text every frame invalidates everything — measured 2.5% hit rate on a 10 Hz identical repaint. Keyed on content it's 100%, while genuinely changing content (top) correctly misses and scrolling output sits at ~95% (hits on exposure/blink redraws of already-shaped rows). The digest is cached on the line and invalidated by the same bump() that advances generation, so it costs one pass over the cells — orders of magnitude less than re-shaping.

The cache is capped (2048 entries) and flushed wholesale past the cap; a flush costs one reshape of the visible rows.

Measured

• draw path: drawTerminalContents fell from 778 to 68 samples (−91%) in the same 20 s profile
• whole process on a 9-pane agent workload: 247 → 88 ms/s
• pure-scroll synthetic benchmark: ~7% (that workload was already shape-once-per-line; the win is in-place repaints)

The 2nd commit adds opt-in counters (SWIFTTERM_SHAPED_CACHE_STATS=1 → hits/misses/flushes to stderr every 5 s; a single static bool test per row when unset) — that's how the numbers above were measured, and reviewers can check their own workloads with it.

Notes

• macOS + iOS builds; the full test suite passes (73 tests).
• The stored properties live on the platform view classes (extensions can't hold storage); the cache logic is shared in AppleTerminalView.swift.
• Happy to split the stats commit out, rename things, or rework the eviction policy to LRU if you'd prefer — the wholesale flush was chosen for simplicity and hasn't been observable in practice.

[migueldeicaza]

Oh that is a good idea - nice find. Let me see where the cache is, need to think about it.

[migueldeicaza]

I am afraid that the idea of the cache is a good one, but like they say "There are 2 hard problems in computer science: cache invalidation, naming things, and off-by-1 errors". And this change did not survive :-)

Few issues:

• iOS link hover does not invalidate the cache.

• The content hash omits the cell payload. Link rendering uses cell.hasPayload, but the digest only includes code, width, and attributes.

• Runtime rendering options can reuse stale ViewLineInfo as the epoch bumping is not consistent.

• Sadly, image count is not a sufficient image identity. ShapedLine retains the exact image array, but contentHash includes only images?.count. Replacing an image or placement with another image while the count stays constant reuses the old array.