Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

perf(ide): draw terminal panes with WebGL, falling back to canvas

rubenluetke10-beepe1976fb14fac
diff --git a/jarvis/ui/web/frontend/package-lock.json b/jarvis/ui/web/frontend/package-lock.json
index 52257a78e7..e850db1787 100644
--- a/jarvis/ui/web/frontend/package-lock.json
+++ b/jarvis/ui/web/frontend/package-lock.json
@@ -27,6 +27,7 @@
"@xterm/addon-search": "^0.16.0",
"@xterm/addon-unicode11": "^0.9.0",
"@xterm/addon-web-links": "^0.11.0",
+ "@xterm/addon-webgl": "^0.18.0",
"@xterm/xterm": "^5.5.0",
"@xyflow/react": "^12.10.2",
"class-variance-authority": "^0.7.0",
@@ -3032,6 +3033,15 @@
"@xterm/xterm": "^5.0.0"
}
},
+ "node_modules/@xterm/addon-webgl": {
+ "version": "0.18.0",
+ "resolved": "https://registry.npmjs.org/@xterm/addon-webgl/-/addon-webgl-0.18.0.tgz",
+ "integrity": "sha512-xCnfMBTI+/HKPdRnSOHaJDRqEpq2Ugy8LEj9GiY4J3zJObo3joylIFaMvzBwbYRg8zLtkO0KQaStCeSfoaI2/w==",
+ "license": "MIT",
+ "peerDependencies": {
+ "@xterm/xterm": "^5.0.0"
+ }
+ },
"node_modules/@xterm/xterm": {
"version": "5.5.0",
"resolved": "https://registry.npmjs.org/@xterm/xterm/-/xterm-5.5.0.tgz",
diff --git a/jarvis/ui/web/frontend/package.json b/jarvis/ui/web/frontend/package.json
index a7508ebbd1..b30aecf1f1 100644
--- a/jarvis/ui/web/frontend/package.json
+++ b/jarvis/ui/web/frontend/package.json
@@ -29,6 +29,7 @@
"@xterm/addon-search": "^0.16.0",
"@xterm/addon-unicode11": "^0.9.0",
"@xterm/addon-web-links": "^0.11.0",
+ "@xterm/addon-webgl": "^0.18.0",
"@xterm/xterm": "^5.5.0",
"@xyflow/react": "^12.10.2",
"class-variance-authority": "^0.7.0",
diff --git a/jarvis/ui/web/frontend/src/components/agentic/AgenticTerminal.tsx b/jarvis/ui/web/frontend/src/components/agentic/AgenticTerminal.tsx
index fa4ee05aff..ae31943844 100644
--- a/jarvis/ui/web/frontend/src/components/agentic/AgenticTerminal.tsx
+++ b/jarvis/ui/web/frontend/src/components/agentic/AgenticTerminal.tsx
@@ -53,7 +53,6 @@ import { createPortal } from "react-dom";
import { Terminal } from "@xterm/xterm";
import { FitAddon } from "@xterm/addon-fit";
import { WebLinksAddon } from "@xterm/addon-web-links";
-import { CanvasAddon } from "@xterm/addon-canvas";
import { Unicode11Addon } from "@xterm/addon-unicode11";
import "@xterm/xterm/css/xterm.css";
import {
@@ -98,6 +97,7 @@ import { describeExit, explainExit } from "./paneExit";
import { PaneActivityPill } from "./PaneActivityPill";
import { PaneRecap } from "./PaneRecap";
import { attachToTerminal } from "@/lib/agenticIdeApi";
+import { attachTerminalRenderer } from "./terminalRenderer";
import type { RecapReason, RecapSource } from "@/lib/agenticIdeApi";
import { attachTerminalBridge } from "@/lib/editActions";
import { robustCopy, robustPaste } from "@/lib/clipboard";
@@ -861,11 +861,11 @@ export function AgenticTerminal({
// module exists to prevent.
fontFamily: TERMINAL_FONT_STACK,
fontSize: fontSizeRef.current,
- // Roomier than a console default — the single biggest readability win for
- // an agent that prints prose, diffs and file trees rather than log lines.
- // Kept integral-friendly: fractional cell heights round differently per
- // row and make a redrawn TUI box look ragged.
- lineHeight: 1.3,
+ // A dense console line height, like a standalone terminal: at 1.3 a pane
+ // showed far fewer rows than the same window in a native terminal, which
+ // read as "zoomed in". Kept integral-friendly: fractional cell heights
+ // round differently per row and make a redrawn TUI box look ragged.
+ lineHeight: 1.2,
// Zero, not 0.2: extra tracking is added per cell, so a box-drawing frame
// and the text under it accumulate different sub-pixel offsets and the
// frame visibly bends. Monospace legibility comes from the line height.
@@ -922,16 +922,17 @@ export function AgenticTerminal({
// when the CLI feels like it, which is the per-provider inconsistency the
// scroll rebuild removed. See captureWheelForTerminalHistory.
term.attachCustomWheelEventHandler(captureWheelForTerminalHistory(term));
- // Canvas rather than the DOM renderer: a coding agent's TUI redraws its
- // prompt box on every keystroke, and per-cell DOM elements both lag and
- // land on fractional pixel offsets. Loaded AFTER open() because it needs
- // the mounted element. A failure here is not fatal — xterm falls back to
- // the DOM renderer, which draws correctly, just less crisply.
- try {
- term.loadAddon(new CanvasAddon());
- } catch {
- /* no canvas in this environment — the DOM renderer still works */
- }
+ // WebGL where the page can afford it, the 2D canvas otherwise, and the DOM
+ // renderer as the last resort — never the DOM renderer by choice: a coding
+ // agent's TUI redraws its prompt box on every keystroke, and per-cell DOM
+ // elements both lag and land on fractional pixel offsets. Loaded AFTER
+ // open() because it needs the mounted element. See ./terminalRenderer for
+ // why the canvas renderer alone froze a wall of streaming panes.
+ const renderer = attachTerminalRenderer(term, () => {
+ if (disposed) return;
+ // The fallback renderer starts on an empty surface.
+ term.refresh(0, term.rows - 1);
+ });
termRef.current = term;
fitRef.current = fit;
setTerminalEpoch((current) => current + 1);
@@ -2008,6 +2009,8 @@ export function AgenticTerminal({
} catch {
/* ignore */
}
+ // Before the terminal: frees this pane's WebGL context slot.
+ renderer.dispose();
term.dispose();
termRef.current = null;
fitRef.current = null;
diff --git a/jarvis/ui/web/frontend/src/components/agentic/terminalRenderer.test.ts b/jarvis/ui/web/frontend/src/components/agentic/terminalRenderer.test.ts
new file mode 100644
index 0000000000..a4f08d6efb
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/agentic/terminalRenderer.test.ts
@@ -0,0 +1,116 @@
+import { afterEach, describe, expect, it } from "vitest";
+import type { ITerminalAddon, Terminal } from "@xterm/xterm";
+
+import {
+ MAX_WEBGL_PANES,
+ attachTerminalRenderer,
+ resetWebglPaneCount,
+ type RendererDeps,
+ type WebglLike,
+} from "./terminalRenderer";
+
+/** A terminal that only records which addons it was handed. */
+function fakeTerminal(opts: { refuse?: (addon: ITerminalAddon) => boolean } = {}) {
+ const loaded: ITerminalAddon[] = [];
+ const term = {
+ loadAddon(addon: ITerminalAddon) {
+ if (opts.refuse?.(addon)) throw new Error("no context");
+ loaded.push(addon);
+ },
+ } as unknown as Terminal;
+ return { term, loaded };
+}
+
+class FakeWebgl implements WebglLike {
+ disposed = false;
+ private listeners: Array<() => void> = [];
+ activate() {}
+ dispose() {
+ this.disposed = true;
+ }
+ onContextLoss(listener: () => void) {
+ this.listeners.push(listener);
+ return {
+ dispose: () => {
+ this.listeners = this.listeners.filter((l) => l !== listener);
+ },
+ };
+ }
+ loseContext() {
+ for (const l of [...this.listeners]) l();
+ }
+}
+
+class FakeCanvas implements ITerminalAddon {
+ activate() {}
+ dispose() {}
+}
+
+function deps(): RendererDeps & { webgls: FakeWebgl[] } {
+ const webgls: FakeWebgl[] = [];
+ return {
+ webgls,
+ createWebgl: () => {
+ const w = new FakeWebgl();
+ webgls.push(w);
+ return w;
+ },
+ createCanvas: () => new FakeCanvas(),
+ };
+}
+
+afterEach(() => resetWebglPaneCount());
+
+describe("attachTerminalRenderer", () => {
+ it("draws with WebGL when the page can give it a context", () => {
+ const { term, loaded } = fakeTerminal();
+ const r = attachTerminalRenderer(term, undefined, deps());
+ expect(r.kind).toBe("webgl");
+ expect(loaded[0]).toBeInstanceOf(FakeWebgl);
+ });
+
+ it("falls back to canvas where WebGL cannot load", () => {
+ const { term, loaded } = fakeTerminal({ refuse: (a) => a instanceof FakeWebgl });
+ const r = attachTerminalRenderer(term, undefined, deps());
+ expect(r.kind).toBe("canvas");
+ expect(loaded).toHaveLength(1);
+ expect(loaded[0]).toBeInstanceOf(FakeCanvas);
+ });
+
+ it("switches a pane to canvas in place when its context is lost", () => {
+ const d = deps();
+ const { term, loaded } = fakeTerminal();
+ let repainted = 0;
+ const r = attachTerminalRenderer(term, () => repainted++, d);
+ d.webgls[0].loseContext();
+ expect(d.webgls[0].disposed).toBe(true);
+ expect(r.kind).toBe("canvas");
+ expect(loaded.at(-1)).toBeInstanceOf(FakeCanvas);
+ // The fallback surface starts empty — the caller is told to repaint.
+ expect(repainted).toBe(1);
+ });
+
+ it("stops taking contexts past the cap instead of evicting another pane's", () => {
+ const d = deps();
+ const kinds = Array.from({ length: MAX_WEBGL_PANES + 2 }, () =>
+ attachTerminalRenderer(fakeTerminal().term, undefined, d).kind,
+ );
+ expect(kinds.filter((k) => k === "webgl")).toHaveLength(MAX_WEBGL_PANES);
+ expect(kinds.slice(-2)).toEqual(["canvas", "canvas"]);
+ });
+
+ it("gives the slot back when a pane goes away or loses its context", () => {
+ const d = deps();
+ const panes = Array.from({ length: MAX_WEBGL_PANES }, () =>
+ attachTerminalRenderer(fakeTerminal().term, undefined, d),
+ );
+ panes[0].dispose();
+ d.webgls[1].loseContext();
+ const next = [
+ attachTerminalRenderer(fakeTerminal().term, undefined, d).kind,
+ attachTerminalRenderer(fakeTerminal().term, undefined, d).kind,
+ attachTerminalRenderer(fakeTerminal().term, undefined, d).kind,
+ ];
+ expect(next).toEqual(["webgl", "webgl", "canvas"]);
+ });
+});
diff --git a/jarvis/ui/web/frontend/src/components/agentic/terminalRenderer.ts b/jarvis/ui/web/frontend/src/components/agentic/terminalRenderer.ts
new file mode 100644
index 0000000000..9ed16085dc
--- /dev/null
+++ b/jarvis/ui/web/frontend/src/components/agentic/terminalRenderer.ts
@@ -0,0 +1,154 @@
+/**
+ * Which engine draws a terminal pane's glyphs — and what happens when it dies.
+ *
+ * WebGL first. A coding agent's output SCROLLS, and a scroll moves every row
+ * of the viewport, so each new line is a full-screen repaint. The canvas
+ * renderer does that repaint on the main thread, one `drawImage` + `clip` per
+ * cell run; the WebGL renderer uploads the cell data and draws the whole
+ * screen in one GPU call. Measured on 2026-09-28 with eight panes each
+ * scrolling a line every 120 ms (the shape of eight busy agents): the canvas
+ * renderer held one core at 88 % and fell to ~38 fps, WebGL used 8 % at a
+ * steady 60 fps. The same app profile showed the canvas path as the single
+ * largest cost in the IDE view (`drawImage`, `clip`, `save`/`restore`) — on
+ * a machine already saturated by the agents themselves, that is the work that
+ * turned into multi-second frames, panes painting black, and half-drawn rows.
+ *
+ * Canvas stays as the fallback, and is never worse than what shipped before:
+ *
+ * - no WebGL at all (a headless box, a blocklisted GPU, a driver that refuses
+ * the context) — the addon throws on load and the pane goes straight to
+ * canvas;
+ * - too many contexts — a page may only hold so many live WebGL contexts
+ * before the browser silently kills the oldest, and a 3D scene elsewhere in
+ * the app needs its own. Past {@link MAX_WEBGL_PANES} a new pane takes
+ * canvas instead of evicting someone else's context;
+ * - context LOST later (a GPU reset, a driver update, VRAM exhausted by a
+ * local model) — the addon is disposed and canvas takes over in place.
+ * Lost is terminal for that pane's WebGL: it does not try again, because a
+ * GPU that just dropped a context is exactly the one that would drop it
+ * again (AP-32: survive the loss, release what was held).
+ */
+
+import { CanvasAddon } from "@xterm/addon-canvas";
+import { WebglAddon } from "@xterm/addon-webgl";
+import type { ITerminalAddon, Terminal } from "@xterm/xterm";
+
+/**
+ * How many panes may draw with WebGL at once.
+ *
+ * Chromium keeps 16 live WebGL contexts per page and evicts the oldest past
+ * that. Twelve leaves room for the app's own 3D views without either side
+ * losing a context to the other; a workspace holds at most eight panes, so
+ * this only bites when several workspaces keep their panes mounted.
+ */
+export const MAX_WEBGL_PANES = 12;
+
+export type TerminalRendererKind = "webgl" | "canvas" | "dom";
+
+/** The addon surface this module needs — narrowed so tests can hand in fakes. */
+export interface WebglLike extends ITerminalAddon {
+ onContextLoss: (listener: () => void) => { dispose(): void };
+}
+
+export interface RendererDeps {
+ createWebgl: () => WebglLike;
+ createCanvas: () => ITerminalAddon;
+}
+
+const realDeps: RendererDeps = {
+ createWebgl: () => new WebglAddon(),
+ createCanvas: () => new CanvasAddon(),
+};
+
+let webglPanes = 0;
+
+/** Test hook: forget every pane counted so far. */
+export function resetWebglPaneCount(): void {
+ webglPanes = 0;
+}
+
+export interface AttachedRenderer {
+ /** What is drawing right now — changes from "webgl" to "canvas" on a loss. */
+ readonly kind: TerminalRendererKind;
+ /** Release the renderer's slot. The terminal's own dispose frees the addon. */
+ dispose(): void;
+}
+
+/**
+ * Give `term` the fastest renderer it can keep. Call after `term.open()`.
+ *
+ * `onFallback` hears about a WebGL pane that had to fall back later, so the
+ * caller can repaint — a pane that swaps renderers mid-life starts from an
+ * empty surface.
+ */
+export function attachTerminalRenderer(
+ term: Terminal,
+ onFallback?: () => void,
+ deps: RendererDeps = realDeps,
+): AttachedRenderer {
+ let kind: TerminalRendererKind = "dom";
+ let counted = false;
+ let released = false;
+
+ const release = () => {
+ if (!counted) return;
+ counted = false;
+ webglPanes = Math.max(0, webglPanes - 1);
+ };
+
+ const loadCanvas = (): TerminalRendererKind => {
+ try {
+ term.loadAddon(deps.createCanvas());
+ return "canvas";
+ } catch {
+ // No 2D canvas either: xterm keeps its DOM renderer, which draws
+ // correctly, just more slowly. Nothing to report — it still works.
+ return "dom";
+ }
+ };
+
+ if (webglPanes < MAX_WEBGL_PANES) {
+ let webgl: WebglLike | null = null;
+ try {
+ webgl = deps.createWebgl();
+ term.loadAddon(webgl);
+ webglPanes += 1;
+ counted = true;
+ kind = "webgl";
+ } catch {
+ // No usable WebGL here — canvas is the answer, and that is not an error.
+ try {
+ webgl?.dispose();
+ } catch {
+ /* a half-activated addon has nothing left worth releasing */
+ }
+ webgl = null;
+ }
+ if (webgl) {
+ const lossSubscription = webgl.onContextLoss(() => {
+ lossSubscription.dispose();
+ release();
+ try {
+ webgl?.dispose();
+ } catch {
+ /* the context is already gone; dispose only tidies listeners */
+ }
+ webgl = null;
+ if (released) return;
+ kind = loadCanvas();
+ onFallback?.();
+ });
+ }
+ }
+ if (kind === "dom") kind = loadCanvas();
+
+ return {
+ get kind() {
+ return kind;
+ },
+ dispose() {
+ released = true;
+ release();
+ },
+ };
+}