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.

perf(canvas): freeze viewport raster scale during camera moves

enes00c9c5fcb9ed
diff --git a/CLAUDE.md b/CLAUDE.md
index 9adb0217e..a173ecd82 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -5229,6 +5229,17 @@ glow that says "this agent finished while you were away" is still on screen when
look for it. `hud.css` is deliberately excluded: the notch HUD's window is never focused, so the
shared gate would freeze it permanently rather than while nobody is looking.
+**A camera move freezes the viewport's raster scale, and only for the move.** `onCanvasMoveStart`
+adds `canvas-camera-moving` to the flow wrapper in EVERY appearance (before the glass-only
+early-return — it is not a glass feature), and `.canvas-camera-moving .react-flow__viewport` sets
+`will-change: transform`, so the compositor scales the already-rastered layer instead of
+re-rasterising every node's DOM at each intermediate zoom. MEASURED (12 WebGL terminals, 60 Hz
+synthetic wheel zoom, M2, production build): **41–48% → 30–36%** total CPU, GPU process **22% →
+15%**. It MUST stay transient: `onCanvasMoveEnd` removes the class 150 ms after the move settles so
+text re-rasters sharp at the final scale — a permanent `will-change` on the viewport leaves every
+terminal blurry after a zoom. `canvas/camera-moving.test.ts` pins both halves (the rule is scoped
+to the class, and no bare `.react-flow__viewport` rule carries `will-change`).
+
## Remote access (phone relay) — free, not Pro
- Phone relay remote access ("Reach this Mac from anywhere") is a **Core (free) feature** as of
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index ab795b9e2..08d6d0184 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -1539,6 +1539,9 @@ export function Canvas() {
const onCanvasMoveStart = useCallback(() => {
if (movingClearRef.current) clearTimeout(movingClearRef.current)
movingClearRef.current = null
+ // Every appearance: freeze the viewport's raster scale for the duration of the move (see the
+ // `.canvas-camera-moving` rule). Before the glass early-return — this is not a glass feature.
+ flowWrapRef.current?.classList.add('canvas-camera-moving')
if (keepBlurWhileMovingRef.current) return
flowWrapRef.current?.classList.add('canvas-moving')
}, [])
@@ -1547,6 +1550,7 @@ export function Canvas() {
movingClearRef.current = setTimeout(() => {
movingClearRef.current = null
flowWrapRef.current?.classList.remove('canvas-moving')
+ flowWrapRef.current?.classList.remove('canvas-camera-moving')
}, 150)
}, [])
useEffect(
diff --git a/src/renderer/canvas/camera-moving.test.ts b/src/renderer/canvas/camera-moving.test.ts
new file mode 100644
index 000000000..3aef2332b
--- /dev/null
+++ b/src/renderer/canvas/camera-moving.test.ts
@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const read = (rel: string) => readFileSync(join(__dirname, '..', rel), 'utf8').replace(/\r\n/g, '\n')
+
+describe('camera-moving raster freeze', () => {
+ it('styles.css promotes the viewport only while the camera moves', () => {
+ const css = read('styles.css')
+ expect(css).toMatch(/\.canvas-camera-moving \.react-flow__viewport\s*\{[^}]*will-change:\s*transform/)
+ // Never permanently: a permanent will-change freezes raster scale and blurs text after zoom.
+ expect(css).not.toMatch(/(^|\n)\.react-flow__viewport\s*\{[^}]*will-change/)
+ })
+
+ it('Canvas adds the class on move start BEFORE the glass early-return, and clears it on end', () => {
+ const src = read('canvas/Canvas.tsx')
+ const start = src.slice(src.indexOf('const onCanvasMoveStart'), src.indexOf('const onCanvasMoveEnd'))
+ const add = start.indexOf("classList.add('canvas-camera-moving')")
+ const glassReturn = start.indexOf('if (keepBlurWhileMovingRef.current) return')
+ expect(add).toBeGreaterThan(-1)
+ expect(add).toBeLessThan(glassReturn)
+ const end = src.slice(src.indexOf('const onCanvasMoveEnd'), src.indexOf('const onCanvasMoveEnd') + 600)
+ expect(end).toContain("classList.remove('canvas-camera-moving')")
+ })
+})
diff --git a/src/renderer/styles.css b/src/renderer/styles.css
index 34bec6b49..8923ca7aa 100644
--- a/src/renderer/styles.css
+++ b/src/renderer/styles.css
@@ -1566,6 +1566,14 @@ body,
.term-node--glass .term-node__body {
background: transparent;
}
+/* Camera move (pan / zoom), every appearance: promote the viewport so the compositor scales the
+ already-rastered layer instead of re-rasterising every node's DOM at each intermediate zoom.
+ MEASURED (12 WebGL terminals, 60 Hz wheel zoom, M2): 41–48% → 30–36% total CPU, GPU process
+ 22% → 15%. Only WHILE moving: the class is removed 150 ms after the move settles so text
+ re-rasters sharp at the final scale — a permanent will-change would leave it blurry. */
+.canvas-camera-moving .react-flow__viewport {
+ will-change: transform;
+}
/* The blur is re-rasterised for every glass node on every frame of a pan/zoom (their backdrop
moves under them). With Keep blur while moving OFF (settings.glassBlurWhileMoving), Canvas marks
the flow wrapper while the camera moves; the tint stays, and the tint alone is what keeps text at