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(canvas): keep maximized nodes clear of persistent controls

reviewa5e8fd28af20
diff --git a/CLAUDE.md b/CLAUDE.md
index f108819c7..fe88a0b2f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -3674,7 +3674,12 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord mea
**ONE exception, and it is not a walk-back of that rule (issue #743): a MAXIMIZED node**
(`isMaximized` — `data.premaxRect`, the flag `maximizeNodeToRect` writes and
`restoreMaximizedNode` clears) is framed against the same rectangle `maximizeTargetRect` placed
- it in, by passing `measurePinnedInsets(box)` to `viewportForRect`. The trade-off above rests on
+ it in, by passing `measureMaximizeInsets(box)` to `viewportForRect`.
+ Maximize also measures `.controls-cluster` and `.dock` (#711): their screen rectangles reserve
+ top/bottom space with an 8px gap, consuming the existing 24px margin first. Chrome outside the
+ horizontally usable area contributes nothing. Menus and hover peeks never reserve a band. Both
+ focus zoom branches use these same vertical insets; refitting observes the persistent chrome
+ as well as pinned panels and compares all four insets. Zone snap retains its side-only policy. The trade-off above rests on
ONE number — how much of the node ends up behind the panel — and for a maximized node that
number is set by the PANEL rather than the node, **by construction**: maximize sized it to be
*exactly* the free area, so centring it in the wider pane buries half the inset less the margin.
@@ -3684,10 +3689,9 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord mea
free area reproduces maximize's own origin (`marginPx + insets.left`) exactly — which is what
makes this a fix rather than a second opinion about placement. It applies to BOTH zoom branches
(the rectangle question is the same one; splitting it would be two rectangles again, which is
- the bug), and with no pinned panel `insets` is zero and the whole thing is a mathematical no-op.
+ the bug). With no pinned panels or overlapping persistent controls, `insets` is zero.
A pane narrower than the panels over it falls back to the whole pane rather than solving against
- a negative width. `measurePinnedInsets` reads the DOM, so it is asked only for a node that can
- use the answer.
+ a negative width. `measureMaximizeInsets` reads the DOM only when framing a maximized node.
`settings.focusZoomToNode` (Behavior, default ON) is the escape hatch for the rescale: off, the
camera keeps the zoom `getZoom()` reports and only pans, and that zoom is passed through
**unclamped** — it is one the canvas is already displaying, and re-clamping it to the framing
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0223794bd..92a26f913 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -611,6 +611,11 @@ examples). If the same effect also WRITES, latch its first run: otherwise switch
mid-session applies stored state to whatever the user is doing right then, which is a different
feature from the one they asked for.
+Maximize placement and refocusing must use the same measured usable rectangle
+(`measureMaximizeInsets`): pinned side panels plus persistent top controls and bottom dock.
+Do not hardcode chrome heights or add the outer margin twice; transient menus must not resize
+terminals. Ordinary focus and zone snap keep their own policies.
+
## Testing
`npm test` must pass, and `npm run typecheck` is the fastest gate.
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 9cbed6b7a..600fac868 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -304,6 +304,7 @@ import {
} from '../lib/nodeFocus'
import { NODE_MAXIMIZE_MARGIN_PX, maximizeTargetRect } from '../lib/nodeMaximize'
import { NO_INSETS, measurePinnedInsets, type ScreenInsets } from '../lib/pinnedInsets'
+import { measureMaximizeInsets, MAXIMIZE_CHROME_SELECTOR } from '../lib/maximizeInsets'
import { ZONE_GUTTER_PX, ZONES, zoneTargetRect, type ZoneId } from '../lib/nodeZones'
import {
recordBreadcrumb,
@@ -7179,9 +7180,9 @@ export function Canvas() {
// lands in the middle, only the rescale is dropped.
const keepZoom = useSettings.getState().settings.focusZoomToNode ? undefined : getZoom()
// A MAXIMIZED node is framed against the rectangle its own placement used (issue #743);
- // everything else is centred in the whole pane, as it always was. `measurePinnedInsets`
+ // everything else is centred in the whole pane, as it always was. `measureMaximizeInsets`
// reads the DOM, so it is asked only for the node that can use the answer.
- const insets = isMaximized(node) ? measurePinnedInsets(box) : NO_INSETS
+ const insets = isMaximized(node) ? measureMaximizeInsets(box) : NO_INSETS
const viewport = viewportForRect(rect, box.width, box.height, keepZoom, insets)
if (viewport) void setViewport(viewport, { duration: 300 })
},
@@ -7663,7 +7664,7 @@ export function Canvas() {
wrap.width,
wrap.height,
NODE_MAXIMIZE_MARGIN_PX,
- measurePinnedInsets(wrap)
+ measureMaximizeInsets(wrap)
)
: null
if (!rect) return false
@@ -7673,7 +7674,7 @@ export function Canvas() {
}, [placementTargetNode, setNodes, markDirty, getViewport])
/**
- * Keep a maximized node fitted to the area the pinned side panels leave over.
+ * Keep a maximized node fitted to the area the pinned panels and persistent controls leave over.
*
* Maximize is a MODE, not a one-shot placement — a zone snap is the one-shot kind and stays
* where it was put. While maximize is on the node claims the whole usable canvas, so pinning a
@@ -7689,10 +7690,16 @@ export function Canvas() {
const fitMaximizedToUsableArea = useCallback(() => {
const wrap = flowWrapRef.current?.getBoundingClientRect()
if (!wrap) return
- const insets = measurePinnedInsets(wrap)
+ const insets = measureMaximizeInsets(wrap)
const prev = lastInsetsRef.current
lastInsetsRef.current = insets
- if (prev && prev.left === insets.left && prev.right === insets.right) return
+ if (
+ prev &&
+ prev.left === insets.left &&
+ prev.right === insets.right &&
+ prev.top === insets.top &&
+ prev.bottom === insets.bottom
+ ) return
if (!nodesRef.current.some((n) => n.data.premaxRect)) return
const rect = maximizeTargetRect(
getViewport(),
@@ -7716,9 +7723,7 @@ export function Canvas() {
useEffect(() => {
fitMaximizedToUsableArea()
- const panels = Array.from(
- document.querySelectorAll('.sessions-sidebar--pinned, .drawer--pinned')
- )
+ const panels = Array.from(document.querySelectorAll(MAXIMIZE_CHROME_SELECTOR))
// A ResizeObserver covers width changes (`uiScale`, the drawer's wide variant) but NOT the
// drawer's entry animation, which is opacity + transform — a transform never fires it, so the
// panel is measured ~10px off its settled position. `animationend` closes exactly that gap.
diff --git a/src/renderer/canvas/canvas-wiring.test.tsx b/src/renderer/canvas/canvas-wiring.test.tsx
index 8fade74b5..2eb5168a2 100644
--- a/src/renderer/canvas/canvas-wiring.test.tsx
+++ b/src/renderer/canvas/canvas-wiring.test.tsx
@@ -183,18 +183,6 @@ describe('breadcrumb wiring the CLAUDE.md bullet calls load-bearing', () => {
expect(frame).toContain('settings.focusZoomToNode ? undefined : getZoom()')
})
- it('insets that framing ONLY for a maximized node (issue #743)', () => {
- // The trade-off above is about how much of the node ends up behind the panel, and for a
- // maximized node that number is set by the PANEL, not the node: it is exactly as wide as the
- // free area, so centring it in the wider pane buries half the inset less the margin. Keying
- // on anything looser would walk back the whole-pane rule for ordinary nodes.
- const frame = CANVAS_SRC.slice(
- CANVAS_SRC.indexOf('const frameNode = useCallback'),
- CANVAS_SRC.indexOf('const goToNode = useCallback')
- )
- expect(frame).toContain('const insets = isMaximized(node) ? measurePinnedInsets(box) : NO_INSETS')
- })
-
it('the resume card slot is spent only on a card that can render, and only when opted in', () => {
// Gated on settings.showResumeCard (default off) FIRST — a disabled card must not spend the
// one-shot slot — then once per app run, only with a live stop, and never under the opaque
diff --git a/src/renderer/lib/maximizeInsets.test.ts b/src/renderer/lib/maximizeInsets.test.ts
new file mode 100644
index 000000000..368037b34
--- /dev/null
+++ b/src/renderer/lib/maximizeInsets.test.ts
@@ -0,0 +1,65 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest'
+import { measureMaximizeInsets } from './maximizeInsets'
+import { maximizeTargetRect } from './nodeMaximize'
+import { viewportForRect } from './nodeFocus'
+
+const wrap = { left: 100, right: 1300, top: 36, bottom: 836 }
+function chrome(className: string, left: number, top: number, right: number, bottom: number) {
+ const el = document.createElement('div')
+ el.className = className
+ el.getBoundingClientRect = () =>
+ ({ left, top, right, bottom, width: right - left, height: bottom - top }) as DOMRect
+ document.body.append(el)
+ return el
+}
+afterEach(() => document.body.replaceChildren())
+
+describe('maximize persistent chrome geometry (#711)', () => {
+ it.each([0.7345, 1, 1.1704, 2])('clears controls and dock at zoom %s and refocuses without drift', (zoom) => {
+ chrome('sessions-sidebar--pinned', 114, 90, 422, 780)
+ chrome('controls-cluster', 950, 50, 1286, 84)
+ chrome('dock', 500, 770, 900, 822)
+ const insets = measureMaximizeInsets(wrap)
+ const viewport = { x: -123, y: 87, zoom }
+ const rect = maximizeTargetRect(viewport, 1200, 800, 24, insets)!
+ expect(rect.x * zoom + viewport.x + wrap.left).toBeCloseTo(446)
+ expect(rect.y * zoom + viewport.y + wrap.top).toBeCloseTo(92)
+ expect((rect.y + rect.height) * zoom + viewport.y + wrap.top).toBeCloseTo(762)
+ const focused = viewportForRect(rect, 1200, 800, zoom, insets)!
+ expect(focused.x).toBeCloseTo(viewport.x)
+ expect(focused.y).toBeCloseTo(viewport.y)
+ expect(focused.zoom).toBe(zoom)
+ const fit = viewportForRect(rect, 1200, 800, undefined, insets)!
+ expect(rect.y * fit.zoom + fit.y + wrap.top).toBeGreaterThanOrEqual(84)
+ expect((rect.y + rect.height) * fit.zoom + fit.y + wrap.top).toBeLessThanOrEqual(770)
+ })
+
+ it('does not spend a top band for controls already behind the pinned right band', () => {
+ chrome('drawer--pinned', 920, 90, 1286, 780)
+ chrome('controls-cluster', 950, 50, 1286, 84)
+ expect(measureMaximizeInsets(wrap)).toEqual({ left: 0, right: 380, top: 0, bottom: 0 })
+ })
+
+ it('ignores hover panels, zero-size/hidden chrome, outside chrome and transient menus', () => {
+ chrome('sessions-sidebar', 114, 90, 422, 780)
+ chrome('controls-cluster', 950, 50, 950, 84)
+ chrome('dock', 500, 850, 900, 890)
+ chrome('dock-menu', 500, 300, 900, 822)
+ expect(measureMaximizeInsets(wrap)).toEqual({ left: 0, right: 0, top: 0, bottom: 0 })
+ })
+
+ it('uses current scaled chrome dimensions and releases the space when it disappears', () => {
+ const dock = chrome('dock', 300, 730, 1000, 822)
+ expect(measureMaximizeInsets(wrap).bottom).toBe(90)
+ dock.remove()
+ expect(measureMaximizeInsets(wrap).bottom).toBe(0)
+ })
+
+ it('refuses an unusably short viewport instead of inventing available space', () => {
+ chrome('controls-cluster', 110, 40, 390, 100)
+ chrome('dock', 110, 140, 390, 200)
+ const small = { left: 100, right: 400, top: 36, bottom: 210 }
+ expect(maximizeTargetRect({ x: 0, y: 0, zoom: 1 }, 300, 174, 24, measureMaximizeInsets(small))).toBeNull()
+ })
+})
diff --git a/src/renderer/lib/maximizeInsets.ts b/src/renderer/lib/maximizeInsets.ts
new file mode 100644
index 000000000..2074a0e3c
--- /dev/null
+++ b/src/renderer/lib/maximizeInsets.ts
@@ -0,0 +1,30 @@
+import { NODE_MAXIMIZE_MARGIN_PX } from './nodeMaximize'
+import { measurePinnedInsets, type RectLike, type ScreenInsets } from './pinnedInsets'
+
+export const MAXIMIZE_CHROME_SELECTOR =
+ '.sessions-sidebar--pinned, .drawer--pinned, .controls-cluster, .dock'
+
+/** Maximize alone reserves the persistent top controls and bottom dock. Transient menus do not
+ * resize terminals. Measure screen pixels (including UI scale), relative to this canvas wrapper.
+ * Keep just 8px between chrome and node, reusing the existing 24px margin rather than adding it
+ * twice. Ignore chrome already excluded by the pinned side panels. */
+export function measureMaximizeInsets(wrap: RectLike): ScreenInsets {
+ const sides = measurePinnedInsets(wrap)
+ let top = 0
+ let bottom = 0
+ if (typeof document === 'undefined') return { ...sides, top, bottom }
+ const left = wrap.left + sides.left + NODE_MAXIMIZE_MARGIN_PX
+ const right = wrap.right - sides.right - NODE_MAXIMIZE_MARGIN_PX
+ for (const selector of ['.controls-cluster', '.dock']) {
+ for (const el of document.querySelectorAll(selector)) {
+ const r = el.getBoundingClientRect()
+ if (r.right <= r.left || r.bottom <= r.top) continue
+ if (r.right <= left || r.left >= right || r.bottom <= wrap.top || r.top >= wrap.bottom) continue
+ const depth = selector === '.controls-cluster' ? r.bottom - wrap.top : wrap.bottom - r.top
+ const extra = Math.max(0, depth + 8 - NODE_MAXIMIZE_MARGIN_PX)
+ if (selector === '.controls-cluster') top = Math.max(top, extra)
+ else bottom = Math.max(bottom, extra)
+ }
+ }
+ return { ...sides, top, bottom }
+}
diff --git a/src/renderer/lib/nodeFocus.ts b/src/renderer/lib/nodeFocus.ts
index af0a813b7..980700875 100644
--- a/src/renderer/lib/nodeFocus.ts
+++ b/src/renderer/lib/nodeFocus.ts
@@ -152,23 +152,26 @@ export function viewportForRect(
const freeWidth = containerWidth - insets.left - insets.right
const originX = freeWidth > 0 ? insets.left : 0
const width = freeWidth > 0 ? freeWidth : containerWidth
+ const freeHeight = containerHeight - (insets.top ?? 0) - (insets.bottom ?? 0)
+ const originY = freeHeight > 0 ? (insets.top ?? 0) : 0
+ const height = freeHeight > 0 ? freeHeight : containerHeight
if (zoom !== undefined) {
if (!(zoom > 0)) return null
return {
x: originX + width / 2 - (rect.x + rect.width / 2) * zoom,
- y: containerHeight / 2 - (rect.y + rect.height / 2) * zoom,
+ y: originY + height / 2 - (rect.y + rect.height / 2) * zoom,
zoom
}
}
const fitted = getViewportForBounds(
rect,
width,
- containerHeight,
+ height,
FIT_NODE_OPTIONS.minZoom,
FIT_NODE_OPTIONS.maxZoom,
FIT_NODE_OPTIONS.padding
)
- return originX ? { ...fitted, x: fitted.x + originX } : fitted
+ return { ...fitted, x: fitted.x + originX, y: fitted.y + originY }
}
/** Whether React Flow already knows this node's on-screen size — i.e. whether `fitView` will
diff --git a/src/renderer/lib/nodeMaximize.ts b/src/renderer/lib/nodeMaximize.ts
index 221e1a9f2..e7ac138cb 100644
--- a/src/renderer/lib/nodeMaximize.ts
+++ b/src/renderer/lib/nodeMaximize.ts
@@ -23,7 +23,7 @@ export interface FlowRect {
/**
* The visible canvas area in FLOW coordinates, inset by `marginPx` (screen px) and by whatever
- * pinned side panels cover (`insets`). Null when the
+ * pinned panels and persistent chrome cover (`insets`). Null when the
* container has no usable size yet (first tick after mount) or is too small for a node to mean
* anything — the caller must then leave the node alone, exactly like `viewportForRect`'s null.
*/
@@ -37,13 +37,13 @@ export function maximizeTargetRect(
if (!(viewport.zoom > 0)) return null
const originX = marginPx + insets.left
const innerW = containerWidth - marginPx * 2 - insets.left - insets.right
- const innerH = containerHeight - marginPx * 2
+ const innerH = containerHeight - marginPx * 2 - (insets.top ?? 0) - (insets.bottom ?? 0)
// Below this the "maximized" node would be smaller than a default terminal's header — refuse
// rather than produce a comic-strip node the user then has to fish the restore button out of.
if (!(innerW >= 120) || !(innerH >= 120)) return null
return {
x: (originX - viewport.x) / viewport.zoom,
- y: (marginPx - viewport.y) / viewport.zoom,
+ y: (marginPx + (insets.top ?? 0) - viewport.y) / viewport.zoom,
width: innerW / viewport.zoom,
height: innerH / viewport.zoom
}
diff --git a/src/renderer/lib/pinnedInsets.ts b/src/renderer/lib/pinnedInsets.ts
index 5568d4d46..cc3b78782 100644
--- a/src/renderer/lib/pinnedInsets.ts
+++ b/src/renderer/lib/pinnedInsets.ts
@@ -18,10 +18,12 @@ export interface RectLike {
bottom: number
}
-/** Screen-px to keep clear on each horizontal edge of the canvas wrapper. */
+/** Screen-px to exclude before placement margins. Vertical edges are optional for side-only callers. */
export interface ScreenInsets {
left: number
right: number
+ top?: number
+ bottom?: number
}
export const NO_INSETS: ScreenInsets = { left: 0, right: 0 }
diff --git a/src/renderer/nodes/MaximizeButton.tsx b/src/renderer/nodes/MaximizeButton.tsx
index 8cd52dda7..8b9c4ac18 100644
--- a/src/renderer/nodes/MaximizeButton.tsx
+++ b/src/renderer/nodes/MaximizeButton.tsx
@@ -12,7 +12,7 @@ import { commandTooltip } from '../lib/keybindingOverrides'
import { markWorkspaceDirty } from '../state/workspaceDirty'
import { maximizeNodeToRect, restoreMaximizedNode, type CanvasNode } from '../state/workspace'
import { NODE_MAXIMIZE_MARGIN_PX, maximizeTargetRect } from '../lib/nodeMaximize'
-import { measurePinnedInsets } from '../lib/pinnedInsets'
+import { measureMaximizeInsets } from '../lib/maximizeInsets'
export function MaximizeButton({ id, maximized }: { id: string; maximized: boolean }) {
const { setNodes, getViewport } = useReactFlow()
@@ -31,7 +31,7 @@ export function MaximizeButton({ id, maximized }: { id: string; maximized: boole
width,
height,
NODE_MAXIMIZE_MARGIN_PX,
- wrap ? measurePinnedInsets(wrap) : undefined
+ wrap ? measureMaximizeInsets(wrap) : undefined
)
return rect ? maximizeNodeToRect(flow, id, rect) : ns
})