Kickoff: Persian parity in the terminal — root causes & where the finish line is

[mbaneshi]

Mission

Make Persian — and every Arabic-script language (Arabic, Urdu, Pashto, Sorani Kurdish) — first-class in the terminal, on par with English: reading, typing, letter joining, fonts, search, cursor, copy/paste.

Not a config tweak for one setup. The daily stack (WezTerm → Zellij → Neovim / Claude Code) breaks Persian at every layer, and the breakage shares one root cause, so it gets treated as one problem and fixed from the bottom up.

Root cause: the cell grid

A terminal is a grid of equal-width cells filled left-to-right; the application decides where everything goes. Persian violates three of that model's assumptions:

Terminal assumes	Persian reality	Symptom
Each cell is independent	Shaping — a letter's form depends on its neighbours	Disconnected letters
Text runs left-to-right	BiDi — visual order depends on the whole line (esp. mixed Persian / English / digits)	Reversed words, swapped numbers, flipped brackets
1 character = 1 cell	Width — «لا» is two chars, one glyph; ZWNJ and diacritics are zero-width	Cursor drifts from its real position

The deepest knot is ownership: nobody has settled whether the terminal or the application does RTL reordering. Both do it → double-reversed. Neither does → stays reversed. Egmont Koblinger's 2019 draft BiDi in Terminal Emulators addresses exactly this; VTE implements part of it, adoption is otherwise thin. Its current status is a research item.

The nine layers

1. Encoding & normalisation (Arabic ي/ك vs Persian ی/ک; three digit families)
2. Input (layout, ZWNJ typing, key delivery)
3. Character width ← foundation
4. Shaping ← foundation
5. BiDi ← foundation
6. Cursor, selection, copy
7. Fonts (very few Persian monospace fonts; fallback sizing)
8. Multiplexers (Zellij / tmux repaint cell-by-cell, shattering shaping runs)
9. Apps & frameworks (Neovim, Ink, ncurses, readline)

Layers 3–5 come first — everything else rides on them.

Roadmap

1. Root-cause map — primary-source research: Unicode (UAX docs: prior-art catalog for Persian/RTL in the terminal #9 BiDi, UAX feat(site): first-class Prior work section — on-site catalog + Persian notes #11 / width), ECMA-48 BiDi controls, the Koblinger draft, real terminal + app behaviour, font landscape.
2. Torture-test suite — reproducible mixed text (ZWNJ, «لا», digits, brackets, diacritics) that scores any terminal × app combination. The ruler every fix is measured against.
3. Fixes — font + terminal config first, then multiplexer / editor / apps (or upstream patches), finally pushing the ownership standard. Bottom-up, in dependency order.

Open decision — where's the finish line?

This sets how deep phase 1 goes and what gets built after:

• Recommendation: do the map + torture suite regardless (they have standalone value), and decide upstream fixes vs. our own tooling only after we know where the upstream projects actually stand. Building our own layer before that is likely duplicate work — and until RTL ownership is settled, any fix just moves the bug around.

Discuss here; the resolved answer folds into a spec under docs/superpowers/specs/.