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.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
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.tsindex 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.tsindex 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 = trueowed.add(c)}@@ -219,8 +233,10 @@ function applyZoomCrisp(zoom: number, displayChanged = false): void {if (!enabled) returnfor (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 = falseif (c.visible && !c.granted) {c.releaseOwed = falseowed.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 = ++visibilityClockcancelAcquire(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}/**