Chrome-RTL/README.md

Persian RTL Fixer — Vazirmatn

A dependency-free Chrome extension (Manifest V3) that fixes Persian text direction on dynamic websites, especially streaming AI chats, without rewriting the page’s text.

What it changes

• A Persian-leading text block gets dir="rtl" and right alignment.
• English-leading mixed content gets dir="auto" so both scripts remain readable.
• Arabic-only, Hebrew, and English-only text are left untouched.
• Latin digits such as 1234567890 are never converted or rewritten.
• Unstyled Persian text receives the bundled Vazirmatn font.
• Any font selected by the website is preserved, including inherited, generic, inline, and web fonts.
• Text inputs use automatic direction and receive Vazirmatn only after Persian text is present.

The content script batches DOM mutations, so token-by-token AI responses are corrected without rescanning the whole page for every character.

Safety model

The extension never wraps, replaces, or restructures text nodes. It changes only reversible dir attributes and inline font styles on existing elements. Code blocks, SVG, MathML, and unsupported form controls are skipped. Disabling the extension restores every owned change without reloading the page.

The detector requires Persian-specific characters before acting. This intentionally favors precision over guessing: ambiguous text made entirely from letters shared with Arabic is not modified.

Install as an unpacked extension

1. Open chrome://extensions.
2. Enable Developer mode.
3. Select Load unpacked and choose this directory.
4. Pin Persian RTL Fixer from the extensions menu.

To use the local demo.html, open the extension’s details and enable Allow access to file URLs first.

Popup settings

Setting	Default	Behavior
Enable on this site	On	Pauses correction for the current hostname
Conservative RTL correction	On	Corrects clearly Persian blocks while preserving uncertain layouts
Vazirmatn for unstyled text	On	Applies Vazirmatn only when the site declares no font
Smart input direction	On	Uses automatic direction in text fields
Master switch	On	Enables or disables the extension everywhere

Settings are stored locally through chrome.storage.local. The extension does not send page text anywhere.

Development

npm install
npm test
npm run check:encoding

The automated suites cover real Persian fixtures, Arabic isolation, mixed direction, Latin-digit integrity, inherited and stylesheet fonts, streaming mutations, reversible teardown, protected content, input behavior, popup states, and UTF-8 integrity.

Project layout

manifest.json          Manifest V3 configuration
src/content.js         Persian detector, DOM correction, and lifecycle
popup/                 Accessible toolbar popup
fonts/                 Bundled Vazirmatn WOFF2 files
icons/                 Extension icons
demo.html              Manual and streaming test page
test/                  jsdom and integrity tests

Open shadow roots and related frames are supported where Chrome exposes them. Closed shadow roots are inaccessible to browser extensions.

Vazirmatn is distributed under the SIL Open Font License.