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 a focused node clear of a pinned side panel

Erik Zwepe3cea9fe638b
diff --git a/CLAUDE.md b/CLAUDE.md
index f37981d13..d422afa1e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4590,6 +4590,15 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord mea
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. `measureMaximizeInsets` reads the DOM only when framing a maximized node.
+ **A second, narrower exception: a PINNED side panel (issue #854).** An ordinary node is still
+ centred in the pane, but if that lands part of it under a pinned sessions sidebar or explorer
+ (`measurePinnedInsets` — pinned only, never the hover overlay), `clearOfPinnedPanels` moves it
+ the least distance that uncovers it (plus a 12px gap when there is room). A node too wide for
+ the free area stays centred at a caller's zoom (a shift only swaps which edge is covered) and is
+ fitted into the free area when the zoom is ours. This is not the rejected nudge of 5e8abfe7:
+ that cleared the sidebar as an OVERLAY, which is open whenever the click comes from it, so every
+ jump moved; pinning is the user's statement that the panel stays. The reporter measured 36–47px
+ of a large node under a pinned 321px sidebar on every jump.
`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/src/renderer/lib/nodeFocus.policy.test.ts b/src/renderer/lib/nodeFocus.policy.test.ts
index 0c4690dc1..7e83890ad 100644
--- a/src/renderer/lib/nodeFocus.policy.test.ts
+++ b/src/renderer/lib/nodeFocus.policy.test.ts
@@ -38,18 +38,30 @@ describe('Canvas focus policy (#743, #711)', () => {
const target = maximizeTargetRect(camera, box.width, box.height, 24, measureMaximizeInsets(box))!
const maximized = maximizeNodeToRect([node], node.id, target)
const restored = restoreMaximizedNode(maximized, node.id)[0]
- const readChrome = vi.spyOn(document, 'querySelectorAll')
-
- // Normal and restored nodes centre in the whole pane, regardless of visible chrome.
+ // Normal and restored nodes centre in the whole pane, and are kept clear of the PINNED
+ // sessions sidebar (inset 322 here) when that is possible (#854). Vertically: centred.
for (const candidate of [node, restored]) {
const rect = nodeFitRect(candidate, [candidate])!
expect(rect).toEqual(originalRect)
const focus = viewportForNodeFocus(candidate, rect, box, zoom)!
- expect((rect.x + rect.width / 2) * focus.zoom + focus.x).toBeCloseTo(600)
expect((rect.y + rect.height / 2) * focus.zoom + focus.y).toBeCloseTo(400)
+ const left = rect.x * focus.zoom + focus.x
+ const right = (rect.x + rect.width) * focus.zoom + focus.x
+ if (zoom === 2) {
+ // Wider than the free area at the user's zoom: stays centred (a shift only swaps edges).
+ expect(focus.zoom).toBe(2)
+ expect((rect.x + rect.width / 2) * focus.zoom + focus.x).toBeCloseTo(600)
+ } else if (zoom === 0.7345) {
+ // Already clear of the panel when centred: untouched.
+ expect(left).toBeGreaterThan(322)
+ expect((rect.x + rect.width / 2) * focus.zoom + focus.x).toBeCloseTo(600)
+ } else {
+ // Our zoom: the node ends up entirely beside the pinned panel.
+ expect(left).toBeGreaterThanOrEqual(322 - 1e-8)
+ expect(right).toBeLessThanOrEqual(1200 + 1e-8)
+ }
if (zoom !== undefined) expect(focus.zoom).toBe(zoom)
}
- expect(readChrome).not.toHaveBeenCalled()
const rect = nodeFitRect(maximized[0], maximized)!
const focus = viewportForNodeFocus(maximized[0], rect, box, zoom)!
@@ -65,3 +77,24 @@ describe('Canvas focus policy (#743, #711)', () => {
}
})
})
+
+describe('ordinary focus without a pinned panel (#854)', () => {
+ it.each([undefined, 0.7345, 2])('centres in the whole pane (keepZoom=%s)', (zoom) => {
+ // Only the controls cluster and the dock: nothing pinned at the sides.
+ for (const [className, left, top, right, bottom] of [
+ ['controls-cluster', 950, 50, 1286, 84],
+ ['dock', 500, 770, 900, 822]
+ ] as const) {
+ 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)
+ }
+ const node = ordinary()
+ const rect = nodeFitRect(node, [node])!
+ const focus = viewportForNodeFocus(node, rect, box, zoom)!
+ expect((rect.x + rect.width / 2) * focus.zoom + focus.x).toBeCloseTo(600)
+ expect((rect.y + rect.height / 2) * focus.zoom + focus.y).toBeCloseTo(400)
+ })
+})
diff --git a/src/renderer/lib/nodeFocus.test.ts b/src/renderer/lib/nodeFocus.test.ts
index 6cdf9a3d2..f8c2484c6 100644
--- a/src/renderer/lib/nodeFocus.test.ts
+++ b/src/renderer/lib/nodeFocus.test.ts
@@ -9,6 +9,8 @@ import {
viewportForRect
} from './nodeFocus'
import type { FocusableNode } from './nodeFocus'
+import { clearOfPinnedPanels } from './nodeFocus'
+import { NO_INSETS } from './pinnedInsets'
import { NODE_MAXIMIZE_MARGIN_PX } from './nodeMaximize'
const term = (over: Partial<FocusableNode> = {}): FocusableNode => ({
@@ -271,3 +273,70 @@ describe('isMaximized', () => {
expect(isMaximized(undefined)).toBe(false)
})
})
+
+describe('clearOfPinnedPanels — a focused node lands clear of a PINNED panel (issue #854)', () => {
+ const W = 1470
+ const H = 862
+ const pinnedLeft = { left: 321, right: 0 }
+ // Screen x of the node's left and right edge under a viewport.
+ const edges = (v: { x: number; zoom: number }, r: { x: number; width: number }) => [
+ v.x + r.x * v.zoom,
+ v.x + (r.x + r.width) * v.zoom
+ ]
+ const centred = (r: { x: number; y: number; width: number; height: number }, zoom: number) => ({
+ x: W / 2 - (r.x + r.width / 2) * zoom,
+ y: H / 2 - (r.y + r.height / 2) * zoom,
+ zoom
+ })
+
+ it('leaves the pane-centred viewport alone when nothing is pinned', () => {
+ const r = { x: 0, y: 0, width: 900, height: 500 }
+ const v = centred(r, 1)
+ expect(clearOfPinnedPanels(v, r, W, H, NO_INSETS)).toBe(v)
+ })
+
+ it('leaves it alone when the centred node already clears the pinned panel', () => {
+ const r = { x: 0, y: 0, width: 600, height: 400 } // left edge at 435 > 321
+ const v = centred(r, 1)
+ expect(clearOfPinnedPanels(v, r, W, H, pinnedLeft)).toBe(v)
+ })
+
+ it('nudges a node that fits the free area just clear of the panel (the reported case)', () => {
+ // 900px wide centred in 1470 → left edge at 285, 36px under a panel ending at 321.
+ const r = { x: 0, y: 0, width: 900, height: 500 }
+ const v = centred(r, 1)
+ const out = clearOfPinnedPanels(v, r, W, H, pinnedLeft)
+ const [left, right] = edges(out, r)
+ expect(left).toBeGreaterThanOrEqual(321)
+ expect(left - 321).toBeLessThanOrEqual(12) // just clear, not re-centred in the free area
+ expect(right).toBeLessThanOrEqual(W)
+ expect(out.zoom).toBe(1)
+ expect(out.y).toBe(v.y) // vertical placement untouched
+ })
+
+ it('works the same for a panel pinned on the right (the explorer)', () => {
+ const r = { x: 0, y: 0, width: 900, height: 500 }
+ const v = centred(r, 1)
+ const out = clearOfPinnedPanels(v, r, W, H, { left: 0, right: 321 })
+ const [, right] = edges(out, r)
+ expect(right).toBeLessThanOrEqual(W - 321)
+ expect(W - 321 - right).toBeLessThanOrEqual(12)
+ })
+
+ it('keeps the user zoom and stays centred when the node is wider than the free area at that zoom', () => {
+ // A shift would only swap which edge is covered (the rule from 5e8abfe7).
+ const r = { x: 0, y: 0, width: 1300, height: 500 }
+ const v = centred(r, 1)
+ expect(clearOfPinnedPanels(v, r, W, H, pinnedLeft, 1)).toBe(v)
+ })
+
+ it('fits a too-wide node into the free area when the zoom is its own to choose', () => {
+ const r = { x: 0, y: 0, width: 1300, height: 500 }
+ const v = centred(r, 1)
+ const out = clearOfPinnedPanels(v, r, W, H, pinnedLeft)
+ const [left, right] = edges(out, r)
+ expect(left).toBeGreaterThanOrEqual(321)
+ expect(right).toBeLessThanOrEqual(W)
+ expect(out.zoom).toBeLessThan(1)
+ })
+})
diff --git a/src/renderer/lib/nodeFocus.ts b/src/renderer/lib/nodeFocus.ts
index 09624d6c2..342ee2876 100644
--- a/src/renderer/lib/nodeFocus.ts
+++ b/src/renderer/lib/nodeFocus.ts
@@ -1,6 +1,6 @@
import { getViewportForBounds, type Rect, type Viewport } from '@xyflow/system'
-import { NO_INSETS, type RectLike, type ScreenInsets } from './pinnedInsets'
+import { NO_INSETS, measurePinnedInsets, type RectLike, type ScreenInsets } from './pinnedInsets'
import { measureMaximizeInsets } from './maximizeInsets'
/**
@@ -184,14 +184,71 @@ export function isMeasured(
return !!(numeric(node?.measured?.width) && numeric(node?.measured?.height))
}
-/** Shared Canvas focus policy: only maximized nodes use their placement's chrome reservations.
- * Ordinary/restored nodes stay centred in the whole pane, without measuring overlay geometry. */
+/** Gap kept between a nudged node and the pinned panel it was moved clear of, room permitting. */
+const PINNED_CLEAR_GAP_PX = 12
+
+/**
+ * Keep a pane-centred node out from under a PINNED side panel (issue #854).
+ *
+ * Why this is not the rejected "nudge clear of the chrome" from 5e8abfe7: that one cleared the
+ * sessions sidebar as an OVERLAY — open, by definition, whenever "go to node" is clicked from it —
+ * so every jump moved right. This one only knows PINNED panels (`measurePinnedInsets`), which the
+ * user placed there to stay ("this one stays", see pinnedInsets.ts). With nothing pinned, or a
+ * node that already clears the panel, the viewport is returned untouched: centred in the pane.
+ *
+ * Otherwise, in order:
+ * - the node fits the free area at this zoom → shift it just clear of the panel (plus a small gap
+ * when there is room), not re-centred in the free area: the least movement that uncovers it;
+ * - it does not fit, and the zoom was the caller's (`focusZoomToNode` off) → leave it centred: a
+ * shift would only swap which edge is covered (the rule 5e8abfe7 already stated);
+ * - it does not fit, and the zoom is ours to choose → fit it into the free area, the way a
+ * maximized node is framed (#743).
+ * Vertical placement is never touched.
+ */
+export function clearOfPinnedPanels(
+ viewport: Viewport,
+ rect: Rect,
+ containerWidth: number,
+ containerHeight: number,
+ insets: ScreenInsets,
+ keepZoom?: number
+): Viewport {
+ if (!insets.left && !insets.right) return viewport
+ const freeLeft = insets.left
+ const freeRight = containerWidth - insets.right
+ const freeWidth = freeRight - freeLeft
+ if (!(freeWidth > 0)) return viewport
+ const left = viewport.x + rect.x * viewport.zoom
+ const width = rect.width * viewport.zoom
+ const right = left + width
+ if (left >= freeLeft && right <= freeRight) return viewport
+ if (width <= freeWidth) {
+ const gap = Math.min(PINNED_CLEAR_GAP_PX, (freeWidth - width) / 2)
+ const shift = left < freeLeft ? freeLeft + gap - left : freeRight - gap - right
+ return { ...viewport, x: viewport.x + shift }
+ }
+ if (keepZoom !== undefined) return viewport
+ return (
+ viewportForRect(rect, containerWidth, containerHeight, undefined, {
+ left: insets.left,
+ right: insets.right
+ }) ?? viewport
+ )
+}
+
+/** Shared Canvas focus policy. A maximized node is framed against its placement's chrome
+ * reservations (#743). Any other node is centred in the whole pane, then kept clear of a PINNED
+ * side panel it would otherwise land under (#854; see `clearOfPinnedPanels`). */
export function viewportForNodeFocus(
node: { data?: { premaxRect?: unknown } },
rect: Rect,
box: RectLike & { width: number; height: number },
zoom?: number
): Viewport | null {
- const insets = isMaximized(node) ? measureMaximizeInsets(box) : NO_INSETS
- return viewportForRect(rect, box.width, box.height, zoom, insets)
+ if (isMaximized(node)) {
+ return viewportForRect(rect, box.width, box.height, zoom, measureMaximizeInsets(box))
+ }
+ const centred = viewportForRect(rect, box.width, box.height, zoom, NO_INSETS)
+ if (!centred) return null
+ return clearOfPinnedPanels(centred, rect, box.width, box.height, measurePinnedInsets(box), zoom)
}