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
import type { Terminal } from '@xterm/xterm'
/**
* Make the DOM and WebGL renderers agree on the cell width, so a renderer swap (budget grant or
* release) is horizontally pixel-stable instead of visibly reflowing the text.
*
* The disagreement is a rounding split inside xterm: the WebGL renderer FLOORS the measured char
* width to whole device pixels (`Math.floor(charWidth × dpr)` — its glyph atlas needs an integer
* grid), while the DOM renderer uses the RAW fractional measurement and pins each row's advance
* to it via `letter-spacing`. A char measured at 8.43px therefore lays out on an 8.0px cell under
* WebGL and an 8.43px cell under DOM — ~30px of drift across 80 columns, which is what a swap
* flashes as "the text got wider".
*
* The fix quantizes at the SOURCE both renderers read: `CharSizeService`'s measure strategy is
* wrapped so every measurement lands on the device-pixel grid (`ceil(width × dpr) / dpr`).
* The WebGL floor then loses nothing (it floors an already-integer product) and the DOM renderer
* lays out on the identical cell — and `fit`/`proposeDimensions` read the same service, so the
* column math stays consistent with what either renderer draws. Height is left alone: both
* renderers already ceil it through the same formula.
*
* Rounded UP, never down. The first version floored, and on a DPR 1 display that is a whole pixel:
* MEASURED on a 5120x1440 DPR 1 monitor, Menlo 13 measures 7.8125px and floored to 7.0, so the DOM
* renderer pinned every glyph with `letter-spacing: -0.8125px` (text ~10% too tight) and the last
* column's glyph ran past the edge of the screen element and was cut off ("opnieuw" ending in half a
* "w"). A cell at least as wide as its glyph cannot overhang. The 1e-3 device-pixel slack keeps a
* measurement that is already on the grid (7.000000000001) from gaining a whole pixel.
*
* Costs and edges, called out because they are deliberate:
* - A cell can widen by less than 1/dpr px (<0.5px on retina) versus the unquantized DOM cell, so
* text spreads a little and a terminal fits a few fewer columns at the same width (about 10% for
* Menlo 13 at DPR 1). The column count is what tmux is told, so nothing is clipped.
* - The dpr is read at MEASURE time (live, via the core's browser service with a window
* fallback). Moving the window to a display with a different dpr re-quantizes on the next
* measure (font/size changes, refresh); until one runs, the widths sit on the old grid —
* exactly the pre-existing xterm behaviour for its own dpr-derived dimensions.
* - This pokes xterm internals (`_core._charSizeService._measureStrategy`), in the same
* guarded, fail-open style as TerminalNode's `restoreDomRenderer`: if any field is missing
* on a future xterm, the wrap silently does not install and both renderers keep xterm's
* stock behaviour — nothing regresses but the swap parity.
*
* Idempotent per terminal (a marker on the strategy), safe to call on every mount/adopt. Returns
* whether the quantizing wrap is installed.
*/
interface MeasureResult {
width: number
height: number
}
interface MeasureStrategyLike {
measure(): Readonly<MeasureResult>
__ntQuantized?: boolean
}
interface CharSizeServiceLike {
measure(): void
_measureStrategy?: MeasureStrategyLike
}
interface CoreLike {
_charSizeService?: CharSizeServiceLike
_coreBrowserService?: { dpr?: number }
}
/** Device pixels a measurement may sit above the grid and still count as on it (float noise). */
const GRID_SLACK_DEVICE_PX = 1e-3
export function quantizeCharSize(
term: Terminal,
win: { devicePixelRatio?: number } | undefined = typeof window === 'undefined' ? undefined : window
): boolean {
try {
const core = (term as unknown as { _core?: CoreLike })._core
const svc = core?._charSizeService
const strategy = svc?._measureStrategy
if (!svc || typeof svc.measure !== 'function' || !strategy || typeof strategy.measure !== 'function') {
return false
}
if (strategy.__ntQuantized) return true
const original = strategy.measure.bind(strategy)
strategy.measure = () => {
const result = original()
const dpr = core?._coreBrowserService?.dpr || win?.devicePixelRatio || 1
if (!result || !Number.isFinite(result.width) || !Number.isFinite(dpr) || dpr <= 0) return result
const quantized = Math.ceil(result.width * dpr - GRID_SLACK_DEVICE_PX) / dpr
// A zero measurement (element not rendered yet) stays zero — xterm treats it as "unknown".
if (quantized <= 0) return result
return { width: quantized, height: result.height }
}
strategy.__ntQuantized = true
// Re-measure NOW: `term.open()` already measured unquantized, and the renderer built from
// that measurement is live. The service change-gates internally, so this fires its
// char-size-change event (renderers recompute dimensions) only when the width actually moves.
svc.measure()
return true
} catch {
return false
}
}