docs: N-3 tab-bar label design spec (and the defect measuring it turned up)

[mizu-jun]

Docs only — no code. Requesting sign-off on the two open questions in §7 before any implementation PR.

Why the spec exists

P4b excluded tab-bar labels with one line — "requires rebuilding tab width and hit computation off measured text" — and P4e repeated it. Measuring the tab bar first, as P4c–P4f each did, moves the work in both directions.

1. The stated blocker is smaller than it reads

The hit computation is already downstream of the width. tab_hit_rects, tab_close_hit_rects and tab_tearout_hit_rects are published by the renderer into ClientState every frame (ui_verts.rs) and only read by mouse.rs:422, 503, 1396. There is no mirrored formula to keep in step — the P4c footer-link problem does not exist here. Correcting the width corrects all seven of its consumers at once.

2. There is a live defect underneath it

A tab is sized by character count:

let label_w = (label.chars().count() as f32 * cell_w + padding * 2.0)...

and drawn by display width (add_string_verts advances via UnicodeWidthChar, so a full-width char takes two cells).

Title	chars().count()	drawn	tab
build	5	5 cells	5 cells + padding
ビルド	3	6 cells	3 cells + padding

Today, with no ramp involved:

• the label draws past its own pill, over the neighbouring tab;
• tab_hit_rects records the narrow width, so clicking the text you are reading activates the next pane;
• the close and tear-out buttons are placed from the narrow edge and land inside the drawn text.

The 24-character truncation cap has the same bug — 24 chars is 24 cells of Latin or 48 of Japanese.

This is not a regression the ramp would introduce; it is a defect the ramp forces into the open, because once glyphs advance by their own measured width no character count could ever be right.

Decisions in the spec

• D1 measure the label, never count it — one function, seven consumers unchanged.
• D2 truncate to a width budget via truncate_run_to_width, not to 24 characters.
• D3 the Nerd Font process icon leaves the label string and is drawn as its own run: it resolves through the terminal font's fallback chain while measure_run asks the chrome face, and a glyph present in one and absent in the other measures wrong in exactly the direction that overflows.
• D4 tabs stay content-sized. Equal-width tabs and a scrolling strip (WT's model) are a layout redesign with their own hit-region, drag and overflow questions; folding them in would make a visual regression unattributable.

Six gates (G-width, G-fit, G-hit, G-single, G-truncate, G-icon) and a three-PR breakdown (N-3a pure width + tests → N-3b adopt in the builder → N-3c the icon run). G-hit looks tautological and is worth writing precisely because it fails today.

Open questions — §7, for the maintainer

1. Minimum tab width. The draw loop stops at label_w < cell_w * 2.0. Measured text has no natural cell, so the floor becomes either a fixed pixel minimum or "room for the ellipsis plus padding". Spec recommends the ellipsis rule (same rule truncate_run_to_width already applies).
2. Does the ● activity dot stay inside the label? It is the same font-fallback question D3 moves the process icon out of the string to avoid. More common glyph, so it probably measures — but "probably measures" is what the CJK defect is made of. Spec recommends measuring it once on a real font stack before deciding.

🤖 Generated with Claude Code

[github-actions]

Coverage report

Generated by cargo llvm-cov (workspace minus nexterm-client-gpu and nexterm-i18n).

[github-actions]

Coverage report

Generated by cargo llvm-cov (workspace minus nexterm-client-gpu and nexterm-i18n).