Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

fix(terminal): the crisp gate releases only what is on screen (#986)

reviewb6ffc06b3d36
diff --git a/src/renderer/terminal/webgl-budget.test.ts b/src/renderer/terminal/webgl-budget.test.ts
index 296980536..38c15c970 100644
--- a/src/renderer/terminal/webgl-budget.test.ts
+++ b/src/renderer/terminal/webgl-budget.test.ts
@@ -22,6 +22,7 @@ import {
WEBGL_REACQUIRE_AFTER_LOSS_MS,
type WebglClientHandle
} from './webgl-budget'
+import { FIT_NODE_OPTIONS } from '../lib/nodeFocus'
/** A fake client that records acquire/release calls and reports a configurable acquire result. */
function fakeClient(id: string, opts: { acquireOk?: boolean } = {}) {
@@ -366,7 +367,7 @@ describe('webgl-budget coordinator', () => {
vi.advanceTimersByTime(WEBGL_DRAIN_MS * 10)
}
- it('crossing above the threshold gives every context back — including VISIBLE holders', () => {
+ it('crossing above the threshold gives every on-screen context back — VISIBLE holders too', () => {
const a = fakeClient('a')
const b = fakeClient('b')
grant(a)
@@ -440,6 +441,67 @@ describe('webgl-budget coordinator', () => {
zoomTo(Number.NaN)
expect(a.rec.held).toBe(true)
})
+
+ it('a hidden holder keeps its warm context through the gate, and the way back re-grants nothing for it', () => {
+ const a = fakeClient('a')
+ const h = fakeClient('h')
+ grant(a)
+ grant(h)
+ h.handle.setVisible(false)
+ zoomTo(WEBGL_CRISP_ABOVE_ZOOM + 0.01)
+ expect(a.rec.held).toBe(false) // on screen: goes crisp
+ expect(h.rec.releases).toBe(0) // off screen: the blur shows nowhere
+ zoomTo(WEBGL_GPU_RESUME_BELOW_ZOOM - 0.01)
+ h.handle.setVisible(true)
+ vi.advanceTimersByTime(WEBGL_ACQUIRE_DEBOUNCE_MS + WEBGL_DRAIN_MS * 5)
+ expect(h.rec.held).toBe(true)
+ expect(h.rec.acquires).toBe(1) // never let go, so never re-granted
+ expect(a.rec.acquires).toBe(2)
+ })
+
+ it('a warm holder panned into view while zoomed in goes crisp — at rest, not mid-gesture', () => {
+ const h = fakeClient('h')
+ grant(h)
+ h.handle.setVisible(false)
+ zoomTo(WEBGL_CRISP_ABOVE_ZOOM + 0.01)
+ setWebglGesture(true)
+ h.handle.setVisible(true)
+ vi.advanceTimersByTime(WEBGL_DRAIN_MS * 5)
+ expect(h.rec.held).toBe(true)
+ setWebglGesture(false)
+ vi.advanceTimersByTime(WEBGL_DRAIN_MS * 5)
+ expect(h.rec.held).toBe(false)
+ })
+
+ it('a zoomed-in pan that only crosses a warm holder leaves it warm', () => {
+ const h = fakeClient('h')
+ grant(h)
+ h.handle.setVisible(false)
+ zoomTo(WEBGL_CRISP_ABOVE_ZOOM + 0.01)
+ setWebglGesture(true)
+ h.handle.setVisible(true)
+ h.handle.setVisible(false)
+ setWebglGesture(false)
+ vi.advanceTimersByTime(WEBGL_DRAIN_MS * 5)
+ expect(h.rec.releases).toBe(0)
+ expect(h.rec.held).toBe(true)
+ })
+
+ it('zooming back out does not cancel a pressure release a hidden holder still owes', () => {
+ const a = fakeClient('a')
+ const h = fakeClient('h')
+ grant(a)
+ grant(h)
+ h.handle.setVisible(false)
+ setWebglGesture(true)
+ setWebglZoom(WEBGL_CRISP_ABOVE_ZOOM + 0.01)
+ releaseAllHiddenGrants()
+ setWebglZoom(WEBGL_GPU_RESUME_BELOW_ZOOM - 0.01)
+ setWebglGesture(false)
+ vi.advanceTimersByTime(WEBGL_DRAIN_MS * 5)
+ expect(h.rec.held).toBe(false) // the pressure sweep's release stands
+ expect(a.rec.releases).toBe(0) // the brief overshoot is still forgiven
+ })
})
describe('crisp gate on a low-DPI display (issue #986)', () => {
@@ -526,6 +588,39 @@ describe('webgl-budget coordinator', () => {
expect(a.rec.held).toBe(false)
})
+ it('a node focus round trip swaps only what is on screen (goToNode frames past this line)', () => {
+ // On a 1x display every focus crosses the low-DPI line: goToNode frames at up to
+ // FIT_NODE_OPTIONS.maxZoom. Releasing the whole pool there put the focused node behind every
+ // off-screen release and re-granted all of them on the way back out.
+ expect(FIT_NODE_OPTIONS.maxZoom).toBeGreaterThan(WEBGL_LOW_DPI_CRISP_ABOVE_ZOOM)
+ setWebglDevicePixelRatio(1)
+ setWebglBudget(24)
+ const cs = Array.from({ length: 24 }, (_, i) => fakeClient(`c${i}`))
+ cs.forEach(grant)
+ expect(cs.every((c) => c.rec.held)).toBe(true)
+ const focused = cs[23] // registered last: the worst place in the drain's queue
+ const others = cs.slice(0, 23)
+
+ setWebglGesture(true)
+ others.forEach((c) => c.handle.setVisible(false))
+ setWebglZoom(FIT_NODE_OPTIONS.maxZoom)
+ setWebglGesture(false) // at rest: the drain's FIRST batch
+ expect(focused.rec.held).toBe(false)
+ vi.advanceTimersByTime(WEBGL_DRAIN_MS * 20)
+ expect(others.every((c) => c.rec.held)).toBe(true)
+
+ // Back out to the overview: everything on screen again (reported while the gate is still
+ // closed — the order an IntersectionObserver can deliver it in).
+ setWebglGesture(true)
+ cs.forEach((c) => c.handle.setVisible(true))
+ setWebglZoom(0.6)
+ setWebglGesture(false)
+ vi.advanceTimersByTime(WEBGL_ACQUIRE_DEBOUNCE_MS + WEBGL_DRAIN_MS * 20)
+ expect(cs.every((c) => c.rec.held)).toBe(true)
+ expect(others.every((c) => c.rec.acquires === 1 && c.rec.releases === 0)).toBe(true)
+ expect(focused.rec.acquires).toBe(2)
+ })
+
it('ignores a non-finite or non-positive ratio', () => {
const a = fakeClient('a')
grant(a)
diff --git a/src/renderer/terminal/webgl-budget.ts b/src/renderer/terminal/webgl-budget.ts
index 10ab6116e..9fdcf5f2b 100644
--- a/src/renderer/terminal/webgl-budget.ts
+++ b/src/renderer/terminal/webgl-budget.ts
@@ -107,8 +107,10 @@ export function getWebglBudget(): number {
}
/**
- * THE CRISP GATE — above this canvas zoom the coordinator holds NO contexts, and every terminal
- * paints through xterm's DOM renderer instead.
+ * THE CRISP GATE — above this canvas zoom no terminal ON SCREEN holds a context: each one paints
+ * through xterm's DOM renderer instead. Hidden holders keep their warm contexts through the gate
+ * (the blur only matters where it can be seen), and one that comes into view while the gate is
+ * closed gives its context back at rest (see `setVisible`).
*
* A GPU terminal is a BITMAP: the addon rasterizes into a canvas sized from the element's LAYOUT
* box in device pixels, and React Flow's `transform: scale()` then magnifies that bitmap. xterm
@@ -126,8 +128,8 @@ export function getWebglBudget(): number {
* work from outside the addon: three variants (dpr override; + pinning the backing store; +
* re-running the renderer resize) all left the terminal drawing almost nothing, because the
* renderer assumes throughout that its canvas is at true device resolution. Swapping renderers is
- * what remains, and it is affordable exactly where it is needed: at this zoom only one or two
- * terminals fit on screen, so the swap is a couple of nodes, not a canvas-wide rebalance.
+ * what remains, and it is affordable because only what is on screen swaps: at this zoom that is
+ * one or two terminals, not a canvas-wide rebalance.
*
* This is deliberately the INVERSE of the zoom gate removed in the budget-only lifecycle change,
* and it is not that gate returning: that one suspended the GPU when zoomed OUT past 40% on a
@@ -148,10 +150,19 @@ export const WEBGL_GPU_RESUME_BELOW_ZOOM = 1.6
* all the way to 175%; dom 39.7% at 100%, 38.1% at 110%, falling to 26.5% at 200%. At DPR 2 the
* softening is milder and reads as fine, so a high-DPI display keeps the 175% threshold.
*
- * On a low-DPI display every zoom-in past 100% therefore swaps to DOM. That is more terminals than
- * the high-DPI case (at 110% most of a canvas can still be on screen), so it costs DOM rendering
- * where there used to be GPU; that is the trade #361 left open ("moves to ~1.2 and nothing else
- * changes") and the one #986 asks for. 100% itself, and every zoom-out, stay on the GPU.
+ * On a low-DPI display every zoom-in past 100% therefore swaps the terminals on screen to DOM.
+ * That is more terminals than the high-DPI case (at 110% most of a canvas can still be on screen),
+ * so it costs DOM rendering where there used to be GPU; that is the trade #361 left open ("moves
+ * to ~1.2 and nothing else changes") and the one #986 asks for. 100% itself, and every zoom-out,
+ * stay on the GPU.
+ *
+ * It is also the COMMON path here, not a rare one: `goToNode` frames a node at up to 138%
+ * (`FIT_NODE_OPTIONS.maxZoom`), so on a low-DPI display every focus — sidebar, ⌘K, notification,
+ * double-click — crosses this line and comes back. That is why the gate leaves hidden holders
+ * warm. Releasing the whole pool instead, with 24 holders and the focused node registered last,
+ * put that node's release behind 22 off-screen ones (1.1 s after the canvas settled, at
+ * `WEBGL_SWAPS_PER_DRAIN` per `WEBGL_DRAIN_MS`) and cost 24 re-grants — shader compile + atlas
+ * build each — on the way back out, for a round trip that swapped nothing at all before #986.
*/
export const WEBGL_LOW_DPI_CRISP_ABOVE_ZOOM = 1.02
/** Resume threshold for the low-DPI gate — the same hysteresis rule, just above 100%. */
@@ -159,7 +170,8 @@ export const WEBGL_LOW_DPI_GPU_RESUME_BELOW_ZOOM = 1.01
/** Below this devicePixelRatio the low-DPI thresholds apply. */
const LOW_DPI_BELOW = 2
-/** True while the canvas is zoomed past the crisp threshold — grants are blocked. */
+/** True while the canvas is zoomed past the crisp threshold — grants are blocked, and every holder
+ * on screen owes its context back. */
let zoomCrisp = false
/** Last reported canvas zoom, so a display change can re-evaluate it. */
let lastZoom = 1
@@ -187,10 +199,10 @@ export function setWebglDevicePixelRatio(dpr: number): void {
/**
* Report the canvas zoom (React Flow viewport scale). Cheap and idempotent — call it from the
* zoom/pan handler; state only changes when a hysteresis boundary is crossed. Crossing UP marks
- * every held context release-OWED and drains; crossing DOWN forgives owed releases still held
- * (kept warm through a brief overshoot) and queues budget-gated grants for visible clients. Both
- * directions go through `owed`/`drain`, so nothing swaps mid-gesture and a multi-node crossing
- * trickles.
+ * every context held ON SCREEN release-OWED and drains (hidden holders stay warm); crossing DOWN
+ * forgives the owed releases still held (kept warm through a brief overshoot) and queues
+ * budget-gated grants for visible clients. Both directions go through `owed`/`drain`, so nothing
+ * swaps mid-gesture and a multi-node crossing trickles.
*/
export function setWebglZoom(zoom: number): void {
if (!Number.isFinite(zoom)) return
@@ -208,7 +220,9 @@ function applyZoomCrisp(zoom: number, displayChanged = false): void {
if (zoomCrisp) {
for (const c of clients.values()) {
cancelAcquire(c)
- if (c.granted) {
+ // Only the terminals on screen show the blur. A hidden holder keeps its warm context for the
+ // zoom back out; if it is panned into view first, `setVisible` queues its release then.
+ if (c.granted && c.visible) {
c.releaseOwed = true
owed.add(c)
}
@@ -219,8 +233,10 @@ function applyZoomCrisp(zoom: number, displayChanged = false): void {
if (!enabled) return
for (const c of clients.values()) {
// Zoomed back in under the threshold before the drain got to this client: keep the context,
- // releasing and re-granting it back to back is the churn this design forbids.
- if (c.granted && c.releaseOwed) c.releaseOwed = false
+ // releasing and re-granting it back to back is the churn this design forbids. Visible only:
+ // those are the gate's releases, while a HIDDEN holder's owed release is the pressure sweep's
+ // (`releaseAllHiddenGrants`), which a zoom has no business cancelling.
+ if (c.granted && c.releaseOwed && c.visible) c.releaseOwed = false
if (c.visible && !c.granted) {
c.releaseOwed = false
owed.add(c)
@@ -511,7 +527,16 @@ function setVisible(c: Client, visible: boolean): void {
// Re-visible: keep the warm context, and forgive a release parked in the deferred-drain
// queue (a pressure sweep that queued this client before it came back).
c.releaseOwed = false
- if (c.granted) return
+ if (c.granted) {
+ // …unless the canvas is zoomed past the crisp threshold: a warm holder panned into view
+ // there must go crisp like the ones already on screen. Queued, so it swaps at rest.
+ if (zoomCrisp) {
+ c.releaseOwed = true
+ owed.add(c)
+ drain()
+ }
+ return
+ }
// Debounce the acquire so a fast pan-through never grabs a context for a two-frame flash.
if (!c.acquireTimer) {
c.acquireTimer = setTimeout(() => {
@@ -525,6 +550,10 @@ function setVisible(c: Client, visible: boolean): void {
// any length, and the LRU reclaim candidate the moment a visible newcomer needs the slot.
c.hiddenAt = ++visibilityClock
cancelAcquire(c)
+ // A release still owed from while it was on screen is the crisp gate's (the pressure sweep only
+ // queues hidden holders). Off screen the blur no longer shows, so this holder stays warm like
+ // every other hidden one — a zoomed-in pan must not tear down each node it merely crossed.
+ if (zoomCrisp) c.releaseOwed = false
}
/**