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
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.mdindex 4d36c3779..ca5ca002d 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -2703,16 +2703,23 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord meaThe geometry is `renderer/lib/nodeFocus.ts`: the node's rect from React Flow's own measurementwhen 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) — everydeliberate `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 thediff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsxindex 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.tsxindex 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 opaquediff --git a/src/renderer/components/settings/sections/BehaviorSection.tsx b/src/renderer/components/settings/sections/BehaviorSection.tsxindex 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}><FieldRowlabel="Open Markdown in preview"diff --git a/src/renderer/lib/nodeFocus.test.ts b/src/renderer/lib/nodeFocus.test.tsindex 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.tsindex 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.zoomreturn {- 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.tsindex 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: numberdoubleClickFocus: 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,