diff --git a/bun.lock b/bun.lock
index efe01bf957f3..3e1199267aa9 100644
--- a/bun.lock
+++ b/bun.lock
@@ -948,6 +948,7 @@
         "@opentui/core": "catalog:",
         "@opentui/keymap": "catalog:",
         "@opentui/solid": "catalog:",
+        "bidi-js": "1.1.0",
         "clipboardy": "4.0.0",
         "diff": "catalog:",
         "effect": "catalog:",
@@ -3196,6 +3197,8 @@
 
     "before-after-hook": ["before-after-hook@2.2.3", "", {}, "sha512-NzUnlZexiaH/46WDhANlyR2bXRopNg4F/zuSA3OpZnllCUgRaOF2znDioDWrmbNVsuZk6l9pMquQB38cfBZwkQ=="],
 
+    "bidi-js": ["bidi-js@1.1.0", "", { "dependencies": { "require-from-string": "^2.0.2" } }, "sha512-fX1Onk0tdVPC7obPWB5EbJ1z7NVhLq4m2xZLq2YXBkxzMXIGRpNMU88n0EPgWseKl12J7zXs7qrDxPK4sRs2fg=="],
+
     "bignumber.js": ["bignumber.js@9.3.1", "", {}, "sha512-Ko0uX15oIUS7wJ3Rb30Fs6SkVbLmPBAKdlm7q9+ak9bbIeFf0MwuBsQV6z7+X768/cHsfg+WlysDWJcmthjsjQ=="],
 
     "bin-links": ["bin-links@6.0.2", "", { "dependencies": { "cmd-shim": "^8.0.0", "npm-normalize-package-bin": "^5.0.0", "proc-log": "^6.0.0", "read-cmd-shim": "^6.0.0", "write-file-atomic": "^7.0.0" } }, "sha512-frE1t78WOwJ45PKV2cF2tNPjTcs9L1J9s6VkrV59wanRP4GlaomuxYPVma7BwthMg8WnfSory4w5PTE6FZZ81w=="],
diff --git a/docs/rtl/README.ar.md b/docs/rtl/README.ar.md
new file mode 100644
index 000000000000..9ff5f455f7be
--- /dev/null
+++ b/docs/rtl/README.ar.md
@@ -0,0 +1,138 @@
+# دعم الكتابة من اليمين لليسار (RTL / BiDi) في واجهة OpenCode النصية
+
+بقى النص العربي والفارسي والأردي والعبري يظهر صح في واجهة OpenCode النصية —
+في **مربع الكتابة (البرومبت)** وفي **ردود المساعد** — عن طريق تنفيذ خوارزمية
+يونيكود للاتجاهين (UAX #9) في طبقة الرسم داخل التطبيق نفسه، من غير أي اعتماد
+على دعم الـ terminal، ومن غير أي إعادة كتابة destructive للنص.
+
+> English: [README.md](./README.md)
+
+## إيه اللي بيشتغل
+
+- **العربي لوحده** يقرأ طبيعي من اليمين لليسار ويتحاذى لليمين.
+- **عربي + إنجليزي** بيفضل الإنجليزي (`npm`، `API`، أسماء المتغيرات) في مكانه
+  الطبيعي حسب ترتيب يونيكود ثنائي الاتجاه.
+- **المقاطع اللاتينية بتفضل LTR**: أكواد inline، أسماء ملفات، مسارات، روابط،
+  أوامر، أسماء حزم، وأرقام — كلها بتتعزل بـ LRI/PDI.
+- **الكود دايمًا LTR**: بلوكات الكود والجداول والـ diffs بتستخدم الراسم
+  الأصلي ومابيتغيرش ترتيبها أبدًا.
+- **الالتفاف (wrapping)** محسوب بالـ grapheme وبعرض الخلية؛ أسطر الالتفاف
+  بتفضل متحاذية يمين وبالترتيب البصري الصح.
+- **مؤشر الكتابة واعي بالاتجاه**: الأسهم بتتحرك بصريًا؛ الكتابة واللصق
+  والتراجع والقيمة المخزنة تفضل يونيكود منطقي.
+- **النسخ واللصق سليم**: التحديد بيرجّع النص المنطقي الأصلي، مش ترتيب بصري
+  ولا حروف تحكم مخفية.
+
+## الخطوط
+
+التطبيق ميقدرش يختار خطوط — الـ terminal هو اللي بيختار. سيب الخط الـ
+monospaced زي ما هو واتأكد إن في خط عربي متاح كـ fallback في إعدادات
+الـ terminal (مثلًا `"face": "Cascadia Mono, Cairo, Segoe UI"` في
+Windows Terminal)، وبعدين اقفل التيرمنال وافتحه تاني.
+
+## التثبيت (ويندوز، من نفس المستودع)
+
+
+```powershell
+# 1) تثبيت اعتماديات الـ workspace
+bun install
+
+# 2) بناء ملف تنفيذي لمنصتك الحالية
+bun run --cwd packages/opencode script/build.ts --single --skip-install --skip-embed-web-ui
+
+# 3) تشغيله
+.\packages\opencode\dist\opencode-windows-x64\bin\opencode.exe
+```
+
+لاستبدال نسخة npm المثبتة (مع الاحتفاظ بنسخة احتياطية):
+
+```powershell
+$new    = ".\packages\opencode\dist\opencode-windows-x64\bin\opencode.exe"
+$stable = "$env:APPDATA\npm\node_modules\opencode-ai\bin\opencode.exe"
+Copy-Item $stable "$stable.original-backup" -Force
+Copy-Item $new $stable -Force
+```
+
+## المعمارية
+
+الواجهة مبنية على `@opentui/solid` فوق `@opentui/core@0.4.5`. تخطيط النص
+والالتفاف والتشكيل ورسم الخلايا كلها بتحصل داخل **مكتبة Zig أصلية**
+(`bufferDrawTextBufferView` / `drawEditorView`) مفيها أي دعم BiDi ومفيش بديل
+JS. الحزمة المنشورة بتيجي JavaScript مبنية ومضغوطة، فالتعديل ده **مش** بيعدل
+OpenTUI نفسه؛ هو بيعمل subclass للكلاسات العامة بتاعته وبيبدّل بس نقطة الرسم
+ونقطة رسم المؤشر.
+
+| الجزء | الملف |
+| --- | --- |
+| محرك UAX #9 ونموذج الـ grapheme والالتفاف والعزل وخرايط المؤشر | `packages/tui/src/util/bidi.ts` |
+| مربع الكتابة (`BidiTextareaRenderable`) | `packages/tui/src/component/bidi-textarea.ts` |
+| ماركداون ردود المساعد (hook اسمه `renderNode`) | `packages/tui/src/component/bidi-markdown.ts` |
+| صدى رسالة المستخدم (`BidiTextRenderable`) | `packages/tui/src/component/bidi-text.ts` |
+| تسجيل العناصر (`extend`) | `packages/tui/src/component/bidi-elements.ts` |
+
+الربط:
+
+- `packages/tui/src/component/prompt/index.tsx` — `<textarea>` بتتحول لـ `<bidi_textarea>`
+- `packages/tui/src/routes/session/index.tsx` — `<markdown renderNode={bidiMarkdownRenderNode}>`
+  ورسالة المستخدم `<text>` بتتحول لـ `<bidi_text>`
+
+### اكتشاف الاتجاه
+
+لكل فقرة، بنعمل فحص سريع لأي كتابة RTL قوية (عبري، عربي، سرياني، ثانا، نكو،
+مندائي، وأشكال العرض). لو موجودة، `bidi-js` بيحسب مستويات التضمين واتجاه
+الفقرة حسب UAX #9 (أول حرف قوي، مع احترام العوازل). الفقرة مابتتصنفش RTL لمجرد
+إن فيها اسم إنجليزي؛ والمحتوى الإنجليزي البحت بيمشي على المسار الأصلي حرفيًا.
+
+### العزل بدل إعادة الكتابة
+
+بنجمّع محتوى LTR (روابط، مسارات، أسماء بنقط أو شرطات، أرقام، أكواد inline)
+جوّه LRI/PDI. العوازل دي موجودة بس في تدفّق تخطيط داخلي — مابتترسمش ومابتتخزنش،
+فالنسخ واللصق بيرجّعوا النص المنطقي النظيف.
+
+### الالتفاف
+
+تقسيم الـ graphemes بـ `Intl.Segmenter`، وعرض الخلية بـ `Bun.stringWidth`
+(السطر الجديد بيتحسب عرض 1 زي اصطلاح الـ textarea). النص المنطقي الملتف بيتزامن
+مع الـ buffer الأصلي عشان القياس والتحديد والنسخ، وبعدين كل سطر بصري بيتعاد
+ترتيبه بـ UAX #9 (L2)؛ أسطر RTL بتتحاذى يمين وأسطر LTR بتتحاذى شمال.
+
+### خرايط المؤشر
+
+كل سطر بيخزّن `boundaryCols` (حدود منطقية ← عمود بصري) و`logicalWidths`
+(حدود منطقية ← عرض منطقي). المؤشر المنطقي ← حد ← مكان بصري؛ والحركة بتمشي
+على الأعمدة البصرية عبر حدود الأسطر؛ والتحديد بـ Shift بيستخدم آلية التحديد
+المنطقية الأصلية.
+
+## الاعتمادية
+
+[`bidi-js@1.1.0`](https://www.npmjs.com/package/bidi-js) — رخصة MIT،
+JavaScript خالص، بدون اعتماديات وقت التشغيل، ومُختبر ضد مجموعة اختبارات
+يونيكود الرسمية للاتجاهين. بيوفّر بدائيات UAX #9 (حساب المستويات وإعادة
+الترتيب والانعكاس)؛ وكل سياسات الرسم موجودة في المستودع ده.
+
+## الاختبارات
+
+```bash
+bun test --cwd packages/tui ./test/util/bidi.test.ts
+bun test --cwd packages/tui ./test/component/bidi-render.test.tsx
+bun test --cwd packages/tui ./test/component/bidi-mixed.test.tsx
+bun test --cwd packages/tui ./test/bidi-e2e.test.tsx
+bun test --cwd packages/tui ./test/bidi-dialogs-e2e.test.tsx
+bun run --cwd packages/tui typecheck
+```
+
+## حدود معروفة
+
+- **تشكيل** الحروف العربية متروك للـ terminal والخط؛ التعديل ده بيتحكم في
+  الترتيب والاتجاه والمحاذاة، وهوه اللي الراسم الخلوي يقدر يتحكم فيه.
+- إخفاء الماركداون (backticks المخفية) ممكن يفقد ألوان بعض المقاطع لفترة
+  بسيطة وقت البث؛ لكن الترتيب دايمًا صح.
+- جداول الماركداون بتفضل بالراسم الأصلي: العربي جوه الخلايا بيظهر بالترتيب
+  المنطقي على الشمال. الجداول سطح بيانات، وإعادة تدفقها حسب الاتجاه هتكسر
+  محاذاة الأعمدة والنسخ/اللصق.
+- سطور الـ diff بتحافظ على بنية الكود؛ والنص العربي في السطور المضافة/المحذوفة
+  بيتبع اتجاه الفقرة وعلامات +/- وأرقام السطور ثابتة.
+- علامات القوائم (`-`، `1.`) بتفضل على الحرف الشمال؛ ومحتوى العنصر بيتبع
+  اتجاه الفقرة.
+- `Home`/`End` والقفز بين الكلمات لسه بمنطق الإزاحة المنطقية (سلوك أصلي).
+- الضغط بالماوس في البرومبت لسه بالسلوك الأصلي؛ حركة الكيبورد واعية بالكامل.
diff --git a/docs/rtl/README.md b/docs/rtl/README.md
new file mode 100644
index 000000000000..bb892d97bdce
--- /dev/null
+++ b/docs/rtl/README.md
@@ -0,0 +1,154 @@
+# Native BiDi / RTL support in the OpenCode TUI
+
+Arabic, Persian, Urdu and Hebrew text now renders correctly in the native TUI —
+in the **prompt input** and in **assistant output** — implementing the Unicode
+Bidirectional Algorithm (UAX #9) at the application rendering layer, with no
+terminal-side BiDi requirement and no destructive text rewriting.
+
+> العربية: [README.ar.md](./README.ar.md)
+
+## What works
+
+- **Arabic-only text** reads naturally right-to-left and is right-aligned.
+- **Mixed Arabic + English** keeps embedded English (`npm`, `API`, identifiers)
+  in natural bidi flow.
+- **LTR islands stay LTR**: code spans, filenames, paths, URLs, commands,
+  package names and numbers are directionally isolated with LRI/PDI.
+- **Code always stays LTR**: fenced code blocks, tables and diffs keep the stock
+  renderer and are never reordered.
+- **Wrapping** is grapheme- and width-aware; wrapped RTL continuation lines stay
+  right-aligned and in the correct visual order.
+- **The prompt caret is bidi-aware**: arrow keys move visually; typing, paste,
+  undo and the stored value remain logical Unicode.
+- **Copy/paste is untouched**: selection returns the original logical text,
+  never visual-order or control characters.
+
+## Fonts
+
+The TUI cannot select fonts — the terminal does. Keep your monospaced font and
+make sure an Arabic-capable font is available as a fallback in your terminal
+settings (for example `"face": "Cascadia Mono, Cairo, Segoe UI"` in Windows
+Terminal), then restart the terminal.
+
+## Install (Windows, from this repository)
+
+```powershell
+# 1) install workspace dependencies
+bun install
+
+# 2) build a single-platform native binary
+bun run --cwd packages/opencode script/build.ts --single --skip-install --skip-embed-web-ui
+
+# 3) run it
+.\packages\opencode\dist\opencode-windows-x64\bin\opencode.exe
+```
+
+To replace an existing npm install (keep a backup of the original binary):
+
+```powershell
+$new    = ".\packages\opencode\dist\opencode-windows-x64\bin\opencode.exe"
+$stable = "$env:APPDATA\npm\node_modules\opencode-ai\bin\opencode.exe"
+Copy-Item $stable "$stable.original-backup" -Force
+Copy-Item $new $stable -Force
+```
+
+## Architecture
+
+The TUI is `@opentui/solid` over `@opentui/core@0.4.5`. Text layout, wrapping,
+shaping and cell painting in OpenTUI all happen in a **native Zig library**
+(`bufferDrawTextBufferView` / `drawEditorView`) that has no BiDi support and no
+JS fallback. The published package ships bundled JS, so this change does **not**
+patch OpenTUI; it subclasses its public renderables and overrides only the paint
+and caret entry points:
+
+| Piece | File |
+| --- | --- |
+| UAX #9 engine wrapper, grapheme model, wrapping, isolates, cursor maps | `packages/tui/src/util/bidi.ts` |
+| Prompt input (`BidiTextareaRenderable extends TextareaRenderable`) | `packages/tui/src/component/bidi-textarea.ts` |
+| Assistant markdown (`renderNode` hook for paragraphs/headings) | `packages/tui/src/component/bidi-markdown.ts` |
+| User message echo (`BidiTextRenderable extends TextRenderable`) | `packages/tui/src/component/bidi-text.ts` |
+| Element registration (`extend({ bidi_text, bidi_textarea })`) | `packages/tui/src/component/bidi-elements.ts` |
+
+Wiring:
+
+- `packages/tui/src/component/prompt/index.tsx` — `<textarea>` → `<bidi_textarea>`
+- `packages/tui/src/routes/session/index.tsx` — `<markdown renderNode={bidiMarkdownRenderNode}>`
+  and user echo `<text>` → `<bidi_text>`
+
+### Direction detection
+
+Per paragraph, a strong-RTL script probe runs first (Hebrew, Arabic, Syriac,
+Thaana, NKo, Mandaic, presentation forms). If found, `bidi-js` resolves embedding
+levels and the paragraph base direction via UAX #9 P2/P3 (first strong
+character, isolates honored). A paragraph is never classified RTL just because
+it contains an English identifier; English-only content takes the stock path
+bit-for-bit.
+
+### Isolation instead of rewriting
+
+`bidi-js` is wrapped in LRI/PDI for LTR islands (URLs, `a/b.c` paths, dotted and
+dashed identifiers, numbers, markdown code spans). Isolates exist only in a
+layout-only augmented stream — they are never painted and never stored, so
+selection/copy return pristine logical text.
+
+### Wrapping
+
+Grapheme segmentation via `Intl.Segmenter`; cell widths via `Bun.stringWidth`
+(newlines count as one width unit, matching the textarea offset convention).
+Wrapped **logical** text is synced into the native text buffer so measurement,
+selection and copy keep working, then each visual line is reordered
+independently with UAX #9 L2 flip segments; RTL lines align to the right edge,
+LTR lines to the left.
+
+### Caret mapping
+
+Each line stores `boundaryCols` (logical boundary → visual column) and
+`logicalWidths` (logical boundary → logical width). Logical cursor → boundary →
+visual caret; caret motion walks visual columns monotonically across line edges;
+shift-selection reuses the native logical selection machinery.
+
+## Dependency
+
+[`bidi-js@1.1.0`](https://www.npmjs.com/package/bidi-js) — MIT, pure JS, no
+runtime dependencies, verified against the Unicode bidi conformance suite. It
+provides the UAX #9 primitives (`getEmbeddingLevels`, `getReorderSegments`,
+mirroring); all rendering policy lives in this repository.
+
+## Tests
+
+```bash
+bun test --cwd packages/tui ./test/util/bidi.test.ts
+bun test --cwd packages/tui ./test/component/bidi-render.test.tsx
+bun test --cwd packages/tui ./test/component/bidi-mixed.test.tsx
+bun test --cwd packages/tui ./test/bidi-e2e.test.tsx
+bun test --cwd packages/tui ./test/bidi-dialogs-e2e.test.tsx
+bun run --cwd packages/tui typecheck
+```
+
+- `test/util/bidi.test.ts` — engine: detection, ordering, isolates, wrapping,
+  cursor round-trips.
+- `test/component/bidi-render.test.tsx` — real OpenTUI test renderer: RTL
+  painting, right alignment, code LTR, English-identical-to-stock, caret, copy.
+- `test/component/bidi-mixed.test.tsx` — mixed-direction paragraphs: code
+  spans, commands, dotted identifiers, spaced Windows paths, URLs, versions,
+  key:line references, bold markers, lists, links, tables of punctuation,
+  tashkeel preservation, wrapping around LTR tokens.
+- `test/bidi-e2e.test.tsx` — boots the real app, types Arabic with real key
+  presses, streams a real assistant message.
+
+## Known limitations
+
+- Arabic glyph **shaping** is left to the terminal/font; this change controls
+  order, direction and alignment, which is what a cell-grid renderer can own.
+- Markdown `conceal` (hidden backticks) may drop per-span colors in a brief
+  streaming window; order always stays correct.
+- Markdown tables keep the stock grid renderer: Arabic inside table cells
+  renders in logical order, left-aligned. Tables are a data surface; reflowing
+  them per direction would break column alignment and copy/paste.
+- Diff hunks keep code structure; Arabic prose inside added/removed lines
+  follows paragraph direction while signs and line numbers stay put.
+- List markers (`-`, `1.`) stay on the left edge; item content follows
+  paragraph direction.
+- `Home`/`End`/word-jump keep logical-offset semantics (native behavior).
+- Mouse click positioning in the prompt keeps native behavior; keyboard motion
+  is fully bidi-aware.
diff --git a/docs/rtl/install-windows.ps1 b/docs/rtl/install-windows.ps1
new file mode 100644
index 000000000000..a01c2ede5e74
--- /dev/null
+++ b/docs/rtl/install-windows.ps1
@@ -0,0 +1,55 @@
+# Builds the RTL/BiDi dev build and installs it over the npm-installed
+# `opencode` (stable) and `opencode2` (beta @opencode-ai/cli) binaries on
+# Windows. Original binaries are kept next to the new ones as
+# `*.original-backup` so restore-windows.ps1 can roll back.
+#
+# Usage (from the repository root):
+#   powershell -ExecutionPolicy Bypass -File docs/rtl/install-windows.ps1
+
+$ErrorActionPreference = "Stop"
+
+$repo = Resolve-Path (Join-Path $PSScriptRoot "..\..")
+$exe = Join-Path $repo "packages\opencode\dist\opencode-windows-x64\bin\opencode.exe"
+
+Write-Host "Building single-platform native binary..."
+Push-Location $repo
+try {
+  bun run --cwd packages/opencode script/build.ts --single --skip-install --skip-embed-web-ui
+} finally {
+  Pop-Location
+}
+
+if (-not (Test-Path $exe)) {
+  throw "Build did not produce $exe"
+}
+
+$targets = @(
+  (Join-Path $env:APPDATA "npm\node_modules\opencode-ai\bin\opencode.exe"),
+  (Join-Path $env:APPDATA "npm\node_modules\@opencode-ai\cli\bin\opencode2.exe")
+)
+
+foreach ($target in $targets) {
+  if (-not (Test-Path $target)) {
+    Write-Host "Skipping (not installed): $target"
+    continue
+  }
+  $backup = "$target.original-backup"
+  if (-not (Test-Path $backup)) {
+    Copy-Item $target $backup -Force
+    Write-Host "Backed up: $backup"
+  }
+  try {
+    Copy-Item $exe $target -Force
+    Write-Host "Installed: $target"
+  } catch {
+    # A running instance locks the executable. Windows allows renaming a
+    # running image, so move it aside first, then place the new build.
+    Move-Item -LiteralPath $target -Destination $backup -Force
+    Copy-Item $exe $target -Force
+    Write-Host "Installed (renamed running binary): $target"
+  }
+}
+
+Write-Host ""
+Write-Host "Done. Restart any running OpenCode window to pick up the new build."
+Write-Host 'Verify with: opencode --version'
diff --git a/docs/rtl/restore-windows.ps1 b/docs/rtl/restore-windows.ps1
new file mode 100644
index 000000000000..8a45b1cb7f5a
--- /dev/null
+++ b/docs/rtl/restore-windows.ps1
@@ -0,0 +1,31 @@
+# Restores the npm-installed `opencode` (stable) and `opencode2` (beta)
+# binaries that install-windows.ps1 replaced.
+#
+# Usage (from the repository root):
+#   powershell -ExecutionPolicy Bypass -File docs/rtl/restore-windows.ps1
+
+$ErrorActionPreference = "Stop"
+
+$targets = @(
+  (Join-Path $env:APPDATA "npm\node_modules\opencode-ai\bin\opencode.exe"),
+  (Join-Path $env:APPDATA "npm\node_modules\@opencode-ai\cli\bin\opencode2.exe")
+)
+
+foreach ($target in $targets) {
+  $backup = "$target.original-backup"
+  if (-not (Test-Path $backup)) {
+    Write-Host "No backup found for: $target"
+    continue
+  }
+  try {
+    Copy-Item $backup $target -Force
+    Write-Host "Restored: $target"
+  } catch {
+    Move-Item -LiteralPath $target -Destination "$target.rtl-build" -Force
+    Copy-Item $backup $target -Force
+    Write-Host "Restored (renamed running binary): $target"
+  }
+}
+
+Write-Host ""
+Write-Host "Done. Restart any running OpenCode window to pick up the original build."
diff --git a/packages/tui/package.json b/packages/tui/package.json
index 4b9b95b35e68..ef8b04443fc7 100644
--- a/packages/tui/package.json
+++ b/packages/tui/package.json
@@ -55,6 +55,7 @@
     "@opentui/core": "catalog:",
     "@opentui/keymap": "catalog:",
     "@opentui/solid": "catalog:",
+    "bidi-js": "1.1.0",
     "clipboardy": "4.0.0",
     "diff": "catalog:",
     "effect": "catalog:",
diff --git a/packages/tui/src/app.tsx b/packages/tui/src/app.tsx
index 3f1da522bb06..ec68723dc23a 100644
--- a/packages/tui/src/app.tsx
+++ b/packages/tui/src/app.tsx
@@ -45,6 +45,7 @@ import { DialogMcp } from "./component/dialog-mcp"
 import { DialogStatus } from "./component/dialog-status"
 import { DialogDebug } from "./component/dialog-debug"
 import { DialogThemeList } from "./component/dialog-theme-list"
+import "./component/bidi-elements"
 import { DialogHelp } from "./ui/dialog-help"
 import { DialogAgent } from "./component/dialog-agent"
 import { DialogSessionList } from "./component/dialog-session-list"
diff --git a/packages/tui/src/component/bidi-elements.ts b/packages/tui/src/component/bidi-elements.ts
new file mode 100644
index 000000000000..e49d040f540d
--- /dev/null
+++ b/packages/tui/src/component/bidi-elements.ts
@@ -0,0 +1,31 @@
+import { extend } from "@opentui/solid"
+import { BidiTextRenderable } from "./bidi-text"
+import { BidiTextareaRenderable } from "./bidi-textarea"
+import { installBidiCodePaint } from "./bidi-markdown"
+
+// Registers the bidi-aware elements with the OpenTUI solid catalogue so they
+// can be used as <bidi_text> and <bidi_textarea> in JSX. Import this module
+// from any component that renders them.
+//
+// Overriding the built-in `text` component is what makes RTL work "everywhere"
+// without touching every call site: dialogs, lists, tool output, toasts and
+// status lines all render through <text>. BidiTextRenderable defers to the
+// stock painter whenever the content has no strong RTL characters, so
+// English-only output is unchanged.
+//
+// installBidiCodePaint does the same for markdown code blocks at the
+// CodeRenderable level, which is the only layer that sees list items,
+// blockquotes and streaming updates (those paths never consult renderNode).
+extend({
+  text: BidiTextRenderable,
+  bidi_text: BidiTextRenderable,
+  bidi_textarea: BidiTextareaRenderable,
+})
+installBidiCodePaint()
+
+declare module "@opentui/solid" {
+  interface OpenTUIComponents {
+    bidi_text: typeof BidiTextRenderable
+    bidi_textarea: typeof BidiTextareaRenderable
+  }
+}
diff --git a/packages/tui/src/component/bidi-markdown.ts b/packages/tui/src/component/bidi-markdown.ts
new file mode 100644
index 000000000000..41fab764b9bc
--- /dev/null
+++ b/packages/tui/src/component/bidi-markdown.ts
@@ -0,0 +1,237 @@
+import {
+  CodeRenderable,
+  TextBuffer,
+  type ChunkRenderContext,
+  type OnChunksCallback,
+  type OptimizedBuffer,
+  type TextChunk,
+} from "@opentui/core"
+import { hasRtl, layoutBidiText, paintBidiCell, widthOffsetToBoundary, wrappedLogicalText, type BidiLayout } from "../util/bidi"
+
+// Markdown bidi painting, installed once on CodeRenderable itself so every
+// markdown-prose block inherits it: top-level paragraphs and headings, list
+// items, blockquotes and table fallbacks. OpenTUI builds those code blocks
+// internally (list rows and streaming updates never consult renderNode), so
+// per-instance patching always misses surfaces; the prototype sees them all.
+//
+// Only blocks whose content carries strong RTL characters AND whose filetype
+// is unset or "markdown" take the bidi path. Fenced code blocks carry a real
+// filetype and English-only blocks have no RTL, so both keep the stock
+// painter bit-for-bit. The logical string is never mutated: isolates live in
+// a layout-only stream, and the native buffer only ever holds wrapped logical
+// text, so selection and copy keep working.
+
+type StyledSource = {
+  text: string
+  chunks: TextChunk[]
+  // Char offset where each chunk starts within text.
+  offsets: number[]
+}
+
+type BidiCodeState = {
+  styled: StyledSource | undefined
+  layout: BidiLayout | undefined
+  // Logical source text of the current layout (pre-wrap).
+  source: string
+  wrapped: string | undefined
+  width: number
+  // Bumped on every captured chunk update so style-only changes (same text,
+  // new styles) still rebuild the layout instead of painting a stale one.
+  styledVersion: number
+  paintedVersion: number
+  chunksWrapper: OnChunksCallback | undefined
+}
+
+const blockStates = new WeakMap<CodeRenderable, BidiCodeState>()
+let prototypePatched = false
+
+// Protected members of TextBufferRenderable needed for buffer sync, plus
+// the highlight machinery. startHighlight/_highlightsDirty are private in
+// the .d.ts but public at runtime; these shapes only widen the TypeScript
+// view. Coupled to @opentui/core 0.4.5 (see script/upgrade-opentui.ts when
+// bumping).
+type CodeInternals = {
+  textBuffer: TextBuffer
+  plainText: string
+  updateTextInfo(): void
+  startHighlight(): void
+  _highlightsDirty?: boolean
+}
+
+function blockState(renderable: CodeRenderable) {
+  let state = blockStates.get(renderable)
+  if (!state) {
+    state = {
+      styled: undefined,
+      layout: undefined,
+      source: "",
+      wrapped: undefined,
+      width: 0,
+      styledVersion: 0,
+      paintedVersion: -1,
+      chunksWrapper: undefined,
+    }
+    blockStates.set(renderable, state)
+  }
+  return state
+}
+
+function proseFiletype(renderable: CodeRenderable) {
+  return (renderable as unknown as { filetype?: unknown }).filetype
+}
+
+function shouldBidiPaint(renderable: CodeRenderable) {
+  if (renderable.width <= 0) return false
+  const filetype = proseFiletype(renderable)
+  if (filetype !== undefined && filetype !== "markdown") return false
+  const content = renderable.content
+  return typeof content === "string" && hasRtl(content)
+}
+
+// Wraps onChunks once per instance so tree-sitter styled chunks are captured
+// for the paint below. Assigning marks highlights dirty, which restarts
+// highlighting through the wrapper; afterwards the installed wrapper is
+// detected and left alone, so this converges instead of looping.
+function ensureChunksWrapped(renderable: CodeRenderable, state: BidiCodeState) {
+  const current = renderable.onChunks
+  if (current === state.chunksWrapper) return
+  const previous = current
+  const wrapper: OnChunksCallback = async (chunks: TextChunk[], context: ChunkRenderContext) => {
+    const result = previous ? await previous(chunks, context) : undefined
+    const captured = result ?? chunks
+    let text = ""
+    const offsets: number[] = []
+    for (const chunk of captured) {
+      offsets.push(text.length)
+      text += chunk.text
+    }
+    state.styled = { text, chunks: captured, offsets }
+    state.styledVersion++
+    state.layout = undefined
+    state.wrapped = undefined
+    return result
+  }
+  state.chunksWrapper = wrapper
+  renderable.onChunks = wrapper
+}
+
+export function installBidiCodePaint() {
+  if (prototypePatched) return
+  prototypePatched = true
+  const proto = CodeRenderable.prototype as unknown as {
+    renderSelf(buffer: OptimizedBuffer): void
+  }
+  const stockRenderSelf = proto.renderSelf
+  proto.renderSelf = function (this: CodeRenderable, buffer: OptimizedBuffer) {
+    if (!shouldBidiPaint(this)) {
+      stockRenderSelf.call(this, buffer)
+      return
+    }
+    const state = blockState(this)
+    ensureChunksWrapped(this, state)
+    paintBidiBlock(this, state, buffer, () => stockRenderSelf.call(this, buffer))
+  }
+}
+
+function paintBidiBlock(
+  renderable: CodeRenderable,
+  state: BidiCodeState,
+  buffer: OptimizedBuffer,
+  paintStock: () => void,
+) {
+  const internals = renderable as unknown as CodeInternals
+  const content = renderable.content
+  const plain = internals.plainText
+  // The buffer may hold our pre-wrapped text; recover the logical source.
+  const current = state.wrapped !== undefined && plain === state.wrapped ? state.source : plain
+  if (!hasRtl(content) || renderable.width <= 0) {
+    if (state.wrapped !== undefined) {
+      if (plain !== content) {
+        internals.textBuffer.setText(content)
+        internals.updateTextInfo()
+      }
+      state.wrapped = undefined
+      state.layout = undefined
+    }
+    paintStock()
+    return
+  }
+
+    if (
+      state.source !== current ||
+      state.width !== renderable.width ||
+      state.paintedVersion !== state.styledVersion
+    ) {
+      state.source = current
+      state.width = renderable.width
+      state.paintedVersion = state.styledVersion
+      state.layout = layoutBidiText(current, renderable.width)
+      state.wrapped = wrappedLogicalText(state.layout)
+    }
+
+    // The patched paint replaces Code's renderSelf, which normally starts
+    // tree-sitter highlighting when dirty. Mirror that kickoff exactly
+    // (clear the flag synchronously, then start) so syntax colors keep
+    // flowing for RTL blocks on content, theme, and conceal changes.
+    if (internals._highlightsDirty) {
+      internals._highlightsDirty = false
+      internals.startHighlight()
+    }
+
+    if (plain !== state.wrapped) {
+      internals.textBuffer.setText(state.wrapped ?? current)
+      internals.updateTextInfo()
+    }
+    paintStyledLines(buffer, state, renderable)
+  }
+
+function paintStyledLines(buffer: OptimizedBuffer, state: BidiCodeState, renderable: CodeRenderable) {
+  const layout = state.layout
+  if (!layout) return
+  // Styles apply only when the captured chunk text still matches the layout
+  // source; otherwise the paint falls back to the renderable defaults (the
+  // brief streaming window before tree-sitter styling lands).
+  const styled = state.styled && state.styled.text === state.source ? state.styled : undefined
+  const defaultFg = renderable.fg
+  const defaultBg = renderable.bg
+  const defaultAttributes = renderable.attributes
+  const selection = renderable.getSelection()
+  const selectionFg = renderable.selectionFg ?? defaultFg
+  const selectionBg = renderable.selectionBg ?? defaultBg
+  const selStart = selection ? widthOffsetToBoundary(layout, selection.start) : -1
+  const selEnd = selection ? widthOffsetToBoundary(layout, selection.end) : -1
+  const width = renderable.width
+  for (let i = 0; i < layout.lines.length; i++) {
+    const line = layout.lines[i]
+    const y = renderable.screenY + i
+    if (y < 0 || y >= buffer.height) continue
+    const x0 = line.rtl ? renderable.screenX + width - line.width : renderable.screenX
+    for (const cell of line.cells) {
+      const x = x0 + cell.col
+      if (x < 0 || x >= buffer.width) continue
+      const chunk = styled ? chunkAt(styled, layout.glyphs[cell.glyph].charIndex) : undefined
+      const selected = selStart >= 0 && cell.glyph >= selStart && cell.glyph < selEnd
+      paintBidiCell(
+        buffer,
+        x,
+        y,
+        cell.char,
+        selected ? selectionFg : (chunk?.fg ?? defaultFg),
+        selected ? selectionBg : (chunk?.bg ?? defaultBg),
+        chunk?.attributes ?? defaultAttributes,
+      )
+    }
+  }
+}
+
+function chunkAt(source: StyledSource, charIndex: number) {
+  let lo = 0
+  let hi = source.offsets.length - 1
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1
+    if (source.offsets[mid] <= charIndex) lo = mid
+    else hi = mid - 1
+  }
+  const chunk = source.chunks[lo]
+  return chunk && charIndex < source.offsets[lo] + chunk.text.length ? chunk : undefined
+}
diff --git a/packages/tui/src/component/bidi-text.ts b/packages/tui/src/component/bidi-text.ts
new file mode 100644
index 000000000000..9c1077808cdb
--- /dev/null
+++ b/packages/tui/src/component/bidi-text.ts
@@ -0,0 +1,66 @@
+import { TextRenderable, type OptimizedBuffer } from "@opentui/core"
+import { hasRtl, layoutBidiText, paintBidiCell, wrappedLogicalText, type BidiLayout } from "../util/bidi"
+
+// RTL-aware text element for user-authored content (chat input echoes).
+// English-only content renders through the stock OpenTUI path untouched; the
+// bidi layout runs only when strong RTL characters are present. The logical
+// string is never mutated: the native text buffer is only re-synced to the
+// wrapped logical form so measurement, selection and copy keep working.
+export class BidiTextRenderable extends TextRenderable {
+  private bidiSource: string | undefined
+  private bidiWrapped: string | undefined
+  private bidiLayout: BidiLayout | undefined
+  private bidiWidth = 0
+
+  protected override renderSelf(buffer: OptimizedBuffer): void {
+    const plain = this.plainText
+    if (this.bidiWrapped !== undefined && plain !== this.bidiWrapped && plain !== this.bidiSource) {
+      // Content was updated externally; adopt the buffer text as the new
+      // logical source before any wrapping decision.
+      this.bidiSource = plain
+      this.bidiLayout = undefined
+    }
+    const source = this.bidiSource ?? plain
+    if (!hasRtl(source) || this.width <= 0) {
+      this.restoreLogical(source, plain)
+      super.renderSelf(buffer)
+      return
+    }
+
+    if (!this.bidiLayout || this.bidiWidth !== this.width) {
+      this.bidiLayout = layoutBidiText(source, this.width)
+      this.bidiWidth = this.width
+      this.bidiWrapped = wrappedLogicalText(this.bidiLayout)
+      this.bidiSource = source
+    }
+
+    if (plain !== this.bidiWrapped) {
+      this.textBuffer.setText(this.bidiWrapped ?? source)
+      this.updateTextInfo()
+    }
+
+    const layout = this.bidiLayout
+    const fg = this.fg
+    const bg = this.bg
+    const attributes = this.attributes
+    for (let i = 0; i < layout.lines.length; i++) {
+      const line = layout.lines[i]
+      const y = this._screenY + i
+      if (y < 0 || y >= buffer.height) continue
+      const x0 = line.rtl ? this._screenX + this.width - line.width : this._screenX
+      for (const cell of line.cells) {
+        const x = x0 + cell.col
+        if (x < 0 || x >= buffer.width) continue
+        paintBidiCell(buffer, x, y, cell.char, fg, bg, attributes)
+      }
+    }
+  }
+
+  private restoreLogical(source: string, plain: string) {
+    if (this.bidiWrapped === undefined || plain !== this.bidiWrapped) return
+    this.textBuffer.setText(source)
+    this.updateTextInfo()
+    this.bidiWrapped = undefined
+    this.bidiLayout = undefined
+  }
+}
diff --git a/packages/tui/src/component/bidi-textarea.ts b/packages/tui/src/component/bidi-textarea.ts
new file mode 100644
index 000000000000..987fab82be42
--- /dev/null
+++ b/packages/tui/src/component/bidi-textarea.ts
@@ -0,0 +1,186 @@
+import { TextareaRenderable, type OptimizedBuffer } from "@opentui/core"
+import {
+  boundaryToLogicalCursor,
+  boundaryToVisual,
+  hasRtl,
+  layoutBidiText,
+  logicalCursorToBoundary,
+  paintBidiCell,
+  visualStep,
+  visualToBoundary,
+  widthOffsetToBoundary,
+  type BidiLayout,
+} from "../util/bidi"
+
+// RTL-aware prompt input. The edit buffer always stores logical Unicode text
+// (typing, paste, undo and value reads are untouched); only painting, caret
+// placement and left/right/up/down motion are bidi-aware. When the text has
+// no strong RTL characters every code path defers to the stock OpenTUI
+// textarea, so English-only behavior is bit-for-bit unchanged.
+export class BidiTextareaRenderable extends TextareaRenderable {
+  private bidiState: { source: string; width: number; layout: BidiLayout; scroll: number } | undefined
+  private bidiDesiredCol: number | undefined
+
+  private bidiLayout() {
+    const source = this.plainText
+    if (!hasRtl(source)) {
+      this.bidiState = undefined
+      return undefined
+    }
+    const width = this.width
+    if (width <= 0) return undefined
+    if (this.bidiState && this.bidiState.source === source && this.bidiState.width === width) return this.bidiState
+    this.bidiState = { source, width, layout: layoutBidiText(source, width), scroll: this.bidiState?.scroll ?? 0 }
+    return this.bidiState
+  }
+
+  private bidiViewportHeight() {
+    return Math.max(1, Math.floor(this.height))
+  }
+
+  private clampBidiScroll(state: NonNullable<BidiTextareaRenderable["bidiState"]>) {
+    const height = this.bidiViewportHeight()
+    state.scroll = Math.max(0, Math.min(state.scroll, Math.max(0, state.layout.lines.length - height)))
+  }
+
+  private currentBoundary(state: NonNullable<BidiTextareaRenderable["bidiState"]>) {
+    const cursor = this.editBuffer.getCursorPosition()
+    return logicalCursorToBoundary(state.layout, cursor.row, cursor.col)
+  }
+
+  private moveToBoundary(layout: BidiLayout, boundary: number) {
+    const position = boundaryToLogicalCursor(layout, boundary)
+    this.editBuffer.setCursor(position.row, position.col)
+    this.bidiDesiredCol = undefined
+  }
+
+  protected override renderSelf(buffer: OptimizedBuffer): void {
+    const state = this.bidiLayout()
+    if (!state) {
+      super.renderSelf(buffer)
+      return
+    }
+    this.clampBidiScroll(state)
+    const selection = this.getSelection()
+    const selStart = selection ? widthOffsetToBoundary(state.layout, selection.start) : -1
+    const selEnd = selection ? widthOffsetToBoundary(state.layout, selection.end) : -1
+    const selectionFg = this._selectionFg ?? this._textColor
+    const selectionBg = this._selectionBg ?? this._backgroundColor
+    const height = this.bidiViewportHeight()
+    for (let i = state.scroll; i < state.layout.lines.length && i < state.scroll + height; i++) {
+      const line = state.layout.lines[i]
+      const y = this._screenY + (i - state.scroll)
+      if (y < 0 || y >= buffer.height) continue
+      const x0 = line.rtl ? this._screenX + state.width - line.width : this._screenX
+      for (const cell of line.cells) {
+        const x = x0 + cell.col
+        if (x < 0 || x >= buffer.width) continue
+        const selected = selStart >= 0 && cell.glyph >= selStart && cell.glyph < selEnd
+        paintBidiCell(
+          buffer,
+          x,
+          y,
+          cell.char,
+          selected ? selectionFg : this._textColor,
+          selected ? selectionBg : this._backgroundColor,
+          this._defaultAttributes,
+        )
+      }
+    }
+  }
+
+  protected override renderCursor(buffer: OptimizedBuffer): void {
+    const state = this.bidiLayout()
+    if (!state) {
+      super.renderCursor(buffer)
+      return
+    }
+    if (!this._showCursor || !this._focused) return
+    const boundary = this.currentBoundary(state)
+    const position = boundaryToVisual(state.layout, boundary)
+    const height = this.bidiViewportHeight()
+    if (position.line < state.scroll) state.scroll = position.line
+    if (position.line >= state.scroll + height) state.scroll = position.line - height + 1
+    this.clampBidiScroll(state)
+    const line = state.layout.lines[position.line]
+    const x = (line.rtl ? this._screenX + state.width - line.width : this._screenX) + position.col
+    this._ctx.setCursorPosition(x + 1, this._screenY + (position.line - state.scroll) + 1, true)
+    this._ctx.setCursorStyle({ ...this._cursorStyle, color: this._cursorColor })
+    void buffer
+  }
+
+  override moveCursorLeft(options?: { select?: boolean }): boolean {
+    const state = this.bidiLayout()
+    if (!state) return super.moveCursorLeft(options)
+    const select = options?.select ?? false
+    if (!select && this.hasSelection()) return super.moveCursorLeft(options)
+    this.updateSelectionForMovement(select, true)
+    this.moveToBoundary(state.layout, visualStep(state.layout, this.currentBoundary(state), -1))
+    this.updateSelectionForMovement(select, false)
+    this.requestRender()
+    return true
+  }
+
+  override moveCursorRight(options?: { select?: boolean }): boolean {
+    const state = this.bidiLayout()
+    if (!state) return super.moveCursorRight(options)
+    const select = options?.select ?? false
+    if (!select && this.hasSelection()) return super.moveCursorRight(options)
+    this.updateSelectionForMovement(select, true)
+    this.moveToBoundary(state.layout, visualStep(state.layout, this.currentBoundary(state), 1))
+    this.updateSelectionForMovement(select, false)
+    this.requestRender()
+    return true
+  }
+
+  override moveCursorUp(options?: { select?: boolean }): boolean {
+    const state = this.bidiLayout()
+    if (!state) return super.moveCursorUp(options)
+    const select = options?.select ?? false
+    this.updateSelectionForMovement(select, true)
+    const boundary = this.currentBoundary(state)
+    const position = boundaryToVisual(state.layout, boundary)
+    if (position.line === 0) {
+      this.editBuffer.setCursor(0, 0)
+    } else {
+      const desired = this.bidiDesiredCol ?? position.col
+      this.moveToBoundary(state.layout, visualToBoundary(state.layout, position.line - 1, desired))
+      this.bidiDesiredCol = desired
+    }
+    this.updateSelectionForMovement(select, false)
+    this.requestRender()
+    return true
+  }
+
+  override moveCursorDown(options?: { select?: boolean }): boolean {
+    const state = this.bidiLayout()
+    if (!state) return super.moveCursorDown(options)
+    const select = options?.select ?? false
+    this.updateSelectionForMovement(select, true)
+    const boundary = this.currentBoundary(state)
+    const position = boundaryToVisual(state.layout, boundary)
+    if (position.line >= state.layout.lines.length - 1) {
+      const last = state.layout.paragraphs[state.layout.paragraphs.length - 1]
+      this.editBuffer.setCursor(state.layout.paragraphs.length - 1, state.layout.boundaryWidths[last.end] - last.startWidth)
+    } else {
+      const desired = this.bidiDesiredCol ?? position.col
+      this.moveToBoundary(state.layout, visualToBoundary(state.layout, position.line + 1, desired))
+      this.bidiDesiredCol = desired
+    }
+    this.updateSelectionForMovement(select, false)
+    this.requestRender()
+    return true
+  }
+
+  protected override handleScroll(event: { type: string; scroll?: { direction: string; delta: number } }): void {
+    super.handleScroll(event)
+    const state = this.bidiLayout()
+    if (!state || !event.scroll) return
+    const delta = event.scroll.delta
+    if (event.scroll.direction === "up") state.scroll = Math.max(0, state.scroll - delta)
+    if (event.scroll.direction === "down") {
+      state.scroll = Math.min(state.scroll + delta, Math.max(0, state.layout.lines.length - this.bidiViewportHeight()))
+    }
+    this.requestRender()
+  }
+}
diff --git a/packages/tui/src/component/prompt/index.tsx b/packages/tui/src/component/prompt/index.tsx
index c48c751739ce..a3598c9b98ca 100644
--- a/packages/tui/src/component/prompt/index.tsx
+++ b/packages/tui/src/component/prompt/index.tsx
@@ -57,6 +57,7 @@ import { usePromptWorkspace } from "./workspace"
 import { usePromptMove } from "./move"
 import { readLocalAttachment } from "./local-attachment"
 import { useLocation } from "../../context/location"
+import "../../component/bidi-elements"
 
 registerOpencodeSpinner()
 
@@ -1366,7 +1367,7 @@ export function Prompt(props: PromptProps) {
             flexGrow={1}
             width="100%"
           >
-            <textarea
+            <bidi_textarea
               width="100%"
               placeholder={placeholderText()}
               placeholderColor={theme.textMuted}
diff --git a/packages/tui/src/routes/session/index.tsx b/packages/tui/src/routes/session/index.tsx
index 2b54f21671b3..f9b6d977e69a 100644
--- a/packages/tui/src/routes/session/index.tsx
+++ b/packages/tui/src/routes/session/index.tsx
@@ -81,6 +81,7 @@ import { getRevertDiffFiles } from "../../util/revert-diff"
 import { OPENCODE_BASE_MODE, useBindings, useCommandShortcut, useOpencodeKeymap } from "../../keymap"
 import { usePathFormatter } from "../../context/path-format"
 import { LocationProvider } from "../../context/location"
+import "../../component/bidi-elements"
 
 addDefaultParsers(parsers.parsers)
 
@@ -1416,7 +1417,7 @@ function UserMessage(props: {
             backgroundColor={hover() ? theme.backgroundElement : theme.backgroundPanel}
             flexShrink={0}
           >
-            <text fg={theme.text}>{text()}</text>
+            <bidi_text fg={theme.text}>{text()}</bidi_text>
             <Show when={files().length}>
               <box flexDirection="row" paddingBottom={metadataVisible() ? 1 : 0} paddingTop={1} gap={1} flexWrap="wrap">
                 <For each={files()}>
diff --git a/packages/tui/src/util/bidi.ts b/packages/tui/src/util/bidi.ts
new file mode 100644
index 000000000000..53383d75fa21
--- /dev/null
+++ b/packages/tui/src/util/bidi.ts
@@ -0,0 +1,630 @@
+import bidiFactory from "bidi-js"
+import type { OptimizedBuffer, RGBA } from "@opentui/core"
+
+// Unicode Bidirectional Algorithm (UAX #9) engine. bidi-js is a pure-JS
+// implementation verified against the Unicode bidi conformance suite. All
+// reordering below is derived from resolved embedding levels, never from
+// naive string reversal.
+const bidi = bidiFactory()
+
+const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" })
+
+// Directional isolates used for layout only. They mark embedded LTR content
+// (paths, URLs, code spans, numbers) inside RTL paragraphs so surrounding
+// neutrals cannot leak into the wrong run. They are never painted and never
+// stored in any buffer, so copy/paste and logical text stay untouched.
+const LRI = "\u2066"
+const PDI = "\u2069"
+
+// Strong RTL coverage: Hebrew, Arabic, Syriac, Thaana, NKO, Samaritan,
+// Mandaic, extensions, presentation forms, RLM/ALM/RLE/RLO.
+const RTL_PROBE =
+  /[\u0590-\u05FF\u0600-\u06FF\u0700-\u074F\u0750-\u077F\u0860-\u08FF\uFB1D-\uFDFF\uFE70-\uFEFF\u200F\u202B\u061C]/
+
+export function hasRtl(text: string) {
+  return RTL_PROBE.test(text)
+}
+
+// LTR island seeds embedded in RTL text, matched on logical text and wrapped
+// in LRI/PDI during layout. Bare English words far from any seed stay bare:
+// UAX #9 already renders them as LTR runs and they must stay in natural bidi
+// flow with the surrounding sentence. Seeds adjacent to bare Latin/digit
+// words absorb them (see expandIslands). Multi-token runs are isolated so
+// surrounding neutrals (backticks, asterisks, colons, dots, slashes,
+// brackets) cannot leak into them or split them apart.
+const LTR_ISLAND =
+  /`[^`\n]+`|[A-Za-z]:\\[A-Za-z0-9_@.\\-]*(?: +[A-Za-z0-9_@.\\-]+)*(?::\d+)?|(?:https?:\/\/|www\.)\S+|[A-Za-z0-9_@]+(?:[/\\.-][A-Za-z0-9_@-]+)+(?::\d+)?|[A-Za-z0-9_@]+:\d+|\d+(?:[.,:/]\d+)*%?/g
+
+export type BidiGlyph = {
+  char: string
+  // Terminal cell width. Newlines count as one offset position to match the
+  // textarea width-offset convention.
+  width: number
+  // Char index of the glyph within the source string.
+  charIndex: number
+  newline: boolean
+  // Isolate control glyph: participates in the bidi computation only.
+  control: boolean
+}
+
+export type BidiCell = {
+  // Display text; mirrored brackets already substituted for RTL runs.
+  char: string
+  width: number
+  // Global glyph index in the logical stream (never a control glyph).
+  glyph: number
+  // Visual column where the cell starts on its line.
+  col: number
+  // True when the cell belongs to an odd (RTL) embedding level.
+  rtl: boolean
+}
+
+export type BidiLine = {
+  // Cells in left-to-right paint order.
+  cells: BidiCell[]
+  // Painted width excluding edge whitespace.
+  width: number
+  // Paragraph base direction; RTL lines align to the right edge.
+  rtl: boolean
+  // Global glyph range of the line, edge whitespace excluded.
+  start: number
+  end: number
+  // Local logical boundary (0..end-start) -> visual column on the line.
+  boundaryCols: number[]
+  // Local logical boundary (0..end-start) -> cumulative logical width.
+  logicalWidths: number[]
+}
+
+export type BidiParagraph = {
+  // Glyph range of the paragraph excluding its terminating newline glyph.
+  start: number
+  end: number
+  // Visual line range within layout.lines.
+  firstLine: number
+  lineCount: number
+  // Cumulative logical width at the paragraph start boundary.
+  startWidth: number
+}
+
+export type BidiLayout = {
+  glyphs: BidiGlyph[]
+  lines: BidiLine[]
+  paragraphs: BidiParagraph[]
+  // Global boundary -> visual line index.
+  boundaryLine: Int32Array
+  // Global boundary -> cumulative logical width offset (newline = 1).
+  boundaryWidths: Float64Array
+  // Global boundary -> paragraph index.
+  boundaryParagraph: Int32Array
+}
+
+// Caller-provided isolate ranges in char-index space of the source string.
+export type BidiIsolateRange = [number, number]
+
+// Paints one laid-out cell. The native setCell stores a single code point and
+// silently drops combining marks (Arabic tashkeel); drawText keeps grapheme
+// clusters intact, so multi-unit glyphs go through drawText.
+export function paintBidiCell(
+  buffer: OptimizedBuffer,
+  x: number,
+  y: number,
+  char: string,
+  fg: RGBA,
+  bg: RGBA,
+  attributes: number,
+) {
+  if (char.length > 1) buffer.drawText(char, x, y, fg, bg, attributes)
+  else buffer.setCell(x, y, char, fg, bg, attributes)
+}
+
+const WHITESPACE = /\s/
+
+function glyphWidth(char: string) {
+  if (char === "\n") return 1
+  return Bun.stringWidth(char)
+}
+
+// Greedy word wrapping mirroring the native text-buffer policy: break after
+// whitespace when possible, hard-break a run that cannot fit, and never split
+// a grapheme. Breaks outside LTR islands are preferred so an island is kept
+// on one visual line whenever it fits; breaking inside an island is only the
+// fallback before a mid-word hard break.
+function wrapGlyphs(
+  glyphs: BidiGlyph[],
+  start: number,
+  end: number,
+  maxWidth: number,
+  inIsland?: (index: number) => boolean,
+) {
+  const ranges: Array<[number, number]> = []
+  const limit = maxWidth > 0 ? maxWidth : Number.POSITIVE_INFINITY
+  let lineStart = start
+  let width = 0
+  let breakAt = -1
+  let breakOutside = -1
+  const noteBreak = (pos: number, at: number) => {
+    breakAt = pos
+    if (!inIsland || !inIsland(at)) breakOutside = pos
+  }
+  const rescanBreaks = (from: number, to: number) => {
+    breakAt = -1
+    breakOutside = -1
+    for (let j = from; j < to; j++) {
+      if (WHITESPACE.test(glyphs[j].char)) noteBreak(j + 1, j)
+    }
+  }
+  for (let i = start; i < end; i++) {
+    const glyph = glyphs[i]
+    if (glyph.newline) {
+      ranges.push([lineStart, i])
+      lineStart = i + 1
+      width = 0
+      breakAt = -1
+      breakOutside = -1
+      continue
+    }
+    if (width + glyph.width > limit && i > lineStart) {
+      const cut = breakOutside > lineStart ? breakOutside : breakAt
+      if (cut > lineStart) {
+        ranges.push([lineStart, cut])
+        lineStart = cut
+      } else {
+        ranges.push([lineStart, i])
+        lineStart = i
+      }
+      width = 0
+      for (let j = lineStart; j < i; j++) width += glyphs[j].width
+      rescanBreaks(lineStart, i)
+    }
+    width += glyph.width
+    if (WHITESPACE.test(glyph.char)) noteBreak(i + 1, i)
+  }
+  ranges.push([lineStart, end])
+  return ranges
+}
+
+function trimEdgeWhitespace(glyphs: BidiGlyph[], start: number, end: number) {
+  while (
+    start < end &&
+    !glyphs[start].newline &&
+    !glyphs[start].control &&
+    WHITESPACE.test(glyphs[start].char)
+  ) {
+    start++
+  }
+  while (
+    end > start &&
+    !glyphs[end - 1].newline &&
+    !glyphs[end - 1].control &&
+    WHITESPACE.test(glyphs[end - 1].char)
+  ) {
+    end--
+  }
+  return [start, end] as const
+}
+
+function mergeRanges(ranges: Array<[number, number]>) {
+  if (ranges.length === 0) return [] as Array<[number, number]>
+  const sorted = ranges.slice().sort((a, b) => a[0] - b[0] || a[1] - b[1])
+  const merged: Array<[number, number]> = [[sorted[0][0], sorted[0][1]]]
+  for (const [from, to] of sorted.slice(1)) {
+    const last = merged[merged.length - 1]
+    if (from <= last[1] + 1) {
+      last[1] = Math.max(last[1], to)
+      continue
+    }
+    merged.push([from, to])
+  }
+  return merged
+}
+
+// ASCII word characters only; RTL text never matches, so expansion always
+// stops at direction boundaries. The first code unit decides: combining marks
+// ride with their base letter either way.
+const ISLAND_WORD = /[A-Za-z0-9_@]/
+
+function isIslandWord(glyph: BidiGlyph | undefined) {
+  return !!glyph && !glyph.newline && !glyph.control && ISLAND_WORD.test(glyph.char[0] ?? "")
+}
+
+function isIslandSpace(glyph: BidiGlyph | undefined) {
+  const char = glyph?.control || glyph?.newline ? undefined : glyph?.char
+  return char === " " || char === "\t"
+}
+
+// Expands every island across directly adjacent Latin/digit words and the
+// spaces joining them, so one isolate covers each maximal LTR run. This is
+// required, not cosmetic: UAX #9 L2 resolves a bare LTR run and a neighboring
+// isolate as sibling sub-flips plus the whole-line flip, and that composition
+// swaps the two runs. A single isolate over the whole run keeps them ordered.
+function expandIslands(
+  glyphs: BidiGlyph[],
+  paraStart: number,
+  paraEnd: number,
+  ranges: Array<[number, number]>,
+) {
+  return ranges.map(([from, to]) => {
+    let start = from
+    for (;;) {
+      let i = start - 1
+      while (i >= paraStart && isIslandSpace(glyphs[i])) i--
+      if (i < paraStart || !isIslandWord(glyphs[i])) break
+      while (i - 1 >= paraStart && isIslandWord(glyphs[i - 1])) i--
+      start = i
+    }
+    let end = to
+    for (;;) {
+      let i = end + 1
+      while (i < paraEnd && isIslandSpace(glyphs[i])) i++
+      if (i >= paraEnd || !isIslandWord(glyphs[i])) break
+      while (i + 1 < paraEnd && isIslandWord(glyphs[i + 1])) i++
+      end = i
+    }
+    return [start, end] as [number, number]
+  })
+}
+
+export function layoutBidiText(text: string, maxWidth: number, isolateRanges: BidiIsolateRange[] = []): BidiLayout {
+  // Global logical glyph stream. Boundaries sit between glyphs; boundary g is
+  // "before glyph g" and the final boundary equals glyphs.length.
+  const glyphs: BidiGlyph[] = []
+  const charToGlyph = new Map<number, number>()
+  for (const part of graphemes.segment(text)) {
+    charToGlyph.set(part.index, glyphs.length)
+    glyphs.push({
+      char: part.segment,
+      width: glyphWidth(part.segment),
+      charIndex: part.index,
+      newline: part.segment === "\n",
+      control: false,
+    })
+  }
+
+  const boundaryWidths = new Float64Array(glyphs.length + 1)
+  {
+    let width = 0
+    for (let i = 0; i < glyphs.length; i++) {
+      boundaryWidths[i] = width
+      width += glyphs[i].width
+    }
+    boundaryWidths[glyphs.length] = width
+  }
+
+  const lines: BidiLine[] = []
+  const paragraphs: BidiParagraph[] = []
+  const boundaryLine = new Int32Array(glyphs.length + 1).fill(-1)
+  const boundaryParagraph = new Int32Array(glyphs.length + 1).fill(-1)
+
+  const registerLine = (line: BidiLine) => {
+    lines.push(line)
+    const lineIndex = lines.length - 1
+    for (let g = line.start; g <= line.end; g++) {
+      if (boundaryLine[g] === -1 || g === line.end) boundaryLine[g] = lineIndex
+      if (boundaryParagraph[g] === -1) boundaryParagraph[g] = paragraphs.length
+    }
+  }
+
+  const layoutParagraph = (paraStart: number, paraEnd: number) => {
+    const firstLine = lines.length
+    const baseChar = glyphs[paraStart]?.charIndex ?? text.length
+    const endChar = glyphs[paraEnd]?.charIndex ?? text.length
+    const paraText = text.slice(baseChar, endChar)
+    const rtlParagraph = hasRtl(paraText)
+
+    // LTR islands: caller-provided ranges plus regex detection, expanded so one
+    // isolate covers each maximal LTR run, then merged so isolates never nest.
+    const detected: Array<[number, number]> = []
+    if (rtlParagraph) {
+      LTR_ISLAND.lastIndex = 0
+      let match = LTR_ISLAND.exec(paraText)
+      while (match) {
+        // A code span containing strong RTL prose is not an LTR island;
+        // isolating it would pin Arabic left-to-right. Let it flow naturally.
+        if (!(match[0].startsWith("`") && hasRtl(match[0]))) {
+          const from = charToGlyph.get(baseChar + match.index)
+          const to = charToGlyph.get(baseChar + match.index + match[0].length - 1)
+          if (from !== undefined && to !== undefined && to >= from) detected.push([from, to])
+        }
+        match = LTR_ISLAND.exec(paraText)
+      }
+    }
+    const callerRanges = isolateRanges.flatMap(([from, to]) => {
+      let first = -1
+      let last = -1
+      for (let unit = from; unit <= Math.min(to, text.length - 1); unit++) {
+        const glyph = charToGlyph.get(unit)
+        if (glyph === undefined || glyphs[glyph].newline) continue
+        if (first === -1) first = glyph
+        last = glyph
+      }
+      return first === -1 || first < paraStart || last >= paraEnd ? [] : [[first, last] as [number, number]]
+    })
+    const islands = mergeRanges([...callerRanges, ...expandIslands(glyphs, paraStart, paraEnd, detected)])
+
+    // Augmented glyph stream with LRI/PDI around islands. Control glyphs are
+    // zero width and map back to -1 in the logical stream.
+    const augmented: BidiGlyph[] = []
+    const augmentedToLogical: number[] = []
+    const augmentedIsland: boolean[] = []
+    let islandCursor = 0
+    for (let i = paraStart; i < paraEnd; i++) {
+      while (islandCursor < islands.length && islands[islandCursor][1] < i) islandCursor++
+      const island = islands[islandCursor]
+      const inIsland = !!island && i >= island[0] && i <= island[1]
+      if (island && i === island[0]) {
+        augmented.push({ char: LRI, width: 0, charIndex: -1, newline: false, control: true })
+        augmentedToLogical.push(-1)
+        augmentedIsland.push(false)
+      }
+      augmented.push(glyphs[i])
+      augmentedToLogical.push(i)
+      augmentedIsland.push(inIsland)
+      if (island && i === island[1]) {
+        augmented.push({ char: PDI, width: 0, charIndex: -1, newline: false, control: true })
+        augmentedToLogical.push(-1)
+        augmentedIsland.push(false)
+      }
+    }
+
+    // Code-unit offsets for every augmented glyph (bidi-js works per unit).
+    const starts = new Uint32Array(augmented.length)
+    {
+      let unit = 0
+      for (let i = 0; i < augmented.length; i++) {
+        starts[i] = unit
+        unit += augmented[i].char.length
+      }
+    }
+    const augmentedText = augmented.map((g) => g.char).join("")
+
+    // Resolve embedding levels; the paragraph direction follows UAX #9 P2/P3
+    // (first strong character, honoring isolates).
+    const embedding = rtlParagraph ? bidi.getEmbeddingLevels(augmentedText, "auto") : undefined
+    const levels = embedding ? embedding.levels : new Uint8Array(augmentedText.length)
+    const rtl = embedding ? (embedding.paragraphs[0].level & 1) === 1 : false
+
+    for (const [rawStart, rawEnd] of wrapGlyphs(augmented, 0, augmented.length, maxWidth, (i) => augmentedIsland[i])) {
+      const [rangeStart, rangeEnd] = trimEdgeWhitespace(augmented, rawStart, rawEnd)
+
+      // Visual order starts logical over the FULL augmented stream, isolate
+      // controls included. UAX #9 L2 flips move LRI/PDI along with content;
+      // excluding controls first and clamping afterwards corrupts the order
+      // (words rotate, punctuation jumps). Controls are zero-width and are
+      // skipped when emitting cells below.
+      const order: number[] = []
+      for (let i = rangeStart; i < rangeEnd; i++) order.push(i)
+      if (embedding) {
+        const unitStart = starts[rangeStart]
+        const unitEnd = starts[rangeEnd - 1] + augmented[rangeEnd - 1].char.length - 1
+        for (const [fromUnits, toUnits] of bidi.getReorderSegments(augmentedText, embedding, unitStart, unitEnd)) {
+          // Map the inclusive unit flip onto the augmented glyphs it covers.
+          // Flip boundaries always align to grapheme boundaries because every
+          // code unit of one grapheme shares a single embedding level.
+          let gFrom = -1
+          let gTo = -1
+          for (let g = rangeStart; g < rangeEnd; g++) {
+            const gStart = starts[g]
+            const gEnd = gStart + augmented[g].char.length - 1
+            if (gEnd < fromUnits || gStart > toUnits) continue
+            if (gFrom === -1) gFrom = g
+            gTo = g
+          }
+          if (gFrom === -1 || gTo === -1) continue
+          let posFrom = -1
+          let posTo = -1
+          for (let p = 0; p < order.length; p++) {
+            if (order[p] < gFrom || order[p] > gTo) continue
+            if (posFrom === -1) posFrom = p
+            posTo = p
+          }
+          if (posFrom === -1 || posTo === -1) continue
+          for (let i = posFrom, j = posTo; i < j; i++, j--) {
+            const tmp = order[i]
+            order[i] = order[j]
+            order[j] = tmp
+          }
+        }
+      }
+
+      const cells: BidiCell[] = []
+      let col = 0
+      let width = 0
+      for (const augmentedIndex of order) {
+        if (augmented[augmentedIndex].control) continue
+        const glyphIndex = augmentedToLogical[augmentedIndex]
+        const glyph = glyphs[glyphIndex]
+        const rtlCell = embedding ? (levels[starts[augmentedIndex]] & 1) === 1 : false
+        const mirrored = rtlCell ? bidi.getMirroredCharacter(glyph.char) : null
+        cells.push({ char: mirrored ?? glyph.char, width: glyph.width, glyph: glyphIndex, col, rtl: rtlCell })
+        col += glyph.width
+        width += glyph.width
+      }
+
+      // Logical (unwrapped) glyph sequence of this line; boundary indices are
+      // logical positions, independent of visual order.
+      const logicalGlyphs: number[] = []
+      for (let i = rangeStart; i < rangeEnd; i++) {
+        if (augmented[i].control) continue
+        logicalGlyphs.push(augmentedToLogical[i])
+      }
+      const count = logicalGlyphs.length
+
+      if (count === 0) {
+        registerLine({ cells: [], width: 0, rtl, start: paraStart, end: paraStart, boundaryCols: [0], logicalWidths: [0] })
+        continue
+      }
+
+      const localOfGlyph = new Map(logicalGlyphs.map((glyph, index) => [glyph, index]))
+      const boundaryCols = Array.from({ length: count + 1 }, () => -1)
+      const logicalWidths = Array.from({ length: count + 1 }, () => 0)
+      for (let i = 0; i < count; i++) {
+        logicalWidths[i + 1] = logicalWidths[i] + glyphs[logicalGlyphs[i]].width
+      }
+      for (const cell of cells) {
+        const local = localOfGlyph.get(cell.glyph)!
+        if (cell.rtl) {
+          boundaryCols[local] = cell.col + cell.width
+          boundaryCols[local + 1] = cell.col
+        } else {
+          boundaryCols[local] = cell.col
+          boundaryCols[local + 1] = cell.col + cell.width
+        }
+      }
+      for (let i = 0; i <= count; i++) {
+        if (boundaryCols[i] !== -1) continue
+        let j = i - 1
+        while (j >= 0 && boundaryCols[j] === -1) j--
+        boundaryCols[i] = j >= 0 ? boundaryCols[j] : 0
+      }
+
+      registerLine({
+        cells,
+        width,
+        rtl,
+        start: logicalGlyphs[0],
+        end: logicalGlyphs[count - 1] + 1,
+        boundaryCols,
+        logicalWidths,
+      })
+    }
+
+    paragraphs.push({
+      start: paraStart,
+      end: paraEnd,
+      firstLine,
+      lineCount: lines.length - firstLine,
+      startWidth: boundaryWidths[paraStart],
+    })
+  }
+
+  let paraStart = 0
+  for (let i = 0; i < glyphs.length; i++) {
+    if (!glyphs[i].newline) continue
+    layoutParagraph(paraStart, i)
+    boundaryLine[i] = lines.length - 1
+    boundaryParagraph[i] = paragraphs.length - 1
+    paraStart = i + 1
+  }
+  layoutParagraph(paraStart, glyphs.length)
+  for (let g = 0; g <= glyphs.length; g++) {
+    if (boundaryLine[g] === -1) boundaryLine[g] = Math.max(0, lines.length - 1)
+    if (boundaryParagraph[g] === -1) boundaryParagraph[g] = Math.max(0, paragraphs.length - 1)
+  }
+
+  return { glyphs, lines, paragraphs, boundaryLine, boundaryWidths, boundaryParagraph }
+}
+
+// Maps a logical cursor (paragraph row plus logical width column) to a global
+// boundary index. Width columns follow the native convention: each grapheme
+// contributes its display width and a newline contributes one.
+export function logicalCursorToBoundary(layout: BidiLayout, row: number, col: number) {
+  const paragraph = layout.paragraphs[Math.min(Math.max(row, 0), layout.paragraphs.length - 1)]
+  if (!paragraph) return 0
+  let boundary = paragraph.start
+  let width = paragraph.startWidth
+  const target = Math.max(0, col)
+  while (boundary < paragraph.end) {
+    const glyph = layout.glyphs[boundary]
+    if (width + glyph.width > target) break
+    width += glyph.width
+    boundary++
+  }
+  return boundary
+}
+
+// Maps a global boundary to its visual caret position (line index and visual
+// column on that line).
+export function boundaryToVisual(layout: BidiLayout, boundary: number) {
+  const clamped = Math.max(0, Math.min(boundary, layout.boundaryLine.length - 1))
+  const lineIndex = layout.boundaryLine[clamped]
+  const line = layout.lines[lineIndex]
+  if (!line) return { line: 0, col: 0 }
+  const local = Math.max(0, Math.min(clamped - line.start, line.boundaryCols.length - 1))
+  return { line: lineIndex, col: line.boundaryCols[local] ?? 0 }
+}
+
+// Inverse mapping: a visual caret position to the closest global boundary,
+// used for caret motion and hit testing.
+export function visualToBoundary(layout: BidiLayout, lineIndex: number, col: number) {
+  const line = layout.lines[Math.max(0, Math.min(lineIndex, layout.lines.length - 1))]
+  let best = 0
+  let bestDistance = Number.POSITIVE_INFINITY
+  for (let i = 0; i < line.boundaryCols.length; i++) {
+    const distance = Math.abs((line.boundaryCols[i] ?? 0) - col)
+    if (distance < bestDistance) {
+      bestDistance = distance
+      best = i
+    }
+  }
+  return line.start + best
+}
+
+// Steps one caret position visually left (-1) or right (+1), crossing line
+// boundaries the way bidi-aware editors do.
+export function visualStep(layout: BidiLayout, boundary: number, dir: -1 | 1) {
+  const position = boundaryToVisual(layout, boundary)
+  const line = layout.lines[position.line]
+  const cols = line.boundaryCols
+  if (dir < 0) {
+    let candidate = -1
+    for (let i = 0; i < cols.length; i++) {
+      const value = cols[i]
+      if (value < position.col && (candidate === -1 || value > cols[candidate])) candidate = i
+    }
+    if (candidate !== -1) return line.start + candidate
+    if (position.line > 0) {
+      const previous = layout.lines[position.line - 1]
+      let maxIndex = 0
+      for (let i = 1; i < previous.boundaryCols.length; i++) {
+        if ((previous.boundaryCols[i] ?? 0) > (previous.boundaryCols[maxIndex] ?? 0)) maxIndex = i
+      }
+      return previous.start + maxIndex
+    }
+    return boundary
+  }
+  let candidate = -1
+  for (let i = 0; i < cols.length; i++) {
+    const value = cols[i]
+    if (value > position.col && (candidate === -1 || value < cols[candidate])) candidate = i
+  }
+  if (candidate !== -1) return line.start + candidate
+  if (position.line < layout.lines.length - 1) {
+    const next = layout.lines[position.line + 1]
+    let minIndex = 0
+    for (let i = 1; i < next.boundaryCols.length; i++) {
+      if ((next.boundaryCols[i] ?? 0) < (next.boundaryCols[minIndex] ?? 0)) minIndex = i
+    }
+    return next.start + minIndex
+  }
+  return boundary
+}
+
+// Converts a boundary back to native logical cursor coordinates.
+export function boundaryToLogicalCursor(layout: BidiLayout, boundary: number) {
+  const clamped = Math.max(0, Math.min(boundary, layout.boundaryWidths.length - 1))
+  const paragraphIndex = layout.boundaryParagraph[clamped] ?? 0
+  const paragraph = layout.paragraphs[paragraphIndex]
+  if (!paragraph) return { row: 0, col: 0 }
+  return { row: paragraphIndex, col: Math.max(0, layout.boundaryWidths[clamped] - paragraph.startWidth) }
+}
+
+// Global width offsets (native selection and cursor offsets) are
+// display-width offsets; locate the boundary at or before the offset.
+export function widthOffsetToBoundary(layout: BidiLayout, offset: number) {
+  const widths = layout.boundaryWidths
+  let lo = 0
+  let hi = widths.length - 1
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1
+    if (widths[mid] <= offset) lo = mid
+    else hi = mid - 1
+  }
+  return lo
+}
+
+// Reconstructs wrapped logical text with explicit newlines at wrap points so
+// the native text buffer can be kept in sync for measurement and selection
+// while the stored content stays logically ordered.
+export function wrappedLogicalText(layout: BidiLayout) {
+  return layout.lines.map((line) => layout.glyphs.slice(line.start, line.end).map((g) => g.char).join("")).join("\n")
+}
diff --git a/packages/tui/test/bidi-dialogs-e2e.test.tsx b/packages/tui/test/bidi-dialogs-e2e.test.tsx
new file mode 100644
index 000000000000..3d49b54dcb37
--- /dev/null
+++ b/packages/tui/test/bidi-dialogs-e2e.test.tsx
@@ -0,0 +1,154 @@
+import { expect, mock, test } from "bun:test"
+import { createTestRenderer } from "@opentui/core/testing"
+import { Effect } from "effect"
+import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
+import { Global } from "@opencode-ai/core/global"
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui"
+import type { Event, GlobalEvent } from "@opencode-ai/sdk/v2"
+import { createTuiResolvedConfig } from "./fixture/tui-runtime"
+import { createEventSource, createFetch, directory, json } from "./fixture/tui-sdk"
+
+const W = 80
+const H = 24
+const ARABIC_TITLE = "محادثة تجريبية"
+
+function global(payload: Event): GlobalEvent {
+  return { directory, project: "proj_test", payload }
+}
+
+function reverseArabic(text: string) {
+  return text
+    .split(" ")
+    .reverse()
+    .map((word) => word.split("").reverse().join(""))
+    .join(" ")
+}
+
+async function bootApp(args: Record<string, unknown> = {}) {
+  const setup = await createTestRenderer({ width: W, height: H, useThread: false })
+  const core = await import("@opentui/core")
+  mock.module("@opentui/core", () => ({ ...core, createCliRenderer: async () => setup.renderer }))
+  const events = createEventSource()
+  const calls = createFetch((url) => {
+    if (url.pathname === "/config/providers")
+      return json({
+        providers: [
+          {
+            id: "test-provider",
+            name: "Test",
+            source: "config",
+            env: [],
+            options: {},
+            models: { "test-model": { id: "test-model", name: "Test Model", capabilities: {} } },
+          },
+        ],
+        default: {},
+      })
+    if (url.pathname === "/session")
+      return json([
+        {
+          id: "ses_test",
+          title: ARABIC_TITLE,
+          slug: "ses-test",
+          projectID: "proj_test",
+          directory,
+          version: "0.0.0-test",
+          time: { created: 0, updated: 0 },
+        },
+      ])
+    if (url.pathname === "/session/ses_test/message") return json([])
+    if (url.pathname === "/session/ses_test/todo") return json([])
+    if (url.pathname === "/session/ses_test/diff") return json([])
+    if (url.pathname === "/session/ses_test")
+      return json({
+        id: "ses_test",
+        slug: "ses-test",
+        projectID: "proj_test",
+        directory,
+        version: "0.0.0-test",
+        time: { created: 0, updated: 0 },
+        title: ARABIC_TITLE,
+      })
+    if (url.pathname === "/api/session/ses_test")
+      return json({
+        data: {
+          id: "ses_test",
+          projectID: "proj_test",
+          cost: 0,
+          tokens: { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } },
+          time: { created: 0, updated: 0 },
+          title: ARABIC_TITLE,
+          location: { directory },
+        },
+      })
+    return undefined
+  }, events)
+
+  let api: TuiPluginApi | undefined
+  let started!: () => void
+  const ready = new Promise<void>((resolve) => {
+    started = resolve
+  })
+
+  const { run } = await import("../src/app")
+  const task = Effect.runPromise(
+    run({
+      url: "http://test",
+      directory,
+      config: createTuiResolvedConfig({ plugin_enabled: {} }),
+      fetch: calls.fetch,
+      events: events.source,
+      args,
+      pluginHost: {
+        async start(input) {
+          api = input.api
+          input.runtime.setupSlots(input.api)
+          started()
+        },
+        async dispose() {},
+      },
+    }).pipe(Effect.provide(AppNodeBuilder.build(Global.node))),
+  )
+  await ready
+  const pollFrame = async (predicate: (frame: string) => boolean, label = "frame") => {
+    let frame = ""
+    for (let i = 0; i < 150; i++) {
+      await Bun.sleep(100)
+      await setup.renderOnce()
+      frame = setup.captureCharFrame()
+      if (predicate(frame)) return frame
+    }
+    throw new Error(`timed out waiting for ${label}; last frame:\n${frame}`)
+  }
+  await pollFrame((frame) => frame.includes("ctrl+p commands"), "session footer")
+
+  return {
+    waitForFrame: pollFrame,
+    dispatch: (name: string) => api?.keymap.dispatchCommand(name),
+    exit: async () => {
+      try {
+        api?.keymap.dispatchCommand("app.exit")
+        await task
+      } finally {
+        mock.restore()
+        if (!setup.renderer.isDestroyed) setup.renderer.destroy()
+      }
+    },
+  }
+}
+
+test("e2e: Arabic renders RTL inside a DialogSelect list", async () => {
+  const app = await bootApp({ sessionID: "ses_test" })
+  try {
+    app.dispatch("session.list")
+    const frame = await app.waitForFrame(
+      (f) => f.includes("Sessions") && f.includes(reverseArabic(ARABIC_TITLE)),
+      "arabic session title",
+    )
+    const row = frame.split("\n").find((line) => line.includes(reverseArabic(ARABIC_TITLE)))!
+    // RTL title is right-aligned within the dialog row, not at the left padding.
+    expect(row.indexOf(reverseArabic(ARABIC_TITLE))).toBeGreaterThan(20)
+  } finally {
+    await app.exit()
+  }
+}, 60000)
diff --git a/packages/tui/test/bidi-e2e.test.tsx b/packages/tui/test/bidi-e2e.test.tsx
new file mode 100644
index 000000000000..febb17c4fdbf
--- /dev/null
+++ b/packages/tui/test/bidi-e2e.test.tsx
@@ -0,0 +1,247 @@
+import { expect, mock, test } from "bun:test"
+import { createTestRenderer } from "@opentui/core/testing"
+import { Effect } from "effect"
+import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
+import { Global } from "@opencode-ai/core/global"
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui"
+import type { Event, GlobalEvent } from "@opencode-ai/sdk/v2"
+import { createTuiResolvedConfig } from "./fixture/tui-runtime"
+import { createEventSource, createFetch, directory, json } from "./fixture/tui-sdk"
+
+const W = 80
+const H = 24
+
+function global(payload: Event): GlobalEvent {
+  return { directory, project: "proj_test", payload }
+}
+
+type BootedApp = {
+  waitForFrame: (predicate: (frame: string) => boolean, label?: string) => Promise<string>
+  captureCharFrame: () => string
+  typeText: (text: string) => Promise<void>
+  emit: (payload: Event) => void
+  exit: () => Promise<void>
+}
+
+async function bootApp(args: Record<string, unknown> = {}): Promise<BootedApp> {
+  const setup = await createTestRenderer({ width: W, height: H, useThread: false })
+  const core = await import("@opentui/core")
+  mock.module("@opentui/core", () => ({ ...core, createCliRenderer: async () => setup.renderer }))
+  const events = createEventSource()
+  const calls = createFetch((url) => {
+    // One connected provider keeps the "Connect a provider" dialog closed.
+    if (url.pathname === "/config/providers")
+      return json({
+        providers: [
+          {
+            id: "test-provider",
+            name: "Test",
+            source: "config",
+            env: [],
+            options: {},
+            models: {
+              "test-model": {
+                id: "test-model",
+                name: "Test Model",
+                capabilities: {},
+              },
+            },
+          },
+        ],
+        default: {},
+      })
+    if (url.pathname === "/session/ses_test/message") return json([])
+    if (url.pathname === "/session/ses_test/todo") return json([])
+    if (url.pathname === "/session/ses_test/diff") return json([])
+    // Legacy (v1) session fetch used by the session route.
+    if (url.pathname === "/session/ses_test")
+      return json({
+        id: "ses_test",
+        slug: "ses-test",
+        projectID: "proj_test",
+        directory,
+        version: "0.0.0-test",
+        time: { created: 0, updated: 0 },
+        title: "Test session",
+      })
+    if (url.pathname === "/api/session/ses_test")
+      return json({
+        data: {
+          id: "ses_test",
+          projectID: "proj_test",
+          cost: 0,
+          tokens: { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } },
+          time: { created: 0, updated: 0 },
+          title: "Test session",
+          location: { directory },
+        },
+      })
+    if (url.pathname === "/session")
+      return json([
+        {
+          id: "ses_test",
+          title: "Test session",
+          slug: "ses-test",
+          projectID: "proj_test",
+          directory,
+          version: "0.0.0-test",
+          time: { created: 0, updated: 0 },
+        },
+      ])
+    return undefined
+  }, events)
+
+  let api: TuiPluginApi | undefined
+  let started!: () => void
+  const ready = new Promise<void>((resolve) => {
+    started = resolve
+  })
+
+  const { run } = await import("../src/app")
+  const task = Effect.runPromise(
+    run({
+      url: "http://test",
+      directory,
+      config: createTuiResolvedConfig({ plugin_enabled: {} }),
+      fetch: calls.fetch,
+      events: events.source,
+      args,
+      pluginHost: {
+        async start(input) {
+          api = input.api
+          // Mirror the real plugin host (packages/opencode/src/plugin/tui/runtime.ts):
+          // slots render null until they are set up.
+          input.runtime.setupSlots(input.api)
+          started()
+        },
+        async dispose() {},
+      },
+    }).pipe(Effect.provide(AppNodeBuilder.build(Global.node))),
+  )
+  await ready
+  // Poll for content with sleeps: hydration resolves outside the render
+  // scheduler's awareness, so scheduler-gated helpers (waitForFrame/flush)
+  // can give up while async fetches are still in flight.
+  const pollFrame = async (predicate: (frame: string) => boolean, label = "frame") => {
+    let frame = ""
+    for (let i = 0; i < 150; i++) {
+      await Bun.sleep(100)
+      await setup.renderOnce()
+      frame = setup.captureCharFrame()
+      if (predicate(frame)) return frame
+    }
+    throw new Error(`timed out waiting for ${label}; last frame:\n${frame}`)
+  }
+  // Wait for the session view to settle (the session footer is a stable
+  // marker; the session prompt itself shows no placeholder text).
+  await pollFrame((frame) => frame.includes("ctrl+p commands"), "session footer")
+
+  return {
+    waitForFrame: pollFrame,
+    captureCharFrame: setup.captureCharFrame,
+    typeText: setup.mockInput.typeText,
+    emit: (payload: Event) => events.emit(global(payload)),
+    exit: async () => {
+      try {
+        api?.keymap.dispatchCommand("app.exit")
+        await task
+      } finally {
+        mock.restore()
+        if (!setup.renderer.isDestroyed) setup.renderer.destroy()
+      }
+    },
+  }
+}
+
+test("e2e: Arabic prompt input and assistant output in a real session view", async () => {
+  const app = await bootApp({ sessionID: "ses_test" })
+  try {
+    // A) Real keypresses through the real session Prompt into the real bidi
+    // textarea. "ازيك يا صاحبي" must paint as "يبحاص اي كيزا".
+    await app.typeText("ازيك يا صاحبي")
+    const typed = await app.waitForFrame((f) => f.includes("يبحاص اي كيزا"))
+    expect(typed.includes("يبحاص اي كيزا")).toBe(true)
+
+    // Mixed Arabic + English through the same path keeps npm intact.
+    await app.typeText(" + npm هنا")
+    const mixed = await app.waitForFrame((f) => f.includes("npm"))
+    expect(mixed.includes("npm")).toBe(true)
+
+    // B) Assistant text through the sync event vocabulary the session view
+    // reads (message.updated + message.part.updated/delta).
+    const assistant = {
+      id: "msg_ar_1",
+      sessionID: "ses_test",
+      role: "assistant",
+      time: { created: 1 },
+      parentID: "msg_ar_1",
+      modelID: "test-model",
+      providerID: "test-provider",
+      mode: "build",
+      agent: "build",
+      path: { cwd: directory, root: directory },
+      cost: 0,
+      tokens: { input: 0, output: 0, reasoning: 0, cache: { read: 0, write: 0 } },
+    } as const
+    app.emit({ id: "evt_msg_1", type: "message.updated", properties: { sessionID: "ses_test", info: assistant } })
+    app.emit({
+      id: "evt_part_1",
+      type: "message.part.updated",
+      properties: {
+        sessionID: "ses_test",
+        time: 2,
+        part: {
+          id: "txt_1",
+          sessionID: "ses_test",
+          messageID: "msg_ar_1",
+          type: "text",
+          text: "مرحبا بالعالم",
+        },
+      },
+    })
+    // "مرحبا بالعالم" paints as the RTL visual "ملاعلاب ابحرم".
+    const frame = await app.waitForFrame((f) => f.includes("ملاعلاب ابحرم"), "arabic assistant text")
+    expect(frame.includes("ملاعلاب ابحرم")).toBe(true)
+
+    // RTL paragraphs are right-aligned within the message width, not left.
+    const arabicRow = frame.split("\n").find((line) => line.includes("ملاعلاب ابحرم"))!
+    const column = arabicRow.indexOf("ملاعلاب ابحرم")
+    expect(column).toBeGreaterThan(20)
+    expect(arabicRow.trimEnd().endsWith("ملاعلاب ابحرم")).toBe(true)
+
+    app.emit({
+      id: "evt_delta_2",
+      type: "message.part.delta",
+      properties: {
+        sessionID: "ses_test",
+        messageID: "msg_ar_1",
+        partID: "txt_1",
+        field: "text",
+        delta: "\n\nعدّل src/components/Button.tsx الآن",
+      },
+    })
+    // The path stays a contiguous LTR island inside the RTL paragraph.
+    const island = await app.waitForFrame((f) => f.includes("src/components/Button.tsx"), "path island")
+    expect(island.includes("src/components/Button.tsx")).toBe(true)
+
+    app.emit({
+      id: "evt_delta_3",
+      type: "message.part.delta",
+      properties: {
+        sessionID: "ses_test",
+        messageID: "msg_ar_1",
+        partID: "txt_1",
+        field: "text",
+        delta: "\n\n**السبب:** النسخة `0.1.9` بتستخدم `npm install opencode-rtl`",
+      },
+    })
+    // Styled mixed markdown (bold markers, version and command code spans)
+    // keeps every LTR token intact through real highlighting and conceal.
+    // Conceal hides the markers, so the painted tokens are the bare forms.
+    const styled = await app.waitForFrame((f) => f.includes("npm install opencode-rtl"), "styled mixed markdown")
+    expect(styled.includes("npm install opencode-rtl")).toBe(true)
+    expect(styled.includes("0.1.9")).toBe(true)
+  } finally {
+    await app.exit()
+  }
+}, 60000)
diff --git a/packages/tui/test/component/bidi-mixed.test.tsx b/packages/tui/test/component/bidi-mixed.test.tsx
new file mode 100644
index 000000000000..2d3bfb1e5b9e
--- /dev/null
+++ b/packages/tui/test/component/bidi-mixed.test.tsx
@@ -0,0 +1,242 @@
+import { describe, expect, test } from "bun:test"
+import { MarkdownRenderable, SyntaxStyle, type TreeSitterClient } from "@opentui/core"
+import { createTestRenderer } from "@opentui/core/testing"
+import "../../src/component/bidi-elements"
+
+// Regression coverage for mixed-direction paragraphs: Arabic prose carrying
+// LTR runs (code spans, commands, dotted identifiers, Windows paths with
+// spaces, URLs, versions, key:line references) plus Markdown punctuation.
+// Every LTR run must survive as one contiguous visual LTR segment while the
+// Arabic around it stays RTL and right-aligned. Logical text is never
+// rewritten: the assertions below look for the exact logical LTR substrings
+// in the painted frame.
+const WIDTH = 80
+const HEIGHT = 24
+
+// Zero-highlight client keeps the tests offline and deterministic.
+const offlineClient: TreeSitterClient = {
+  highlightOnce: async () => ({ highlights: [] }),
+} as unknown as TreeSitterClient
+
+async function frameFor(content: string, width = WIDTH) {
+  const setup = await createTestRenderer({ width, height: HEIGHT })
+  try {
+    const el = new MarkdownRenderable(setup.renderer, {
+      content,
+      syntaxStyle: SyntaxStyle.create(),
+      treeSitterClient: offlineClient,
+      streaming: true,
+      conceal: true,
+    })
+    setup.renderer.root.add(el)
+    await setup.renderOnce()
+    await setup.renderOnce()
+    await setup.renderOnce()
+    return setup.captureCharFrame().split("\n")
+  } finally {
+    setup.renderer.destroy()
+  }
+}
+
+function reverseArabic(text: string) {
+  return text
+    .split(" ")
+    .reverse()
+    .map((word) => word.split("").reverse().join(""))
+    .join(" ")
+}
+
+describe("mixed-direction markdown paragraphs", () => {
+  test("code spans keep logical word order inside backticks", async () => {
+    const rows = await frameFor("شغّل `npm install opencode-rtl` ثم افتح `package.json`")
+    const row = rows.find((line) => line.includes("npm"))!
+    expect(row).toContain("`npm install opencode-rtl`")
+    expect(row).toContain("`package.json`")
+  })
+
+  test("bold markers and version code spans stay attached", async () => {
+    const rows = await frameFor("**السبب:** النسخة `0.1.9` بتصدر")
+    const row = rows.find((line) => line.includes("0.1.9"))!
+    expect(row).toContain("`0.1.9`")
+    expect(row).toContain("**:ببسلا**")
+    expect(row.match(/\*\*/g)?.length).toBe(2)
+  })
+
+  test("code span with braces, slash and comma stays one LTR unit", async () => {
+    const rows = await frameFor("بيطلب `default { id, effect/setup }` الآن")
+    const row = rows.find((line) => line.includes("default"))!
+    expect(row).toContain("`default { id, effect/setup }`")
+  })
+
+  test("windows path with a space stays one visual run when it fits", async () => {
+    const rows = await frameFor("افتح `C:\\Users\\Muhamed beshir\\.config\\opencode\\opencode.json` الآن")
+    const row = rows.find((line) => line.includes("C:\\Users"))!
+    expect(row).toContain("C:\\Users\\Muhamed beshir\\.config\\opencode\\opencode.json")
+  })
+
+  test("windows path wrapping continues in logical order", async () => {
+    const rows = await frameFor("افتح `C:\\Users\\Muhamed beshir\\.config\\opencode\\opencode.json` الآن", 40)
+    const first = rows.findIndex((line) => line.includes("C:\\Users\\Muhamed"))
+    const second = rows.findIndex((line) => line.includes("beshir\\.config"))
+    expect(first).toBeGreaterThanOrEqual(0)
+    expect(second).toBeGreaterThan(first)
+    expect(rows[first]).toContain("C:\\Users\\Muhamed")
+    expect(rows[second]).toContain("beshir\\.config\\opencode\\opencode.json")
+  })
+
+  test("key:line references stay attached", async () => {
+    const rows = await frameFor("شوف `opencode.json:3` هناك")
+    const row = rows.find((line) => line.includes("opencode.json"))!
+    expect(row).toContain("opencode.json:3")
+  })
+
+  test("urls stay one LTR run", async () => {
+    const rows = await frameFor("حمّل https://example.com/docs/x ثم تابع")
+    const row = rows.find((line) => line.includes("https://"))!
+    expect(row).toContain("https://example.com/docs/x")
+  })
+
+  test("code spans containing Arabic are not pinned left-to-right", async () => {
+    const rows = await frameFor("نفّذ `الأمر` الآن")
+    // Grapheme-correct visual of نفّذ is ذفّن: the shadda travels with its
+    // base letter instead of being dropped or detached.
+    const row = rows.find((line) => line.includes("ذفّن"))!
+    expect(row).toContain(reverseArabic("الأمر"))
+    expect(row).not.toContain("الأمر")
+  })
+
+  test("tashkeel travels with its base letter", async () => {
+    const rows = await frameFor("قال حمّل الملف")
+    const row = rows.find((line) => line.includes("لمّح"))!
+    expect(row).toContain("لمّح")
+  })
+
+  test("long mixed paragraph keeps every token intact and stays right-aligned", async () => {
+    const rows = await frameFor(
+      "**السبب:** النسخة `0.1.9` بتصدر `default { id, server }` لكن `opencode` بيطلب `default { id, effect/setup }` عشان `err_4462d8c`",
+      60,
+    )
+    const text = rows.join("\n")
+    for (const token of [
+      "`0.1.9`",
+      "`default { id, server }`",
+      "`opencode`",
+      "`default { id, effect/setup }`",
+      "`err_4462d8c`",
+    ]) {
+      expect(text).toContain(token)
+    }
+    const first = rows[0]
+    expect(first.replace(/\s+$/, "").length).toBe(60)
+  })
+
+  test("audit: bare english words at the end of a sentence", async () => {
+    const rows = await frameFor("احفظ التغييرات ثم شغّل npm install")
+    const row = rows.find((line) => line.includes("npm install"))!
+    expect(row).toContain("npm install")
+    // An RTL paragraph ending in English puts that run at the visual left,
+    // after the right-alignment padding.
+    expect(row.trimStart().startsWith("npm install")).toBe(true)
+  })
+
+  test("audit: dotted path mid-sentence", async () => {
+    const rows = await frameFor("افتح الملف src/components/Button.tsx ثم عدّل الزر")
+    const row = rows.find((line) => line.includes("src/components/Button.tsx"))!
+    expect(row).toContain("src/components/Button.tsx")
+  })
+
+  test("audit: curly-quoted english phrase", async () => {
+    const rows = await frameFor("اضغط على \u201CSave framing\u201D ثم أكمل")
+    const row = rows.find((line) => line.includes("Save framing"))!
+    expect(row).toContain("Save framing")
+  })
+
+  test("audit: numbers and windows path without spaces", async () => {
+    const rows = await frameFor("تم حفظ 25 ملف في C:\\Users\\Muhamed\\project")
+    const text = rows.join("\n")
+    expect(text).toContain("25")
+    expect(text).toContain("C:\\Users\\Muhamed\\project")
+  })
+
+  test("audit: numbers amid arabic words", async () => {
+    const rows = await frameFor("تم العثور على 131 مشكلة و15 اختبار")
+    const text = rows.join("\n")
+    expect(text).toContain("131")
+    expect(text).toContain("15")
+    expect(text).toContain("ةلكشم")
+    expect(text).toContain("رابتخا")
+  })
+
+  test("audit: bold heading plus command code span", async () => {
+    const rows = await frameFor("**تم الحفظ بنجاح** ثم شغّل `npm test`")
+    const text = rows.join("\n")
+    expect(text).toContain("`npm test`")
+    expect(text.match(/\*\*/g)?.length).toBe(2)
+  })
+
+  test("audit: list item with code span", async () => {
+    const rows = await frameFor("- عنصر عربي مع `code` ثم كلام")
+    const row = rows.find((line) => line.includes("code"))!
+    expect(row).toContain("`code`")
+  })
+
+  test("audit: list item with link keeps the url intact", async () => {
+    const rows = await frameFor("- [رابط عربي](https://example.com) هنا")
+    const row = rows.find((line) => line.includes("https://example.com"))!
+    expect(row).toContain("https://example.com")
+  })
+
+  test("audit: parens, percent, arrow and numbers", async () => {
+    const rows = await frameFor("دعم (CORS) الكامل 100% → تم")
+    const text = rows.join("\n")
+    expect(text).toContain("CORS")
+    expect(text).toContain("100%")
+    expect(text).toContain("→")
+  })
+
+  test("audit: kitchen sink wrapped across lines", async () => {
+    const rows = await frameFor("دعم (CORS) الكامل `src/app.js:10` بنسبة 100% → تم `npm test` الآن", 40)
+    const text = rows.join("\n")
+    for (const token of ["CORS", "src/app.js:10", "100%", "→", "npm test"]) {
+      expect(text).toContain(token)
+    }
+    expect(rows[0].replace(/\s+$/, "").length).toBe(40)
+  })
+
+  test("audit: tool output prose keeps mixed runs ordered", async () => {
+    const setup = await createTestRenderer({ width: 80, height: 8 })
+    try {
+      const { BidiTextRenderable } = await import("../../src/component/bidi-text")
+      const el = new BidiTextRenderable(setup.renderer, {
+        content: "فشل errorHandler في `config.json:3`",
+        width: 80,
+      })
+      setup.renderer.root.add(el)
+      await setup.renderOnce()
+      const row = setup.captureCharFrame().split("\n")[0]
+      expect(row).toContain("errorHandler")
+      expect(row).toContain("config.json:3")
+    } finally {
+      setup.renderer.destroy()
+    }
+  })
+
+  test("audit: diff lines keep code structure with arabic comments readable", async () => {
+    const setup = await createTestRenderer({ width: 80, height: 8 })
+    try {
+      const { DiffRenderable } = await import("@opentui/core")
+      const el = new DiffRenderable(setup.renderer, {
+        diff: "--- a/f.js\n+++ b/f.js\n@@ -1 +1 @@\n-// hello\n+// مرحبا بالعالم\n",
+        syntaxStyle: SyntaxStyle.create(),
+      })
+      setup.renderer.root.add(el)
+      await setup.renderOnce()
+      await setup.renderOnce()
+      const text = setup.captureCharFrame()
+      expect(text).toContain("// hello")
+      expect(text).toContain("ملاعلاب ابحرم")
+    } finally {
+      setup.renderer.destroy()
+    }
+  })
+})
diff --git a/packages/tui/test/component/bidi-render.test.tsx b/packages/tui/test/component/bidi-render.test.tsx
new file mode 100644
index 000000000000..0ff6b54cbddc
--- /dev/null
+++ b/packages/tui/test/component/bidi-render.test.tsx
@@ -0,0 +1,282 @@
+import { describe, expect, test } from "bun:test"
+import {
+  MarkdownRenderable,
+  SyntaxStyle,
+  TextRenderable,
+  TextareaRenderable,
+  type TreeSitterClient,
+} from "@opentui/core"
+import { createTestRenderer, type TestRendererSetup } from "@opentui/core/testing"
+import { BidiTextRenderable } from "../../src/component/bidi-text"
+import { BidiTextareaRenderable } from "../../src/component/bidi-textarea"
+import "../../src/component/bidi-elements"
+
+const WIDTH = 40
+const HEIGHT = 12
+
+// Zero-highlight client keeps the markdown tests offline and deterministic:
+// chunks still flow through onChunks (our capture hook).
+const offlineClient: TreeSitterClient = {
+  highlightOnce: async () => ({ highlights: [] }),
+} as unknown as TreeSitterClient
+
+function row(frame: string, index: number) {
+  // Frames join rows with newlines and cells can hold multi-unit graphemes,
+  // so slice by row instead of by fixed character offsets.
+  return frame.split("\n")[index] ?? ""
+}
+
+function reverseArabic(text: string) {
+  return text
+    .split(" ")
+    .reverse()
+    .map((word) => (word === "npm install" ? word : word.split("").reverse().join("")))
+    .join(" ")
+}
+
+async function withRenderer(run: (setup: TestRendererSetup) => Promise<void>) {
+  const setup = await createTestRenderer({ width: WIDTH, height: HEIGHT })
+  try {
+    await run(setup)
+  } finally {
+    setup.renderer.destroy()
+  }
+}
+
+describe("bidi text rendering", () => {
+  test("Arabic renders right-aligned in visual RTL order", async () => {
+    await withRenderer(async (setup) => {
+      const el = new BidiTextRenderable(setup.renderer, { content: "مرحبا بالعالم", width: WIDTH })
+      setup.renderer.root.add(el)
+      await setup.renderOnce()
+      const line = row(setup.captureCharFrame(), 0)
+      // Right-aligned: leading padding, content flush with the right edge.
+      expect(line.startsWith(" ")).toBe(true)
+      expect(line.trimEnd().length).toBe(WIDTH)
+      expect(line.trim()).toBe(reverseArabic("مرحبا بالعالم"))
+    })
+  })
+
+  test("mixed Arabic and English keeps the English run LTR", async () => {
+    await withRenderer(async (setup) => {
+      const el = new BidiTextRenderable(setup.renderer, { content: "استخدم npm install هنا", width: WIDTH })
+      setup.renderer.root.add(el)
+      await setup.renderOnce()
+      const line = row(setup.captureCharFrame(), 0)
+      expect(line).toContain("npm install")
+      expect(line.trimEnd().endsWith("مدختسا")).toBe(true)
+    })
+  })
+
+  test("English-only output is identical to the stock text renderer", async () => {
+    const english = "the quick brown fox jumps over the lazy dog again"
+    const stockFrame = await withRendererFrame(async (setup) => {
+      const el = new TextRenderable(setup.renderer, { content: english, width: WIDTH })
+      setup.renderer.root.add(el)
+      await setup.renderOnce()
+      return setup.captureCharFrame()
+    })
+    const bidiFrame = await withRendererFrame(async (setup) => {
+      const el = new BidiTextRenderable(setup.renderer, { content: english, width: WIDTH })
+      setup.renderer.root.add(el)
+      await setup.renderOnce()
+      return setup.captureCharFrame()
+    })
+    expect(bidiFrame).toBe(stockFrame)
+  })
+
+  test("logical text is preserved for copy/paste and wrapping sync", async () => {
+    await withRenderer(async (setup) => {
+      const el = new BidiTextRenderable(setup.renderer, { content: "مرحبا بالعالم", width: WIDTH })
+      setup.renderer.root.add(el)
+      await setup.renderOnce()
+      // The native buffer holds the wrapped logical text, never reordered
+      // or control-polluted characters.
+      expect(el.plainText).toBe("مرحبا بالعالم")
+      expect(el.plainText).not.toContain("\u2066")
+    })
+  })
+})
+
+async function withRendererFrame(run: (setup: TestRendererSetup) => Promise<string>) {
+  const setup = await createTestRenderer({ width: WIDTH, height: HEIGHT })
+  try {
+    return await run(setup)
+  } finally {
+    setup.renderer.destroy()
+  }
+}
+
+describe("bidi markdown rendering", () => {
+  test("Arabic paragraph renders RTL and right-aligned", async () => {
+    await withRenderer(async (setup) => {
+      const el = new MarkdownRenderable(setup.renderer, {
+        content: "مرحبا بالعالم",
+        syntaxStyle: SyntaxStyle.create(),
+        treeSitterClient: offlineClient,
+      })
+      setup.renderer.root.add(el)
+      await setup.renderOnce()
+      await setup.renderOnce()
+      const line = row(setup.captureCharFrame(), 0)
+      expect(line.replace(/\s+$/, "").length).toBe(WIDTH)
+      expect(line).toContain(reverseArabic("مرحبا بالعالم"))
+    })
+  })
+
+  test("fenced code blocks stay LTR and left-aligned", async () => {
+    await withRenderer(async (setup) => {
+      const el = new MarkdownRenderable(setup.renderer, {
+        content: "```ts\nconst value = 42\n```",
+        syntaxStyle: SyntaxStyle.create(),
+        treeSitterClient: offlineClient,
+      })
+      setup.renderer.root.add(el)
+      await setup.renderOnce()
+      await setup.renderOnce()
+      const line = row(setup.captureCharFrame(), 0)
+      expect(line.startsWith("const value = 42")).toBe(true)
+    })
+  })
+
+  test("Arabic paragraph with inline code keeps the code LTR", async () => {
+    await withRenderer(async (setup) => {
+      const el = new MarkdownRenderable(setup.renderer, {
+        content: "استخدم `npm install` لتثبيت الحزمة",
+        syntaxStyle: SyntaxStyle.create(),
+        treeSitterClient: offlineClient,
+      })
+      setup.renderer.root.add(el)
+      await setup.renderOnce()
+      await setup.renderOnce()
+      const line = row(setup.captureCharFrame(), 0)
+      expect(line).toContain("npm install")
+      expect(line.trimEnd().endsWith("مدختسا")).toBe(true)
+    })
+  })
+
+  test("style-only re-highlight keeps painting RTL without crashing", async () => {
+    await withRenderer(async (setup) => {
+      const el = new MarkdownRenderable(setup.renderer, {
+        content: "مرحبا بالعالم",
+        syntaxStyle: SyntaxStyle.create(),
+        treeSitterClient: offlineClient,
+      })
+      setup.renderer.root.add(el)
+      await setup.renderOnce()
+      await setup.renderOnce()
+      // A theme change re-runs tree-sitter with identical text; the patched
+      // block must rebuild from the new chunks instead of painting stale
+      // (or missing) layout state.
+      el.syntaxStyle = SyntaxStyle.create()
+      await setup.renderOnce()
+      await setup.renderOnce()
+      const line = row(setup.captureCharFrame(), 0)
+      expect(line).toContain(reverseArabic("مرحبا بالعالم"))
+    })
+  })
+})
+
+describe("bidi textarea rendering", () => {
+  test("Arabic prompt renders RTL while the value stays logical", async () => {
+    await withRenderer(async (setup) => {
+      const el = new BidiTextareaRenderable(setup.renderer, { width: WIDTH })
+      setup.renderer.root.add(el)
+      el.focus()
+      el.insertText("ازيك يا صاحبي")
+      await setup.renderOnce()
+      const line = row(setup.captureCharFrame(), 0)
+      // Visual order is the RTL sequence aligned to the right edge.
+      expect(line.replace(/\s+$/, "").length).toBe(WIDTH)
+      expect(line).toContain(
+        "ازيك يا صاحبي".split(" ").reverse().map((w) => w.split("").reverse().join("")).join(" "),
+      )
+      // The underlying value is untouched logical Unicode.
+      expect(el.plainText).toBe("ازيك يا صاحبي")
+    })
+  })
+
+  test("tashkeel travels with its base letter in the prompt", async () => {
+    await withRenderer(async (setup) => {
+      const el = new BidiTextareaRenderable(setup.renderer, { width: WIDTH })
+      setup.renderer.root.add(el)
+      el.focus()
+      el.insertText("نفّذ")
+      await setup.renderOnce()
+      const line = row(setup.captureCharFrame(), 0)
+      expect(line).toContain("ذفّن")
+      expect(el.plainText).toBe("نفّذ")
+    })
+  })
+
+  test("English prompt renders exactly like the stock textarea", async () => {
+    const stock = await withRendererFrame(async (setup) => {
+      const el = new TextareaRenderable(setup.renderer, { width: WIDTH })
+      setup.renderer.root.add(el)
+      el.focus()
+      el.insertText("hello world")
+      await setup.renderOnce()
+      return setup.captureCharFrame()
+    })
+    const bidi = await withRendererFrame(async (setup) => {
+      const el = new BidiTextareaRenderable(setup.renderer, { width: WIDTH })
+      setup.renderer.root.add(el)
+      el.focus()
+      el.insertText("hello world")
+      await setup.renderOnce()
+      return setup.captureCharFrame()
+    })
+    expect(bidi).toBe(stock)
+  })
+
+  test("caret sits at the text's visual left edge for the logical end of RTL", async () => {
+    await withRenderer(async (setup) => {
+      const el = new BidiTextareaRenderable(setup.renderer, { width: WIDTH })
+      setup.renderer.root.add(el)
+      el.focus()
+      el.insertText("ازيك يا صاحبي")
+      await setup.renderOnce()
+      // Logical end of an RTL line is the visually leftmost point of the
+      // right-aligned text: width - lineWidth + 1 in 1-based columns.
+      const lineWidth = Bun.stringWidth("ازيك يا صاحبي")
+      const cursor = setup.captureSpans().cursor
+      expect(cursor[0]).toBe(WIDTH - lineWidth + 1)
+    })
+  })
+
+  test("arrow keys move the caret visually", async () => {
+    await withRenderer(async (setup) => {
+      const el = new BidiTextareaRenderable(setup.renderer, { width: WIDTH })
+      setup.renderer.root.add(el)
+      el.focus()
+      el.insertText("استخدم npm install هنا")
+      await setup.renderOnce()
+      // After typing, the caret is at the logical end, which is the visually
+      // leftmost point of the right-aligned RTL text.
+      const start = setup.captureSpans().cursor[0]
+      // Arrow-right steps visually right into the text (logically backward).
+      el.moveCursorRight()
+      await setup.renderOnce()
+      const afterRight = setup.captureSpans().cursor[0]
+      expect(afterRight).toBeGreaterThan(start)
+      // Arrow-left returns visually left toward the logical end.
+      el.moveCursorLeft()
+      await setup.renderOnce()
+      const afterLeft = setup.captureSpans().cursor[0]
+      expect(afterLeft).toBe(start)
+    })
+  })
+
+  test("selection copy returns logical text", async () => {
+    await withRenderer(async (setup) => {
+      const el = new BidiTextareaRenderable(setup.renderer, { width: WIDTH })
+      setup.renderer.root.add(el)
+      el.focus()
+      el.insertText("استخدم npm install هنا")
+      el.setSelection(0, 6)
+      await setup.renderOnce()
+      // Selection copy is logical Unicode, never visual order.
+      expect(el.getSelectedText()).toBe("استخدم")
+    })
+  })
+})
diff --git a/packages/tui/test/util/bidi.test.ts b/packages/tui/test/util/bidi.test.ts
new file mode 100644
index 000000000000..1e37e957d6b4
--- /dev/null
+++ b/packages/tui/test/util/bidi.test.ts
@@ -0,0 +1,208 @@
+import { describe, expect, test } from "bun:test"
+import {
+  boundaryToLogicalCursor,
+  boundaryToVisual,
+  hasRtl,
+  layoutBidiText,
+  logicalCursorToBoundary,
+  visualStep,
+  visualToBoundary,
+  wrappedLogicalText,
+  type BidiLayout,
+} from "../../src/util/bidi"
+
+function visualText(layout: BidiLayout, line = 0) {
+  return layout.lines[line].cells.map((cell) => cell.char).join("")
+}
+
+// The terminal paints cells left to right, so a correct RTL rendering shows
+// the word order reversed and each RTL word's characters reversed, while LTR
+// islands stay intact.
+function rtlVisual(text: string) {
+  return text
+    .split(" ")
+    .reverse()
+    .map((word) => (hasRtl(word) ? word.split("").reverse().join("") : word))
+    .join(" ")
+}
+
+describe("bidi direction detection", () => {
+  test("English-only text is not RTL and needs no bidi work", () => {
+    expect(hasRtl("hello world")).toBe(false)
+    expect(hasRtl("use npm install src/components/Button.tsx https://example.com 25 files")).toBe(false)
+  })
+
+  test("Arabic, Persian and Hebrew are detected", () => {
+    expect(hasRtl("مرحبا بالعالم")).toBe(true)
+    expect(hasRtl("سلام دنیا")).toBe(true)
+    expect(hasRtl("שלום עולם")).toBe(true)
+    expect(hasRtl("اردو")).toBe(true)
+  })
+
+  test("paragraph direction follows the first strong character", () => {
+    // A paragraph is not RTL merely because it contains an English
+    // identifier; the Arabic first strong character wins.
+    const arabic = layoutBidiText("استخدم npm install لتثبيت الحزمة", 80)
+    expect(arabic.lines[0].rtl).toBe(true)
+
+    // An English-led paragraph stays LTR; the embedded Arabic word itself
+    // renders as a reversed RTL run.
+    const english = layoutBidiText("hello مرحبا world", 80)
+    expect(english.lines[0].rtl).toBe(false)
+    expect(english.lines[0].cells.map((c) => c.char).join("")).toBe("hello ابحرم world")
+  })
+})
+
+describe("bidi visual ordering", () => {
+  test("Arabic only reads right to left", () => {
+    const layout = layoutBidiText("مرحبا بالعالم", 80)
+    expect(layout.lines).toHaveLength(1)
+    expect(layout.lines[0].rtl).toBe(true)
+    expect(visualText(layout)).toBe(rtlVisual("مرحبا بالعالم"))
+  })
+
+  test("Arabic + English keeps embedded English words in natural bidi flow", () => {
+    const layout = layoutBidiText("استخدم npm install لتثبيت الحزمة", 80)
+    const visual = visualText(layout)
+    expect(visual).toContain("npm install")
+    // The sentence reads RTL: the trailing Arabic segment sits on the visual
+    // left, the leading Arabic on the visual right.
+    expect(visual.startsWith("ةمزحلا")).toBe(true)
+    expect(visual.endsWith("مدختسا")).toBe(true)
+  })
+
+  test("Arabic + filename treats the path as an LTR isolate", () => {
+    const layout = layoutBidiText("عدّل src/components/Button.tsx ثم عدّل الزر", 80)
+    expect(visualText(layout)).toContain("src/components/Button.tsx")
+  })
+
+  test("Arabic + URL treats the URL as an LTR isolate", () => {
+    const layout = layoutBidiText("افتح https://example.com", 80)
+    const visual = visualText(layout)
+    expect(visual).toContain("https://example.com")
+    expect(visual.endsWith("حتفا")).toBe(true)
+  })
+
+  test("Arabic + numbers keeps digits grouped", () => {
+    const layout = layoutBidiText("تم تحميل 25 ملف", 80)
+    expect(visualText(layout)).toContain("25")
+  })
+
+  test("backtick code spans stay LTR inside Arabic", () => {
+    const layout = layoutBidiText("استخدم `npm install` هنا", 80)
+    const visual = visualText(layout)
+    expect(visual).toContain("npm install")
+  })
+
+  test("brackets mirror in RTL runs", () => {
+    const layout = layoutBidiText("(مرحبا)", 80)
+    const visual = visualText(layout)
+    // Reading RTL: the opening paren sits at the visual right rendered as a
+    // mirrored ")" glyph and vice versa, hugging the reversed word.
+    expect(visual).toBe("(ابحرم)")
+  })
+
+  test("isolate controls never leak into rendered cells or wrapped text", () => {
+    const layout = layoutBidiText("افتح https://example.com من هنا", 80)
+    for (const line of layout.lines) {
+      for (const cell of line.cells) {
+        expect(cell.char).not.toBe("\u2066")
+        expect(cell.char).not.toBe("\u2069")
+      }
+    }
+    expect(wrappedLogicalText(layout)).not.toContain("\u2066")
+    expect(wrappedLogicalText(layout)).not.toContain("\u2069")
+  })
+})
+
+describe("bidi wrapping", () => {
+  test("Arabic wraps across multiple lines without scrambling", () => {
+    const layout = layoutBidiText("هذا نص عربي طويل يجب أن يلتف على عدة أسطر عند العرض داخل نافذة صغيرة", 20)
+    expect(layout.lines.length).toBeGreaterThan(2)
+    for (const line of layout.lines) {
+      expect(line.rtl).toBe(true)
+      expect(line.width).toBeLessThanOrEqual(20)
+    }
+    // Every glyph appears at most once and every non-whitespace glyph is
+    // painted somewhere; whitespace at wrap points is legitimately trimmed.
+    const painted = layout.lines.flatMap((line) => line.cells.map((c) => c.glyph))
+    expect(new Set(painted).size).toBe(painted.length)
+    const expected = layout.glyphs
+      .map((_, index) => index)
+      .filter((index) => !layout.glyphs[index].newline && layout.glyphs[index].char.trim() !== "")
+    for (const index of expected) expect(painted).toContain(index)
+  })
+
+  test("wrapped logical text preserves the original characters", () => {
+    const source = "استخدم npm install لتثبيت الحزمة"
+    const layout = layoutBidiText(source, 12)
+    const wrapped = wrappedLogicalText(layout)
+    // Joining the wrap lines reproduces the source modulo whitespace that
+    // lives at the wrap points.
+    expect(wrapped.replace(/\s+/g, " ").trim()).toBe(source.replace(/\s+/g, " ").trim())
+  })
+
+  test("English-only wrapping is untouched logical order", () => {
+    const layout = layoutBidiText("the quick brown fox jumps over the lazy dog", 12)
+    for (const line of layout.lines) {
+      expect(line.rtl).toBe(false)
+      expect(line.cells.map((c) => c.char).join("")).toBe(
+        layout.glyphs.slice(line.start, line.end).map((g) => g.char).join(""),
+      )
+    }
+  })
+})
+
+describe("bidi cursor mapping", () => {
+  test("logical and visual cursor positions map inversely", () => {
+    const layout = layoutBidiText("ازيك يا صاحبي", 80)
+    for (let boundary = 0; boundary <= layout.glyphs.length; boundary++) {
+      const logical = boundaryToLogicalCursor(layout, boundary)
+      const roundTrip = logicalCursorToBoundary(layout, logical.row, logical.col)
+      expect(roundTrip).toBe(boundary)
+    }
+  })
+
+  test("RTL logical start is the visual right edge and vice versa", () => {
+    const layout = layoutBidiText("ازيك يا صاحبي", 80)
+    const line = layout.lines[0]
+    const start = boundaryToVisual(layout, 0)
+    const end = boundaryToVisual(layout, layout.glyphs.length)
+    expect(start.col).toBe(line.width)
+    expect(end.col).toBe(0)
+  })
+
+  test("arrow stepping moves through visual columns monotonically", () => {
+    const layout = layoutBidiText("استخدم npm install هنا", 80)
+    let boundary = logicalCursorToBoundary(layout, 0, Number.MAX_SAFE_INTEGER)
+    let col = boundaryToVisual(layout, boundary).col
+    const cols: number[] = []
+    for (let step = 0; step < layout.glyphs.length + 2; step++) {
+      const next = visualStep(layout, boundary, 1)
+      const nextCol = boundaryToVisual(layout, next).col
+      if (next === boundary) break
+      cols.push(nextCol)
+      expect(nextCol).toBeGreaterThanOrEqual(col)
+      col = nextCol
+      boundary = next
+    }
+    // The caret can walk the entire line; boundaries that share a visual
+    // column (zero-width adjacency) may be snapped over.
+    expect(cols.length).toBeGreaterThanOrEqual(Math.floor(layout.glyphs.length / 2))
+    // Stepping left reverses the walk.
+    for (let step = 0; step < cols.length; step++) {
+      const back = visualStep(layout, boundary, -1)
+      if (back === boundary) break
+      boundary = back
+    }
+    const logical = boundaryToLogicalCursor(layout, boundary)
+    expect(logical.row).toBe(0)
+  })
+
+  test("visual column maps back to a nearby boundary", () => {
+    const layout = layoutBidiText("استخدم npm install هنا", 80)
+    const boundary = visualToBoundary(layout, 0, 5)
+    const back = boundaryToVisual(layout, boundary)
+    expect(Math.abs(back.col - 5)).toBeLessThanOrEqual(1)
+  })
+})