From d25e81e35cdd95896bba436d8b05df04497e5807 Mon Sep 17 00:00:00 2001
From: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
Date: Wed, 8 Jul 2026 17:05:17 -0700
Subject: [PATCH] Document WebGL decoration limitation for Arabic shaping
 joiner

Add comments explaining a known upstream limitation in xterm.js WebGL
renderer where search-match highlights inside a joined run render
all-or-nothing, similar to ligatures.
---
 .../src/lib/pane-manager/terminal-arabic-shaping-joiner.ts  | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/renderer/src/lib/pane-manager/terminal-arabic-shaping-joiner.ts b/src/renderer/src/lib/pane-manager/terminal-arabic-shaping-joiner.ts
index 1749fe4aa63..5b9b5f8dc95 100644
--- a/src/renderer/src/lib/pane-manager/terminal-arabic-shaping-joiner.ts
+++ b/src/renderer/src/lib/pane-manager/terminal-arabic-shaping-joiner.ts
@@ -92,6 +92,12 @@ function canOpenRtlRun(codePoint: number): boolean {
  * standalone width-0 cell (e.g. RLM at line start) makes xterm's
  * CharacterJoinerService skip the cell without advancing its string index,
  * shifting the run's cell range by one — fix belongs upstream in xterm.js.
+ *
+ * Known upstream limitation #2: the WebGL renderer un-joins a range for the
+ * cursor or a partial selection but not for decorations, so a search-match
+ * highlight inside a joined run renders all-or-nothing — the whole run when
+ * the match covers the run's first cell, otherwise not at all. Same class as
+ * ligatures today, extended here to phrase-length runs.
  */
 export function findRtlJoinRanges(text: string): [number, number][] {
   const length = text.length