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): crisp text past 100% zoom on low-DPI displays (#986)

Erik Zwep9504ff857c27
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 19447fa0b..a5e16e8c2 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -82,6 +82,7 @@ import { terminalKey } from '../terminal/terminal-config'
import {
setWebglGesture,
setWebglZoom,
+ watchWebglDevicePixelRatio,
releaseAllHiddenGrants,
WEBGL_GESTURE_SETTLE_MS
} from '../terminal/webgl-budget'
@@ -9535,9 +9536,10 @@ export function Canvas() {
zoomRafRef.current = null
setZoomPct(Math.round(viewportRef.current.zoom * 100))
setGroupLabelBoost(viewportRef.current.zoom)
- // Feed the crisp gate (GPU text is a magnified bitmap past ~175%; the DOM renderer
- // re-rasters and stays sharp). Idempotent + hysteresis inside, and the swaps it queues
- // only run once the gesture settles — per-frame cost here is a float compare.
+ // Feed the crisp gate (GPU text is a magnified bitmap past ~175%, or past 100% on a
+ // low-DPI display; the DOM renderer re-rasters and stays sharp). Idempotent + hysteresis
+ // inside, and the swaps it queues only run once the gesture settles — per-frame cost
+ // here is a float compare.
setWebglZoom(viewportRef.current.zoom)
})
}
@@ -13541,6 +13543,10 @@ export function Canvas() {
})
}, [])
+ // The crisp gate's zoom threshold depends on the display (issue #986): report the device-pixel
+ // ratio now and whenever the window moves to a display with a different one.
+ useEffect(() => watchWebglDevicePixelRatio(window), [])
+
// Safety net for a lost Stop POST / crashed CLI: decay working entries that saw no hook
// event at all for STALE_WORKING_MS (the sweep itself is cheap; see agentStatus.ts).
//
diff --git a/src/renderer/terminal/webgl-budget.test.ts b/src/renderer/terminal/webgl-budget.test.ts
index e49129ce8..dada08460 100644
--- a/src/renderer/terminal/webgl-budget.test.ts
+++ b/src/renderer/terminal/webgl-budget.test.ts
@@ -9,6 +9,10 @@ import {
setWebglEnabled,
setWebglGesture,
setWebglZoom,
+ setWebglDevicePixelRatio,
+ watchWebglDevicePixelRatio,
+ WEBGL_LOW_DPI_CRISP_ABOVE_ZOOM,
+ WEBGL_LOW_DPI_GPU_RESUME_BELOW_ZOOM,
WEBGL_ACQUIRE_DEBOUNCE_MS,
WEBGL_CRISP_ABOVE_ZOOM,
WEBGL_GPU_RESUME_BELOW_ZOOM,
@@ -439,6 +443,103 @@ describe('webgl-budget coordinator', () => {
})
})
+ describe('crisp gate on a low-DPI display (issue #986)', () => {
+ // At devicePixelRatio 1 there is no spare resolution: ANY non-integer magnification of the GPU
+ // bitmap smears glyph edges. Measured at DPR 1 (mid-ramp share of ink, higher = blurrier):
+ // webgl 35.6% at 100% but ~62% from 110% up to 175%, while dom stays at or under ~40%.
+ const zoomTo = (zoom: number): void => {
+ setWebglZoom(zoom)
+ vi.advanceTimersByTime(WEBGL_DRAIN_MS * 10)
+ }
+
+ it('at DPR 1 a zoom just past 100% already goes crisp, and 100% itself stays on the GPU', () => {
+ setWebglDevicePixelRatio(1)
+ const a = fakeClient('a')
+ zoomTo(1)
+ grant(a)
+ expect(a.rec.held).toBe(true)
+ zoomTo(1.1)
+ expect(a.rec.held).toBe(false)
+ zoomTo(1)
+ expect(a.rec.held).toBe(true)
+ })
+
+ it('keeps its own hysteresis band just above 100%', () => {
+ setWebglDevicePixelRatio(1)
+ const a = fakeClient('a')
+ grant(a)
+ zoomTo(WEBGL_LOW_DPI_CRISP_ABOVE_ZOOM + 0.001)
+ expect(a.rec.releases).toBe(1)
+ zoomTo(WEBGL_LOW_DPI_GPU_RESUME_BELOW_ZOOM + 0.001) // in the band: still crisp
+ expect(a.rec.acquires).toBe(1)
+ zoomTo(WEBGL_LOW_DPI_GPU_RESUME_BELOW_ZOOM - 0.001)
+ expect(a.rec.acquires).toBe(2)
+ })
+
+ it('a high-DPI display keeps the original 175% threshold', () => {
+ setWebglDevicePixelRatio(2)
+ const a = fakeClient('a')
+ grant(a)
+ zoomTo(1.5)
+ expect(a.rec.held).toBe(true)
+ zoomTo(WEBGL_CRISP_ABOVE_ZOOM + 0.01)
+ expect(a.rec.held).toBe(false)
+ })
+
+ it('moving the window between displays re-evaluates the current zoom', () => {
+ const a = fakeClient('a')
+ setWebglDevicePixelRatio(2)
+ grant(a)
+ zoomTo(1.25)
+ expect(a.rec.held).toBe(true)
+ setWebglDevicePixelRatio(1) // dragged onto the low-DPI monitor
+ vi.advanceTimersByTime(WEBGL_DRAIN_MS * 10)
+ expect(a.rec.held).toBe(false)
+ setWebglDevicePixelRatio(2) // and back onto the retina display
+ vi.advanceTimersByTime(WEBGL_DRAIN_MS * 10)
+ expect(a.rec.held).toBe(true)
+ })
+
+ it('watchWebglDevicePixelRatio reports the ratio now and on every display change, then unsubscribes', () => {
+ const listeners = new Set<() => void>()
+ const queries: string[] = []
+ const win = {
+ devicePixelRatio: 2,
+ matchMedia(q: string) {
+ queries.push(q)
+ return {
+ addEventListener: (_: 'change', fn: () => void) => listeners.add(fn),
+ removeEventListener: (_: 'change', fn: () => void) => listeners.delete(fn)
+ }
+ }
+ }
+ const a = fakeClient('a')
+ const stop = watchWebglDevicePixelRatio(win)
+ grant(a)
+ zoomTo(1.25)
+ expect(a.rec.held).toBe(true)
+ win.devicePixelRatio = 1
+ ;[...listeners].forEach((fn) => fn())
+ vi.advanceTimersByTime(WEBGL_DRAIN_MS * 10)
+ expect(a.rec.held).toBe(false)
+ // The query is ratio-specific, so each change re-subscribes against the NEW ratio.
+ expect(queries).toEqual(['(resolution: 2dppx)', '(resolution: 1dppx)'])
+ expect(listeners.size).toBe(1)
+ stop()
+ expect(listeners.size).toBe(0)
+ })
+
+ it('ignores a non-finite or non-positive ratio', () => {
+ const a = fakeClient('a')
+ grant(a)
+ zoomTo(1.25)
+ setWebglDevicePixelRatio(Number.NaN)
+ setWebglDevicePixelRatio(0)
+ vi.advanceTimersByTime(WEBGL_DRAIN_MS * 10)
+ expect(a.rec.held).toBe(true)
+ })
+ })
+
describe('gesture latch (no swaps mid-gesture, staggered drain at rest)', () => {
it('defers grants while a gesture runs and executes them at rest', () => {
setWebglGesture(true)
diff --git a/src/renderer/terminal/webgl-budget.ts b/src/renderer/terminal/webgl-budget.ts
index 0e8dc5ef5..fb561fd72 100644
--- a/src/renderer/terminal/webgl-budget.ts
+++ b/src/renderer/terminal/webgl-budget.ts
@@ -141,8 +141,73 @@ export const WEBGL_CRISP_ABOVE_ZOOM = 1.75
* boundary must not thrash swap cycles — renderer churn is its own hazard. */
export const WEBGL_GPU_RESUME_BELOW_ZOOM = 1.6
+/**
+ * The crisp gate on a LOW-DPI display (devicePixelRatio under 2, issue #986). There is no spare
+ * resolution there, so any non-integer magnification of the GPU bitmap smears glyph edges, well
+ * below 175%. Measured at DPR 1 with the same metric as above: webgl 35.6% at 100%, ~62% from 110%
+ * 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.
+ */
+export const WEBGL_LOW_DPI_CRISP_ABOVE_ZOOM = 1.02
+/** Resume threshold for the low-DPI gate — the same hysteresis rule, just above 100%. */
+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. */
let zoomCrisp = false
+/** Last reported canvas zoom, so a display change can re-evaluate it. */
+let lastZoom = 1
+/** Last reported devicePixelRatio. Unknown until the canvas reports one, and unknown behaves as
+ * high-DPI — the thresholds this gate had before #986. */
+let devicePixelRatio = Number.POSITIVE_INFINITY
+
+/**
+ * Report the window's devicePixelRatio (it changes when the window moves between displays).
+ * Re-evaluates the current zoom against the thresholds for the new ratio.
+ */
+export function setWebglDevicePixelRatio(dpr: number): void {
+ if (!Number.isFinite(dpr) || dpr <= 0 || dpr === devicePixelRatio) return
+ devicePixelRatio = dpr
+ applyZoomCrisp(lastZoom)
+}
+
+interface DprMediaQuery {
+ addEventListener(type: 'change', listener: () => void): void
+ removeEventListener(type: 'change', listener: () => void): void
+}
+
+/**
+ * Report `win.devicePixelRatio` now, and again whenever it changes (a window dragged between a
+ * retina and a low-DPI display). A `(resolution: Ndppx)` query only fires when the ratio LEAVES N,
+ * so every change re-subscribes against the new ratio. Returns the unsubscribe.
+ */
+export function watchWebglDevicePixelRatio(win: {
+ devicePixelRatio: number
+ matchMedia?: (query: string) => DprMediaQuery
+}): () => void {
+ let query: DprMediaQuery | null = null
+ const subscribe = (): void => {
+ setWebglDevicePixelRatio(win.devicePixelRatio)
+ if (typeof win.matchMedia !== 'function') return
+ query = win.matchMedia(`(resolution: ${win.devicePixelRatio}dppx)`)
+ query.addEventListener('change', onChange)
+ }
+ function onChange(): void {
+ query?.removeEventListener('change', onChange)
+ subscribe()
+ }
+ subscribe()
+ return () => {
+ query?.removeEventListener('change', onChange)
+ query = null
+ }
+}
/**
* Report the canvas zoom (React Flow viewport scale). Cheap and idempotent — call it from the
@@ -154,7 +219,15 @@ let zoomCrisp = false
*/
export function setWebglZoom(zoom: number): void {
if (!Number.isFinite(zoom)) return
- const next = zoomCrisp ? zoom > WEBGL_GPU_RESUME_BELOW_ZOOM : zoom > WEBGL_CRISP_ABOVE_ZOOM
+ lastZoom = zoom
+ applyZoomCrisp(zoom)
+}
+
+function applyZoomCrisp(zoom: number): void {
+ const lowDpi = devicePixelRatio < LOW_DPI_BELOW
+ const crispAbove = lowDpi ? WEBGL_LOW_DPI_CRISP_ABOVE_ZOOM : WEBGL_CRISP_ABOVE_ZOOM
+ const resumeBelow = lowDpi ? WEBGL_LOW_DPI_GPU_RESUME_BELOW_ZOOM : WEBGL_GPU_RESUME_BELOW_ZOOM
+ const next = zoomCrisp ? zoom > resumeBelow : zoom > crispAbove
if (next === zoomCrisp) return
zoomCrisp = next
if (zoomCrisp) {
@@ -569,6 +642,8 @@ export function __resetWebglBudgetForTests(): void {
budget = WEBGL_BUDGET
enabled = true
zoomCrisp = false
+ lastZoom = 1
+ devicePixelRatio = Number.POSITIVE_INFINITY
gestureActive = false
owed.clear()
if (drainTimer) {