Skip to content

perf(vt): stateful single-pass control-sequence framer - #76

Merged
bsommers merged 3 commits into
mainfrom
perf/vt-single-pass-scanner
Nov 11, 2026
Merged

bsommers merged 3 commits into
mainfrom
perf/vt-single-pass-scanner

Conversation

@bsommers

Copy link
Copy Markdown
Owner

What

Step 3c of the responsiveness work: one stateful, linear-time control-sequence framer (src/vt/framer.rs) in front of the VT engine, replacing the stateless per-read side scans in src/vt/scan.rs and src/vt/scan_osc_dcs.rs.

  • Withholds ESC/CSI/OSC until complete, keeps DCS/APC/SOS/PM away from the engine, and emits completed sequences as events with exact bodies.
  • Handlers that read engine state (CSI 6n, DECRQM, alt-screen switches, Sixel/Kitty placement, ESC # n) run after the engine has consumed their sequence.
  • Carry limits: CSI 256 bytes, OSC 1 MiB + 64, APC Kitty limit + 4 KiB, DCS 4 MiB. An over-limit sequence is dropped whole.

Bugs this fixes

  • Only OSC 52 survived a read boundary; split CSI/OSC/DCS/APC, ESC # n and OSC 1337;Canvas were lost.
  • A split Sixel or Kitty payload was printed on the grid.
  • A title ended at a later BEL instead of its own terminator.
  • CSI 6n reported the end-of-read cursor.
  • ESC[2J ESC[?38h in one read printed "J".

Measurements (release, before → after)

Case Before After
Unterminated OSC 52, 512 KiB in 64-byte reads 2.59 s 0.63 ms
16,000 unterminated OSC 0 in one read 591 ms 0.21 ms
4 MiB coloured text, 4 KiB reads 76.8 ms 79.8 ms

Normal throughput is unchanged within noise (single runs).

Verification

  • tests/vt_split_invariance.rs (15 tests): 38 corpus items at every 2-way split and byte-by-byte, 40 seeded generated streams under random chunking, 4 invalid-UTF-8/raw-C1 items. Compared: grid, scrollback, modes, events, query replies, OSC 52 output. Scanner steps are asserted equal to input bytes.
  • Against the old src/, the 14 tests that completed all fail.
  • Local gate after merging main: 178 of 180 pass; the two failures are phase68_69_surface_parity and swarm_wiring, which fail on main and are fixed by ci: six-cell OS/arch matrix, coverage gate, VT fuzz test, fix two stale swarm tests #71. GOLDENS OK 11.
  • Independent read-only review found no serious defect.

Behaviour changes

  • OSC 133 and DCS/APC now need a BEL/ST terminator to take effect.
  • The 4 MiB DCS limit is new.
  • During Tektronix capture the framer is bypassed, so in-band canvas OSCs are not recognised inside capture.
  • Canvas OSCs queue up to 1 MiB between pane drains; beyond that they are dropped.

Known gaps

  • A CAN/SUB inside an OSC drops it; vte would dispatch it.
  • A Tektronix-enter sequence inside a chunk classified as binary noise never starts capture.
  • A UTF-8 character split just before a Tektronix-enter sequence can reach the engine un-joined.
  • The binary-noise heuristic is still per read, so noise streams are not split-invariant.
  • One live-PTY test (spawned_child_pty_receives_bilterm_env) failed once under load during development and passed on every rerun; not proven to be a flake.
  • The ghostty-vt feature build and asciicast recording were not tested.

🤖 Generated with Claude Code

bsommers and others added 3 commits November 10, 2026 06:56
…e engine

The side scanner was stateless per PTY read: only OSC 52 survived a split, each
ESC handler searched to the end of the chunk (quadratic for many unterminated
OSCs), and the OSC 52 carry was re-scanned from scratch on every read
(quadratic for a long unterminated sequence).

src/vt/framer.rs is a byte state machine that follows the engine's own
boundaries (vte 0.13 table: ESC restarts, CAN/SUB cancel, C0 executes inside
ESC/CSI, no 8-bit C1 introducers). It withholds ESC/CSI/OSC until complete,
keeps DCS/APC/SOS/PM away from the engine, and reports completed sequences to
the handlers, which now receive exact bodies. Handlers that read engine state
run after the engine has consumed their sequence. The carry is bounded and an
over-long sequence is dropped whole.

Also fixed, each with a regression test in tests/vt_split_invariance.rs:
split CSI/OSC/DCS/APC lost; split Sixel/Kitty payload printed on the grid;
title ending at a later BEL; CSI 6n reporting the end-of-read cursor; split
ESC # n lost; CSI ?38h swallowing earlier sequences; split OSC 1337;Canvas.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@bsommers
bsommers merged commit dbb5674 into main Nov 11, 2026
29 of 30 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant