From bc416786ff552542e73b3fbe9625403ce55073df Mon Sep 17 00:00:00 2001
From: muhamedbeshir <mbeshir011@gmail.com>
Date: Sat, 12 Sep 2026 05:20:49 +0300
Subject: [PATCH 01/10] feat(tui): native bidi/RTL rendering for prompts and
 messages

Render Arabic, Persian, Urdu and Hebrew text correctly in the native TUI using UAX #9, without terminal-side bidi support or destructive text rewriting.

- Add bidi-js based layout engine (direction detection via first strong char, LRI/PDI isolation for URLs/paths/numbers/code spans, grapheme- and width-aware wrapping, logical<->visual caret maps).
- Add BidiTextareaRenderable for the prompt: visual caret placement and visual arrow-key motion while the edit buffer stays logical Unicode.
- Add a markdown renderNode hook for assistant paragraphs/headings; fenced code, tables and diffs keep the stock LTR renderer.
- Add BidiTextRenderable for user message echoes.
- English-only content takes the stock render path unchanged; selection/copy return logical text.
- Tests: engine unit tests, real test-renderer component tests, and an app-level e2e that types Arabic via real key presses and streams an assistant reply.
---
 bun.lock                                      |   3 +
 packages/tui/package.json                     |   1 +
 packages/tui/src/component/bidi-elements.ts   |  18 +
 packages/tui/src/component/bidi-markdown.ts   | 197 +++++++
 packages/tui/src/component/bidi-text.ts       |  66 +++
 packages/tui/src/component/bidi-textarea.ts   | 184 ++++++
 packages/tui/src/component/prompt/index.tsx   |   3 +-
 packages/tui/src/routes/session/index.tsx     |   5 +-
 packages/tui/src/util/bidi.ts                 | 537 ++++++++++++++++++
 packages/tui/test/bidi-e2e.test.tsx           | 223 ++++++++
 .../tui/test/component/bidi-render.test.tsx   | 271 +++++++++
 packages/tui/test/util/bidi.test.ts           | 208 +++++++
 12 files changed, 1714 insertions(+), 2 deletions(-)
 create mode 100644 packages/tui/src/component/bidi-elements.ts
 create mode 100644 packages/tui/src/component/bidi-markdown.ts
 create mode 100644 packages/tui/src/component/bidi-text.ts
 create mode 100644 packages/tui/src/component/bidi-textarea.ts
 create mode 100644 packages/tui/src/util/bidi.ts
 create mode 100644 packages/tui/test/bidi-e2e.test.tsx
 create mode 100644 packages/tui/test/component/bidi-render.test.tsx
 create mode 100644 packages/tui/test/util/bidi.test.ts

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/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/component/bidi-elements.ts b/packages/tui/src/component/bidi-elements.ts
new file mode 100644
index 000000000000..a276563d3c8c
--- /dev/null
+++ b/packages/tui/src/component/bidi-elements.ts
@@ -0,0 +1,18 @@
+import { extend } from "@opentui/solid"
+import { BidiTextRenderable } from "./bidi-text"
+import { BidiTextareaRenderable } from "./bidi-textarea"
+
+// 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.
+extend({
+  bidi_text: BidiTextRenderable,
+  bidi_textarea: BidiTextareaRenderable,
+})
+
+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..2813b248da02
--- /dev/null
+++ b/packages/tui/src/component/bidi-markdown.ts
@@ -0,0 +1,197 @@
+import {
+  CodeRenderable,
+  TextBuffer,
+  type ChunkRenderContext,
+  type OnChunksCallback,
+  type OptimizedBuffer,
+  type RenderNodeContext,
+  type TextChunk,
+} from "@opentui/core"
+import { hasRtl, layoutBidiText, widthOffsetToBoundary, wrappedLogicalText, type BidiLayout } from "../util/bidi"
+
+// Markdown renderNode hook that installs bidi-aware painting on the text
+// blocks (paragraph/heading) of a <markdown> element. Fenced code blocks,
+// tables, diffs and every other block keep the stock LTR renderer, which is
+// the required behavior for code.
+//
+// OpenTUI 0.4.5 offers renderNode as the only per-block override that
+// preserves in-place streaming updates, so the hook patches the default
+// renderable instance: it shadows renderSelf (the paint entrypoint) and
+// wraps the onChunks callback to capture the tree-sitter styled chunks.
+// Nothing else about the renderable changes: measurement, selection, copy
+// and streaming reconciliation continue through the native text buffer,
+// which is kept in sync with the wrapped logical text.
+
+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
+}
+
+const patched = new WeakSet<CodeRenderable>()
+
+// 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
+}
+
+export function bidiMarkdownRenderNode(token: { type: string }, context: RenderNodeContext) {
+  if (token.type !== "paragraph" && token.type !== "heading") return undefined
+  const renderable = context.defaultRender()
+  if (!(renderable instanceof CodeRenderable)) return renderable ?? undefined
+  applyBidiCodePaint(renderable)
+  return renderable
+}
+
+export function applyBidiCodePaint(renderable: CodeRenderable) {
+  if (patched.has(renderable)) return
+  patched.add(renderable)
+
+  const state: BidiCodeState = {
+    styled: undefined,
+    layout: undefined,
+    source: "",
+    wrapped: undefined,
+    width: 0,
+    styledVersion: 0,
+    paintedVersion: -1,
+  }
+  const internals = renderable as unknown as CodeInternals
+  const self = renderable as unknown as { renderSelf(buffer: OptimizedBuffer): void }
+  const originalRenderSelf = self.renderSelf.bind(renderable)
+
+  const originalOnChunks: OnChunksCallback | undefined = renderable.onChunks
+  renderable.onChunks = async (chunks: TextChunk[], context: ChunkRenderContext) => {
+    const result = originalOnChunks ? await originalOnChunks(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
+  }
+
+  self.renderSelf = (buffer: OptimizedBuffer) => {
+    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
+      }
+      originalRenderSelf(buffer)
+      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
+      buffer.setCell(
+        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..5b49523c84cf
--- /dev/null
+++ b/packages/tui/src/component/bidi-text.ts
@@ -0,0 +1,66 @@
+import { TextRenderable, type OptimizedBuffer } from "@opentui/core"
+import { hasRtl, layoutBidiText, 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
+        buffer.setCell(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..efd148da8333
--- /dev/null
+++ b/packages/tui/src/component/bidi-textarea.ts
@@ -0,0 +1,184 @@
+import { TextareaRenderable, type OptimizedBuffer } from "@opentui/core"
+import {
+  boundaryToLogicalCursor,
+  boundaryToVisual,
+  hasRtl,
+  layoutBidiText,
+  logicalCursorToBoundary,
+  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
+        buffer.setCell(
+          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..b2f59362c607 100644
--- a/packages/tui/src/routes/session/index.tsx
+++ b/packages/tui/src/routes/session/index.tsx
@@ -81,6 +81,8 @@ 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 { bidiMarkdownRenderNode } from "../../component/bidi-markdown"
+import "../../component/bidi-elements"
 
 addDefaultParsers(parsers.parsers)
 
@@ -1416,7 +1418,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()}>
@@ -1693,6 +1695,7 @@ function TextPart(props: { last: boolean; part: TextPart; message: AssistantMess
           syntaxStyle={syntax()}
           streaming={true}
           internalBlockMode="top-level"
+          renderNode={bidiMarkdownRenderNode}
           content={props.part.text.trim()}
           tableOptions={{ style: "grid" }}
           conceal={ctx.conceal()}
diff --git a/packages/tui/src/util/bidi.ts b/packages/tui/src/util/bidi.ts
new file mode 100644
index 000000000000..fd1b86ea8a53
--- /dev/null
+++ b/packages/tui/src/util/bidi.ts
@@ -0,0 +1,537 @@
+import bidiFactory from "bidi-js"
+
+// 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 islands embedded in RTL text, matched on logical text and wrapped in
+// LRI/PDI during layout. Bare English words are deliberately not isolated:
+// UAX #9 already renders them as LTR runs and they must stay in natural bidi
+// flow with the surrounding sentence.
+const LTR_ISLAND =
+  /(?:https?:\/\/|www\.)\S+|[A-Za-z0-9_@]+(?:[/\\.-][A-Za-z0-9_@-]+)+|\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]
+
+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.
+function wrapGlyphs(glyphs: BidiGlyph[], start: number, end: number, maxWidth: number) {
+  const ranges: Array<[number, number]> = []
+  const limit = maxWidth > 0 ? maxWidth : Number.POSITIVE_INFINITY
+  let lineStart = start
+  let width = 0
+  let breakAt = -1
+  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
+      continue
+    }
+    if (width + glyph.width > limit && i > lineStart) {
+      if (breakAt > lineStart) {
+        ranges.push([lineStart, breakAt])
+        lineStart = breakAt
+      } else {
+        ranges.push([lineStart, i])
+        lineStart = i
+      }
+      width = 0
+      for (let j = lineStart; j < i; j++) width += glyphs[j].width
+      breakAt = -1
+      for (let j = lineStart; j < i; j++) {
+        if (WHITESPACE.test(glyphs[j].char)) breakAt = j + 1
+      }
+    }
+    width += glyph.width
+    if (WHITESPACE.test(glyph.char)) breakAt = i + 1
+  }
+  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
+}
+
+// Converts a UTF-16 code-unit index into a glyph index using the glyph
+// start-offset table; bidi-js works in code units while layout works in
+// graphemes.
+function unitToGlyph(starts: Uint32Array, unit: number) {
+  let lo = 0
+  let hi = starts.length - 1
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1
+    if (starts[mid] <= unit) lo = mid
+    else hi = mid - 1
+  }
+  return lo
+}
+
+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
+}
+
+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, all converted
+    // to glyph indices and merged so isolates never nest.
+    const detected: Array<[number, number]> = []
+    if (rtlParagraph) {
+      LTR_ISLAND.lastIndex = 0
+      let match = LTR_ISLAND.exec(paraText)
+      while (match) {
+        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, ...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[] = []
+    let islandCursor = 0
+    for (let i = paraStart; i < paraEnd; i++) {
+      while (islandCursor < islands.length && islands[islandCursor][1] < i) islandCursor++
+      const island = islands[islandCursor]
+      if (island && i === island[0]) {
+        augmented.push({ char: LRI, width: 0, charIndex: -1, newline: false, control: true })
+        augmentedToLogical.push(-1)
+      }
+      augmented.push(glyphs[i])
+      augmentedToLogical.push(i)
+      if (island && i === island[1]) {
+        augmented.push({ char: PDI, width: 0, charIndex: -1, newline: false, control: true })
+        augmentedToLogical.push(-1)
+      }
+    }
+
+    // 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)) {
+      const [rangeStart, rangeEnd] = trimEdgeWhitespace(augmented, rawStart, rawEnd)
+      const augmentedGlyphs: number[] = []
+      for (let i = rangeStart; i < rangeEnd; i++) {
+        if (!augmented[i].control) augmentedGlyphs.push(i)
+      }
+      const count = augmentedGlyphs.length
+
+      if (count === 0) {
+        registerLine({ cells: [], width: 0, rtl, start: paraStart, end: paraStart, boundaryCols: [0], logicalWidths: [0] })
+        continue
+      }
+
+      // Visual order starts logical; UAX #9 L2 flip segments are applied as
+      // glyph-range reversals derived from the resolved levels.
+      const order = augmentedGlyphs.slice()
+      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)) {
+          // Flip endpoints may land on LRI/PDI control glyphs, which are not
+          // part of the visual order; clamp to the non-control glyphs inside
+          // the flip range.
+          const fromGlyph = unitToGlyph(starts, fromUnits!)
+          const toGlyph = unitToGlyph(starts, toUnits!)
+          let from = -1
+          let to = -1
+          for (let i = 0; i < order.length; i++) {
+            const glyph = order[i]
+            if (glyph < fromGlyph || glyph > toGlyph) continue
+            if (from === -1) from = i
+            to = i
+          }
+          if (from === -1 || to === -1) continue
+          for (let i = from, j = to; 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) {
+        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 = augmentedGlyphs.map((index) => augmentedToLogical[index])
+      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-e2e.test.tsx b/packages/tui/test/bidi-e2e.test.tsx
new file mode 100644
index 000000000000..c6dd7dc1ee9e
--- /dev/null
+++ b/packages/tui/test/bidi-e2e.test.tsx
@@ -0,0 +1,223 @@
+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)
+
+    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)
+  } finally {
+    await app.exit()
+  }
+}, 60000)
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..f010e6d2b79a
--- /dev/null
+++ b/packages/tui/test/component/bidi-render.test.tsx
@@ -0,0 +1,271 @@
+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 { bidiMarkdownRenderNode } from "../../src/component/bidi-markdown"
+
+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) {
+  return frame.slice(index * WIDTH, (index + 1) * WIDTH)
+}
+
+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(),
+        renderNode: bidiMarkdownRenderNode,
+        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(),
+        renderNode: bidiMarkdownRenderNode,
+        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(),
+        renderNode: bidiMarkdownRenderNode,
+        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(),
+        renderNode: bidiMarkdownRenderNode,
+        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("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)
+  })
+})

From 49e117960cc9d146803dd4a38e02dc3047dfa095 Mon Sep 17 00:00:00 2001
From: muhamedbeshir <mbeshir011@gmail.com>
Date: Sat, 12 Sep 2026 05:20:50 +0300
Subject: [PATCH 02/10] docs(rtl): add bilingual Arabic/English RTL guide and
 Windows install scripts

Document the native bidi/RTL TUI support in English (docs/rtl/README.md) and Arabic (docs/rtl/README.ar.md), and add install-windows.ps1 / restore-windows.ps1 to swap the dev build over the npm-installed opencode binaries.
---
 docs/rtl/README.ar.md        | 121 +++++++++++++++++++++++++++++++
 docs/rtl/README.md           | 134 +++++++++++++++++++++++++++++++++++
 docs/rtl/install-windows.ps1 |  55 ++++++++++++++
 docs/rtl/restore-windows.ps1 |  31 ++++++++
 4 files changed, 341 insertions(+)
 create mode 100644 docs/rtl/README.ar.md
 create mode 100644 docs/rtl/README.md
 create mode 100644 docs/rtl/install-windows.ps1
 create mode 100644 docs/rtl/restore-windows.ps1

diff --git a/docs/rtl/README.ar.md b/docs/rtl/README.ar.md
new file mode 100644
index 000000000000..11531a8e8a98
--- /dev/null
+++ b/docs/rtl/README.ar.md
@@ -0,0 +1,121 @@
+# دعم الكتابة من اليمين لليسار (RTL / BiDi) في واجهة OpenCode النصية
+
+بقى النص العربي والفارسي والأردي والعبري يظهر صح في واجهة OpenCode النصية —
+في **مربع الكتابة (البرومبت)** وفي **ردود المساعد** — عن طريق تنفيذ خوارزمية
+يونيكود للاتجاهين (UAX #9) في طبقة الرسم داخل التطبيق نفسه، من غير أي اعتماد
+على دعم الـ terminal، ومن غير أي إعادة كتابة destructive للنص.
+
+> English: [README.md](./README.md)
+
+## إيه اللي بيشتغل
+
+- **العربي لوحده** يقرأ طبيعي من اليمين لليسار ويتحاذى لليمين.
+- **عربي + إنجليزي** بيفضل الإنجليزي (`npm`، `API`، أسماء المتغيرات) في مكانه
+  الطبيعي حسب ترتيب يونيكود ثنائي الاتجاه.
+- **المقاطع اللاتينية بتفضل LTR**: أكواد inline، أسماء ملفات، مسارات، روابط،
+  أوامر، أسماء حزم، وأرقام — كلها بتتعزل بـ LRI/PDI.
+- **الكود دايمًا LTR**: بلوكات الكود والجداول والـ diffs بتستخدم الراسم
+  الأصلي ومابيتغيرش ترتيبها أبدًا.
+- **الالتفاف (wrapping)** محسوب بالـ grapheme وبعرض الخلية؛ أسطر الالتفاف
+  بتفضل متحاذية يمين وبالترتيب البصري الصح.
+- **مؤشر الكتابة واعي بالاتجاه**: الأسهم بتتحرك بصريًا؛ الكتابة واللصق
+  والتراجع والقيمة المخزنة تفضل يونيكود منطقي.
+- **النسخ واللصق سليم**: التحديد بيرجّع النص المنطقي الأصلي، مش ترتيب بصري
+  ولا حروف تحكم مخفية.
+
+## التثبيت (ويندوز، من نفس المستودع)
+
+```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/bidi-e2e.test.tsx
+bun run --cwd packages/tui typecheck
+```
+
+## حدود معروفة
+
+- **تشكيل** الحروف العربية متروك للـ terminal والخط؛ التعديل ده بيتحكم في
+  الترتيب والاتجاه والمحاذاة، وهوه اللي الراسم الخلوي يقدر يتحكم فيه.
+- إخفاء الماركداون (backticks المخفية) ممكن يفقد ألوان بعض المقاطع لفترة
+  بسيطة وقت البث؛ لكن الترتيب دايمًا صح.
+- `Home`/`End` والقفز بين الكلمات لسه بمنطق الإزاحة المنطقية (سلوك أصلي).
+- الضغط بالماوس في البرومبت لسه بالسلوك الأصلي؛ حركة الكيبورد واعية بالكامل.
diff --git a/docs/rtl/README.md b/docs/rtl/README.md
new file mode 100644
index 000000000000..a9a9c9dbf09d
--- /dev/null
+++ b/docs/rtl/README.md
@@ -0,0 +1,134 @@
+# 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.
+
+## 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/bidi-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/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.
+- `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."

From d7f575417c83d73a4ee8ee9c294296961f12edbd Mon Sep 17 00:00:00 2001
From: muhamedbeshir <mbeshir011@gmail.com>
Date: Sat, 12 Sep 2026 05:43:52 +0300
Subject: [PATCH 03/10] docs(rtl): add Arabic font guidance and Windows
 Terminal fallback script

The TUI cannot select fonts; the terminal does. Document recommended Arabic fonts and add a safe, backed-up script that adds Arabic font fallbacks to Windows Terminal without changing the monospaced main face.
---
 docs/rtl/README.ar.md                        |  8 ++
 docs/rtl/README.md                           |  7 ++
 docs/rtl/configure-windows-terminal-font.ps1 | 89 +++++++++++++++++++
 docs/rtl/fonts.ar.md                         | 91 ++++++++++++++++++++
 docs/rtl/fonts.md                            | 90 +++++++++++++++++++
 5 files changed, 285 insertions(+)
 create mode 100644 docs/rtl/configure-windows-terminal-font.ps1
 create mode 100644 docs/rtl/fonts.ar.md
 create mode 100644 docs/rtl/fonts.md

diff --git a/docs/rtl/README.ar.md b/docs/rtl/README.ar.md
index 11531a8e8a98..a4886ceecd2f 100644
--- a/docs/rtl/README.ar.md
+++ b/docs/rtl/README.ar.md
@@ -23,8 +23,16 @@
 - **النسخ واللصق سليم**: التحديد بيرجّع النص المنطقي الأصلي، مش ترتيب بصري
   ولا حروف تحكم مخفية.
 
+## الخطوط
+
+التطبيق ميقدرش يختار خطوط — الـ terminal هو اللي بيختار. سيب الخط الـ
+monospaced زي ما هو وضيف خط عربي كـ **fallback** (Cairo، Noto Naskh Arabic،
+Segoe UI، Tahoma). التفاصيل في [fonts.ar.md](./fonts.ar.md) والسكربت
+[`configure-windows-terminal-font.ps1`](./configure-windows-terminal-font.ps1).
+
 ## التثبيت (ويندوز، من نفس المستودع)
 
+
 ```powershell
 # 1) تثبيت اعتماديات الـ workspace
 bun install
diff --git a/docs/rtl/README.md b/docs/rtl/README.md
index a9a9c9dbf09d..b156a7c45820 100644
--- a/docs/rtl/README.md
+++ b/docs/rtl/README.md
@@ -23,6 +23,13 @@ terminal-side BiDi requirement and no destructive text rewriting.
 - **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
+add an Arabic-capable font as a **fallback** (Cairo, Noto Naskh Arabic, Segoe
+UI, Tahoma). See [fonts.md](./fonts.md) and the helper script
+[`configure-windows-terminal-font.ps1`](./configure-windows-terminal-font.ps1).
+
 ## Install (Windows, from this repository)
 
 ```powershell
diff --git a/docs/rtl/configure-windows-terminal-font.ps1 b/docs/rtl/configure-windows-terminal-font.ps1
new file mode 100644
index 000000000000..5a65ad9d0a85
--- /dev/null
+++ b/docs/rtl/configure-windows-terminal-font.ps1
@@ -0,0 +1,89 @@
+# Adds Arabic-capable font fallbacks to Windows Terminal so Arabic text renders
+# with proper joining, while keeping your monospaced font for Latin/code.
+#
+# The OpenCode bidi change handles ordering/alignment; this script only handles
+# font selection, which is owned by the terminal, not by the application.
+#
+# Usage (defaults are safe and reversible):
+#   powershell -ExecutionPolicy Bypass -File docs/rtl/configure-windows-terminal-font.ps1
+#   powershell -ExecutionPolicy Bypass -File docs/rtl/configure-windows-terminal-font.ps1 -Face "Cascadia Mono"
+#   powershell -ExecutionPolicy Bypass -File docs/rtl/configure-windows-terminal-font.ps1 -Fallbacks Cairo,"Noto Naskh Arabic","Segoe UI","Tahoma"
+#
+# A timestamped backup of settings.json is written next to it before any change.
+
+param(
+  [string]$Face,
+  [string[]]$Fallbacks = @("Cairo", "Noto Naskh Arabic", "Segoe UI", "Tahoma"),
+  [string]$SettingsPath
+)
+
+$ErrorActionPreference = "Stop"
+
+$candidates = @(
+  (Join-Path $env:LOCALAPPDATA "Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json"),
+  (Join-Path $env:LOCALAPPDATA "Packages\Microsoft.WindowsTerminalPreview_8wekyb3d8bbwe\LocalState\settings.json"),
+  (Join-Path $env:LOCALAPPDATA "Microsoft\Windows Terminal\settings.json")
+)
+
+$settingsPath = $SettingsPath
+if (-not $settingsPath) {
+  $settingsPath = $candidates | Where-Object { Test-Path $_ } | Select-Object -First 1
+}
+if (-not $settingsPath -or -not (Test-Path $settingsPath)) {
+  throw "Windows Terminal settings.json not found. Install Windows Terminal or edit the font manually (see docs/rtl/fonts.md)."
+}
+
+Write-Host "Settings: $settingsPath"
+
+# Report which requested fonts are actually installed.
+$fontFiles = @()
+foreach ($dir in @((Join-Path $env:WINDIR "Fonts"), (Join-Path $env:LOCALAPPDATA "Microsoft\Windows\Fonts"))) {
+  if (Test-Path $dir) {
+    $fontFiles += Get-ChildItem $dir -File -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Name
+  }
+}
+foreach ($name in @($Fallbacks + @($Face)) | Where-Object { $_ } | Select-Object -Unique) {
+  $needle = $name -replace "\s", "*"
+  if ($fontFiles -like "*$needle*") {
+    Write-Host "  installed: $name"
+  } else {
+    Write-Host "  NOT installed: $name (install it, or remove it from the fallback list)"
+  }
+}
+
+$backup = "$settingsPath.rtl-backup-" + (Get-Date -Format "yyyyMMdd-HHmmss")
+Copy-Item -LiteralPath $settingsPath -Destination $backup -Force
+Write-Host "Backup:   $backup"
+
+$raw = Get-Content -LiteralPath $settingsPath -Raw
+# Windows Terminal allows // comments; strip full-line comments so Windows
+# PowerShell's JSON parser can read the file. Inline comments are left alone.
+$cleaned = ($raw -split "`n" | Where-Object { $_ -notmatch '^\s*//' }) -join "`n"
+
+$json = $cleaned | ConvertFrom-Json
+
+if (-not $json.profiles) {
+  $json | Add-Member -NotePropertyName profiles -NotePropertyValue ([pscustomobject]@{}) -Force
+}
+if (-not $json.profiles.defaults) {
+  $json.profiles | Add-Member -NotePropertyName defaults -NotePropertyValue ([pscustomobject]@{}) -Force
+}
+if (-not $json.profiles.defaults.font) {
+  $json.profiles.defaults | Add-Member -NotePropertyName font -NotePropertyValue ([pscustomobject]@{}) -Force
+}
+
+$json.profiles.defaults.font | Add-Member -NotePropertyName fallbacks -NotePropertyValue $Fallbacks -Force
+if ($Face) {
+  $json.profiles.defaults.font | Add-Member -NotePropertyName face -NotePropertyValue $Face -Force
+}
+
+$output = $json | ConvertTo-Json -Depth 64
+$utf8 = New-Object System.Text.UTF8Encoding($false)
+[System.IO.File]::WriteAllText($settingsPath, $output, $utf8)
+
+Write-Host ""
+Write-Host "Updated profiles.defaults.font:"
+Write-Host ("  fallbacks = " + ($Fallbacks -join ", "))
+if ($Face) { Write-Host ("  face      = " + $Face) }
+Write-Host ""
+Write-Host "Restart Windows Terminal to apply. To undo, copy the backup over settings.json."
diff --git a/docs/rtl/fonts.ar.md b/docs/rtl/fonts.ar.md
new file mode 100644
index 000000000000..5534513741d2
--- /dev/null
+++ b/docs/rtl/fonts.ar.md
@@ -0,0 +1,91 @@
+# الخطوط العربية وإعداد الـ terminal
+
+التطبيق (TUI) ميقدرش يحمّل أو يختار خطوط. هو بيطلع خلايا يونيكود، والـ terminal
+هو اللي بيرسمها بالخط اللي **أنت** بتختاره. التعديل اللي في المستودع ده بيظبط
+**الترتيب والاتجاه والمحاذاة والالتفاف**؛ أما خط الـ terminal فهو اللي بيخلي
+الحروف العربية تتوصل وتطلع بشكل صح.
+
+> English: [fonts.md](./fonts.md)
+
+## ليه مينفعش نحدد الخط من OpenCode
+
+خلية الـ terminal هي حرف يونيكود واحد بيرسمه محرك خطوط الـ terminal (DirectWrite
+في Windows Terminal). التطبيقات مينفعش تودّي خطوط في المسار ده. اللي التطبيق
+**يقدر** يعمله — واللي بيعمله المستودع ده — هو إنه يحط الحروف الصح في الخلايا
+الصح بالترتيب الصح.
+
+## خطوط عربية مقترحة
+
+| الخط | الطراز | ملاحظات |
+| --- | --- | --- |
+| [Cairo](https://fonts.google.com/specimen/Cairo) | سانس حديث | متناسب العرض؛ الأفضل كـ fallback |
+| [Noto Naskh Arabic](https://fonts.google.com/noto/specimen/Noto+Naskh+Arabic) | نسخ تقليدي | متناسب العرض |
+| [IBM Plex Sans Arabic](https://fonts.google.com/specimen/IBM+Plex+Sans+Arabic) | سانس احترافي | متناسب العرض |
+| [Amiri](https://fonts.google.com/specimen/Amiri) | نسخ كلاسيكي | متناسب العرض |
+| [Tajawal](https://fonts.google.com/specimen/Tajawal) / [Almarai](https://fonts.google.com/specimen/Almarai) | سانس حديث | متناسب العرض |
+
+ويندوز بيجي أصلًا بخطوط **Segoe UI** و **Tahoma** و **Arial** وبيغطوا العربي،
+فالعربي بيظهر من غير أي حاجة — لكن مش دايمًا بأحسن توصيل. تركيب خط من اللي فوق
+بيحسّن شكل التشكيل.
+
+> ملاحظة مهمة: الخطوط دي **متناسبة العرض** مش monospaced. لو حطيت واحد منها كـ
+> `face` أساسي، النص اللاتيني هيبقى غير متساوي العرض والمحاذاة ممكن تخرب. الإعداد
+> الموصى به إنك تسيب الخط الـ monospaced الأساسي وتضيف الخط العربي كـ
+> **fallback**، فالحروف العربية بس هي اللي تستخدمه.
+
+## Windows Terminal
+
+ملف `settings.json` (نسخة المتجر):
+
+```
+%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json
+```
+
+أضف الخطوط العربية كـ fallbacks داخل `profiles.defaults.font`:
+
+```json
+{
+  "profiles": {
+    "defaults": {
+      "font": {
+        "fallbacks": ["Cairo", "Noto Naskh Arabic", "Segoe UI", "Tahoma"]
+      }
+    }
+  }
+}
+```
+
+أو شغّل السكربت الجاهز في نفس المجلد (بيعمل نسخة احتياطية أول حاجة):
+
+```powershell
+powershell -ExecutionPolicy Bypass -File docs/rtl/configure-windows-terminal-font.ps1
+# أو مع تحديد الخط الأساسي كمان:
+powershell -ExecutionPolicy Bypass -File docs/rtl/configure-windows-terminal-font.ps1 -Face "Cascadia Mono"
+```
+
+بعد التعديل اقفل Windows Terminal وافتحه تاني.
+
+## ترمينال VS Code
+
+في `settings.json`:
+
+```json
+{
+  "terminal.integrated.fontFamily": "'Cascadia Mono', 'Cairo', 'Noto Naskh Arabic', monospace"
+}
+```
+
+## الـ Console القديم (conhost)
+
+كليك يمين على شريط العنوان → Properties → Font. التغطية محدودة؛ وWindows
+Terminal أفضل للعربي.
+
+## للتأكد
+
+اكتب في برومبت OpenCode:
+
+```
+أهلاً بك في OpenCode
+```
+
+ولازم تلاقي الكلام مقروء من اليمين لليسار ومحاذى يمين.
diff --git a/docs/rtl/fonts.md b/docs/rtl/fonts.md
new file mode 100644
index 000000000000..fb8f5a75a88c
--- /dev/null
+++ b/docs/rtl/fonts.md
@@ -0,0 +1,90 @@
+# Arabic fonts & terminal setup
+
+The TUI cannot bundle or select fonts. It emits Unicode cells; the terminal
+emulator renders them with a font **you** choose. The bidi work in this
+repository fixes **ordering, direction, alignment and wrapping**; the terminal
+font is what makes Arabic letters join and look right.
+
+> العربية: [fonts.ar.md](./fonts.ar.md)
+
+## Why not set the font from OpenCode
+
+A terminal cell is one Unicode code point drawn by the terminal's font engine
+(DirectWrite on Windows Terminal). Applications cannot ship fonts into that
+pipeline. What an application *can* do — and what this repository does — is put
+the right code points in the right cells in the right order.
+
+## Recommended Arabic-capable fonts
+
+| Font | Style | Notes |
+| --- | --- | --- |
+| [Cairo](https://fonts.google.com/specimen/Cairo) | modern sans | proportional; best used as a fallback |
+| [Noto Naskh Arabic](https://fonts.google.com/noto/specimen/Noto+Naskh+Arabic) | traditional naskh | proportional |
+| [IBM Plex Sans Arabic](https://fonts.google.com/specimen/IBM+Plex+Sans+Arabic) | professional sans | proportional |
+| [Amiri](https://fonts.google.com/specimen/Amiri) | classical naskh | proportional |
+| [Tajawal](https://fonts.google.com/specimen/Tajawal) / [Almarai](https://fonts.google.com/specimen/Almarai) | modern sans | proportional |
+
+Windows already ships **Segoe UI**, **Tahoma** and **Arial**, which cover Arabic
+glyphs, so Arabic renders out of the box — just not always with consistent
+joining. Installing one of the fonts above improves shaping.
+
+> Note: these Arabic fonts are **proportional**, not monospaced. Setting one as
+> the terminal's main `face` makes Latin text non-monospaced and can misalign
+> columns. The recommended setup keeps your monospaced face and adds the Arabic
+> font as a **fallback**, so only Arabic glyphs use it.
+
+## Windows Terminal
+
+`settings.json` (Store build):
+
+```
+%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json
+```
+
+Add Arabic fallbacks to `profiles.defaults.font`:
+
+```json
+{
+  "profiles": {
+    "defaults": {
+      "font": {
+        "fallbacks": ["Cairo", "Noto Naskh Arabic", "Segoe UI", "Tahoma"]
+      }
+    }
+  }
+}
+```
+
+Or run the helper script in this folder, which backs up `settings.json` first:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File docs/rtl/configure-windows-terminal-font.ps1
+# or also set the main face:
+powershell -ExecutionPolicy Bypass -File docs/rtl/configure-windows-terminal-font.ps1 -Face "Cascadia Mono"
+```
+
+Restart Windows Terminal after changing the setting.
+
+## VS Code integrated terminal
+
+`settings.json`:
+
+```json
+{
+  "terminal.integrated.fontFamily": "'Cascadia Mono', 'Cairo', 'Noto Naskh Arabic', monospace"
+}
+```
+
+## Legacy Windows Console (conhost)
+
+Right-click the title bar → Properties → Font. Coverage is limited; Windows
+Terminal is recommended for Arabic.
+
+## Verify
+
+Type this in the OpenCode prompt and confirm the words read right-to-left and
+are right-aligned:
+
+```
+أهلاً بك في OpenCode
+```

From 2a72ea83faef946cd70d9f7f3321927fa57d78f1 Mon Sep 17 00:00:00 2001
From: muhamedbeshir <mbeshir011@gmail.com>
Date: Sat, 12 Sep 2026 09:16:57 +0300
Subject: [PATCH 04/10] feat(tui): add /fonts command to pick the terminal
 Arabic font

The TUI cannot render with its own font, so /fonts is an application-level bridge: it lists installed font families (recommended Arabic fonts first) and writes the choice into Windows Terminal or the VS Code terminal settings, keeping a timestamped backup. It never installs fonts.
---
 docs/rtl/fonts.ar.md                         |  12 +
 docs/rtl/fonts.md                            |  12 +
 packages/tui/src/app.tsx                     |  12 +
 packages/tui/src/component/dialog-fonts.tsx  |  44 ++++
 packages/tui/src/util/terminal-font.ts       | 233 +++++++++++++++++++
 packages/tui/test/util/terminal-font.test.ts |  98 ++++++++
 6 files changed, 411 insertions(+)
 create mode 100644 packages/tui/src/component/dialog-fonts.tsx
 create mode 100644 packages/tui/src/util/terminal-font.ts
 create mode 100644 packages/tui/test/util/terminal-font.test.ts

diff --git a/docs/rtl/fonts.ar.md b/docs/rtl/fonts.ar.md
index 5534513741d2..809a715fcb01 100644
--- a/docs/rtl/fonts.ar.md
+++ b/docs/rtl/fonts.ar.md
@@ -41,6 +41,18 @@
 %LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json
 ```
 
+### اختيار الخط من جوه OpenCode
+
+اكتب `/fonts` في البرومبت وهتفتحلك قايمة الخطوط. بتعرض الخطوط المركّبة على
+جهازك (الخطوط العربية المقترحة في الأول)، وبتحفظ اختيارك في إعدادات الـ terminal
+لوحدها مع نسخة احتياطية. بعد كده اقفل التيرمنال وافتحه تاني. **ومش بتركّب أي خط
+على الجهاز.**
+
+الأمر ده بيعدّل `profiles.defaults.font.fallbacks`، يعني العربي هيستخدم الخط
+اللي اخترته والإنجليزي والكود هيفضلوا بالخط الـ monospaced.
+
+### يدويًا
+
 أضف الخطوط العربية كـ fallbacks داخل `profiles.defaults.font`:
 
 ```json
diff --git a/docs/rtl/fonts.md b/docs/rtl/fonts.md
index fb8f5a75a88c..63b142a39222 100644
--- a/docs/rtl/fonts.md
+++ b/docs/rtl/fonts.md
@@ -41,6 +41,18 @@ joining. Installing one of the fonts above improves shaping.
 %LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json
 ```
 
+### Pick it from inside OpenCode
+
+Type `/fonts` in the prompt to open the font picker. It lists the fonts installed
+on your machine (recommended Arabic fonts first), and writes your choice into
+the terminal's settings for you — keeping a timestamped backup. Then restart the
+terminal. It never installs fonts.
+
+Under the hood it sets `profiles.defaults.font.fallbacks`, so Arabic uses the
+chosen font while Latin and code stay monospaced.
+
+### Manually
+
 Add Arabic fallbacks to `profiles.defaults.font`:
 
 ```json
diff --git a/packages/tui/src/app.tsx b/packages/tui/src/app.tsx
index 3f1da522bb06..a2ddfb69d1b7 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 { DialogFonts } from "./component/dialog-fonts"
 import { DialogHelp } from "./ui/dialog-help"
 import { DialogAgent } from "./component/dialog-agent"
 import { DialogSessionList } from "./component/dialog-session-list"
@@ -745,6 +746,17 @@ function App(props: { onSnapshot?: () => Promise<string[]>; pluginHost: TuiPlugi
         },
         category: "Provider",
       },
+      {
+        name: "font.pick",
+        title: "Terminal font for Arabic",
+        desc: "Choose the font the terminal uses for RTL text",
+        slashName: "fonts",
+        slashAliases: ["font"],
+        run: () => {
+          dialog.replace(() => <DialogFonts />)
+        },
+        category: "System",
+      },
       ...(sync.data.console_state.switchableOrgCount > 1
         ? [
             {
diff --git a/packages/tui/src/component/dialog-fonts.tsx b/packages/tui/src/component/dialog-fonts.tsx
new file mode 100644
index 000000000000..e071581aaf40
--- /dev/null
+++ b/packages/tui/src/component/dialog-fonts.tsx
@@ -0,0 +1,44 @@
+import { DialogSelect } from "../ui/dialog-select"
+import { useDialog } from "../ui/dialog"
+import { useToast } from "../ui/toast"
+import { applyArabicFont, fontChoices } from "../util/terminal-font"
+
+// The TUI cannot render with its own font, so this dialog picks the font the
+// terminal uses for Arabic text and writes it into the terminal's settings
+// (Windows Terminal or VS Code). It never installs fonts.
+export function DialogFonts() {
+  const dialog = useDialog()
+  const toast = useToast()
+  const options = fontChoices().map((choice) => ({
+    title: choice.family,
+    value: choice.family,
+    description: choice.installed
+      ? choice.recommended
+        ? "installed · recommended for Arabic"
+        : "installed"
+      : "not installed — the terminal will fall back to another font",
+    category: choice.recommended ? "Recommended for Arabic" : "All installed fonts",
+  }))
+
+  return (
+    <DialogSelect
+      title="Terminal font for Arabic"
+      placeholder="Search fonts…"
+      options={options}
+      onSelect={(option) => {
+        const result = applyArabicFont(option.value)
+        if (!result.ok) {
+          toast.show({ variant: "error", message: result.message, duration: 6000 })
+          return
+        }
+        dialog.clear()
+        toast.show({
+          variant: "success",
+          message: `${option.value} set in ${result.target}. ${result.hint}`,
+          duration: 10000,
+        })
+      }}
+      footer={`Saved with a backup next to the settings file. The TUI itself cannot choose fonts — the terminal does.`}
+    />
+  )
+}
diff --git a/packages/tui/src/util/terminal-font.ts b/packages/tui/src/util/terminal-font.ts
new file mode 100644
index 000000000000..03ac57b964dd
--- /dev/null
+++ b/packages/tui/src/util/terminal-font.ts
@@ -0,0 +1,233 @@
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+// The TUI cannot render with its own font - the terminal emulator owns text
+// shaping and font selection. This module is the application-level bridge: it
+// detects installed font families and writes the user's choice into the
+// settings of the terminal that actually renders the cells (Windows Terminal
+// or the VS Code integrated terminal), keeping a timestamped backup.
+
+export const RECOMMENDED_ARABIC_FONTS = [
+  "Cairo",
+  "Noto Naskh Arabic",
+  "IBM Plex Sans Arabic",
+  "Amiri",
+  "Tajawal",
+  "Almarai",
+  "Segoe UI",
+  "Tahoma",
+  "Arial",
+] as const
+
+export type FontChoice = { family: string; installed: boolean; recommended: boolean }
+
+export type ApplyOutcome =
+  | { ok: true; target: string; path: string; backup: string; hint: string }
+  | { ok: false; message: string }
+
+function timestamp() {
+  const date = new Date()
+  const pad = (value: number) => String(value).padStart(2, "0")
+  return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`
+}
+
+// JSON with comments (VS Code settings, Windows Terminal settings) is not
+// valid JSON. Strip comments and trailing commas before parsing.
+export function sanitizeJsonc(text: string) {
+  let out = ""
+  let inString = false
+  let quote = ""
+  let index = 0
+  while (index < text.length) {
+    const char = text[index]
+    const next = text[index + 1]
+    if (inString) {
+      out += char
+      if (char === "\\") {
+        out += next ?? ""
+        index += 2
+        continue
+      }
+      if (char === quote) inString = false
+      index++
+      continue
+    }
+    if (char === '"' || char === "'") {
+      inString = true
+      quote = char
+      out += char
+      index++
+      continue
+    }
+    if (char === "/" && next === "/") {
+      while (index < text.length && text[index] !== "\n") index++
+      continue
+    }
+    if (char === "/" && next === "*") {
+      index += 2
+      while (index < text.length && !(text[index] === "*" && text[index + 1] === "/")) index++
+      index += 2
+      continue
+    }
+    out += char
+    index++
+  }
+  return out.replace(/,(\s*[}\]])/g, "$1")
+}
+
+export function windowsTerminalSettingsPath(): string | undefined {
+  if (!process.env.LOCALAPPDATA) return undefined
+  const candidates = [
+    path.join(
+      process.env.LOCALAPPDATA,
+      "Packages/Microsoft.WindowsTerminal_8wekyb3d8bbwe/LocalState/settings.json",
+    ),
+    path.join(
+      process.env.LOCALAPPDATA,
+      "Packages/Microsoft.WindowsTerminalPreview_8wekyb3d8bbwe/LocalState/settings.json",
+    ),
+    path.join(process.env.LOCALAPPDATA, "Microsoft/Windows Terminal/settings.json"),
+  ]
+  return candidates.find((candidate) => existsSync(candidate))
+}
+
+export function vscodeSettingsPath(): string | undefined {
+  if (!process.env.APPDATA) return undefined
+  const candidates = [
+    path.join(process.env.APPDATA, "Code/User/settings.json"),
+    path.join(process.env.APPDATA, "Code - Insiders/User/settings.json"),
+  ]
+  return candidates.find((candidate) => existsSync(candidate))
+}
+
+function backup(file: string) {
+  const target = `${file}.opencode-backup-${timestamp()}`
+  copyFileSync(file, target)
+  return target
+}
+
+function readJsonc(file: string) {
+  return JSON.parse(sanitizeJsonc(readFileSync(file, "utf8"))) as Record<string, unknown>
+}
+
+function writeJson(file: string, value: unknown) {
+  writeFileSync(file, JSON.stringify(value, null, 4), { encoding: "utf8" })
+}
+
+export function readWindowsTerminalFont(): { face?: string; fallbacks: string[] } | undefined {
+  const file = windowsTerminalSettingsPath()
+  if (!file) return undefined
+  const json = readJsonc(file)
+  const defaults = (json.profiles as Record<string, unknown> | undefined)?.defaults as
+    | Record<string, unknown>
+    | undefined
+  const font = defaults?.font as { face?: unknown; fallbacks?: unknown } | undefined
+  return {
+    face: typeof font?.face === "string" ? font.face : undefined,
+    fallbacks: Array.isArray(font?.fallbacks) ? font.fallbacks.filter((item): item is string => typeof item === "string") : [],
+  }
+}
+
+export function writeWindowsTerminalFont(input: { face?: string; fallbacks: string[] }): {
+  path: string
+  backup: string
+} {
+  const file = windowsTerminalSettingsPath()
+  if (!file) throw new Error("Windows Terminal settings.json not found")
+  const created = backup(file)
+  const json = readJsonc(file)
+  const profiles = (json.profiles ??= {}) as Record<string, unknown>
+  const defaults = (profiles.defaults ??= {}) as Record<string, unknown>
+  const font = (defaults.font ??= {}) as Record<string, unknown>
+  font.fallbacks = [...input.fallbacks]
+  if (input.face !== undefined) font.face = input.face
+  writeJson(file, json)
+  return { path: file, backup: created }
+}
+
+export function appendFontFamily(existing: string | undefined, family: string) {
+  const parts = (existing ?? "")
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean)
+  const unquoted = (value: string) => value.replace(/^['"]|['"]$/g, "")
+  if (parts.some((part) => unquoted(part) === family)) return parts.join(", ")
+  const trailing = parts.length > 0 && unquoted(parts[parts.length - 1]).toLowerCase() === "monospace" ? parts.pop() : undefined
+  parts.push(`'${family}'`)
+  if (trailing !== undefined) parts.push(trailing)
+  return parts.join(", ")
+}
+
+export function writeVSCodeFontFamily(family: string): { path: string; backup: string } {
+  const file = vscodeSettingsPath()
+  if (!file) throw new Error("VS Code settings.json not found")
+  const created = backup(file)
+  const json = readJsonc(file)
+  const key = "terminal.integrated.fontFamily"
+  const existing = typeof json[key] === "string" ? (json[key] as string) : undefined
+  json[key] = appendFontFamily(existing, family)
+  writeJson(file, json)
+  return { path: file, backup: created }
+}
+
+export function installedFontFamilies(): string[] {
+  if (process.platform !== "win32") return []
+  const roots = [
+    "HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\Fonts",
+    "HKCU\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\Fonts",
+  ]
+  const found = new Set<string>()
+  for (const root of roots) {
+    const result = Bun.spawnSync(["reg", "query", root], { stdout: "pipe", stderr: "ignore" })
+    if (result.exitCode !== 0) continue
+    for (const line of result.stdout.toString().split(/\r?\n/)) {
+      const match = line.match(/^\s+(.+?)\s+REG_SZ\s+/)
+      if (!match) continue
+      const family = match[1].replace(/\s+\((TrueType|OpenType|All res|Type 1)\)\s*$/i, "").trim()
+      if (family) found.add(family)
+    }
+  }
+  return [...found].sort((a, b) => a.localeCompare(b, undefined, { sensitivity: "base" }))
+}
+
+export function isFontInstalled(family: string, installed = installedFontFamilies()) {
+  return installed.some((name) => name === family || name.startsWith(`${family} `))
+}
+
+export function fontChoices(): FontChoice[] {
+  const installed = installedFontFamilies()
+  const recommended: FontChoice[] = RECOMMENDED_ARABIC_FONTS.map((family) => ({
+    family,
+    installed: isFontInstalled(family, installed),
+    recommended: true,
+  }))
+  const others: FontChoice[] = installed
+    .filter((name) => !recommended.some((choice) => name === choice.family || name.startsWith(`${choice.family} `)))
+    .map((family) => ({ family, installed: true, recommended: false }))
+  return [...recommended, ...others]
+}
+
+export function applyArabicFont(family: string): ApplyOutcome {
+  if (windowsTerminalSettingsPath()) {
+    const fallbacks = [family, ...RECOMMENDED_ARABIC_FONTS.filter((item) => item !== family)]
+    const written = writeWindowsTerminalFont({ fallbacks })
+    return {
+      ok: true,
+      target: "Windows Terminal",
+      path: written.path,
+      backup: written.backup,
+      hint: "Close every Windows Terminal window and reopen it for the font to take effect.",
+    }
+  }
+  if (vscodeSettingsPath()) {
+    const written = writeVSCodeFontFamily(family)
+    return {
+      ok: true,
+      target: "VS Code integrated terminal",
+      path: written.path,
+      backup: written.backup,
+      hint: "Open a new terminal in VS Code for the font to take effect.",
+    }
+  }
+  return { ok: false, message: "No supported terminal settings found (Windows Terminal or VS Code)." }
+}
diff --git a/packages/tui/test/util/terminal-font.test.ts b/packages/tui/test/util/terminal-font.test.ts
new file mode 100644
index 000000000000..d2cf486e1fa0
--- /dev/null
+++ b/packages/tui/test/util/terminal-font.test.ts
@@ -0,0 +1,98 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import {
+  RECOMMENDED_ARABIC_FONTS,
+  appendFontFamily,
+  applyArabicFont,
+  isFontInstalled,
+  sanitizeJsonc,
+} from "../../src/util/terminal-font"
+
+const roots: string[] = []
+const env = { local: process.env.LOCALAPPDATA, appdata: process.env.APPDATA }
+
+function tempDir() {
+  const dir = mkdtempSync(path.join(tmpdir(), "oc-font-"))
+  roots.push(dir)
+  return dir
+}
+
+afterEach(() => {
+  process.env.LOCALAPPDATA = env.local
+  process.env.APPDATA = env.appdata
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+describe("sanitizeJsonc", () => {
+  test("removes line, block comments and trailing commas", () => {
+    const input = `{
+      // a comment
+      "a": 1, /* inline */
+      "b": [1, 2,],
+    }`
+    expect(JSON.parse(sanitizeJsonc(input))).toEqual({ a: 1, b: [1, 2] })
+  })
+
+  test("does not touch comment markers inside strings", () => {
+    const input = `{ "url": "https://example.com//x", "a": 1 }`
+    expect(JSON.parse(sanitizeJsonc(input))).toEqual({ url: "https://example.com//x", a: 1 })
+  })
+})
+
+describe("appendFontFamily", () => {
+  test("appends and keeps monospace last", () => {
+    expect(appendFontFamily("'Cascadia Mono', monospace", "Cairo")).toBe("'Cascadia Mono', 'Cairo', monospace")
+  })
+
+  test("is idempotent", () => {
+    expect(appendFontFamily("'Cairo', monospace", "Cairo")).toBe("'Cairo', monospace")
+  })
+
+  test("starts a list when unset", () => {
+    expect(appendFontFamily(undefined, "Noto Naskh Arabic")).toBe("'Noto Naskh Arabic'")
+  })
+})
+
+describe("isFontInstalled", () => {
+  test("matches exact names and named instances", () => {
+    const installed = ["Cairo", "Cairo Black", "Tahoma"]
+    expect(isFontInstalled("Cairo", installed)).toBe(true)
+    expect(isFontInstalled("Tahoma", installed)).toBe(true)
+    expect(isFontInstalled("Amiri", installed)).toBe(false)
+  })
+})
+
+describe("applyArabicFont", () => {
+  test("writes Windows Terminal fallbacks and keeps a backup", () => {
+    const root = tempDir()
+    const settings = path.join(root, "Packages/Microsoft.WindowsTerminal_8wekyb3d8bbwe/LocalState/settings.json")
+    mkdirSync(path.dirname(settings), { recursive: true })
+    writeFileSync(settings, JSON.stringify({ profiles: { defaults: { font: { face: "Cascadia Mono" } } } }))
+    process.env.LOCALAPPDATA = root
+    process.env.APPDATA = path.join(root, "no-vscode")
+
+    const result = applyArabicFont("Amiri")
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    expect(result.target).toBe("Windows Terminal")
+
+    const written = JSON.parse(readFileSync(settings, "utf8"))
+    expect(written.profiles.defaults.font.face).toBe("Cascadia Mono")
+    expect(written.profiles.defaults.font.fallbacks[0]).toBe("Amiri")
+    for (const font of RECOMMENDED_ARABIC_FONTS) {
+      if (font === "Amiri") continue
+      expect(written.profiles.defaults.font.fallbacks).toContain(font)
+    }
+    expect(readFileSync(result.backup, "utf8")).toContain("Cascadia Mono")
+  })
+
+  test("reports failure when no supported terminal exists", () => {
+    const root = tempDir()
+    process.env.LOCALAPPDATA = path.join(root, "missing")
+    process.env.APPDATA = path.join(root, "missing2")
+    const result = applyArabicFont("Cairo")
+    expect(result.ok).toBe(false)
+  })
+})

From c02fb2bb6f99fff0c60879225cdc9eaa81c8dcbf Mon Sep 17 00:00:00 2001
From: muhamedbeshir <mbeshir011@gmail.com>
Date: Sat, 12 Sep 2026 09:54:54 +0300
Subject: [PATCH 05/10] fix(tui): render RTL on all text surfaces and repair
 the font picker

- Wrap the /fonts dialog footer in <text> so the dialog no longer crashes
  with an orphan-text error and actually opens.
- Register BidiTextRenderable as the global 	ext component so RTL
  ordering/alignment works in dialogs, lists, tool output and toasts,
  not only in the prompt and message bodies. English-only content still
  takes the stock paint path.
- Detect the hosting terminal (Windows Terminal vs VS Code) before writing
  the Arabic font, and preserve existing fallbacks instead of replacing them.
- Add e2e coverage for the dialog and host detection.
---
 packages/tui/src/app.tsx                     |   1 +
 packages/tui/src/component/bidi-elements.ts  |   7 +
 packages/tui/src/component/dialog-fonts.tsx  |   4 +-
 packages/tui/src/util/terminal-font.ts       |  80 ++++++---
 packages/tui/test/bidi-dialogs-e2e.test.tsx  | 161 +++++++++++++++++++
 packages/tui/test/util/terminal-font.test.ts |  66 +++++++-
 6 files changed, 296 insertions(+), 23 deletions(-)
 create mode 100644 packages/tui/test/bidi-dialogs-e2e.test.tsx

diff --git a/packages/tui/src/app.tsx b/packages/tui/src/app.tsx
index a2ddfb69d1b7..fc25f2f84d85 100644
--- a/packages/tui/src/app.tsx
+++ b/packages/tui/src/app.tsx
@@ -46,6 +46,7 @@ import { DialogStatus } from "./component/dialog-status"
 import { DialogDebug } from "./component/dialog-debug"
 import { DialogThemeList } from "./component/dialog-theme-list"
 import { DialogFonts } from "./component/dialog-fonts"
+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
index a276563d3c8c..201e4d8fac8d 100644
--- a/packages/tui/src/component/bidi-elements.ts
+++ b/packages/tui/src/component/bidi-elements.ts
@@ -5,7 +5,14 @@ import { BidiTextareaRenderable } from "./bidi-textarea"
 // 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.
 extend({
+  text: BidiTextRenderable,
   bidi_text: BidiTextRenderable,
   bidi_textarea: BidiTextareaRenderable,
 })
diff --git a/packages/tui/src/component/dialog-fonts.tsx b/packages/tui/src/component/dialog-fonts.tsx
index e071581aaf40..848008db2669 100644
--- a/packages/tui/src/component/dialog-fonts.tsx
+++ b/packages/tui/src/component/dialog-fonts.tsx
@@ -38,7 +38,9 @@ export function DialogFonts() {
           duration: 10000,
         })
       }}
-      footer={`Saved with a backup next to the settings file. The TUI itself cannot choose fonts — the terminal does.`}
+      footer={
+        <text>Saved with a backup next to the settings file. The TUI itself cannot choose fonts — the terminal does.</text>
+      }
     />
   )
 }
diff --git a/packages/tui/src/util/terminal-font.ts b/packages/tui/src/util/terminal-font.ts
index 03ac57b964dd..fed43a106a9a 100644
--- a/packages/tui/src/util/terminal-font.ts
+++ b/packages/tui/src/util/terminal-font.ts
@@ -139,12 +139,29 @@ export function writeWindowsTerminalFont(input: { face?: string; fallbacks: stri
   const profiles = (json.profiles ??= {}) as Record<string, unknown>
   const defaults = (profiles.defaults ??= {}) as Record<string, unknown>
   const font = (defaults.font ??= {}) as Record<string, unknown>
-  font.fallbacks = [...input.fallbacks]
+  const existing = Array.isArray(font.fallbacks)
+    ? font.fallbacks.filter((item): item is string => typeof item === "string")
+    : []
+  font.fallbacks = mergeFallbacks(existing, input.fallbacks)
   if (input.face !== undefined) font.face = input.face
   writeJson(file, json)
   return { path: file, backup: created }
 }
 
+// Keeps the user's existing fallbacks after the Arabic ones so choosing a font
+// never drops a fallback the terminal already relied on.
+export function mergeFallbacks(existing: string[], incoming: string[]) {
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const family of [...incoming, ...existing]) {
+    const key = family.trim().toLowerCase()
+    if (!key || seen.has(key)) continue
+    seen.add(key)
+    out.push(family)
+  }
+  return out
+}
+
 export function appendFontFamily(existing: string | undefined, family: string) {
   const parts = (existing ?? "")
     .split(",")
@@ -207,27 +224,48 @@ export function fontChoices(): FontChoice[] {
   return [...recommended, ...others]
 }
 
+export type TerminalHost = "windows-terminal" | "vscode" | "other"
+
+// Which terminal is actually hosting this process. Picking the settings file by
+// presence alone is wrong when both Windows Terminal and VS Code are installed:
+// the dialog must write the settings of the terminal that renders the cells.
+export function detectTerminalHost(env: NodeJS.ProcessEnv = process.env): TerminalHost {
+  if (env.WT_SESSION) return "windows-terminal"
+  if (env.TERM_PROGRAM === "vscode" || env.VSCODE_INJECTION || env.VSCODE_IPC_HOOK_CLI) return "vscode"
+  return "other"
+}
+
 export function applyArabicFont(family: string): ApplyOutcome {
-  if (windowsTerminalSettingsPath()) {
-    const fallbacks = [family, ...RECOMMENDED_ARABIC_FONTS.filter((item) => item !== family)]
-    const written = writeWindowsTerminalFont({ fallbacks })
-    return {
-      ok: true,
-      target: "Windows Terminal",
-      path: written.path,
-      backup: written.backup,
-      hint: "Close every Windows Terminal window and reopen it for the font to take effect.",
-    }
+  const host = detectTerminalHost()
+  const windowsTerminal = windowsTerminalSettingsPath()
+  const vscode = vscodeSettingsPath()
+
+  if (host === "windows-terminal" && windowsTerminal) return applyWindowsTerminalFont(family)
+  if (host === "vscode" && vscode) return applyVSCodeFont(family)
+  if (windowsTerminal) return applyWindowsTerminalFont(family)
+  if (vscode) return applyVSCodeFont(family)
+  return { ok: false, message: "No supported terminal settings found (Windows Terminal or VS Code)." }
+}
+
+function applyWindowsTerminalFont(family: string): ApplyOutcome {
+  const fallbacks = [family, ...RECOMMENDED_ARABIC_FONTS.filter((item) => item !== family)]
+  const written = writeWindowsTerminalFont({ fallbacks })
+  return {
+    ok: true,
+    target: "Windows Terminal",
+    path: written.path,
+    backup: written.backup,
+    hint: "Close every Windows Terminal window and reopen it for the font to take effect.",
   }
-  if (vscodeSettingsPath()) {
-    const written = writeVSCodeFontFamily(family)
-    return {
-      ok: true,
-      target: "VS Code integrated terminal",
-      path: written.path,
-      backup: written.backup,
-      hint: "Open a new terminal in VS Code for the font to take effect.",
-    }
+}
+
+function applyVSCodeFont(family: string): ApplyOutcome {
+  const written = writeVSCodeFontFamily(family)
+  return {
+    ok: true,
+    target: "VS Code integrated terminal",
+    path: written.path,
+    backup: written.backup,
+    hint: "Open a new terminal in VS Code for the font to take effect.",
   }
-  return { ok: false, message: "No supported terminal settings found (Windows Terminal or VS Code)." }
 }
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..a4813ef2fbf4
--- /dev/null
+++ b/packages/tui/test/bidi-dialogs-e2e.test.tsx
@@ -0,0 +1,161 @@
+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: /fonts command opens the terminal font dialog", async () => {
+  const app = await bootApp({ sessionID: "ses_test" })
+  try {
+    app.dispatch("font.pick")
+    const frame = await app.waitForFrame((f) => f.includes("Terminal font for Arabic"), "fonts dialog")
+    expect(frame.includes("Terminal font for Arabic")).toBe(true)
+    expect(frame.includes("Recommended for Arabic")).toBe(true)
+  } finally {
+    await app.exit()
+  }
+}, 60000)
+
+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(reverseArabic(ARABIC_TITLE)), "arabic session title")
+    expect(frame.includes(reverseArabic(ARABIC_TITLE))).toBe(true)
+  } finally {
+    await app.exit()
+  }
+}, 60000)
diff --git a/packages/tui/test/util/terminal-font.test.ts b/packages/tui/test/util/terminal-font.test.ts
index d2cf486e1fa0..0bb5aeedf900 100644
--- a/packages/tui/test/util/terminal-font.test.ts
+++ b/packages/tui/test/util/terminal-font.test.ts
@@ -6,12 +6,19 @@ import {
   RECOMMENDED_ARABIC_FONTS,
   appendFontFamily,
   applyArabicFont,
+  detectTerminalHost,
   isFontInstalled,
+  mergeFallbacks,
   sanitizeJsonc,
 } from "../../src/util/terminal-font"
 
 const roots: string[] = []
-const env = { local: process.env.LOCALAPPDATA, appdata: process.env.APPDATA }
+const env = {
+  local: process.env.LOCALAPPDATA,
+  appdata: process.env.APPDATA,
+  term: process.env.TERM_PROGRAM,
+  wt: process.env.WT_SESSION,
+}
 
 function tempDir() {
   const dir = mkdtempSync(path.join(tmpdir(), "oc-font-"))
@@ -22,6 +29,10 @@ function tempDir() {
 afterEach(() => {
   process.env.LOCALAPPDATA = env.local
   process.env.APPDATA = env.appdata
+  if (env.term === undefined) delete process.env.TERM_PROGRAM
+  else process.env.TERM_PROGRAM = env.term
+  if (env.wt === undefined) delete process.env.WT_SESSION
+  else process.env.WT_SESSION = env.wt
   for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
 })
 
@@ -64,6 +75,35 @@ describe("isFontInstalled", () => {
   })
 })
 
+describe("detectTerminalHost", () => {
+  test("detects Windows Terminal from WT_SESSION", () => {
+    expect(detectTerminalHost({ WT_SESSION: "abc" })).toBe("windows-terminal")
+  })
+
+  test("detects the VS Code integrated terminal", () => {
+    expect(detectTerminalHost({ TERM_PROGRAM: "vscode" })).toBe("vscode")
+    expect(detectTerminalHost({ VSCODE_INJECTION: "1" })).toBe("vscode")
+  })
+
+  test("falls back to other", () => {
+    expect(detectTerminalHost({})).toBe("other")
+  })
+})
+
+describe("mergeFallbacks", () => {
+  test("keeps the incoming fonts first and preserves existing ones", () => {
+    expect(mergeFallbacks(["Cascadia Mono"], ["Cairo", "Segoe UI"])).toEqual([
+      "Cairo",
+      "Segoe UI",
+      "Cascadia Mono",
+    ])
+  })
+
+  test("deduplicates case-insensitively", () => {
+    expect(mergeFallbacks(["cairo"], ["Cairo"])).toEqual(["Cairo"])
+  })
+})
+
 describe("applyArabicFont", () => {
   test("writes Windows Terminal fallbacks and keeps a backup", () => {
     const root = tempDir()
@@ -88,6 +128,30 @@ describe("applyArabicFont", () => {
     expect(readFileSync(result.backup, "utf8")).toContain("Cascadia Mono")
   })
 
+  test("targets VS Code when hosted by VS Code even if Windows Terminal is installed", () => {
+    const root = tempDir()
+    const wtSettings = path.join(root, "Packages/Microsoft.WindowsTerminal_8wekyb3d8bbwe/LocalState/settings.json")
+    mkdirSync(path.dirname(wtSettings), { recursive: true })
+    writeFileSync(wtSettings, JSON.stringify({ profiles: { defaults: { font: { face: "Cascadia Mono" } } } }))
+
+    const appdata = path.join(root, "appdata")
+    const vscode = path.join(appdata, "Code/User/settings.json")
+    mkdirSync(path.dirname(vscode), { recursive: true })
+    writeFileSync(vscode, JSON.stringify({}))
+
+    process.env.LOCALAPPDATA = root
+    process.env.APPDATA = appdata
+    process.env.TERM_PROGRAM = "vscode"
+    delete process.env.WT_SESSION
+
+    const result = applyArabicFont("Cairo")
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    expect(result.target).toBe("VS Code integrated terminal")
+    expect(JSON.parse(readFileSync(vscode, "utf8"))["terminal.integrated.fontFamily"]).toContain("Cairo")
+    expect(JSON.parse(readFileSync(wtSettings, "utf8")).profiles.defaults.font.fallbacks).toBeUndefined()
+  })
+
   test("reports failure when no supported terminal exists", () => {
     const root = tempDir()
     process.env.LOCALAPPDATA = path.join(root, "missing")

From 771a720e0f254276edda657e40442eadd05900b7 Mon Sep 17 00:00:00 2001
From: muhamedbeshir <mbeshir011@gmail.com>
Date: Sat, 12 Sep 2026 10:02:21 +0300
Subject: [PATCH 06/10] fix(tui): apply bidi to the reasoning panel and assert
 RTL alignment

- Paint reasoning prose through the bidi code renderer so Arabic thinking
  blocks reorder RTL while code lines without Arabic stay LTR.
- Extend the e2e tests to assert right alignment for assistant paragraphs
  and dialog list rows, not just the presence of the visual order.
---
 packages/tui/src/routes/session/index.tsx   | 5 +++--
 packages/tui/test/bidi-dialogs-e2e.test.tsx | 9 +++++++--
 packages/tui/test/bidi-e2e.test.tsx         | 6 ++++++
 3 files changed, 16 insertions(+), 4 deletions(-)

diff --git a/packages/tui/src/routes/session/index.tsx b/packages/tui/src/routes/session/index.tsx
index b2f59362c607..e18993ec1eb3 100644
--- a/packages/tui/src/routes/session/index.tsx
+++ b/packages/tui/src/routes/session/index.tsx
@@ -24,7 +24,7 @@ import { SplitBorder } from "../../ui/border"
 import { useTuiPaths, useTuiTerminalEnvironment } from "../../context/runtime"
 import { Spinner } from "../../component/spinner"
 import { createSyntaxStyleMemo, generateSubtleSyntax, selectedForeground, useTheme } from "../../context/theme"
-import { BoxRenderable, ScrollBoxRenderable, addDefaultParsers, TextAttributes, RGBA } from "@opentui/core"
+import { BoxRenderable, CodeRenderable, ScrollBoxRenderable, addDefaultParsers, TextAttributes, RGBA } from "@opentui/core"
 import { Prompt, type PromptRef } from "../../component/prompt"
 import type {
   AssistantMessage,
@@ -81,7 +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 { bidiMarkdownRenderNode } from "../../component/bidi-markdown"
+import { applyBidiCodePaint, bidiMarkdownRenderNode } from "../../component/bidi-markdown"
 import "../../component/bidi-elements"
 
 addDefaultParsers(parsers.parsers)
@@ -1635,6 +1635,7 @@ function ReasoningPart(props: { last: boolean; part: ReasoningPart; message: Ass
         <Show when={!opaque() && (!inMinimal() || expanded()) && summary().body}>
           <box paddingLeft={inMinimal() ? 2 : 0} marginTop={1}>
             <code
+              ref={(el: CodeRenderable) => applyBidiCodePaint(el)}
               filetype="markdown"
               drawUnstyledText={false}
               streaming={true}
diff --git a/packages/tui/test/bidi-dialogs-e2e.test.tsx b/packages/tui/test/bidi-dialogs-e2e.test.tsx
index a4813ef2fbf4..be3e52e50401 100644
--- a/packages/tui/test/bidi-dialogs-e2e.test.tsx
+++ b/packages/tui/test/bidi-dialogs-e2e.test.tsx
@@ -153,8 +153,13 @@ 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(reverseArabic(ARABIC_TITLE)), "arabic session title")
-    expect(frame.includes(reverseArabic(ARABIC_TITLE))).toBe(true)
+    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()
   }
diff --git a/packages/tui/test/bidi-e2e.test.tsx b/packages/tui/test/bidi-e2e.test.tsx
index c6dd7dc1ee9e..a53b0b6b5900 100644
--- a/packages/tui/test/bidi-e2e.test.tsx
+++ b/packages/tui/test/bidi-e2e.test.tsx
@@ -203,6 +203,12 @@ test("e2e: Arabic prompt input and assistant output in a real session view", asy
     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",

From 20645bd9f9f82bb4b918b92e5861bd9d51c98120 Mon Sep 17 00:00:00 2001
From: muhamedbeshir <mbeshir011@gmail.com>
Date: Sat, 12 Sep 2026 10:23:46 +0300
Subject: [PATCH 07/10] fix(tui): write Windows Terminal fonts as a face
 fallback chain

Windows Terminal has no font.fallbacks setting; it resolves a
comma-separated font.face chain instead. The previous writer stored an
array the terminal silently ignored, so picking a font never changed
anything. The writer now builds 'Mono, <pick>, <arabic...>' preserving
the user's faces, and removes any stale fallbacks key.
---
 docs/rtl/configure-windows-terminal-font.ps1 | 26 ++++++--
 docs/rtl/fonts.ar.md                         |  9 +--
 docs/rtl/fonts.md                            |  9 +--
 packages/tui/src/util/terminal-font.ts       | 66 +++++++++++--------
 packages/tui/test/util/terminal-font.test.ts | 67 ++++++++++++++++----
 5 files changed, 120 insertions(+), 57 deletions(-)

diff --git a/docs/rtl/configure-windows-terminal-font.ps1 b/docs/rtl/configure-windows-terminal-font.ps1
index 5a65ad9d0a85..81d3a13f2ed6 100644
--- a/docs/rtl/configure-windows-terminal-font.ps1
+++ b/docs/rtl/configure-windows-terminal-font.ps1
@@ -1,5 +1,8 @@
-# Adds Arabic-capable font fallbacks to Windows Terminal so Arabic text renders
-# with proper joining, while keeping your monospaced font for Latin/code.
+# Adds an Arabic-capable font fallback chain to Windows Terminal so Arabic text
+# renders with proper joining, while keeping your monospaced font for Latin/code.
+#
+# Windows Terminal honors a comma-separated `face` chain ("Cascadia Mono, Cairo");
+# a `fallbacks` array is not a real setting and is ignored.
 #
 # The OpenCode bidi change handles ordering/alignment; this script only handles
 # font selection, which is owned by the terminal, not by the application.
@@ -72,10 +75,20 @@ if (-not $json.profiles.defaults.font) {
   $json.profiles.defaults | Add-Member -NotePropertyName font -NotePropertyValue ([pscustomobject]@{}) -Force
 }
 
-$json.profiles.defaults.font | Add-Member -NotePropertyName fallbacks -NotePropertyValue $Fallbacks -Force
-if ($Face) {
-  $json.profiles.defaults.font | Add-Member -NotePropertyName face -NotePropertyValue $Face -Force
+# Build the comma-separated face chain: requested main face first, then the
+# faces already configured (never reordered), then the Arabic fallbacks.
+$chain = @()
+if ($Face) { $chain += $Face }
+$existingFace = $json.profiles.defaults.font.face
+if ($existingFace) {
+  $chain += ("$existingFace" -split "," | ForEach-Object { $_.Trim().Trim("'").Trim('"') } | Where-Object { $_ })
+}
+if ($chain.Count -eq 0) { $chain += "Cascadia Mono" }
+foreach ($name in @($Fallbacks) | Where-Object { $_ }) {
+  if ($chain -notcontains $name) { $chain += $name }
 }
+$json.profiles.defaults.font | Add-Member -NotePropertyName face -NotePropertyValue ($chain -join ", ") -Force
+$json.profiles.defaults.font.PSObject.Properties.Remove("fallbacks")
 
 $output = $json | ConvertTo-Json -Depth 64
 $utf8 = New-Object System.Text.UTF8Encoding($false)
@@ -83,7 +96,6 @@ $utf8 = New-Object System.Text.UTF8Encoding($false)
 
 Write-Host ""
 Write-Host "Updated profiles.defaults.font:"
-Write-Host ("  fallbacks = " + ($Fallbacks -join ", "))
-if ($Face) { Write-Host ("  face      = " + $Face) }
+Write-Host ("  face = " + ($chain -join ", "))
 Write-Host ""
 Write-Host "Restart Windows Terminal to apply. To undo, copy the backup over settings.json."
diff --git a/docs/rtl/fonts.ar.md b/docs/rtl/fonts.ar.md
index 809a715fcb01..2da53517abec 100644
--- a/docs/rtl/fonts.ar.md
+++ b/docs/rtl/fonts.ar.md
@@ -48,19 +48,20 @@
 لوحدها مع نسخة احتياطية. بعد كده اقفل التيرمنال وافتحه تاني. **ومش بتركّب أي خط
 على الجهاز.**
 
-الأمر ده بيعدّل `profiles.defaults.font.fallbacks`، يعني العربي هيستخدم الخط
-اللي اخترته والإنجليزي والكود هيفضلوا بالخط الـ monospaced.
+الأمر ده بيعدّل `profiles.defaults.font.face` لسلسلة خطوط مفصولة بفواصل (دي
+الطريقة الوحيدة اللي Windows Terminal بيفهم بيها الـ fallback)، يعني العربي
+هيستخدم الخط اللي اخترته والإنجليزي والكود هيفضلوا بالخط الـ monospaced.
 
 ### يدويًا
 
-أضف الخطوط العربية كـ fallbacks داخل `profiles.defaults.font`:
+أضف الخطوط العربية لسلسلة `face` داخل `profiles.defaults.font`:
 
 ```json
 {
   "profiles": {
     "defaults": {
       "font": {
-        "fallbacks": ["Cairo", "Noto Naskh Arabic", "Segoe UI", "Tahoma"]
+        "face": "Cascadia Mono, Cairo, Noto Naskh Arabic, Segoe UI, Tahoma"
       }
     }
   }
diff --git a/docs/rtl/fonts.md b/docs/rtl/fonts.md
index 63b142a39222..7391e5884204 100644
--- a/docs/rtl/fonts.md
+++ b/docs/rtl/fonts.md
@@ -48,19 +48,20 @@ on your machine (recommended Arabic fonts first), and writes your choice into
 the terminal's settings for you — keeping a timestamped backup. Then restart the
 terminal. It never installs fonts.
 
-Under the hood it sets `profiles.defaults.font.fallbacks`, so Arabic uses the
-chosen font while Latin and code stay monospaced.
+Under the hood it sets `profiles.defaults.font.face` to a comma-separated
+fallback chain (the only fallback mechanism Windows Terminal honors), so
+Arabic uses the chosen font while Latin and code stay monospaced.
 
 ### Manually
 
-Add Arabic fallbacks to `profiles.defaults.font`:
+Add the Arabic fonts to the `face` chain in `profiles.defaults.font`:
 
 ```json
 {
   "profiles": {
     "defaults": {
       "font": {
-        "fallbacks": ["Cairo", "Noto Naskh Arabic", "Segoe UI", "Tahoma"]
+        "face": "Cascadia Mono, Cairo, Noto Naskh Arabic, Segoe UI, Tahoma"
       }
     }
   }
diff --git a/packages/tui/src/util/terminal-font.ts b/packages/tui/src/util/terminal-font.ts
index fed43a106a9a..ff0ec5ce2976 100644
--- a/packages/tui/src/util/terminal-font.ts
+++ b/packages/tui/src/util/terminal-font.ts
@@ -114,21 +114,46 @@ function writeJson(file: string, value: unknown) {
   writeFileSync(file, JSON.stringify(value, null, 4), { encoding: "utf8" })
 }
 
-export function readWindowsTerminalFont(): { face?: string; fallbacks: string[] } | undefined {
+// Windows Terminal resolves `font.face` as a CSS-like fallback chain
+// ("Cascadia Mono, Cairo, ..."). There is no `font.fallbacks` setting;
+// writing one is silently ignored, so the writer below always uses `face`.
+export const DEFAULT_WINDOWS_TERMINAL_FACE = "Cascadia Mono"
+
+export function splitFontFaces(face: string | undefined): string[] {
+  return (face ?? "")
+    .split(",")
+    .map((part) => part.trim().replace(/^['"]|['"]$/g, ""))
+    .filter(Boolean)
+}
+
+// Builds the fallback chain: the user's current faces first (never reordered),
+// then the chosen Arabic font plus the other recommended Arabic fonts.
+export function buildFontFaceChain(existingFace: string | undefined, family: string) {
+  const base = splitFontFaces(existingFace)
+  if (base.length === 0) base.push(DEFAULT_WINDOWS_TERMINAL_FACE)
+  const seen = new Set(base.map((name) => name.toLowerCase()))
+  const out = [...base]
+  for (const name of [family, ...RECOMMENDED_ARABIC_FONTS.filter((item) => item !== family)]) {
+    if (seen.has(name.toLowerCase())) continue
+    seen.add(name.toLowerCase())
+    out.push(name)
+  }
+  return out.join(", ")
+}
+
+export function readWindowsTerminalFont(): { face?: string; faces: string[] } | undefined {
   const file = windowsTerminalSettingsPath()
   if (!file) return undefined
   const json = readJsonc(file)
   const defaults = (json.profiles as Record<string, unknown> | undefined)?.defaults as
     | Record<string, unknown>
     | undefined
-  const font = defaults?.font as { face?: unknown; fallbacks?: unknown } | undefined
-  return {
-    face: typeof font?.face === "string" ? font.face : undefined,
-    fallbacks: Array.isArray(font?.fallbacks) ? font.fallbacks.filter((item): item is string => typeof item === "string") : [],
-  }
+  const font = defaults?.font as { face?: unknown } | undefined
+  const face = typeof font?.face === "string" ? font.face : undefined
+  return { face, faces: splitFontFaces(face) }
 }
 
-export function writeWindowsTerminalFont(input: { face?: string; fallbacks: string[] }): {
+export function writeWindowsTerminalFont(input: { face: string }): {
   path: string
   backup: string
 } {
@@ -139,29 +164,14 @@ export function writeWindowsTerminalFont(input: { face?: string; fallbacks: stri
   const profiles = (json.profiles ??= {}) as Record<string, unknown>
   const defaults = (profiles.defaults ??= {}) as Record<string, unknown>
   const font = (defaults.font ??= {}) as Record<string, unknown>
-  const existing = Array.isArray(font.fallbacks)
-    ? font.fallbacks.filter((item): item is string => typeof item === "string")
-    : []
-  font.fallbacks = mergeFallbacks(existing, input.fallbacks)
-  if (input.face !== undefined) font.face = input.face
+  font.face = input.face
+  // A previous version of this tool wrote an unsupported `fallbacks` array;
+  // remove it so the file only carries settings the terminal honors.
+  delete font.fallbacks
   writeJson(file, json)
   return { path: file, backup: created }
 }
 
-// Keeps the user's existing fallbacks after the Arabic ones so choosing a font
-// never drops a fallback the terminal already relied on.
-export function mergeFallbacks(existing: string[], incoming: string[]) {
-  const seen = new Set<string>()
-  const out: string[] = []
-  for (const family of [...incoming, ...existing]) {
-    const key = family.trim().toLowerCase()
-    if (!key || seen.has(key)) continue
-    seen.add(key)
-    out.push(family)
-  }
-  return out
-}
-
 export function appendFontFamily(existing: string | undefined, family: string) {
   const parts = (existing ?? "")
     .split(",")
@@ -248,8 +258,8 @@ export function applyArabicFont(family: string): ApplyOutcome {
 }
 
 function applyWindowsTerminalFont(family: string): ApplyOutcome {
-  const fallbacks = [family, ...RECOMMENDED_ARABIC_FONTS.filter((item) => item !== family)]
-  const written = writeWindowsTerminalFont({ fallbacks })
+  const face = buildFontFaceChain(readWindowsTerminalFont()?.face, family)
+  const written = writeWindowsTerminalFont({ face })
   return {
     ok: true,
     target: "Windows Terminal",
diff --git a/packages/tui/test/util/terminal-font.test.ts b/packages/tui/test/util/terminal-font.test.ts
index 0bb5aeedf900..b25b6bf4fd23 100644
--- a/packages/tui/test/util/terminal-font.test.ts
+++ b/packages/tui/test/util/terminal-font.test.ts
@@ -6,10 +6,11 @@ import {
   RECOMMENDED_ARABIC_FONTS,
   appendFontFamily,
   applyArabicFont,
+  buildFontFaceChain,
   detectTerminalHost,
   isFontInstalled,
-  mergeFallbacks,
   sanitizeJsonc,
+  splitFontFaces,
 } from "../../src/util/terminal-font"
 
 const roots: string[] = []
@@ -90,22 +91,38 @@ describe("detectTerminalHost", () => {
   })
 })
 
-describe("mergeFallbacks", () => {
-  test("keeps the incoming fonts first and preserves existing ones", () => {
-    expect(mergeFallbacks(["Cascadia Mono"], ["Cairo", "Segoe UI"])).toEqual([
-      "Cairo",
-      "Segoe UI",
-      "Cascadia Mono",
-    ])
+describe("splitFontFaces", () => {
+  test("splits a comma chain and drops quotes and blanks", () => {
+    expect(splitFontFaces(`'Cascadia Mono', Cairo ,, "Segoe UI"`)).toEqual(["Cascadia Mono", "Cairo", "Segoe UI"])
   })
 
-  test("deduplicates case-insensitively", () => {
-    expect(mergeFallbacks(["cairo"], ["Cairo"])).toEqual(["Cairo"])
+  test("returns an empty list when unset", () => {
+    expect(splitFontFaces(undefined)).toEqual([])
+  })
+})
+
+describe("buildFontFaceChain", () => {
+  test("keeps the current faces first, then the chosen Arabic font", () => {
+    expect(buildFontFaceChain("Cascadia Mono", "Cairo")).toBe(
+      ["Cascadia Mono", "Cairo", ...RECOMMENDED_ARABIC_FONTS.filter((f) => f !== "Cairo")].join(", "),
+    )
+  })
+
+  test("defaults to Cascadia Mono when no face is set", () => {
+    expect(buildFontFaceChain(undefined, "Amiri").startsWith("Cascadia Mono, Amiri")).toBe(true)
+  })
+
+  test("never reorders or duplicates the user's faces", () => {
+    expect(buildFontFaceChain("Cascadia Mono, Segoe UI", "Cairo")).toBe(
+      ["Cascadia Mono", "Segoe UI", "Cairo", ...RECOMMENDED_ARABIC_FONTS.filter((f) => f !== "Cairo" && f !== "Segoe UI")].join(
+        ", ",
+      ),
+    )
   })
 })
 
 describe("applyArabicFont", () => {
-  test("writes Windows Terminal fallbacks and keeps a backup", () => {
+  test("writes a Windows Terminal face chain and keeps a backup", () => {
     const root = tempDir()
     const settings = path.join(root, "Packages/Microsoft.WindowsTerminal_8wekyb3d8bbwe/LocalState/settings.json")
     mkdirSync(path.dirname(settings), { recursive: true })
@@ -119,15 +136,37 @@ describe("applyArabicFont", () => {
     expect(result.target).toBe("Windows Terminal")
 
     const written = JSON.parse(readFileSync(settings, "utf8"))
-    expect(written.profiles.defaults.font.face).toBe("Cascadia Mono")
-    expect(written.profiles.defaults.font.fallbacks[0]).toBe("Amiri")
+    const faces = String(written.profiles.defaults.font.face)
+      .split(",")
+      .map((part: string) => part.trim())
+    expect(faces[0]).toBe("Cascadia Mono")
+    expect(faces[1]).toBe("Amiri")
     for (const font of RECOMMENDED_ARABIC_FONTS) {
       if (font === "Amiri") continue
-      expect(written.profiles.defaults.font.fallbacks).toContain(font)
+      expect(faces).toContain(font)
     }
+    expect(written.profiles.defaults.font.fallbacks).toBeUndefined()
     expect(readFileSync(result.backup, "utf8")).toContain("Cascadia Mono")
   })
 
+  test("removes a stale unsupported fallbacks array", () => {
+    const root = tempDir()
+    const settings = path.join(root, "Packages/Microsoft.WindowsTerminal_8wekyb3d8bbwe/LocalState/settings.json")
+    mkdirSync(path.dirname(settings), { recursive: true })
+    writeFileSync(
+      settings,
+      JSON.stringify({ profiles: { defaults: { font: { fallbacks: ["Bauhaus 93", "Cairo"] } } } }),
+    )
+    process.env.LOCALAPPDATA = root
+    process.env.APPDATA = path.join(root, "no-vscode")
+
+    const result = applyArabicFont("Cairo")
+    expect(result.ok).toBe(true)
+    const written = JSON.parse(readFileSync(settings, "utf8"))
+    expect(String(written.profiles.defaults.font.face).startsWith("Cascadia Mono, Cairo")).toBe(true)
+    expect(written.profiles.defaults.font.fallbacks).toBeUndefined()
+  })
+
   test("targets VS Code when hosted by VS Code even if Windows Terminal is installed", () => {
     const root = tempDir()
     const wtSettings = path.join(root, "Packages/Microsoft.WindowsTerminal_8wekyb3d8bbwe/LocalState/settings.json")

From 247a2615a76423d9b2b440fdd6d4b36058a18fb1 Mon Sep 17 00:00:00 2001
From: muhamedbeshir <mbeshir011@gmail.com>
Date: Sun, 13 Sep 2026 05:22:50 +0300
Subject: [PATCH 08/10] fix(tui): chain only resolving fonts so the terminal
 stops warning

Windows Terminal warns about every missing family in the face chain.
Limit the tail to families that resolve on this machine (the picked font
is always kept); the dialog already labels the rest as not installed.
---
 packages/tui/src/util/terminal-font.ts       | 19 ++++++++++---
 packages/tui/test/util/terminal-font.test.ts | 29 +++++++++++++-------
 2 files changed, 34 insertions(+), 14 deletions(-)

diff --git a/packages/tui/src/util/terminal-font.ts b/packages/tui/src/util/terminal-font.ts
index ff0ec5ce2976..ea50806dde9a 100644
--- a/packages/tui/src/util/terminal-font.ts
+++ b/packages/tui/src/util/terminal-font.ts
@@ -126,14 +126,24 @@ export function splitFontFaces(face: string | undefined): string[] {
     .filter(Boolean)
 }
 
+// The chosen font is always kept (the dialog already warns when it is not
+// installed); the rest of the tail is limited to resolving families.
+export function availableFontFamilies(family: string, installed: string[]) {
+  return [
+    family,
+    ...RECOMMENDED_ARABIC_FONTS.filter((item) => item !== family && isFontInstalled(item, installed)),
+  ]
+}
+
 // Builds the fallback chain: the user's current faces first (never reordered),
-// then the chosen Arabic font plus the other recommended Arabic fonts.
-export function buildFontFaceChain(existingFace: string | undefined, family: string) {
+// then the given tail. Windows Terminal warns about every missing family in
+// the chain, so callers pass only resolving families in the tail.
+export function buildFontFaceChain(existingFace: string | undefined, tail: string[]) {
   const base = splitFontFaces(existingFace)
   if (base.length === 0) base.push(DEFAULT_WINDOWS_TERMINAL_FACE)
   const seen = new Set(base.map((name) => name.toLowerCase()))
   const out = [...base]
-  for (const name of [family, ...RECOMMENDED_ARABIC_FONTS.filter((item) => item !== family)]) {
+  for (const name of tail) {
     if (seen.has(name.toLowerCase())) continue
     seen.add(name.toLowerCase())
     out.push(name)
@@ -258,7 +268,8 @@ export function applyArabicFont(family: string): ApplyOutcome {
 }
 
 function applyWindowsTerminalFont(family: string): ApplyOutcome {
-  const face = buildFontFaceChain(readWindowsTerminalFont()?.face, family)
+  const tail = availableFontFamilies(family, installedFontFamilies())
+  const face = buildFontFaceChain(readWindowsTerminalFont()?.face, tail)
   const written = writeWindowsTerminalFont({ face })
   return {
     ok: true,
diff --git a/packages/tui/test/util/terminal-font.test.ts b/packages/tui/test/util/terminal-font.test.ts
index b25b6bf4fd23..88af58385661 100644
--- a/packages/tui/test/util/terminal-font.test.ts
+++ b/packages/tui/test/util/terminal-font.test.ts
@@ -6,8 +6,10 @@ import {
   RECOMMENDED_ARABIC_FONTS,
   appendFontFamily,
   applyArabicFont,
+  availableFontFamilies,
   buildFontFaceChain,
   detectTerminalHost,
+  installedFontFamilies,
   isFontInstalled,
   sanitizeJsonc,
   splitFontFaces,
@@ -101,22 +103,25 @@ describe("splitFontFaces", () => {
   })
 })
 
+describe("availableFontFamilies", () => {
+  test("keeps the chosen font and only resolving recommended fonts", () => {
+    const installed = ["Cairo", "Cairo Regular", "Segoe UI", "Tahoma"]
+    expect(availableFontFamilies("Amiri", installed)).toEqual(["Amiri", "Cairo", "Segoe UI", "Tahoma"])
+  })
+})
+
 describe("buildFontFaceChain", () => {
-  test("keeps the current faces first, then the chosen Arabic font", () => {
-    expect(buildFontFaceChain("Cascadia Mono", "Cairo")).toBe(
-      ["Cascadia Mono", "Cairo", ...RECOMMENDED_ARABIC_FONTS.filter((f) => f !== "Cairo")].join(", "),
-    )
+  test("keeps the current faces first, then the tail", () => {
+    expect(buildFontFaceChain("Cascadia Mono", ["Cairo", "Segoe UI"])).toBe("Cascadia Mono, Cairo, Segoe UI")
   })
 
   test("defaults to Cascadia Mono when no face is set", () => {
-    expect(buildFontFaceChain(undefined, "Amiri").startsWith("Cascadia Mono, Amiri")).toBe(true)
+    expect(buildFontFaceChain(undefined, ["Amiri"]).startsWith("Cascadia Mono, Amiri")).toBe(true)
   })
 
   test("never reorders or duplicates the user's faces", () => {
-    expect(buildFontFaceChain("Cascadia Mono, Segoe UI", "Cairo")).toBe(
-      ["Cascadia Mono", "Segoe UI", "Cairo", ...RECOMMENDED_ARABIC_FONTS.filter((f) => f !== "Cairo" && f !== "Segoe UI")].join(
-        ", ",
-      ),
+    expect(buildFontFaceChain("Cascadia Mono, Segoe UI", ["Cairo", "Segoe UI"])).toBe(
+      "Cascadia Mono, Segoe UI, Cairo",
     )
   })
 })
@@ -141,9 +146,13 @@ describe("applyArabicFont", () => {
       .map((part: string) => part.trim())
     expect(faces[0]).toBe("Cascadia Mono")
     expect(faces[1]).toBe("Amiri")
+    // The tail mirrors what resolves on this machine: installed recommended
+    // fonts are present, missing ones are left out so the terminal never warns.
+    const installed = installedFontFamilies()
     for (const font of RECOMMENDED_ARABIC_FONTS) {
       if (font === "Amiri") continue
-      expect(faces).toContain(font)
+      if (isFontInstalled(font, installed)) expect(faces).toContain(font)
+      else expect(faces).not.toContain(font)
     }
     expect(written.profiles.defaults.font.fallbacks).toBeUndefined()
     expect(readFileSync(result.backup, "utf8")).toContain("Cascadia Mono")

From c4edbd22821d1ecbcf79a711fb082f17ad07a829 Mon Sep 17 00:00:00 2001
From: muhamedbeshir <mbeshir011@gmail.com>
Date: Sun, 13 Sep 2026 05:38:13 +0300
Subject: [PATCH 09/10] feat(tui)!: remove the terminal font picker

Drop the /fonts command, its dialog, the settings writer, docs and
tests. Font selection stays where it belongs: the terminal's own
settings. Bidi rendering itself is unchanged.
---
 docs/rtl/README.ar.md                        |   6 +-
 docs/rtl/README.md                           |   6 +-
 docs/rtl/configure-windows-terminal-font.ps1 | 101 -------
 docs/rtl/fonts.ar.md                         | 104 -------
 docs/rtl/fonts.md                            | 103 -------
 packages/tui/src/app.tsx                     |  12 -
 packages/tui/src/component/dialog-fonts.tsx  |  46 ---
 packages/tui/src/util/terminal-font.ts       | 292 -------------------
 packages/tui/test/bidi-dialogs-e2e.test.tsx  |  12 -
 packages/tui/test/util/terminal-font.test.ts | 210 -------------
 10 files changed, 6 insertions(+), 886 deletions(-)
 delete mode 100644 docs/rtl/configure-windows-terminal-font.ps1
 delete mode 100644 docs/rtl/fonts.ar.md
 delete mode 100644 docs/rtl/fonts.md
 delete mode 100644 packages/tui/src/component/dialog-fonts.tsx
 delete mode 100644 packages/tui/src/util/terminal-font.ts
 delete mode 100644 packages/tui/test/util/terminal-font.test.ts

diff --git a/docs/rtl/README.ar.md b/docs/rtl/README.ar.md
index a4886ceecd2f..8379e8161571 100644
--- a/docs/rtl/README.ar.md
+++ b/docs/rtl/README.ar.md
@@ -26,9 +26,9 @@
 ## الخطوط
 
 التطبيق ميقدرش يختار خطوط — الـ terminal هو اللي بيختار. سيب الخط الـ
-monospaced زي ما هو وضيف خط عربي كـ **fallback** (Cairo، Noto Naskh Arabic،
-Segoe UI، Tahoma). التفاصيل في [fonts.ar.md](./fonts.ar.md) والسكربت
-[`configure-windows-terminal-font.ps1`](./configure-windows-terminal-font.ps1).
+monospaced زي ما هو واتأكد إن في خط عربي متاح كـ fallback في إعدادات
+الـ terminal (مثلًا `"face": "Cascadia Mono, Cairo, Segoe UI"` في
+Windows Terminal)، وبعدين اقفل التيرمنال وافتحه تاني.
 
 ## التثبيت (ويندوز، من نفس المستودع)
 
diff --git a/docs/rtl/README.md b/docs/rtl/README.md
index b156a7c45820..229c4511d8e7 100644
--- a/docs/rtl/README.md
+++ b/docs/rtl/README.md
@@ -26,9 +26,9 @@ terminal-side BiDi requirement and no destructive text rewriting.
 ## Fonts
 
 The TUI cannot select fonts — the terminal does. Keep your monospaced font and
-add an Arabic-capable font as a **fallback** (Cairo, Noto Naskh Arabic, Segoe
-UI, Tahoma). See [fonts.md](./fonts.md) and the helper script
-[`configure-windows-terminal-font.ps1`](./configure-windows-terminal-font.ps1).
+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)
 
diff --git a/docs/rtl/configure-windows-terminal-font.ps1 b/docs/rtl/configure-windows-terminal-font.ps1
deleted file mode 100644
index 81d3a13f2ed6..000000000000
--- a/docs/rtl/configure-windows-terminal-font.ps1
+++ /dev/null
@@ -1,101 +0,0 @@
-# Adds an Arabic-capable font fallback chain to Windows Terminal so Arabic text
-# renders with proper joining, while keeping your monospaced font for Latin/code.
-#
-# Windows Terminal honors a comma-separated `face` chain ("Cascadia Mono, Cairo");
-# a `fallbacks` array is not a real setting and is ignored.
-#
-# The OpenCode bidi change handles ordering/alignment; this script only handles
-# font selection, which is owned by the terminal, not by the application.
-#
-# Usage (defaults are safe and reversible):
-#   powershell -ExecutionPolicy Bypass -File docs/rtl/configure-windows-terminal-font.ps1
-#   powershell -ExecutionPolicy Bypass -File docs/rtl/configure-windows-terminal-font.ps1 -Face "Cascadia Mono"
-#   powershell -ExecutionPolicy Bypass -File docs/rtl/configure-windows-terminal-font.ps1 -Fallbacks Cairo,"Noto Naskh Arabic","Segoe UI","Tahoma"
-#
-# A timestamped backup of settings.json is written next to it before any change.
-
-param(
-  [string]$Face,
-  [string[]]$Fallbacks = @("Cairo", "Noto Naskh Arabic", "Segoe UI", "Tahoma"),
-  [string]$SettingsPath
-)
-
-$ErrorActionPreference = "Stop"
-
-$candidates = @(
-  (Join-Path $env:LOCALAPPDATA "Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json"),
-  (Join-Path $env:LOCALAPPDATA "Packages\Microsoft.WindowsTerminalPreview_8wekyb3d8bbwe\LocalState\settings.json"),
-  (Join-Path $env:LOCALAPPDATA "Microsoft\Windows Terminal\settings.json")
-)
-
-$settingsPath = $SettingsPath
-if (-not $settingsPath) {
-  $settingsPath = $candidates | Where-Object { Test-Path $_ } | Select-Object -First 1
-}
-if (-not $settingsPath -or -not (Test-Path $settingsPath)) {
-  throw "Windows Terminal settings.json not found. Install Windows Terminal or edit the font manually (see docs/rtl/fonts.md)."
-}
-
-Write-Host "Settings: $settingsPath"
-
-# Report which requested fonts are actually installed.
-$fontFiles = @()
-foreach ($dir in @((Join-Path $env:WINDIR "Fonts"), (Join-Path $env:LOCALAPPDATA "Microsoft\Windows\Fonts"))) {
-  if (Test-Path $dir) {
-    $fontFiles += Get-ChildItem $dir -File -ErrorAction SilentlyContinue | Select-Object -ExpandProperty Name
-  }
-}
-foreach ($name in @($Fallbacks + @($Face)) | Where-Object { $_ } | Select-Object -Unique) {
-  $needle = $name -replace "\s", "*"
-  if ($fontFiles -like "*$needle*") {
-    Write-Host "  installed: $name"
-  } else {
-    Write-Host "  NOT installed: $name (install it, or remove it from the fallback list)"
-  }
-}
-
-$backup = "$settingsPath.rtl-backup-" + (Get-Date -Format "yyyyMMdd-HHmmss")
-Copy-Item -LiteralPath $settingsPath -Destination $backup -Force
-Write-Host "Backup:   $backup"
-
-$raw = Get-Content -LiteralPath $settingsPath -Raw
-# Windows Terminal allows // comments; strip full-line comments so Windows
-# PowerShell's JSON parser can read the file. Inline comments are left alone.
-$cleaned = ($raw -split "`n" | Where-Object { $_ -notmatch '^\s*//' }) -join "`n"
-
-$json = $cleaned | ConvertFrom-Json
-
-if (-not $json.profiles) {
-  $json | Add-Member -NotePropertyName profiles -NotePropertyValue ([pscustomobject]@{}) -Force
-}
-if (-not $json.profiles.defaults) {
-  $json.profiles | Add-Member -NotePropertyName defaults -NotePropertyValue ([pscustomobject]@{}) -Force
-}
-if (-not $json.profiles.defaults.font) {
-  $json.profiles.defaults | Add-Member -NotePropertyName font -NotePropertyValue ([pscustomobject]@{}) -Force
-}
-
-# Build the comma-separated face chain: requested main face first, then the
-# faces already configured (never reordered), then the Arabic fallbacks.
-$chain = @()
-if ($Face) { $chain += $Face }
-$existingFace = $json.profiles.defaults.font.face
-if ($existingFace) {
-  $chain += ("$existingFace" -split "," | ForEach-Object { $_.Trim().Trim("'").Trim('"') } | Where-Object { $_ })
-}
-if ($chain.Count -eq 0) { $chain += "Cascadia Mono" }
-foreach ($name in @($Fallbacks) | Where-Object { $_ }) {
-  if ($chain -notcontains $name) { $chain += $name }
-}
-$json.profiles.defaults.font | Add-Member -NotePropertyName face -NotePropertyValue ($chain -join ", ") -Force
-$json.profiles.defaults.font.PSObject.Properties.Remove("fallbacks")
-
-$output = $json | ConvertTo-Json -Depth 64
-$utf8 = New-Object System.Text.UTF8Encoding($false)
-[System.IO.File]::WriteAllText($settingsPath, $output, $utf8)
-
-Write-Host ""
-Write-Host "Updated profiles.defaults.font:"
-Write-Host ("  face = " + ($chain -join ", "))
-Write-Host ""
-Write-Host "Restart Windows Terminal to apply. To undo, copy the backup over settings.json."
diff --git a/docs/rtl/fonts.ar.md b/docs/rtl/fonts.ar.md
deleted file mode 100644
index 2da53517abec..000000000000
--- a/docs/rtl/fonts.ar.md
+++ /dev/null
@@ -1,104 +0,0 @@
-# الخطوط العربية وإعداد الـ terminal
-
-التطبيق (TUI) ميقدرش يحمّل أو يختار خطوط. هو بيطلع خلايا يونيكود، والـ terminal
-هو اللي بيرسمها بالخط اللي **أنت** بتختاره. التعديل اللي في المستودع ده بيظبط
-**الترتيب والاتجاه والمحاذاة والالتفاف**؛ أما خط الـ terminal فهو اللي بيخلي
-الحروف العربية تتوصل وتطلع بشكل صح.
-
-> English: [fonts.md](./fonts.md)
-
-## ليه مينفعش نحدد الخط من OpenCode
-
-خلية الـ terminal هي حرف يونيكود واحد بيرسمه محرك خطوط الـ terminal (DirectWrite
-في Windows Terminal). التطبيقات مينفعش تودّي خطوط في المسار ده. اللي التطبيق
-**يقدر** يعمله — واللي بيعمله المستودع ده — هو إنه يحط الحروف الصح في الخلايا
-الصح بالترتيب الصح.
-
-## خطوط عربية مقترحة
-
-| الخط | الطراز | ملاحظات |
-| --- | --- | --- |
-| [Cairo](https://fonts.google.com/specimen/Cairo) | سانس حديث | متناسب العرض؛ الأفضل كـ fallback |
-| [Noto Naskh Arabic](https://fonts.google.com/noto/specimen/Noto+Naskh+Arabic) | نسخ تقليدي | متناسب العرض |
-| [IBM Plex Sans Arabic](https://fonts.google.com/specimen/IBM+Plex+Sans+Arabic) | سانس احترافي | متناسب العرض |
-| [Amiri](https://fonts.google.com/specimen/Amiri) | نسخ كلاسيكي | متناسب العرض |
-| [Tajawal](https://fonts.google.com/specimen/Tajawal) / [Almarai](https://fonts.google.com/specimen/Almarai) | سانس حديث | متناسب العرض |
-
-ويندوز بيجي أصلًا بخطوط **Segoe UI** و **Tahoma** و **Arial** وبيغطوا العربي،
-فالعربي بيظهر من غير أي حاجة — لكن مش دايمًا بأحسن توصيل. تركيب خط من اللي فوق
-بيحسّن شكل التشكيل.
-
-> ملاحظة مهمة: الخطوط دي **متناسبة العرض** مش monospaced. لو حطيت واحد منها كـ
-> `face` أساسي، النص اللاتيني هيبقى غير متساوي العرض والمحاذاة ممكن تخرب. الإعداد
-> الموصى به إنك تسيب الخط الـ monospaced الأساسي وتضيف الخط العربي كـ
-> **fallback**، فالحروف العربية بس هي اللي تستخدمه.
-
-## Windows Terminal
-
-ملف `settings.json` (نسخة المتجر):
-
-```
-%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json
-```
-
-### اختيار الخط من جوه OpenCode
-
-اكتب `/fonts` في البرومبت وهتفتحلك قايمة الخطوط. بتعرض الخطوط المركّبة على
-جهازك (الخطوط العربية المقترحة في الأول)، وبتحفظ اختيارك في إعدادات الـ terminal
-لوحدها مع نسخة احتياطية. بعد كده اقفل التيرمنال وافتحه تاني. **ومش بتركّب أي خط
-على الجهاز.**
-
-الأمر ده بيعدّل `profiles.defaults.font.face` لسلسلة خطوط مفصولة بفواصل (دي
-الطريقة الوحيدة اللي Windows Terminal بيفهم بيها الـ fallback)، يعني العربي
-هيستخدم الخط اللي اخترته والإنجليزي والكود هيفضلوا بالخط الـ monospaced.
-
-### يدويًا
-
-أضف الخطوط العربية لسلسلة `face` داخل `profiles.defaults.font`:
-
-```json
-{
-  "profiles": {
-    "defaults": {
-      "font": {
-        "face": "Cascadia Mono, Cairo, Noto Naskh Arabic, Segoe UI, Tahoma"
-      }
-    }
-  }
-}
-```
-
-أو شغّل السكربت الجاهز في نفس المجلد (بيعمل نسخة احتياطية أول حاجة):
-
-```powershell
-powershell -ExecutionPolicy Bypass -File docs/rtl/configure-windows-terminal-font.ps1
-# أو مع تحديد الخط الأساسي كمان:
-powershell -ExecutionPolicy Bypass -File docs/rtl/configure-windows-terminal-font.ps1 -Face "Cascadia Mono"
-```
-
-بعد التعديل اقفل Windows Terminal وافتحه تاني.
-
-## ترمينال VS Code
-
-في `settings.json`:
-
-```json
-{
-  "terminal.integrated.fontFamily": "'Cascadia Mono', 'Cairo', 'Noto Naskh Arabic', monospace"
-}
-```
-
-## الـ Console القديم (conhost)
-
-كليك يمين على شريط العنوان → Properties → Font. التغطية محدودة؛ وWindows
-Terminal أفضل للعربي.
-
-## للتأكد
-
-اكتب في برومبت OpenCode:
-
-```
-أهلاً بك في OpenCode
-```
-
-ولازم تلاقي الكلام مقروء من اليمين لليسار ومحاذى يمين.
diff --git a/docs/rtl/fonts.md b/docs/rtl/fonts.md
deleted file mode 100644
index 7391e5884204..000000000000
--- a/docs/rtl/fonts.md
+++ /dev/null
@@ -1,103 +0,0 @@
-# Arabic fonts & terminal setup
-
-The TUI cannot bundle or select fonts. It emits Unicode cells; the terminal
-emulator renders them with a font **you** choose. The bidi work in this
-repository fixes **ordering, direction, alignment and wrapping**; the terminal
-font is what makes Arabic letters join and look right.
-
-> العربية: [fonts.ar.md](./fonts.ar.md)
-
-## Why not set the font from OpenCode
-
-A terminal cell is one Unicode code point drawn by the terminal's font engine
-(DirectWrite on Windows Terminal). Applications cannot ship fonts into that
-pipeline. What an application *can* do — and what this repository does — is put
-the right code points in the right cells in the right order.
-
-## Recommended Arabic-capable fonts
-
-| Font | Style | Notes |
-| --- | --- | --- |
-| [Cairo](https://fonts.google.com/specimen/Cairo) | modern sans | proportional; best used as a fallback |
-| [Noto Naskh Arabic](https://fonts.google.com/noto/specimen/Noto+Naskh+Arabic) | traditional naskh | proportional |
-| [IBM Plex Sans Arabic](https://fonts.google.com/specimen/IBM+Plex+Sans+Arabic) | professional sans | proportional |
-| [Amiri](https://fonts.google.com/specimen/Amiri) | classical naskh | proportional |
-| [Tajawal](https://fonts.google.com/specimen/Tajawal) / [Almarai](https://fonts.google.com/specimen/Almarai) | modern sans | proportional |
-
-Windows already ships **Segoe UI**, **Tahoma** and **Arial**, which cover Arabic
-glyphs, so Arabic renders out of the box — just not always with consistent
-joining. Installing one of the fonts above improves shaping.
-
-> Note: these Arabic fonts are **proportional**, not monospaced. Setting one as
-> the terminal's main `face` makes Latin text non-monospaced and can misalign
-> columns. The recommended setup keeps your monospaced face and adds the Arabic
-> font as a **fallback**, so only Arabic glyphs use it.
-
-## Windows Terminal
-
-`settings.json` (Store build):
-
-```
-%LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json
-```
-
-### Pick it from inside OpenCode
-
-Type `/fonts` in the prompt to open the font picker. It lists the fonts installed
-on your machine (recommended Arabic fonts first), and writes your choice into
-the terminal's settings for you — keeping a timestamped backup. Then restart the
-terminal. It never installs fonts.
-
-Under the hood it sets `profiles.defaults.font.face` to a comma-separated
-fallback chain (the only fallback mechanism Windows Terminal honors), so
-Arabic uses the chosen font while Latin and code stay monospaced.
-
-### Manually
-
-Add the Arabic fonts to the `face` chain in `profiles.defaults.font`:
-
-```json
-{
-  "profiles": {
-    "defaults": {
-      "font": {
-        "face": "Cascadia Mono, Cairo, Noto Naskh Arabic, Segoe UI, Tahoma"
-      }
-    }
-  }
-}
-```
-
-Or run the helper script in this folder, which backs up `settings.json` first:
-
-```powershell
-powershell -ExecutionPolicy Bypass -File docs/rtl/configure-windows-terminal-font.ps1
-# or also set the main face:
-powershell -ExecutionPolicy Bypass -File docs/rtl/configure-windows-terminal-font.ps1 -Face "Cascadia Mono"
-```
-
-Restart Windows Terminal after changing the setting.
-
-## VS Code integrated terminal
-
-`settings.json`:
-
-```json
-{
-  "terminal.integrated.fontFamily": "'Cascadia Mono', 'Cairo', 'Noto Naskh Arabic', monospace"
-}
-```
-
-## Legacy Windows Console (conhost)
-
-Right-click the title bar → Properties → Font. Coverage is limited; Windows
-Terminal is recommended for Arabic.
-
-## Verify
-
-Type this in the OpenCode prompt and confirm the words read right-to-left and
-are right-aligned:
-
-```
-أهلاً بك في OpenCode
-```
diff --git a/packages/tui/src/app.tsx b/packages/tui/src/app.tsx
index fc25f2f84d85..ec68723dc23a 100644
--- a/packages/tui/src/app.tsx
+++ b/packages/tui/src/app.tsx
@@ -45,7 +45,6 @@ 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 { DialogFonts } from "./component/dialog-fonts"
 import "./component/bidi-elements"
 import { DialogHelp } from "./ui/dialog-help"
 import { DialogAgent } from "./component/dialog-agent"
@@ -747,17 +746,6 @@ function App(props: { onSnapshot?: () => Promise<string[]>; pluginHost: TuiPlugi
         },
         category: "Provider",
       },
-      {
-        name: "font.pick",
-        title: "Terminal font for Arabic",
-        desc: "Choose the font the terminal uses for RTL text",
-        slashName: "fonts",
-        slashAliases: ["font"],
-        run: () => {
-          dialog.replace(() => <DialogFonts />)
-        },
-        category: "System",
-      },
       ...(sync.data.console_state.switchableOrgCount > 1
         ? [
             {
diff --git a/packages/tui/src/component/dialog-fonts.tsx b/packages/tui/src/component/dialog-fonts.tsx
deleted file mode 100644
index 848008db2669..000000000000
--- a/packages/tui/src/component/dialog-fonts.tsx
+++ /dev/null
@@ -1,46 +0,0 @@
-import { DialogSelect } from "../ui/dialog-select"
-import { useDialog } from "../ui/dialog"
-import { useToast } from "../ui/toast"
-import { applyArabicFont, fontChoices } from "../util/terminal-font"
-
-// The TUI cannot render with its own font, so this dialog picks the font the
-// terminal uses for Arabic text and writes it into the terminal's settings
-// (Windows Terminal or VS Code). It never installs fonts.
-export function DialogFonts() {
-  const dialog = useDialog()
-  const toast = useToast()
-  const options = fontChoices().map((choice) => ({
-    title: choice.family,
-    value: choice.family,
-    description: choice.installed
-      ? choice.recommended
-        ? "installed · recommended for Arabic"
-        : "installed"
-      : "not installed — the terminal will fall back to another font",
-    category: choice.recommended ? "Recommended for Arabic" : "All installed fonts",
-  }))
-
-  return (
-    <DialogSelect
-      title="Terminal font for Arabic"
-      placeholder="Search fonts…"
-      options={options}
-      onSelect={(option) => {
-        const result = applyArabicFont(option.value)
-        if (!result.ok) {
-          toast.show({ variant: "error", message: result.message, duration: 6000 })
-          return
-        }
-        dialog.clear()
-        toast.show({
-          variant: "success",
-          message: `${option.value} set in ${result.target}. ${result.hint}`,
-          duration: 10000,
-        })
-      }}
-      footer={
-        <text>Saved with a backup next to the settings file. The TUI itself cannot choose fonts — the terminal does.</text>
-      }
-    />
-  )
-}
diff --git a/packages/tui/src/util/terminal-font.ts b/packages/tui/src/util/terminal-font.ts
deleted file mode 100644
index ea50806dde9a..000000000000
--- a/packages/tui/src/util/terminal-font.ts
+++ /dev/null
@@ -1,292 +0,0 @@
-import { copyFileSync, existsSync, readFileSync, writeFileSync } from "node:fs"
-import path from "node:path"
-
-// The TUI cannot render with its own font - the terminal emulator owns text
-// shaping and font selection. This module is the application-level bridge: it
-// detects installed font families and writes the user's choice into the
-// settings of the terminal that actually renders the cells (Windows Terminal
-// or the VS Code integrated terminal), keeping a timestamped backup.
-
-export const RECOMMENDED_ARABIC_FONTS = [
-  "Cairo",
-  "Noto Naskh Arabic",
-  "IBM Plex Sans Arabic",
-  "Amiri",
-  "Tajawal",
-  "Almarai",
-  "Segoe UI",
-  "Tahoma",
-  "Arial",
-] as const
-
-export type FontChoice = { family: string; installed: boolean; recommended: boolean }
-
-export type ApplyOutcome =
-  | { ok: true; target: string; path: string; backup: string; hint: string }
-  | { ok: false; message: string }
-
-function timestamp() {
-  const date = new Date()
-  const pad = (value: number) => String(value).padStart(2, "0")
-  return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`
-}
-
-// JSON with comments (VS Code settings, Windows Terminal settings) is not
-// valid JSON. Strip comments and trailing commas before parsing.
-export function sanitizeJsonc(text: string) {
-  let out = ""
-  let inString = false
-  let quote = ""
-  let index = 0
-  while (index < text.length) {
-    const char = text[index]
-    const next = text[index + 1]
-    if (inString) {
-      out += char
-      if (char === "\\") {
-        out += next ?? ""
-        index += 2
-        continue
-      }
-      if (char === quote) inString = false
-      index++
-      continue
-    }
-    if (char === '"' || char === "'") {
-      inString = true
-      quote = char
-      out += char
-      index++
-      continue
-    }
-    if (char === "/" && next === "/") {
-      while (index < text.length && text[index] !== "\n") index++
-      continue
-    }
-    if (char === "/" && next === "*") {
-      index += 2
-      while (index < text.length && !(text[index] === "*" && text[index + 1] === "/")) index++
-      index += 2
-      continue
-    }
-    out += char
-    index++
-  }
-  return out.replace(/,(\s*[}\]])/g, "$1")
-}
-
-export function windowsTerminalSettingsPath(): string | undefined {
-  if (!process.env.LOCALAPPDATA) return undefined
-  const candidates = [
-    path.join(
-      process.env.LOCALAPPDATA,
-      "Packages/Microsoft.WindowsTerminal_8wekyb3d8bbwe/LocalState/settings.json",
-    ),
-    path.join(
-      process.env.LOCALAPPDATA,
-      "Packages/Microsoft.WindowsTerminalPreview_8wekyb3d8bbwe/LocalState/settings.json",
-    ),
-    path.join(process.env.LOCALAPPDATA, "Microsoft/Windows Terminal/settings.json"),
-  ]
-  return candidates.find((candidate) => existsSync(candidate))
-}
-
-export function vscodeSettingsPath(): string | undefined {
-  if (!process.env.APPDATA) return undefined
-  const candidates = [
-    path.join(process.env.APPDATA, "Code/User/settings.json"),
-    path.join(process.env.APPDATA, "Code - Insiders/User/settings.json"),
-  ]
-  return candidates.find((candidate) => existsSync(candidate))
-}
-
-function backup(file: string) {
-  const target = `${file}.opencode-backup-${timestamp()}`
-  copyFileSync(file, target)
-  return target
-}
-
-function readJsonc(file: string) {
-  return JSON.parse(sanitizeJsonc(readFileSync(file, "utf8"))) as Record<string, unknown>
-}
-
-function writeJson(file: string, value: unknown) {
-  writeFileSync(file, JSON.stringify(value, null, 4), { encoding: "utf8" })
-}
-
-// Windows Terminal resolves `font.face` as a CSS-like fallback chain
-// ("Cascadia Mono, Cairo, ..."). There is no `font.fallbacks` setting;
-// writing one is silently ignored, so the writer below always uses `face`.
-export const DEFAULT_WINDOWS_TERMINAL_FACE = "Cascadia Mono"
-
-export function splitFontFaces(face: string | undefined): string[] {
-  return (face ?? "")
-    .split(",")
-    .map((part) => part.trim().replace(/^['"]|['"]$/g, ""))
-    .filter(Boolean)
-}
-
-// The chosen font is always kept (the dialog already warns when it is not
-// installed); the rest of the tail is limited to resolving families.
-export function availableFontFamilies(family: string, installed: string[]) {
-  return [
-    family,
-    ...RECOMMENDED_ARABIC_FONTS.filter((item) => item !== family && isFontInstalled(item, installed)),
-  ]
-}
-
-// Builds the fallback chain: the user's current faces first (never reordered),
-// then the given tail. Windows Terminal warns about every missing family in
-// the chain, so callers pass only resolving families in the tail.
-export function buildFontFaceChain(existingFace: string | undefined, tail: string[]) {
-  const base = splitFontFaces(existingFace)
-  if (base.length === 0) base.push(DEFAULT_WINDOWS_TERMINAL_FACE)
-  const seen = new Set(base.map((name) => name.toLowerCase()))
-  const out = [...base]
-  for (const name of tail) {
-    if (seen.has(name.toLowerCase())) continue
-    seen.add(name.toLowerCase())
-    out.push(name)
-  }
-  return out.join(", ")
-}
-
-export function readWindowsTerminalFont(): { face?: string; faces: string[] } | undefined {
-  const file = windowsTerminalSettingsPath()
-  if (!file) return undefined
-  const json = readJsonc(file)
-  const defaults = (json.profiles as Record<string, unknown> | undefined)?.defaults as
-    | Record<string, unknown>
-    | undefined
-  const font = defaults?.font as { face?: unknown } | undefined
-  const face = typeof font?.face === "string" ? font.face : undefined
-  return { face, faces: splitFontFaces(face) }
-}
-
-export function writeWindowsTerminalFont(input: { face: string }): {
-  path: string
-  backup: string
-} {
-  const file = windowsTerminalSettingsPath()
-  if (!file) throw new Error("Windows Terminal settings.json not found")
-  const created = backup(file)
-  const json = readJsonc(file)
-  const profiles = (json.profiles ??= {}) as Record<string, unknown>
-  const defaults = (profiles.defaults ??= {}) as Record<string, unknown>
-  const font = (defaults.font ??= {}) as Record<string, unknown>
-  font.face = input.face
-  // A previous version of this tool wrote an unsupported `fallbacks` array;
-  // remove it so the file only carries settings the terminal honors.
-  delete font.fallbacks
-  writeJson(file, json)
-  return { path: file, backup: created }
-}
-
-export function appendFontFamily(existing: string | undefined, family: string) {
-  const parts = (existing ?? "")
-    .split(",")
-    .map((part) => part.trim())
-    .filter(Boolean)
-  const unquoted = (value: string) => value.replace(/^['"]|['"]$/g, "")
-  if (parts.some((part) => unquoted(part) === family)) return parts.join(", ")
-  const trailing = parts.length > 0 && unquoted(parts[parts.length - 1]).toLowerCase() === "monospace" ? parts.pop() : undefined
-  parts.push(`'${family}'`)
-  if (trailing !== undefined) parts.push(trailing)
-  return parts.join(", ")
-}
-
-export function writeVSCodeFontFamily(family: string): { path: string; backup: string } {
-  const file = vscodeSettingsPath()
-  if (!file) throw new Error("VS Code settings.json not found")
-  const created = backup(file)
-  const json = readJsonc(file)
-  const key = "terminal.integrated.fontFamily"
-  const existing = typeof json[key] === "string" ? (json[key] as string) : undefined
-  json[key] = appendFontFamily(existing, family)
-  writeJson(file, json)
-  return { path: file, backup: created }
-}
-
-export function installedFontFamilies(): string[] {
-  if (process.platform !== "win32") return []
-  const roots = [
-    "HKLM\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\Fonts",
-    "HKCU\\SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\Fonts",
-  ]
-  const found = new Set<string>()
-  for (const root of roots) {
-    const result = Bun.spawnSync(["reg", "query", root], { stdout: "pipe", stderr: "ignore" })
-    if (result.exitCode !== 0) continue
-    for (const line of result.stdout.toString().split(/\r?\n/)) {
-      const match = line.match(/^\s+(.+?)\s+REG_SZ\s+/)
-      if (!match) continue
-      const family = match[1].replace(/\s+\((TrueType|OpenType|All res|Type 1)\)\s*$/i, "").trim()
-      if (family) found.add(family)
-    }
-  }
-  return [...found].sort((a, b) => a.localeCompare(b, undefined, { sensitivity: "base" }))
-}
-
-export function isFontInstalled(family: string, installed = installedFontFamilies()) {
-  return installed.some((name) => name === family || name.startsWith(`${family} `))
-}
-
-export function fontChoices(): FontChoice[] {
-  const installed = installedFontFamilies()
-  const recommended: FontChoice[] = RECOMMENDED_ARABIC_FONTS.map((family) => ({
-    family,
-    installed: isFontInstalled(family, installed),
-    recommended: true,
-  }))
-  const others: FontChoice[] = installed
-    .filter((name) => !recommended.some((choice) => name === choice.family || name.startsWith(`${choice.family} `)))
-    .map((family) => ({ family, installed: true, recommended: false }))
-  return [...recommended, ...others]
-}
-
-export type TerminalHost = "windows-terminal" | "vscode" | "other"
-
-// Which terminal is actually hosting this process. Picking the settings file by
-// presence alone is wrong when both Windows Terminal and VS Code are installed:
-// the dialog must write the settings of the terminal that renders the cells.
-export function detectTerminalHost(env: NodeJS.ProcessEnv = process.env): TerminalHost {
-  if (env.WT_SESSION) return "windows-terminal"
-  if (env.TERM_PROGRAM === "vscode" || env.VSCODE_INJECTION || env.VSCODE_IPC_HOOK_CLI) return "vscode"
-  return "other"
-}
-
-export function applyArabicFont(family: string): ApplyOutcome {
-  const host = detectTerminalHost()
-  const windowsTerminal = windowsTerminalSettingsPath()
-  const vscode = vscodeSettingsPath()
-
-  if (host === "windows-terminal" && windowsTerminal) return applyWindowsTerminalFont(family)
-  if (host === "vscode" && vscode) return applyVSCodeFont(family)
-  if (windowsTerminal) return applyWindowsTerminalFont(family)
-  if (vscode) return applyVSCodeFont(family)
-  return { ok: false, message: "No supported terminal settings found (Windows Terminal or VS Code)." }
-}
-
-function applyWindowsTerminalFont(family: string): ApplyOutcome {
-  const tail = availableFontFamilies(family, installedFontFamilies())
-  const face = buildFontFaceChain(readWindowsTerminalFont()?.face, tail)
-  const written = writeWindowsTerminalFont({ face })
-  return {
-    ok: true,
-    target: "Windows Terminal",
-    path: written.path,
-    backup: written.backup,
-    hint: "Close every Windows Terminal window and reopen it for the font to take effect.",
-  }
-}
-
-function applyVSCodeFont(family: string): ApplyOutcome {
-  const written = writeVSCodeFontFamily(family)
-  return {
-    ok: true,
-    target: "VS Code integrated terminal",
-    path: written.path,
-    backup: written.backup,
-    hint: "Open a new terminal in VS Code for the font to take effect.",
-  }
-}
diff --git a/packages/tui/test/bidi-dialogs-e2e.test.tsx b/packages/tui/test/bidi-dialogs-e2e.test.tsx
index be3e52e50401..3d49b54dcb37 100644
--- a/packages/tui/test/bidi-dialogs-e2e.test.tsx
+++ b/packages/tui/test/bidi-dialogs-e2e.test.tsx
@@ -137,18 +137,6 @@ async function bootApp(args: Record<string, unknown> = {}) {
   }
 }
 
-test("e2e: /fonts command opens the terminal font dialog", async () => {
-  const app = await bootApp({ sessionID: "ses_test" })
-  try {
-    app.dispatch("font.pick")
-    const frame = await app.waitForFrame((f) => f.includes("Terminal font for Arabic"), "fonts dialog")
-    expect(frame.includes("Terminal font for Arabic")).toBe(true)
-    expect(frame.includes("Recommended for Arabic")).toBe(true)
-  } finally {
-    await app.exit()
-  }
-}, 60000)
-
 test("e2e: Arabic renders RTL inside a DialogSelect list", async () => {
   const app = await bootApp({ sessionID: "ses_test" })
   try {
diff --git a/packages/tui/test/util/terminal-font.test.ts b/packages/tui/test/util/terminal-font.test.ts
deleted file mode 100644
index 88af58385661..000000000000
--- a/packages/tui/test/util/terminal-font.test.ts
+++ /dev/null
@@ -1,210 +0,0 @@
-import { afterEach, describe, expect, test } from "bun:test"
-import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
-import { tmpdir } from "node:os"
-import path from "node:path"
-import {
-  RECOMMENDED_ARABIC_FONTS,
-  appendFontFamily,
-  applyArabicFont,
-  availableFontFamilies,
-  buildFontFaceChain,
-  detectTerminalHost,
-  installedFontFamilies,
-  isFontInstalled,
-  sanitizeJsonc,
-  splitFontFaces,
-} from "../../src/util/terminal-font"
-
-const roots: string[] = []
-const env = {
-  local: process.env.LOCALAPPDATA,
-  appdata: process.env.APPDATA,
-  term: process.env.TERM_PROGRAM,
-  wt: process.env.WT_SESSION,
-}
-
-function tempDir() {
-  const dir = mkdtempSync(path.join(tmpdir(), "oc-font-"))
-  roots.push(dir)
-  return dir
-}
-
-afterEach(() => {
-  process.env.LOCALAPPDATA = env.local
-  process.env.APPDATA = env.appdata
-  if (env.term === undefined) delete process.env.TERM_PROGRAM
-  else process.env.TERM_PROGRAM = env.term
-  if (env.wt === undefined) delete process.env.WT_SESSION
-  else process.env.WT_SESSION = env.wt
-  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
-})
-
-describe("sanitizeJsonc", () => {
-  test("removes line, block comments and trailing commas", () => {
-    const input = `{
-      // a comment
-      "a": 1, /* inline */
-      "b": [1, 2,],
-    }`
-    expect(JSON.parse(sanitizeJsonc(input))).toEqual({ a: 1, b: [1, 2] })
-  })
-
-  test("does not touch comment markers inside strings", () => {
-    const input = `{ "url": "https://example.com//x", "a": 1 }`
-    expect(JSON.parse(sanitizeJsonc(input))).toEqual({ url: "https://example.com//x", a: 1 })
-  })
-})
-
-describe("appendFontFamily", () => {
-  test("appends and keeps monospace last", () => {
-    expect(appendFontFamily("'Cascadia Mono', monospace", "Cairo")).toBe("'Cascadia Mono', 'Cairo', monospace")
-  })
-
-  test("is idempotent", () => {
-    expect(appendFontFamily("'Cairo', monospace", "Cairo")).toBe("'Cairo', monospace")
-  })
-
-  test("starts a list when unset", () => {
-    expect(appendFontFamily(undefined, "Noto Naskh Arabic")).toBe("'Noto Naskh Arabic'")
-  })
-})
-
-describe("isFontInstalled", () => {
-  test("matches exact names and named instances", () => {
-    const installed = ["Cairo", "Cairo Black", "Tahoma"]
-    expect(isFontInstalled("Cairo", installed)).toBe(true)
-    expect(isFontInstalled("Tahoma", installed)).toBe(true)
-    expect(isFontInstalled("Amiri", installed)).toBe(false)
-  })
-})
-
-describe("detectTerminalHost", () => {
-  test("detects Windows Terminal from WT_SESSION", () => {
-    expect(detectTerminalHost({ WT_SESSION: "abc" })).toBe("windows-terminal")
-  })
-
-  test("detects the VS Code integrated terminal", () => {
-    expect(detectTerminalHost({ TERM_PROGRAM: "vscode" })).toBe("vscode")
-    expect(detectTerminalHost({ VSCODE_INJECTION: "1" })).toBe("vscode")
-  })
-
-  test("falls back to other", () => {
-    expect(detectTerminalHost({})).toBe("other")
-  })
-})
-
-describe("splitFontFaces", () => {
-  test("splits a comma chain and drops quotes and blanks", () => {
-    expect(splitFontFaces(`'Cascadia Mono', Cairo ,, "Segoe UI"`)).toEqual(["Cascadia Mono", "Cairo", "Segoe UI"])
-  })
-
-  test("returns an empty list when unset", () => {
-    expect(splitFontFaces(undefined)).toEqual([])
-  })
-})
-
-describe("availableFontFamilies", () => {
-  test("keeps the chosen font and only resolving recommended fonts", () => {
-    const installed = ["Cairo", "Cairo Regular", "Segoe UI", "Tahoma"]
-    expect(availableFontFamilies("Amiri", installed)).toEqual(["Amiri", "Cairo", "Segoe UI", "Tahoma"])
-  })
-})
-
-describe("buildFontFaceChain", () => {
-  test("keeps the current faces first, then the tail", () => {
-    expect(buildFontFaceChain("Cascadia Mono", ["Cairo", "Segoe UI"])).toBe("Cascadia Mono, Cairo, Segoe UI")
-  })
-
-  test("defaults to Cascadia Mono when no face is set", () => {
-    expect(buildFontFaceChain(undefined, ["Amiri"]).startsWith("Cascadia Mono, Amiri")).toBe(true)
-  })
-
-  test("never reorders or duplicates the user's faces", () => {
-    expect(buildFontFaceChain("Cascadia Mono, Segoe UI", ["Cairo", "Segoe UI"])).toBe(
-      "Cascadia Mono, Segoe UI, Cairo",
-    )
-  })
-})
-
-describe("applyArabicFont", () => {
-  test("writes a Windows Terminal face chain and keeps a backup", () => {
-    const root = tempDir()
-    const settings = path.join(root, "Packages/Microsoft.WindowsTerminal_8wekyb3d8bbwe/LocalState/settings.json")
-    mkdirSync(path.dirname(settings), { recursive: true })
-    writeFileSync(settings, JSON.stringify({ profiles: { defaults: { font: { face: "Cascadia Mono" } } } }))
-    process.env.LOCALAPPDATA = root
-    process.env.APPDATA = path.join(root, "no-vscode")
-
-    const result = applyArabicFont("Amiri")
-    expect(result.ok).toBe(true)
-    if (!result.ok) return
-    expect(result.target).toBe("Windows Terminal")
-
-    const written = JSON.parse(readFileSync(settings, "utf8"))
-    const faces = String(written.profiles.defaults.font.face)
-      .split(",")
-      .map((part: string) => part.trim())
-    expect(faces[0]).toBe("Cascadia Mono")
-    expect(faces[1]).toBe("Amiri")
-    // The tail mirrors what resolves on this machine: installed recommended
-    // fonts are present, missing ones are left out so the terminal never warns.
-    const installed = installedFontFamilies()
-    for (const font of RECOMMENDED_ARABIC_FONTS) {
-      if (font === "Amiri") continue
-      if (isFontInstalled(font, installed)) expect(faces).toContain(font)
-      else expect(faces).not.toContain(font)
-    }
-    expect(written.profiles.defaults.font.fallbacks).toBeUndefined()
-    expect(readFileSync(result.backup, "utf8")).toContain("Cascadia Mono")
-  })
-
-  test("removes a stale unsupported fallbacks array", () => {
-    const root = tempDir()
-    const settings = path.join(root, "Packages/Microsoft.WindowsTerminal_8wekyb3d8bbwe/LocalState/settings.json")
-    mkdirSync(path.dirname(settings), { recursive: true })
-    writeFileSync(
-      settings,
-      JSON.stringify({ profiles: { defaults: { font: { fallbacks: ["Bauhaus 93", "Cairo"] } } } }),
-    )
-    process.env.LOCALAPPDATA = root
-    process.env.APPDATA = path.join(root, "no-vscode")
-
-    const result = applyArabicFont("Cairo")
-    expect(result.ok).toBe(true)
-    const written = JSON.parse(readFileSync(settings, "utf8"))
-    expect(String(written.profiles.defaults.font.face).startsWith("Cascadia Mono, Cairo")).toBe(true)
-    expect(written.profiles.defaults.font.fallbacks).toBeUndefined()
-  })
-
-  test("targets VS Code when hosted by VS Code even if Windows Terminal is installed", () => {
-    const root = tempDir()
-    const wtSettings = path.join(root, "Packages/Microsoft.WindowsTerminal_8wekyb3d8bbwe/LocalState/settings.json")
-    mkdirSync(path.dirname(wtSettings), { recursive: true })
-    writeFileSync(wtSettings, JSON.stringify({ profiles: { defaults: { font: { face: "Cascadia Mono" } } } }))
-
-    const appdata = path.join(root, "appdata")
-    const vscode = path.join(appdata, "Code/User/settings.json")
-    mkdirSync(path.dirname(vscode), { recursive: true })
-    writeFileSync(vscode, JSON.stringify({}))
-
-    process.env.LOCALAPPDATA = root
-    process.env.APPDATA = appdata
-    process.env.TERM_PROGRAM = "vscode"
-    delete process.env.WT_SESSION
-
-    const result = applyArabicFont("Cairo")
-    expect(result.ok).toBe(true)
-    if (!result.ok) return
-    expect(result.target).toBe("VS Code integrated terminal")
-    expect(JSON.parse(readFileSync(vscode, "utf8"))["terminal.integrated.fontFamily"]).toContain("Cairo")
-    expect(JSON.parse(readFileSync(wtSettings, "utf8")).profiles.defaults.font.fallbacks).toBeUndefined()
-  })
-
-  test("reports failure when no supported terminal exists", () => {
-    const root = tempDir()
-    process.env.LOCALAPPDATA = path.join(root, "missing")
-    process.env.APPDATA = path.join(root, "missing2")
-    const result = applyArabicFont("Cairo")
-    expect(result.ok).toBe(false)
-  })
-})

From 916acaa05ead38b3c3065ec7975cb8e2baf839d8 Mon Sep 17 00:00:00 2001
From: mbeshirWaqoor <m.beshir@waqoor.com>
Date: Sun, 13 Sep 2026 08:54:07 +0300
Subject: [PATCH 10/10] fix(tui): correct mixed-direction BiDi ordering,
 isolation and wrapping

- Apply UAX #9 L2 flips over the full augmented stream including isolate
  controls, matching the reference application instead of clamping them
  away. Clamping rotated words and detached punctuation in mixed runs.
- Expand each island across adjacent Latin/digit words so one isolate
  covers every maximal LTR run; sibling sub-flips plus the whole-line
  flip otherwise swap neighboring runs.
- Broaden island seeds: markdown code spans, spaced Windows paths and
  key:line references. Code spans containing RTL prose stay natural.
- Prefer wrapping outside LTR islands so tokens are not split across
  visual lines unless unavoidable.
- Paint multi-unit graphemes with drawText: native setCell drops Arabic
  tashkeel. Shared paintBidiCell helper for text, textarea and markdown.
- Install markdown bidi paint on CodeRenderable itself so list items,
  blockquotes and streaming updates inherit it; fenced code and English
  keep the stock painter. Drop the now-redundant renderNode hook.
- Regression tests for mixed Arabic/English/code/path/URL/number runs,
  lists, links, diffs, wrapping and tashkeel in all three paint paths.
---
 docs/rtl/README.ar.md                         |   9 +
 docs/rtl/README.md                            |  13 +
 packages/tui/src/component/bidi-elements.ts   |   6 +
 packages/tui/src/component/bidi-markdown.ts   | 152 +++++++----
 packages/tui/src/component/bidi-text.ts       |   4 +-
 packages/tui/src/component/bidi-textarea.ts   |   4 +-
 packages/tui/src/routes/session/index.tsx     |   5 +-
 packages/tui/src/util/bidi.ts                 | 219 +++++++++++-----
 packages/tui/test/bidi-e2e.test.tsx           |  18 ++
 .../tui/test/component/bidi-mixed.test.tsx    | 242 ++++++++++++++++++
 .../tui/test/component/bidi-render.test.tsx   |  23 +-
 11 files changed, 563 insertions(+), 132 deletions(-)
 create mode 100644 packages/tui/test/component/bidi-mixed.test.tsx

diff --git a/docs/rtl/README.ar.md b/docs/rtl/README.ar.md
index 8379e8161571..9ff5f455f7be 100644
--- a/docs/rtl/README.ar.md
+++ b/docs/rtl/README.ar.md
@@ -115,7 +115,9 @@ JavaScript خالص، بدون اعتماديات وقت التشغيل، ومُ
 ```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
 ```
 
@@ -125,5 +127,12 @@ bun run --cwd packages/tui typecheck
   الترتيب والاتجاه والمحاذاة، وهوه اللي الراسم الخلوي يقدر يتحكم فيه.
 - إخفاء الماركداون (backticks المخفية) ممكن يفقد ألوان بعض المقاطع لفترة
   بسيطة وقت البث؛ لكن الترتيب دايمًا صح.
+- جداول الماركداون بتفضل بالراسم الأصلي: العربي جوه الخلايا بيظهر بالترتيب
+  المنطقي على الشمال. الجداول سطح بيانات، وإعادة تدفقها حسب الاتجاه هتكسر
+  محاذاة الأعمدة والنسخ/اللصق.
+- سطور الـ diff بتحافظ على بنية الكود؛ والنص العربي في السطور المضافة/المحذوفة
+  بيتبع اتجاه الفقرة وعلامات +/- وأرقام السطور ثابتة.
+- علامات القوائم (`-`، `1.`) بتفضل على الحرف الشمال؛ ومحتوى العنصر بيتبع
+  اتجاه الفقرة.
 - `Home`/`End` والقفز بين الكلمات لسه بمنطق الإزاحة المنطقية (سلوك أصلي).
 - الضغط بالماوس في البرومبت لسه بالسلوك الأصلي؛ حركة الكيبورد واعية بالكامل.
diff --git a/docs/rtl/README.md b/docs/rtl/README.md
index 229c4511d8e7..bb892d97bdce 100644
--- a/docs/rtl/README.md
+++ b/docs/rtl/README.md
@@ -119,7 +119,9 @@ mirroring); all rendering policy lives in this repository.
 ```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
 ```
 
@@ -127,6 +129,10 @@ bun run --cwd packages/tui typecheck
   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.
 
@@ -136,6 +142,13 @@ bun run --cwd packages/tui typecheck
   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/packages/tui/src/component/bidi-elements.ts b/packages/tui/src/component/bidi-elements.ts
index 201e4d8fac8d..e49d040f540d 100644
--- a/packages/tui/src/component/bidi-elements.ts
+++ b/packages/tui/src/component/bidi-elements.ts
@@ -1,6 +1,7 @@
 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
@@ -11,11 +12,16 @@ import { BidiTextareaRenderable } from "./bidi-textarea"
 // 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 {
diff --git a/packages/tui/src/component/bidi-markdown.ts b/packages/tui/src/component/bidi-markdown.ts
index 2813b248da02..41fab764b9bc 100644
--- a/packages/tui/src/component/bidi-markdown.ts
+++ b/packages/tui/src/component/bidi-markdown.ts
@@ -4,23 +4,22 @@ import {
   type ChunkRenderContext,
   type OnChunksCallback,
   type OptimizedBuffer,
-  type RenderNodeContext,
   type TextChunk,
 } from "@opentui/core"
-import { hasRtl, layoutBidiText, widthOffsetToBoundary, wrappedLogicalText, type BidiLayout } from "../util/bidi"
+import { hasRtl, layoutBidiText, paintBidiCell, widthOffsetToBoundary, wrappedLogicalText, type BidiLayout } from "../util/bidi"
 
-// Markdown renderNode hook that installs bidi-aware painting on the text
-// blocks (paragraph/heading) of a <markdown> element. Fenced code blocks,
-// tables, diffs and every other block keep the stock LTR renderer, which is
-// the required behavior for code.
+// 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.
 //
-// OpenTUI 0.4.5 offers renderNode as the only per-block override that
-// preserves in-place streaming updates, so the hook patches the default
-// renderable instance: it shadows renderSelf (the paint entrypoint) and
-// wraps the onChunks callback to capture the tree-sitter styled chunks.
-// Nothing else about the renderable changes: measurement, selection, copy
-// and streaming reconciliation continue through the native text buffer,
-// which is kept in sync with the wrapped logical text.
+// 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
@@ -40,9 +39,11 @@ type BidiCodeState = {
   // new styles) still rebuild the layout instead of painting a stale one.
   styledVersion: number
   paintedVersion: number
+  chunksWrapper: OnChunksCallback | undefined
 }
 
-const patched = new WeakSet<CodeRenderable>()
+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
@@ -57,34 +58,46 @@ type CodeInternals = {
   _highlightsDirty?: boolean
 }
 
-export function bidiMarkdownRenderNode(token: { type: string }, context: RenderNodeContext) {
-  if (token.type !== "paragraph" && token.type !== "heading") return undefined
-  const renderable = context.defaultRender()
-  if (!(renderable instanceof CodeRenderable)) return renderable ?? undefined
-  applyBidiCodePaint(renderable)
-  return renderable
+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
 }
 
-export function applyBidiCodePaint(renderable: CodeRenderable) {
-  if (patched.has(renderable)) return
-  patched.add(renderable)
-
-  const state: BidiCodeState = {
-    styled: undefined,
-    layout: undefined,
-    source: "",
-    wrapped: undefined,
-    width: 0,
-    styledVersion: 0,
-    paintedVersion: -1,
-  }
-  const internals = renderable as unknown as CodeInternals
-  const self = renderable as unknown as { renderSelf(buffer: OptimizedBuffer): void }
-  const originalRenderSelf = self.renderSelf.bind(renderable)
+function proseFiletype(renderable: CodeRenderable) {
+  return (renderable as unknown as { filetype?: unknown }).filetype
+}
 
-  const originalOnChunks: OnChunksCallback | undefined = renderable.onChunks
-  renderable.onChunks = async (chunks: TextChunk[], context: ChunkRenderContext) => {
-    const result = originalOnChunks ? await originalOnChunks(chunks, context) : undefined
+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[] = []
@@ -98,24 +111,51 @@ export function applyBidiCodePaint(renderable: CodeRenderable) {
     state.wrapped = undefined
     return result
   }
+  state.chunksWrapper = wrapper
+  renderable.onChunks = wrapper
+}
 
-  self.renderSelf = (buffer: OptimizedBuffer) => {
-    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
-      }
-      originalRenderSelf(buffer)
+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 ||
@@ -144,7 +184,6 @@ export function applyBidiCodePaint(renderable: CodeRenderable) {
     }
     paintStyledLines(buffer, state, renderable)
   }
-}
 
 function paintStyledLines(buffer: OptimizedBuffer, state: BidiCodeState, renderable: CodeRenderable) {
   const layout = state.layout
@@ -172,7 +211,8 @@ function paintStyledLines(buffer: OptimizedBuffer, state: BidiCodeState, rendera
       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
-      buffer.setCell(
+      paintBidiCell(
+        buffer,
         x,
         y,
         cell.char,
diff --git a/packages/tui/src/component/bidi-text.ts b/packages/tui/src/component/bidi-text.ts
index 5b49523c84cf..9c1077808cdb 100644
--- a/packages/tui/src/component/bidi-text.ts
+++ b/packages/tui/src/component/bidi-text.ts
@@ -1,5 +1,5 @@
 import { TextRenderable, type OptimizedBuffer } from "@opentui/core"
-import { hasRtl, layoutBidiText, wrappedLogicalText, type BidiLayout } from "../util/bidi"
+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
@@ -51,7 +51,7 @@ export class BidiTextRenderable extends TextRenderable {
       for (const cell of line.cells) {
         const x = x0 + cell.col
         if (x < 0 || x >= buffer.width) continue
-        buffer.setCell(x, y, cell.char, fg, bg, attributes)
+        paintBidiCell(buffer, x, y, cell.char, fg, bg, attributes)
       }
     }
   }
diff --git a/packages/tui/src/component/bidi-textarea.ts b/packages/tui/src/component/bidi-textarea.ts
index efd148da8333..987fab82be42 100644
--- a/packages/tui/src/component/bidi-textarea.ts
+++ b/packages/tui/src/component/bidi-textarea.ts
@@ -5,6 +5,7 @@ import {
   hasRtl,
   layoutBidiText,
   logicalCursorToBoundary,
+  paintBidiCell,
   visualStep,
   visualToBoundary,
   widthOffsetToBoundary,
@@ -75,7 +76,8 @@ export class BidiTextareaRenderable extends TextareaRenderable {
         const x = x0 + cell.col
         if (x < 0 || x >= buffer.width) continue
         const selected = selStart >= 0 && cell.glyph >= selStart && cell.glyph < selEnd
-        buffer.setCell(
+        paintBidiCell(
+          buffer,
           x,
           y,
           cell.char,
diff --git a/packages/tui/src/routes/session/index.tsx b/packages/tui/src/routes/session/index.tsx
index e18993ec1eb3..f9b6d977e69a 100644
--- a/packages/tui/src/routes/session/index.tsx
+++ b/packages/tui/src/routes/session/index.tsx
@@ -24,7 +24,7 @@ import { SplitBorder } from "../../ui/border"
 import { useTuiPaths, useTuiTerminalEnvironment } from "../../context/runtime"
 import { Spinner } from "../../component/spinner"
 import { createSyntaxStyleMemo, generateSubtleSyntax, selectedForeground, useTheme } from "../../context/theme"
-import { BoxRenderable, CodeRenderable, ScrollBoxRenderable, addDefaultParsers, TextAttributes, RGBA } from "@opentui/core"
+import { BoxRenderable, ScrollBoxRenderable, addDefaultParsers, TextAttributes, RGBA } from "@opentui/core"
 import { Prompt, type PromptRef } from "../../component/prompt"
 import type {
   AssistantMessage,
@@ -81,7 +81,6 @@ 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 { applyBidiCodePaint, bidiMarkdownRenderNode } from "../../component/bidi-markdown"
 import "../../component/bidi-elements"
 
 addDefaultParsers(parsers.parsers)
@@ -1635,7 +1634,6 @@ function ReasoningPart(props: { last: boolean; part: ReasoningPart; message: Ass
         <Show when={!opaque() && (!inMinimal() || expanded()) && summary().body}>
           <box paddingLeft={inMinimal() ? 2 : 0} marginTop={1}>
             <code
-              ref={(el: CodeRenderable) => applyBidiCodePaint(el)}
               filetype="markdown"
               drawUnstyledText={false}
               streaming={true}
@@ -1696,7 +1694,6 @@ function TextPart(props: { last: boolean; part: TextPart; message: AssistantMess
           syntaxStyle={syntax()}
           streaming={true}
           internalBlockMode="top-level"
-          renderNode={bidiMarkdownRenderNode}
           content={props.part.text.trim()}
           tableOptions={{ style: "grid" }}
           conceal={ctx.conceal()}
diff --git a/packages/tui/src/util/bidi.ts b/packages/tui/src/util/bidi.ts
index fd1b86ea8a53..53383d75fa21 100644
--- a/packages/tui/src/util/bidi.ts
+++ b/packages/tui/src/util/bidi.ts
@@ -1,4 +1,5 @@
 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
@@ -24,12 +25,15 @@ export function hasRtl(text: string) {
   return RTL_PROBE.test(text)
 }
 
-// LTR islands embedded in RTL text, matched on logical text and wrapped in
-// LRI/PDI during layout. Bare English words are deliberately not isolated:
+// 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.
+// 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 =
-  /(?:https?:\/\/|www\.)\S+|[A-Za-z0-9_@]+(?:[/\\.-][A-Za-z0-9_@-]+)+|\d+(?:[.,:/]\d+)*%?/g
+  /`[^`\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
@@ -97,6 +101,22 @@ export type BidiLayout = {
 // 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) {
@@ -106,13 +126,33 @@ function glyphWidth(char: string) {
 
 // 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.
-function wrapGlyphs(glyphs: BidiGlyph[], start: number, end: number, maxWidth: number) {
+// 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) {
@@ -120,25 +160,24 @@ function wrapGlyphs(glyphs: BidiGlyph[], start: number, end: number, maxWidth: n
       lineStart = i + 1
       width = 0
       breakAt = -1
+      breakOutside = -1
       continue
     }
     if (width + glyph.width > limit && i > lineStart) {
-      if (breakAt > lineStart) {
-        ranges.push([lineStart, breakAt])
-        lineStart = breakAt
+      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
-      breakAt = -1
-      for (let j = lineStart; j < i; j++) {
-        if (WHITESPACE.test(glyphs[j].char)) breakAt = j + 1
-      }
+      rescanBreaks(lineStart, i)
     }
     width += glyph.width
-    if (WHITESPACE.test(glyph.char)) breakAt = i + 1
+    if (WHITESPACE.test(glyph.char)) noteBreak(i + 1, i)
   }
   ranges.push([lineStart, end])
   return ranges
@@ -164,20 +203,6 @@ function trimEdgeWhitespace(glyphs: BidiGlyph[], start: number, end: number) {
   return [start, end] as const
 }
 
-// Converts a UTF-16 code-unit index into a glyph index using the glyph
-// start-offset table; bidi-js works in code units while layout works in
-// graphemes.
-function unitToGlyph(starts: Uint32Array, unit: number) {
-  let lo = 0
-  let hi = starts.length - 1
-  while (lo < hi) {
-    const mid = (lo + hi + 1) >> 1
-    if (starts[mid] <= unit) lo = mid
-    else hi = mid - 1
-  }
-  return lo
-}
-
 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])
@@ -193,6 +218,52 @@ function mergeRanges(ranges: Array<[number, number]>) {
   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.
@@ -240,16 +311,20 @@ export function layoutBidiText(text: string, maxWidth: number, isolateRanges: Bi
     const paraText = text.slice(baseChar, endChar)
     const rtlParagraph = hasRtl(paraText)
 
-    // LTR islands: caller-provided ranges plus regex detection, all converted
-    // to glyph indices and merged so isolates never nest.
+    // 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) {
-        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])
+        // 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)
       }
     }
@@ -264,25 +339,30 @@ export function layoutBidiText(text: string, maxWidth: number, isolateRanges: Bi
       }
       return first === -1 || first < paraStart || last >= paraEnd ? [] : [[first, last] as [number, number]]
     })
-    const islands = mergeRanges([...callerRanges, ...detected])
+    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)
       }
     }
 
@@ -303,41 +383,42 @@ export function layoutBidiText(text: string, maxWidth: number, isolateRanges: Bi
     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)) {
+    for (const [rawStart, rawEnd] of wrapGlyphs(augmented, 0, augmented.length, maxWidth, (i) => augmentedIsland[i])) {
       const [rangeStart, rangeEnd] = trimEdgeWhitespace(augmented, rawStart, rawEnd)
-      const augmentedGlyphs: number[] = []
-      for (let i = rangeStart; i < rangeEnd; i++) {
-        if (!augmented[i].control) augmentedGlyphs.push(i)
-      }
-      const count = augmentedGlyphs.length
-
-      if (count === 0) {
-        registerLine({ cells: [], width: 0, rtl, start: paraStart, end: paraStart, boundaryCols: [0], logicalWidths: [0] })
-        continue
-      }
 
-      // Visual order starts logical; UAX #9 L2 flip segments are applied as
-      // glyph-range reversals derived from the resolved levels.
-      const order = augmentedGlyphs.slice()
+      // 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)) {
-          // Flip endpoints may land on LRI/PDI control glyphs, which are not
-          // part of the visual order; clamp to the non-control glyphs inside
-          // the flip range.
-          const fromGlyph = unitToGlyph(starts, fromUnits!)
-          const toGlyph = unitToGlyph(starts, toUnits!)
-          let from = -1
-          let to = -1
-          for (let i = 0; i < order.length; i++) {
-            const glyph = order[i]
-            if (glyph < fromGlyph || glyph > toGlyph) continue
-            if (from === -1) from = i
-            to = i
+          // 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 (from === -1 || to === -1) continue
-          for (let i = from, j = to; i < j; i++, j--) {
+          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
@@ -349,6 +430,7 @@ export function layoutBidiText(text: string, maxWidth: number, isolateRanges: Bi
       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
@@ -360,7 +442,18 @@ export function layoutBidiText(text: string, maxWidth: number, isolateRanges: Bi
 
       // Logical (unwrapped) glyph sequence of this line; boundary indices are
       // logical positions, independent of visual order.
-      const logicalGlyphs = augmentedGlyphs.map((index) => augmentedToLogical[index])
+      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)
diff --git a/packages/tui/test/bidi-e2e.test.tsx b/packages/tui/test/bidi-e2e.test.tsx
index a53b0b6b5900..febb17c4fdbf 100644
--- a/packages/tui/test/bidi-e2e.test.tsx
+++ b/packages/tui/test/bidi-e2e.test.tsx
@@ -223,6 +223,24 @@ test("e2e: Arabic prompt input and assistant output in a real session view", asy
     // 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()
   }
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
index f010e6d2b79a..0ff6b54cbddc 100644
--- a/packages/tui/test/component/bidi-render.test.tsx
+++ b/packages/tui/test/component/bidi-render.test.tsx
@@ -9,7 +9,7 @@ import {
 import { createTestRenderer, type TestRendererSetup } from "@opentui/core/testing"
 import { BidiTextRenderable } from "../../src/component/bidi-text"
 import { BidiTextareaRenderable } from "../../src/component/bidi-textarea"
-import { bidiMarkdownRenderNode } from "../../src/component/bidi-markdown"
+import "../../src/component/bidi-elements"
 
 const WIDTH = 40
 const HEIGHT = 12
@@ -21,7 +21,9 @@ const offlineClient: TreeSitterClient = {
 } as unknown as TreeSitterClient
 
 function row(frame: string, index: number) {
-  return frame.slice(index * WIDTH, (index + 1) * WIDTH)
+  // 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) {
@@ -111,7 +113,6 @@ describe("bidi markdown rendering", () => {
       const el = new MarkdownRenderable(setup.renderer, {
         content: "مرحبا بالعالم",
         syntaxStyle: SyntaxStyle.create(),
-        renderNode: bidiMarkdownRenderNode,
         treeSitterClient: offlineClient,
       })
       setup.renderer.root.add(el)
@@ -128,7 +129,6 @@ describe("bidi markdown rendering", () => {
       const el = new MarkdownRenderable(setup.renderer, {
         content: "```ts\nconst value = 42\n```",
         syntaxStyle: SyntaxStyle.create(),
-        renderNode: bidiMarkdownRenderNode,
         treeSitterClient: offlineClient,
       })
       setup.renderer.root.add(el)
@@ -144,7 +144,6 @@ describe("bidi markdown rendering", () => {
       const el = new MarkdownRenderable(setup.renderer, {
         content: "استخدم `npm install` لتثبيت الحزمة",
         syntaxStyle: SyntaxStyle.create(),
-        renderNode: bidiMarkdownRenderNode,
         treeSitterClient: offlineClient,
       })
       setup.renderer.root.add(el)
@@ -161,7 +160,6 @@ describe("bidi markdown rendering", () => {
       const el = new MarkdownRenderable(setup.renderer, {
         content: "مرحبا بالعالم",
         syntaxStyle: SyntaxStyle.create(),
-        renderNode: bidiMarkdownRenderNode,
         treeSitterClient: offlineClient,
       })
       setup.renderer.root.add(el)
@@ -198,6 +196,19 @@ describe("bidi textarea rendering", () => {
     })
   })
 
+  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 })