# pi-persian-rtl

Persian / Farsi RTL rendering support for the [Pi](https://pi.dev) terminal UI.

## Important: native BiDi is the default

Version `0.1.1` no longer reverses Persian text before sending it to the terminal.
Modern terminals already implement the Unicode Bidirectional Algorithm; manually
reversing the line makes them process it twice and breaks sentences containing
English identifiers, commands, numbers, or URLs.

The package now keeps text in **logical Unicode order**, preserves ANSI styling,
right-aligns Persian-first lines, and wraps them in RLI/PDI isolation controls so
mixed Persian/English content is handled by the terminal's own BiDi engine.

## Install or upgrade

```bash
pi remove npm:pi-arabic-rtl 2>/dev/null || true
pi update npm:pi-persian-rtl
npx pi-persian-rtl apply
```

Restart Pi after upgrading.

For a first installation:

```bash
pi install npm:pi-persian-rtl
```

## Modes

### Native mode — default and recommended

```bash
PI_PERSIAN_RTL_MODE=native pi
```

Native mode:

- does not reverse Persian characters;
- keeps `pi-persian-rtl`, `Context Mode`, URLs, paths, and code in LTR order;
- keeps Persian digits and ZWNJ intact;
- preserves ANSI colors and styles;
- right-aligns Persian-first lines.

### Visual fallback — only for terminals without BiDi support

```bash
PI_PERSIAN_RTL_MODE=visual pi
```

This uses application-side visual reordering. Do **not** use it in GNOME/VTE or
another terminal that already handles BiDi, because that causes double reversal.

### Disable transformation

```bash
PI_PERSIAN_RTL_MODE=off pi
```

## Commands

```bash
npx pi-persian-rtl apply
npx pi-persian-rtl check
npx pi-persian-rtl restore
```

`apply` patches the installed `@earendil-works/pi-tui` output layer. The first
patch creates `.pi-persian-rtl.bak` files beside the modified files. `restore`
restores those backups.

When discovery cannot find Pi's TUI installation:

```bash
PI_TUI_DIST=/path/to/@earendil-works/pi-tui/dist npx pi-persian-rtl apply
```

## Test text

```text
۱. Pi یک دستیار کدنویسی سریع و قابل اعتماد است.
۲. پکیج pi-persian-rtl نسخه ۰.۱.۱ نصب شد.
۳. Context Mode و npm test باید درست نمایش داده شوند.
۴. لینک https://pi.dev و مسیر /home/user/project سالم می‌مانند.
۵. من می‌روم و عدد ۱۲۳٬۴۵۶ را بررسی می‌کنم.
```

## Development

```bash
npm test
npm run check
npm pack
```

## Compatibility

- Current Pi releases using `@earendil-works/pi-tui`.
- Node.js 20 or newer.
- Linux, macOS, and Windows.
- Native mode requires a terminal with Unicode BiDi support.
- Visual mode is an opt-in fallback for terminals without it.

## License

MIT. See `NOTICE` for attribution to the original `pi-arabic-rtl` package that
inspired the patching approach.