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): centre a focused node in the screen, and let the zoom be turned off

Bas Milius5e8abfe70e7b
diff --git a/CLAUDE.md b/CLAUDE.md
index 4d36c3779..ca5ca002d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2703,16 +2703,23 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord mea
The geometry is `renderer/lib/nodeFocus.ts`: the node's rect from React Flow's own measurement
when it has one (`getInternalNode` — `measured` reaches OUR node objects one render later via
`onNodesChange`, and `internals.positionAbsolute` also accounts for `extent:'parent'` clamping),
- else `nodeFitRect` from the PERSISTED size, resolving the group-parent chain. Then the
- chrome-free frame (`solveFitFrame`, pane-local — the same solve `fitAll`'s padding is expressed
- through) → `viewportForRectInFrame`, which centres the node in the space it can actually be seen
- in; no solvable frame ⇒ `viewportForRect` against the whole pane at the flat ratio. Unknowable
- size or no pane ⇒ the camera **stands still**. Two rules a refactor must not undo: framing goes
- through `frameNode` and nothing else (`canvas-wiring.test.tsx` pins that it contains no
- `fitView(`), and a "stands still" branch must never be "helpfully" replaced by a bare `fitView` —
- that IS the origin jump. `fitAll` still uses `fitView` deliberately: it is an explicit user
- gesture on a settled canvas and its fit set is every node, but it carries the same deferral, so
- do not reach for it from anything automatic.
+ else `nodeFitRect` from the PERSISTED size, resolving the group-parent chain. Then
+ `viewportForRectClearOf`: **centred in the SCREEN**, and only nudged — by the smallest amount
+ that works — when the centred node would slide under the floating chrome (the chrome-free frame
+ comes from `solveFitFrame`, pane-local, the same solve `fitAll`'s padding is expressed through).
+ Centring in that FRAME instead was tried and is wrong: the free rect is whatever the dock and the
+ sidebar leave over, not where the eye looks, so a node landed too far right on an ultrawide and
+ half off-screen on a laptop. A node too large for the frame is left centred — a shift there only
+ swaps which edge is covered. Unknowable size or no pane ⇒ the camera **stands still**.
+ `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
+ range would rescale the view the option exists to leave alone. Two rules a refactor must not
+ undo: framing goes through `frameNode` and nothing else (`canvas-wiring.test.tsx` pins that it
+ contains no `fitView(`), and a "stands still" branch must never be "helpfully" replaced by a bare
+ `fitView` — that IS the origin jump. `fitAll` still uses `fitView` deliberately: it is an
+ explicit user gesture on a settled canvas and its fit set is every node, but it carries the same
+ deferral, so do not reach for it from anything automatic.
- **Breadcrumb trail** (`renderer/lib/breadcrumbs.ts` — all the pure logic lives there) — every
deliberate `goToNode` landing records a `NavStop` ({nodeId, at, note}) for the ACTIVE project, and
**Cmd+[ / Cmd+]** (`canvas.goBack` / `canvas.goForward`, bound in `shared/keybindings.ts`) plus the
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 50f2bbfb3..f9bd3b500 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -269,7 +269,7 @@ import {
isMeasured,
nodeFitRect,
viewportForRect,
- viewportForRectInFrame,
+ viewportForRectClearOf,
type FocusableNode
} from '../lib/nodeFocus'
import { NODE_MAXIMIZE_MARGIN_PX, maximizeTargetRect } from '../lib/nodeMaximize'
@@ -6673,14 +6673,20 @@ export function Canvas() {
// Size unknowable / no pane yet: leave the camera where it is. Standing still beats
// teleporting the user to the origin, which is the failure this whole path exists for.
if (!rect || !wrap) return
- const frame = solveFitFrame(wrap, rect.width, rect.height)
const box = wrap.getBoundingClientRect()
- const viewport = frame
- ? viewportForRectInFrame(rect, frame)
- : viewportForRect(rect, box.width, box.height)
+ // `focusZoomToNode` off: keep the zoom the user settled on and only pan. The node is still
+ // centred and still kept clear of the chrome — only the rescale is dropped.
+ const keepZoom = useSettings.getState().settings.focusZoomToNode ? undefined : getZoom()
+ const viewport = viewportForRectClearOf(
+ rect,
+ box.width,
+ box.height,
+ solveFitFrame(wrap, rect.width, rect.height),
+ keepZoom
+ )
if (viewport) void setViewport(viewport, { duration: 300 })
},
- [setViewport, getInternalNode]
+ [setViewport, getInternalNode, getZoom]
)
const goToNode = useCallback(
diff --git a/src/renderer/canvas/canvas-wiring.test.tsx b/src/renderer/canvas/canvas-wiring.test.tsx
index 0cabda1db..a562b986a 100644
--- a/src/renderer/canvas/canvas-wiring.test.tsx
+++ b/src/renderer/canvas/canvas-wiring.test.tsx
@@ -170,6 +170,17 @@ describe('breadcrumb wiring the CLAUDE.md bullet calls load-bearing', () => {
expect(frame).toContain('setViewport(viewport, { duration: 300 })')
})
+ it('frames the node in the SCREEN, honouring the keep-my-zoom setting', () => {
+ // Centring in the chrome-free rect instead read as "too far right" on a wide display and as
+ // half off-screen on a laptop; `viewportForRectClearOf` centres in the pane and only nudges.
+ const frame = CANVAS_SRC.slice(
+ CANVAS_SRC.indexOf('const frameNode = useCallback'),
+ CANVAS_SRC.indexOf('const goToNode = useCallback')
+ )
+ expect(frame).toContain('viewportForRectClearOf(')
+ expect(frame).toContain('settings.focusZoomToNode ? undefined : getZoom()')
+ })
+
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/components/settings/sections/BehaviorSection.tsx b/src/renderer/components/settings/sections/BehaviorSection.tsx
index d26d73e0f..026b9c5a5 100644
--- a/src/renderer/components/settings/sections/BehaviorSection.tsx
+++ b/src/renderer/components/settings/sections/BehaviorSection.tsx
@@ -36,6 +36,10 @@ const ROWS = {
},
panHover: { title: 'Pan-hover delay (ms)', keywords: ['pan', 'hover', 'delay', 'focus', 'guard'] },
doubleClick: { title: 'Double-click to focus', keywords: ['double', 'click', 'focus'] },
+ focusZoom: {
+ title: 'Zoom when going to a node',
+ keywords: ['zoom', 'focus', 'go to', 'node', 'jump', 'camera', 'session', 'sidebar']
+ },
mdPreview: {
title: 'Open Markdown in preview',
keywords: ['markdown', 'md', 'preview', 'render', 'editor', 'docs', 'readme', 'file']
@@ -216,6 +220,19 @@ export function BehaviorSection({ isActive }: { isActive: boolean }): React.JSX.
}
/>
</SearchableRow>
+ <SearchableRow {...ROWS.focusZoom}>
+ <FieldRow
+ label="Zoom when going to a node"
+ description="Off: going to a node keeps your current zoom and only pans to it."
+ control={
+ <Switch
+ checked={settings.focusZoomToNode}
+ onChange={(v) => update({ focusZoomToNode: v })}
+ ariaLabel="Zoom when going to a node"
+ />
+ }
+ />
+ </SearchableRow>
<SearchableRow {...ROWS.mdPreview}>
<FieldRow
label="Open Markdown in preview"
diff --git a/src/renderer/lib/nodeFocus.test.ts b/src/renderer/lib/nodeFocus.test.ts
index 92f32c429..6973f93cb 100644
--- a/src/renderer/lib/nodeFocus.test.ts
+++ b/src/renderer/lib/nodeFocus.test.ts
@@ -6,7 +6,7 @@ import {
isMeasured,
nodeFitRect,
viewportForRect,
- viewportForRectInFrame
+ viewportForRectClearOf
} from './nodeFocus'
import type { FocusableNode } from './nodeFocus'
@@ -149,34 +149,64 @@ describe('viewportForRect', () => {
})
})
-describe('viewportForRectInFrame', () => {
- // 1280×900 pane with a 340px sessions sidebar on the left: the chrome-free frame the solver
- // hands over, in pane-local coordinates.
- const frame = { left: 352, top: 12, right: 1268, bottom: 888 }
-
- it('puts the node in the middle of the free frame, not of the whole pane', () => {
- const rect = { x: 5000, y: 4000, width: 600, height: 400 }
- const vp = viewportForRectInFrame(rect, frame)!
- expect(vp.x + 5300 * vp.zoom).toBeCloseTo((frame.left + frame.right) / 2, 0)
- expect(vp.y + 4200 * vp.zoom).toBeCloseTo((frame.top + frame.bottom) / 2, 0)
- // And emphatically not at the canvas origin, which is where an empty fitView set lands the
- // camera — the failure this whole path exists to make impossible.
- expect(vp.x).not.toBeCloseTo((frame.left + frame.right) / 2, 0)
- })
-
- it('applies the same zoom clamp as every other framing path', () => {
- expect(viewportForRectInFrame({ x: 0, y: 0, width: 8, height: 8 }, frame)!.zoom).toBe(
- FIT_NODE_OPTIONS.maxZoom
- )
- expect(viewportForRectInFrame({ x: 0, y: 0, width: 90000, height: 90000 }, frame)!.zoom).toBe(
- FIT_NODE_OPTIONS.minZoom
- )
- })
-
- it('refuses a frame or a node it cannot size, so the camera stands still', () => {
- const rect = { x: 0, y: 0, width: 600, height: 400 }
- expect(viewportForRectInFrame(rect, { left: 10, top: 10, right: 10, bottom: 900 })).toBeNull()
- expect(viewportForRectInFrame({ x: 0, y: 0, width: 0, height: 400 }, frame)).toBeNull()
+describe('viewportForRectClearOf', () => {
+ const rect = { x: 5000, y: 4000, width: 600, height: 400 }
+ // A sessions sidebar on the left, as the free-rect solver reports it: pane-local coordinates.
+ const sidebar = (left: number, paneW: number, paneH: number) => ({
+ left,
+ top: 12,
+ right: paneW - 12,
+ bottom: paneH - 12
+ })
+
+ it('centres the node in the SCREEN, not in the chrome-free rectangle', () => {
+ // The regression this pins: framing a node in the middle of the free rect reads as "too far
+ // right" on a wide display — the free rect is whatever the dock and the sidebar leave over,
+ // which is not where the eye looks. On an ultrawide the centred node clears the chrome by
+ // itself, so the answer must be the plain centred one.
+ const vp = viewportForRectClearOf(rect, 3440, 1400, sidebar(352, 3440, 1400))!
+ expect(vp).toEqual(viewportForRect(rect, 3440, 1400))
+ expect(vp.x + 5300 * vp.zoom).toBeCloseTo(1720, 0)
+ expect(vp.y + 4200 * vp.zoom).toBeCloseTo(700, 0)
+ })
+
+ it('nudges just enough to clear a panel the centred node would slide under', () => {
+ const frame = sidebar(500, 1440, 900)
+ const vp = viewportForRectClearOf(rect, 1440, 900, frame)!
+ const centred = viewportForRect(rect, 1440, 900)!
+ // Flush against the panel — moved, and no further than it had to be.
+ expect(vp.x + rect.x * vp.zoom).toBeCloseTo(frame.left, 0)
+ expect(vp.x).toBeGreaterThan(centred.x)
+ // The zoom and the other axis are untouched: this is a nudge, not a second framing.
+ expect(vp.zoom).toBe(centred.zoom)
+ expect(vp.y).toBe(centred.y)
+ })
+
+ it('leaves a node too large for the frame centred — a shift only swaps the covered edge', () => {
+ const vp = viewportForRectClearOf(rect, 1440, 900, { left: 600, top: 12, right: 900, bottom: 888 })
+ expect(vp).toEqual(viewportForRect(rect, 1440, 900))
+ })
+
+ it('keeps a given zoom and only pans (settings.focusZoomToNode off)', () => {
+ // The point of the option: a user who settled on a zoom level loses their sense of place when
+ // a jump also rescales the canvas. The node is still centred, and still nudged clear of chrome.
+ const vp = viewportForRectClearOf(rect, 1440, 900, sidebar(352, 1440, 900), 0.5)!
+ expect(vp.zoom).toBe(0.5)
+ expect(vp.x + 5300 * 0.5).toBeCloseTo(720, 0)
+ expect(vp.y + 4200 * 0.5).toBeCloseTo(450, 0)
+ })
+
+ it('passes an out-of-framing-range zoom through — it is one the canvas already shows', () => {
+ // Re-clamping to FIT_NODE_OPTIONS would rescale the very view this option exists to leave
+ // alone; the canvas's own limits already bound what getZoom() can return.
+ expect(viewportForRectClearOf(rect, 1440, 900, null, 1.9)!.zoom).toBe(1.9)
+ expect(viewportForRectClearOf(rect, 1440, 900, null, 0.1)!.zoom).toBe(0.1)
+ expect(viewportForRectClearOf(rect, 1440, 900, null, 0)).toBeNull()
+ })
+
+ it('is the plain centred answer when there is no frame to solve', () => {
+ expect(viewportForRectClearOf(rect, 1440, 900, null)).toEqual(viewportForRect(rect, 1440, 900))
+ expect(viewportForRectClearOf(rect, 0, 0, sidebar(352, 1440, 900))).toBeNull()
})
})
diff --git a/src/renderer/lib/nodeFocus.ts b/src/renderer/lib/nodeFocus.ts
index 1a9a57ed4..ced8bc973 100644
--- a/src/renderer/lib/nodeFocus.ts
+++ b/src/renderer/lib/nodeFocus.ts
@@ -89,14 +89,30 @@ export function nodeFitRect(node: FocusableNode, all: readonly FocusableNode[]):
return { ...absolutePosition(node, all), ...size }
}
-/** The viewport that frames `rect` in a `containerWidth × containerHeight` pane, with the same
- * padding/zoom clamp `fitView` would have applied. Null when the container has no size yet. */
+/**
+ * The viewport that frames `rect` in a `containerWidth × containerHeight` pane, with the same
+ * padding/zoom clamp `fitView` would have applied. Null when the container has no size yet.
+ *
+ * `zoom` keeps the camera at a scale the caller already has (`settings.focusZoomToNode` off): the
+ * node is centred exactly as it would be, at that zoom, so "go to" stays a pan. It is passed
+ * through UNCLAMPED — it is a zoom the canvas is already displaying, and re-clamping it to the
+ * framing range would rescale the view this option exists to leave alone.
+ */
export function viewportForRect(
rect: Rect,
containerWidth: number,
- containerHeight: number
+ containerHeight: number,
+ zoom?: number
): Viewport | null {
if (!(containerWidth > 0) || !(containerHeight > 0)) return null
+ if (zoom !== undefined) {
+ if (!(zoom > 0)) return null
+ return {
+ x: containerWidth / 2 - (rect.x + rect.width / 2) * zoom,
+ y: containerHeight / 2 - (rect.y + rect.height / 2) * zoom,
+ zoom
+ }
+ }
return getViewportForBounds(
rect,
containerWidth,
@@ -117,23 +133,41 @@ export interface FitFrame {
bottom: number
}
+/** The shift that brings a `size`-long span starting at `start` inside `[lo, hi]`, or 0 when it
+ * is already inside — or too long to fit, where any shift trades one clipped edge for the other. */
+function shiftInto(start: number, size: number, lo: number, hi: number): number {
+ if (size >= hi - lo) return 0
+ if (start < lo) return lo - start
+ if (start + size > hi) return hi - (start + size)
+ return 0
+}
+
/**
- * The viewport that puts `rect` in the middle of `frame`, at the zoom that fits it there.
+ * `viewportForRect`, then the SMALLEST nudge that keeps the node clear of the floating chrome.
*
- * The counterpart to `viewportForRect` for callers that solved a chrome-free frame first: the node
- * is centred in the space it can actually be seen in, rather than in the whole pane and then
- * nudged out from under a panel. Null when either box has no usable size.
+ * "Go to node" means putting the node in front of the user, and the middle of the screen is where
+ * that is: a node centred in the chrome-free rectangle instead reads as off to one side on a wide
+ * display (the free rect is whatever the dock and the sidebar leave over, not the eye's centre) and
+ * as half off-screen on a small one. So the centred answer stands, and the frame only pulls it back
+ * when it would otherwise slide under a panel — usually the sessions sidebar the click came from.
+ * A node too large to fit the frame is left centred: any shift there only swaps which edge is
+ * covered. `frame` null (nothing sensible to solve) ⇒ the plain centred answer.
*/
-export function viewportForRectInFrame(rect: Rect, frame: FitFrame): Viewport | null {
- const frameW = frame.right - frame.left
- const frameH = frame.bottom - frame.top
- if (!(frameW > 0) || !(frameH > 0) || !(rect.width > 0) || !(rect.height > 0)) return null
- const fit = Math.min(frameW / rect.width, frameH / rect.height)
- const zoom = Math.min(Math.max(fit, FIT_NODE_OPTIONS.minZoom), FIT_NODE_OPTIONS.maxZoom)
+export function viewportForRectClearOf(
+ rect: Rect,
+ containerWidth: number,
+ containerHeight: number,
+ frame: FitFrame | null,
+ zoom?: number
+): Viewport | null {
+ const centred = viewportForRect(rect, containerWidth, containerHeight, zoom)
+ if (!centred || !frame) return centred
+ const width = rect.width * centred.zoom
+ const height = rect.height * centred.zoom
return {
- x: (frame.left + frame.right) / 2 - (rect.x + rect.width / 2) * zoom,
- y: (frame.top + frame.bottom) / 2 - (rect.y + rect.height / 2) * zoom,
- zoom
+ zoom: centred.zoom,
+ x: centred.x + shiftInto(centred.x + rect.x * centred.zoom, width, frame.left, frame.right),
+ y: centred.y + shiftInto(centred.y + rect.y * centred.zoom, height, frame.top, frame.bottom)
}
}
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 475f1e3d1..a84a89a55 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -1359,6 +1359,12 @@ export interface Settings {
/** ms to dwell over a terminal before it takes pointer focus (pan-across guard). */
panHoverDelay: number
doubleClickFocus: boolean
+ /** "Go to node" (sessions sidebar, notification click, ⌘K jump, breadcrumb steps, presence
+ * travel) fits the node in view. Off: the camera keeps the CURRENT zoom and only pans, which is
+ * what a user who has settled on a zoom level wants — a jump that also rescales the whole canvas
+ * costs them the sense of where they were. Either way the node is centred and kept clear of the
+ * floating chrome (renderer/lib/nodeFocus). */
+ focusZoomToNode: boolean
/** Open Markdown files (.md, .markdown, …) in rendered preview instead of the code editor.
* Only picks the view an editor node OPENS in — the node's Preview/Edit toggle (and the
* markdown-toggle chord) still switches either way. Default ON since the release after
@@ -1669,6 +1675,7 @@ export const DEFAULT_SETTINGS: Settings = {
worktreePathTemplate: DEFAULT_WORKTREE_PATH_TEMPLATE,
panHoverDelay: 600,
doubleClickFocus: true,
+ focusZoomToNode: true,
openMarkdownPreview: true,
openMarkdownPreviewMigrated: true,
terminalMiddleClickPaste: false,