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
import { getViewportForBounds, type Rect, type Viewport } from '@xyflow/system'
import { rootPositionWith } from '@shared/root-position'
import { NO_INSETS, measurePinnedInsets, type RectLike, type ScreenInsets } from './pinnedInsets'
import { measureMaximizeInsets } from './maximizeInsets'
/**
* "Zoom to this node" geometry, computed without React Flow's `fitView`.
*
* Why this exists: `fitView({ nodes: [{ id }] })` is the natural way to frame one node, and it is
* what `Canvas.goToNode` used to do — but it frames nothing when you call it. It sets
* `fitViewQueued` and the fit is RESOLVED LATER: from a subsequent `setNodes` (and only once EVERY
* node is measured) or from the next `updateNodeInternals`. Whatever `nodeLookup` holds by then is
* what gets framed. And the fit set is filtered down to nodes React Flow has already MEASURED
* (`getFitViewNodes` keys off `measured.width && measured.height`; there is no `width`/`height`
* fallback there), so a set that comes out EMPTY collapses the bounds to `{0,0,0,0}` and the camera
* flies to the canvas ORIGIN at max zoom — an empty stretch of canvas, nowhere near the node.
*
* Both halves fire on the same everyday path. A cross-project focus (sessions sidebar, OS
* notification, ⌘K jump, presence travel) switches project → loads its nodes → frames the target,
* all before the mount-time measuring has settled: the queued fit then waits for a later node
* update, and by the time it runs the canvas may have moved on. The second click always works,
* because by then everything is measured — which is what makes it read as "sometimes".
*
* So the maths is ours, from React Flow's measurement when it has one and from the size the node
* was persisted with when it does not — neither needs layout — and the camera is driven with
* `setViewport`, which applies immediately.
*/
/** The subset of a React Flow node this module needs. Loose on purpose: it must accept both a
* freshly deserialized node (`width`/`height`, no `measured`) and a live measured one. */
export interface FocusableNode {
id: string
position: { x: number; y: number }
parentId?: string
width?: number | null
height?: number | null
measured?: { width?: number | null; height?: number | null }
style?: { width?: number | string | null; height?: number | string | null }
}
/**
* Is this node currently MAXIMIZED — i.e. was it placed against the chrome-free rectangle rather
* than dropped somewhere by hand?
*
* `premaxRect` is the maximize MODE flag (`maximizeNodeToRect` writes it, `restoreMaximizedNode`
* clears it), which is what makes it the right key here: it is exactly the set of nodes whose
* position was chosen by `maximizeTargetRect`, and the fix below is about framing a node against
* the rectangle its own placement used.
*
* It survives things that make the node no longer free-area-sized — a manual resize, a window
* resize (maximize deliberately does not re-fit on those) — and that is acceptable in both
* directions: with no pinned panel the inset is zero and this decision is a no-op, and with one
* the worst case is a node framed clear of a panel it was already meant to clear. Unpinning the
* panel needs no special case at all: `fitMaximizedToUsableArea` re-fits every maximized node
* whenever the insets change, so the flag and the geometry re-converge on their own.
*/
export function isMaximized(node: { data?: { premaxRect?: unknown } } | null | undefined): boolean {
return !!node?.data?.premaxRect
}
/** Zoom/padding for framing a single node, shared by both framing paths here so the whole-pane
* and chrome-free-frame answers cannot drift apart: the clamp keeps a small node from filling the
* screen and a huge one from being fit microscopic. */
export const FIT_NODE_OPTIONS = { padding: 0.2, minZoom: 0.25, maxZoom: 1.38 } as const
/** A `parentId` chain longer than this is a data bug (or a cycle) — stop walking. */
const MAX_PARENT_DEPTH = 20
const numeric = (v: unknown): number | null =>
typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : null
const sizeOf = (n: FocusableNode): { width: number; height: number } | null => {
const width = numeric(n.measured?.width) ?? numeric(n.width) ?? numeric(n.style?.width)
const height = numeric(n.measured?.height) ?? numeric(n.height) ?? numeric(n.style?.height)
return width && height ? { width, height } : null
}
/**
* The node's top-left in ABSOLUTE canvas coordinates. A grouped node's `position` is relative to
* its group frame, so the parent chain is walked. Needs no size — unlike `nodeFitRect` this always
* answers, which is what placement (as opposed to framing) needs: a node spawned next to a grouped
* source must be positioned in the same space the source really occupies, not at its raw
* group-relative `position`.
*/
export function absolutePosition(
node: FocusableNode,
all: readonly FocusableNode[]
): { x: number; y: number } {
return rootPositionWith(node, (id) => all.find((n) => n.id === id), MAX_PARENT_DEPTH)
}
/**
* The node's rect in ABSOLUTE canvas coordinates, or null when its size is unknowable (in which
* case the caller must leave the camera alone — a zero-size rect is what produces the origin jump).
*/
export function nodeFitRect(node: FocusableNode, all: readonly FocusableNode[]): Rect | null {
const size = sizeOf(node)
if (!size) return null
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.
*
* **Centred in the pane, and nothing else — `insets` default to none.** Framing a focused node
* against the chrome-free rectangle instead — centred in it, or centred in the pane and then
* nudged clear of it — was tried twice and is wrong both ways: the sessions sidebar is a 300px
* OVERLAY, so either rule pushes the node right by most of its width, and "go to node" stops
* putting the node where the eye is. The couple of dozen pixels of a node that end up behind the
* sidebar cost far less than that. The free-rect solve stays where it earns its keep, in `fitAll`,
* which fits EVERY node and would otherwise tuck them under the dock.
*
* **The MAXIMIZED exception (issue #743), and why it is not a walk-back of that trade-off.** The
* trade-off above rests on one number: how much of the node ends up behind the panel. For an
* ordinary node that is a couple of dozen pixels (33px, measured by the reporter). For a maximized
* one the premise inverts by CONSTRUCTION, not by degree: `maximizeTargetRect` sized the node to
* be *exactly* as wide as the free area, so centring it in the wider pane buries half the inset
* less the margin — 137px in the reported layout, and it scales with the PANEL, not with the node.
* It cannot come out as a few dozen pixels. So a maximized node is framed against the same
* rectangle its own placement used, which — since the node is that rectangle minus two margins —
* reproduces exactly where maximize put it. Everything else still centres in the whole pane,
* because `insets` is `NO_INSETS` unless the caller says otherwise.
*
* `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,
zoom?: number,
insets: ScreenInsets = NO_INSETS
): Viewport | null {
if (!(containerWidth > 0) || !(containerHeight > 0)) return null
// A pane narrower than the panels covering it is not a rectangle anything can be centred in —
// fall back to the whole pane rather than solving against a negative width.
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: originY + height / 2 - (rect.y + rect.height / 2) * zoom,
zoom
}
}
const fitted = getViewportForBounds(
rect,
width,
height,
FIT_NODE_OPTIONS.minZoom,
FIT_NODE_OPTIONS.maxZoom,
FIT_NODE_OPTIONS.padding
)
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
* actually include it in its fit set. Takes the minimal shape so it reads either a user-land
* node or React Flow's own internal node (the authoritative one; see Canvas.goToNode). */
export function isMeasured(
node: { measured?: { width?: number | null; height?: number | null } } | null | undefined
): boolean {
return !!(numeric(node?.measured?.width) && numeric(node?.measured?.height))
}
/** 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 {
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)
}