Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

fix(terminal): self-heal stale viewport after display wake (reflow on wake/context-loss)

Vyapak Goyal513011471523
diff --git a/src/renderer/src/components/PtyTerminalView.tsx b/src/renderer/src/components/PtyTerminalView.tsx
index ab7fa88c..15cd4281 100644
--- a/src/renderer/src/components/PtyTerminalView.tsx
+++ b/src/renderer/src/components/PtyTerminalView.tsx
@@ -2,7 +2,7 @@ import { useEffect, useRef, useState } from 'react';
import type { CSSProperties } from 'react';
import '@xterm/xterm/css/xterm.css';
import { Icon } from './Icon';
-import { acquireTerminal, attachTerminal } from './terminalPool';
+import { acquireTerminal, attachTerminal, reflowTerminal } from './terminalPool';
const DEFAULT_FONT_SIZE = 14;
const MIN_FONT_SIZE = 8;
@@ -240,10 +240,29 @@ export function PtyTerminalView({ ptyId, onStreamData, onUserPrompt, onToggleFul
const onWinResize = () => tryFit(false);
window.addEventListener('resize', onWinResize);
+ // Self-heal after a display wake. Closing the laptop lid sleeps the GPU,
+ // which loses the WebGL context and leaves xterm's cached cell-height (and
+ // the viewport scroll-area derived from it) stale — the full buffer is still
+ // there but only part is scrollable until a re-measure (the user otherwise
+ // has to zoom to force a fit). The ResizeObserver/resize listeners DON'T fire
+ // on lid-open because the window's pixel size is unchanged, so we re-fit
+ // explicitly when the page becomes visible / regains focus. reflowTerminal
+ // re-measures + refits WITHOUT scrolling, so a user reading history isn't
+ // yanked to the bottom. rAF lets the waking layout settle first; if the host
+ // is still unsized the reflow no-ops and the next focus/visibility catches it.
+ const onWake = () => {
+ if (typeof document !== 'undefined' && document.visibilityState !== 'visible') return;
+ requestAnimationFrame(() => reflowTerminal(ptyId));
+ };
+ document.addEventListener('visibilitychange', onWake);
+ window.addEventListener('focus', onWake);
+
return () => {
retries.forEach(clearTimeout);
ro.disconnect();
window.removeEventListener('resize', onWinResize);
+ document.removeEventListener('visibilitychange', onWake);
+ window.removeEventListener('focus', onWake);
// Detach (but DON'T dispose) the terminal — it keeps running in the pool.
entry.onData = undefined;
entry.onPrompt = undefined;
diff --git a/src/renderer/src/components/terminalPool.ts b/src/renderer/src/components/terminalPool.ts
index 241f0464..d5b9b5ba 100644
--- a/src/renderer/src/components/terminalPool.ts
+++ b/src/renderer/src/components/terminalPool.ts
@@ -20,6 +20,8 @@ import { Unicode11Addon } from '@xterm/addon-unicode11';
import '@xterm/xterm/css/xterm.css';
export interface TerminalEntry {
+ /** The pty this terminal mirrors — needed to poke `resizePty` on a reflow. */
+ ptyId: string;
term: Terminal;
fit: FitAddon;
/** The element xterm renders into; views re-parent this in/out of the DOM. */
@@ -78,7 +80,7 @@ export function acquireTerminal(ptyId: string, theme?: ThemeMap, fontSize = 14):
// NOTE: don't open() yet — xterm needs its host connected to the document to
// measure correctly. We open on first attach (see attachTerminal).
- const entry: TerminalEntry = { term, fit, host, opened: false, exited: false, unsub: [] };
+ const entry: TerminalEntry = { ptyId, term, fit, host, opened: false, exited: false, unsub: [] };
// Subscribe to the pty stream ONCE for the terminal's whole lifetime, so the
// buffer keeps filling even while this terminal isn't mounted in any view.
@@ -176,6 +178,14 @@ export function attachTerminal(entry: TerminalEntry, container: HTMLElement): vo
webgl.onContextLoss(() => {
console.warn('[terminal] webgl context lost — falling back to DOM renderer');
try { webgl.dispose(); } catch { /* noop */ }
+ // Laptop sleep == GPU sleep == WebGL context loss: the likely PRIMARY
+ // trigger for the post-wake "can't scroll past a recent point" bug. The
+ // renderer swap leaves xterm's cached cell-height (and the viewport
+ // scroll-area derived from it) stale, so only part of the intact buffer
+ // is scrollable until something forces a re-measure. Heal it here, on the
+ // next frame so the (waking) layout has settled. Guarded + idempotent, so
+ // it composes safely with the visibilitychange/focus path in the view.
+ requestAnimationFrame(() => reflowTerminal(entry.ptyId));
});
entry.term.loadAddon(webgl);
} catch (e) {
@@ -184,6 +194,49 @@ export function attachTerminal(entry: TerminalEntry, container: HTMLElement): vo
}
}
+/**
+ * Re-measure cell metrics and rebuild the viewport scroll-area for a pooled
+ * terminal. Use after a display wake / GPU (WebGL) context loss / DPR change:
+ * xterm caches the cell height measured at open() and only recomputes it on a
+ * font change or resize. When that cached metric goes stale (sleep/wake), the
+ * .xterm-viewport scroll-area height (rows × cellHeight) is wrong, so only PART
+ * of the still-intact buffer is scrollable — the user otherwise has to zoom to
+ * force a fit() and reveal the rest.
+ *
+ * Mirrors the document.fonts.ready re-measure in PtyTerminalView: re-applying the
+ * SAME font invalidates xterm's cached cell metrics, clearTextureAtlas re-rasters
+ * the WebGL glyph atlas at the right size, then fit() recomputes cols/rows and
+ * rebuilds the viewport. Preserves scroll position (NO scrollToBottom) so a user
+ * reading history isn't yanked down. No-op until the terminal is opened and its
+ * host has a real size, so it composes safely with multiple triggers firing
+ * together (onContextLoss + visibilitychange + focus) — a cheap reflow twice is
+ * harmless; the guards make an early/duplicate call a no-op.
+ */
+export function reflowTerminal(ptyId: string): void {
+ const entry = pool.get(ptyId);
+ if (!entry || !entry.opened) return;
+ const host = entry.host;
+ // Skip while detached or unsized — fitting a 0×0 host makes xterm propose a
+ // tiny grid and resize the pty to it (clipped/oversized banner).
+ if (!host.isConnected || !host.clientWidth || !host.clientHeight) return;
+ try {
+ // Re-apply the SAME font options to force xterm's CharSizeService to
+ // re-measure the cell against the now-correct (woken) layout, then drop the
+ // glyph atlas so it re-rasters at the corrected metrics.
+ entry.term.options.fontFamily = entry.term.options.fontFamily;
+ entry.term.options.fontSize = entry.term.options.fontSize;
+ entry.term.clearTextureAtlas?.();
+ const before = { cols: entry.term.cols, rows: entry.term.rows };
+ entry.fit.fit();
+ // Only poke the pty when the grid actually changed (every resize repaints
+ // the TUI and pushes a frame into scrollback).
+ if (entry.term.cols !== before.cols || entry.term.rows !== before.rows) {
+ window.cth.resizePty(ptyId, entry.term.cols, entry.term.rows);
+ }
+ entry.term.refresh(0, Math.max(0, entry.term.rows - 1));
+ } catch { /* host may not be sized yet */ }
+}
+
/**
* Soft-reset a pooled terminal for an IN-PLACE pty respawn (the same ptyId is
* reused — e.g. a model change or agent restart). Clears the screen + scrollback