From ee119fe4373028029a8c1db08d07cd037cd88b70 Mon Sep 17 00:00:00 2001
From: nntrivi2001 <vinnt@smartgift.vn>
Date: Fri, 30 Oct 2026 10:33:57 +0700
Subject: [PATCH] fix(terminal): restamp every glyph-atlas page so no pane
 keeps a stale texture

v2.8.42 reacted to a page merge by toggling the font family on the next
frame, so each renderer re-acquired an atlas. Panes still showed squeezed,
overlapping glyphs: the toggle lands a frame late, swaps every pane onto a
fresh atlas (or onto one another pane already toggled to), and a page added
without a merge shifts nothing yet still raced it.

addon-webgl 0.20 fixes the root cause with globally monotonic page versions.
Do the same on 0.19: whenever the shared atlas adds, removes or merges a page,
give every page a version no texture slot has uploaded, synchronously, so
every renderer on that atlas re-uploads all pages before it draws again.
When the page comes back from the background, restamp and repaint. An addon
of another shape keeps the old font-toggle fallback.
---
 .../lanes/__tests__/LaneDiffView.test.tsx     |  2 +-
 client/src/components/run/TerminalView.tsx    | 64 +++++++++++++++----
 .../run/__tests__/TerminalView.test.tsx       | 56 ++++++++++++++--
 3 files changed, 105 insertions(+), 17 deletions(-)

