feat(terminal): track, draw, and assert on the window title

[Ayman Bagabas (aymanbagabas)]

A program announces what it is doing by setting the window title with OSC 0 or OSC 2, and shell-use threw that away. An agent driving a terminal could see what a program printed but not what it called itself — which is exactly where long-running tools report progress, and how a shell says which command is running.

The emulator now tracks the title, and it is reachable everywhere the other terminal properties already are.

Before / after

Same session, same command, screenshotted by the same screenshot --out:

before	after

The title is drawn centred in the title bar, clamped so it can never run under the window controls, and truncated with an ellipsis when it does not fit. No title leaves the bar exactly as it was, so every screenshot taken without one is byte-identical to before.

Surfaces

$ shell-use get title
{ "value": "vim: notes.md" }

$ shell-use expect title "vim"                  # exit 0
$ shell-use expect title "emacs"                # exit 1
$ shell-use wait title "build complete" --timeout 60000
$ shell-use expect title '^\w+: \S+\.md$' --regex
$ shell-use state | grep title
title: vim: notes.md

state.title, get title, expect title, and wait title, plus get_title / wait_title / expect_title in the Python and JS bindings. All four take --regex, --not, and --timeout where the sibling text commands do.

Widths are counted in columns, not characters

A terminal lays out by column. A CJK glyph is one char but two columns; a combining mark is one char but none. Counting characters drew the snapshot frame four columns out of true, and in the centred title bar it sized the title at half its real width so it spilled over the window controls at both ends.

╭─ 编辑：第三章笔记 ──────────────────╮      36 columns
│ok                                │      36 columns
╰──────────────────────────────────╯      36 columns

One shared truncate_to_columns in terminal/cell.rs serves both. This is the only reason unicode-width is now named in Cargo.toml: alacritty_terminal already pulls the identical 0.2.2, so declaring it added one line to Cargo.lock and zero new packages. Neither alacritty_terminal nor vte re-exports it, and hand-rolling East-Asian-width tables would be both reinvention and wrong on emoji and combining marks — the tests cover 🚀 build and e\u{301}clair for exactly that reason.

An empty title means reset

Programs clear the title by sending an empty one, so OSC 2; reports as None rather than as a title that happens to be blank. Keeping the two apart would only hand every caller the same special case to write.

Snapshots record the title only when asked

expect snapshot --include-title puts it in the frame's top border; the default leaves it out.

This is deliberate and worth a look during review. A stock Ubuntu .bashrc sets PS1='\[\e]0;\u@\h: \w\a\]…', so a normal shell writes its own title on every prompt. Recorded by default, that is:

╭─ ayman@Mac-91: /tmp/ttl ─────────╮

which pins the baseline to one username, hostname, and absolute path, and changes on cd while the screen stays identical. Off by default, a snapshot with no title is byte-identical to one taken before this PR, so every stored baseline keeps passing.

Free

The title stack (CSI 22 t push, CSI 23 t pop) works, because alacritty implements a pop as setting the title it popped and that routes through the same event. There is a test for it rather than any code.

Notes for review

• The title is tracked from Event::Title / Event::ResetTitle in the existing CaptureProxy rather than read back off the terminal, because alacritty exposes no way to read it: Term.title and Term.colors are both private fields, but only colors has a public getter (pub fn colors(&self) -> &Colors). There is no Term::title(), and set_title is a Handler setter. Alacritty's own frontend consumes the same events for the same reason.
• OSC 1 (icon name) is deliberately not supported: vte never dispatches it, and with a single drawn title there is nothing for a separate icon name to do.
• The title is markup-escaped in the SVG like any other text; it is whatever the program chose to send, and there is a test that a title of </text><script> cannot inject an element.
• Tests: 5 conformance cases (which run against every backend, so a future backend inherits them), 5 renderer tests, 4 snapshot tests, and 2 end-to-end tests through a real PTY.

[Ayman Bagabas (aymanbagabas)]

cpendery (@cpendery) ready for review when you have a moment. Branches off latest main, standalone (not part of the #84 → #85 → #86 stack).

GitHub will not let me request you as a reviewer directly (no push access here), hence the mention.

[cpendery (cpendery)]

nit: can we also update the bindings readmes with the new methods?

[Ayman Bagabas (aymanbagabas)]

Thanks cpendery (@cpendery) — all four addressed in 996c5f9, replies inline on each thread.

• Bindings READMEs — get_title/getTitle, wait_title/waitTitle, expect_title/expectTitle added to both API lists.
• UnicodeWidthStr — adopted; it differed on 4 of 10 cases I measured. Also surfaced a pre-existing bug where rows holding an emoji sequence already break the box, filed as Snapshot box misaligns for rows holding emoji sequences #92.
• Snapshot title — border keeps a shortened title, attributes now record the exact one so two long titles cannot collapse into one baseline. Note this nests colour shifts under colors, so a --include-colors baseline needs re-recording once.
• Lock race — fixed here rather than deferred; there were three sites, now sharing one helper.