diff --git a/client/src/components/lanes/__tests__/LaneDiffView.test.tsx b/client/src/components/lanes/__tests__/LaneDiffView.test.tsx
index defb2a3e..ec278082 100644
--- a/client/src/components/lanes/__tests__/LaneDiffView.test.tsx
+++ b/client/src/components/lanes/__tests__/LaneDiffView.test.tsx
@@ -615,7 +615,7 @@ describe("LaneDiffView — a row the server cut down", () => {
     ...FILE,
     hunks: [
       {
-        ...FILE.hunks[0]!,
+        ...FILE.hunks![0]!,
         lines: [
           { type: "del", oldLine: 1, newLine: null, text: '<video src="AAAA', elided: 3_000_000 },
           { type: "add", oldLine: null, newLine: 1, text: '<video src="BBBB', elided: 3_000_000 },
diff --git a/client/src/components/run/TerminalView.tsx b/client/src/components/run/TerminalView.tsx
index ffcc5866..99c44571 100644
--- a/client/src/components/run/TerminalView.tsx
+++ b/client/src/components/run/TerminalView.tsx
@@ -96,6 +96,36 @@ type DropState = "hint" | "paste" | "uploading" | "failed" | "tooBig" | "tooBigL
 /** localStorage flag for xterm's screen-reader mode (a Settings toggle can set it later). */
 export const SCREEN_READER_KEY = "agenthub.terminal.screenReader";
 /** localStorage flag: the "Shift+drag selects text" hint was dismissed. */
+/** The atlas a WebGL addon draws from: @xterm/addon-webgl 0.19 keeps these
+ *  fields unminified in its build. Undefined on any other shape. */
+type AtlasPages = { pages: { version: number }[] };
+const atlasOf = (addon: WebglAddon): AtlasPages | undefined => {
+  const atlas = (addon as unknown as { _renderer?: { _charAtlas?: AtlasPages } })._renderer
+    ?._charAtlas;
+  return Array.isArray(atlas?.pages) ? atlas : undefined;
+};
+/** Last version handed out by `restampAtlas`, shared by every pane. */
+let atlasStamp = 0;
+/**
+ * Gives every page of the addon's glyph atlas a version no texture slot has
+ * uploaded, so EVERY renderer sharing that atlas re-uploads every page from
+ * its canvas on its next draw — what addon-webgl 0.20 does with globally
+ * monotonic page versions. 0.19 counts per page, so after a merge shifts the
+ * pages down a slot can hold a stale page whose counter happens to match, and
+ * glyphs are sampled squeezed or foreign. Steps of 2^24 stay clear of the
+ * per-glyph increments a page makes before the next restamp. False when the
+ * addon is not the shape this knows.
+ */
+const restampAtlas = (addon: WebglAddon): boolean => {
+  const atlas = atlasOf(addon);
+  if (!atlas) return false;
+  for (const page of atlas.pages) {
+    atlasStamp += 2 ** 24;
+    page.version = atlasStamp;
+  }
+  return true;
+};
+
 const SELECT_HINT_KEY = "agenthub.terminal.selectHintSeen";
 const readFlag = (key: string) => {
   try {
@@ -763,31 +793,40 @@ export const TerminalView = memo(function TerminalView({
       };
       document.fonts?.addEventListener("loadingdone", onFontLoaded);
       // @xterm/addon-webgl 0.19 shares ONE glyph atlas between every terminal
-      // with the same font, and when it fills up it merges four pages into one
-      // larger page and shifts the rest down. A GPU texture is re-uploaded only
-      // when its page's `version` differs from the uploaded one, and after a
-      // shift those counters can coincide, so a slot keeps a stale page of
-      // another size: every glyph is sampled squeezed or foreign while the
-      // buffer stays correct (fixed upstream only in 0.20 betas). Any option
-      // change makes each renderer re-acquire its atlas and re-upload all pages,
-      // so this toggles the family's trailing space (as onFontLoaded does) on
-      // a merge. `clearTextureAtlas` is no fix: it empties the SHARED atlas
+      // with the same font. When it fills up it merges four pages into one
+      // larger page and shifts the rest down, and a GPU texture is re-uploaded
+      // only when its page's `version` differs from the uploaded one — after a
+      // shift those per-page counters can coincide, so a slot keeps a stale
+      // page of another size and every glyph is drawn squeezed or foreign
+      // while the buffer stays correct (fixed upstream only in 0.20 betas).
+      // Any change to the page list therefore restamps every page's version
+      // (`restampAtlas`) synchronously, before the next draw of ANY pane on
+      // that atlas. `clearTextureAtlas` is no fix: it empties the SHARED atlas
       // but redraws only this pane, leaving its siblings slicing reused space.
+      // An addon of another shape falls back to toggling the family's
+      // trailing space on the next frame, which makes each renderer re-acquire
+      // its atlas (as onFontLoaded does).
       let atlasFrame = 0;
       const rebuildAtlas = () => {
-        if (atlasFrame) return;
+        if (gpu && restampAtlas(gpu)) return true;
+        if (atlasFrame) return false;
         // Never inside the render that is rasterizing the merging glyph.
         atlasFrame = requestAnimationFrame(() => {
           atlasFrame = 0;
           const family = term.options.fontFamily ?? "";
           term.options.fontFamily = family.endsWith(" ") ? family.trimEnd() : `${family} `;
         });
+        return false;
       };
       const atlasMerged = gpu?.onRemoveTextureAtlasCanvas(rebuildAtlas);
+      const atlasGrew = gpu?.onAddTextureAtlasCanvas(rebuildAtlas);
       // The browser may also drop the textures without a context-loss event
-      // (sleep/resume, a long-backgrounded tab): rebuild when the page is back.
+      // (sleep/resume, a long-backgrounded tab): re-upload when the page is
+      // back, and repaint, since nothing else asks this pane to draw.
       const onPageShown = () => {
-        if (document.visibilityState === "visible") rebuildAtlas();
+        if (document.visibilityState === "visible" && rebuildAtlas()) {
+          term.refresh(0, term.rows - 1);
+        }
       };
       document.addEventListener("visibilitychange", onPageShown);
       window.addEventListener("focus", onPageShown);
@@ -811,6 +850,7 @@ export const TerminalView = memo(function TerminalView({
         document.fonts?.removeEventListener("loadingdone", onFontLoaded);
         if (atlasFrame) cancelAnimationFrame(atlasFrame);
         atlasMerged?.dispose();
+        atlasGrew?.dispose();
         document.removeEventListener("visibilitychange", onPageShown);
         window.removeEventListener("focus", onPageShown);
         window.removeEventListener(FONT_SIZE_EVENT, onFontPref);
diff --git a/client/src/components/run/__tests__/TerminalView.test.tsx b/client/src/components/run/__tests__/TerminalView.test.tsx
index df164860..1a0a1b51 100644
--- a/client/src/components/run/__tests__/TerminalView.test.tsx
+++ b/client/src/components/run/__tests__/TerminalView.test.tsx
@@ -63,6 +63,9 @@ const termState = {
 };
 const onResizeHandlers: Array<() => void> = [];
 const termOptions: { theme?: unknown } = {};
+const refreshMock = vi.fn();
+/** The atlas the next WebGL addon draws from; null = an addon of another shape. */
+const nextAtlas: { pages: { version: number }[] | null } = { pages: null };
 const ctorArgs: Array<{ theme?: unknown }> = [];
 
 vi.mock("@xterm/xterm", () => ({
@@ -92,6 +95,7 @@ vi.mock("@xterm/xterm", () => ({
       return { dispose: vi.fn() };
     },
     dispose: disposeMock,
+    refresh: refreshMock,
     loadAddon: loadAddonMock,
     attachCustomWheelEventHandler: wheelHandlerMock,
     attachCustomKeyEventHandler: keyHandlerMock,
@@ -113,7 +117,12 @@ vi.mock("@xterm/addon-fit", () => ({
 }));
 // The newest WebGL addon, with the context-loss listener the view gave it.
 const gpu: {
-  last: { dispose: ReturnType<typeof vi.fn>; lose: () => void; merge: () => void } | null;
+  last: {
+    dispose: ReturnType<typeof vi.fn>;
+    lose: () => void;
+    merge: () => void;
+    grow: () => void;
+  } | null;
 } = {
   last: null,
 };
@@ -121,8 +130,10 @@ vi.mock("@xterm/addon-webgl", () => ({
   WebglAddon: vi.fn().mockImplementation(() => {
     let onLoss = () => {};
     let onMerge = () => {};
+    let onGrow = () => {};
     const addon = {
       __webgl: true,
+      ...(nextAtlas.pages ? { _renderer: { _charAtlas: { pages: nextAtlas.pages } } } : {}),
       dispose: vi.fn(),
       onContextLoss: (fn: () => void) => {
         onLoss = fn;
@@ -132,8 +143,17 @@ vi.mock("@xterm/addon-webgl", () => ({
         onMerge = fn;
         return { dispose: vi.fn() };
       },
+      onAddTextureAtlasCanvas: (fn: () => void) => {
+        onGrow = fn;
+        return { dispose: vi.fn() };
+      },
+    };
+    gpu.last = {
+      dispose: addon.dispose,
+      lose: () => onLoss(),
+      merge: () => onMerge(),
+      grow: () => onGrow(),
     };
-    gpu.last = { dispose: addon.dispose, lose: () => onLoss(), merge: () => onMerge() };
     return addon;
   }),
 }));
@@ -495,9 +515,37 @@ describe("TerminalView", () => {
     expect(disposeMock).not.toHaveBeenCalled(); // the terminal itself lives on
   });
 
+  it("restamps every atlas page at once when the page list changes", () => {
+    // addon-webgl 0.19 counts versions per page, so after a merge shifts the
+    // pages a texture slot can keep a stale page whose counter matches. Every
+    // page gets a version no slot has uploaded — in every pane on the atlas.
+    const pages = [{ version: 3 }, { version: 7 }, { version: 1 }];
+    nextAtlas.pages = pages;
+    const raf = vi.spyOn(window, "requestAnimationFrame");
+    try {
+      render(<TerminalView runId="agenthub-lane-1" wsBaseUrl="ws://localhost:4820" />);
+      gpu.last!.merge();
+      const first = pages.map((p) => p.version);
+      expect(new Set(first).size).toBe(3);
+      expect(first.every((v) => v > 7)).toBe(true);
+      gpu.last!.grow();
+      expect(pages.every((p, i) => p.version > Math.max(...first) && p.version !== first[i])).toBe(
+        true
+      );
+      expect(raf).not.toHaveBeenCalled(); // synchronous, before any pane draws
+      // The page coming back re-uploads and repaints this pane.
+      refreshMock.mockClear();
+      window.dispatchEvent(new Event("focus"));
+      expect(refreshMock).toHaveBeenCalledWith(0, 27);
+    } finally {
+      nextAtlas.pages = null;
+      raf.mockRestore();
+    }
+  });
+
   it("re-acquires the glyph atlas on the next frame after a page merge", () => {
-    // addon-webgl 0.19 may keep a stale page in a GPU slot after it merges
-    // atlas pages; any option change makes it re-upload every page.
+    // An addon whose atlas this cannot reach: any option change makes each
+    // renderer re-acquire its atlas and re-upload every page.
     const raf = vi.spyOn(window, "requestAnimationFrame").mockImplementation(() => 1);
     render(<TerminalView runId="agenthub-lane-1" wsBaseUrl="ws://localhost:4820" />);
     const opts = termOptions as { fontFamily?: string };