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 type { CanvasLayout, CanvasLayoutNode } from '@shared/canvas-layout'
import { CANVAS_LAYOUT_NAME_MAX } from '@shared/canvas-layout'
import {
COLLAPSED_HEIGHT,
fitGroupToChildren,
GROUP_HEADER,
GROUP_PAD,
rootPosition,
type CanvasNode
} from '../state/workspace'
/**
* Capture and restore of a canvas layout: a named snapshot of node GEOMETRY for one project (see
* the trust model in @shared/canvas-layout).
*
* Pure on purpose. Everything here is array in, array out, so the two halves that decide where a
* canvas ends up can be tested under vitest's default node environment instead of behind React
* Flow, a zustand store and a mounted canvas.
*/
/**
* Node kinds that exist only as a live render and are never serialized (`subagent`, `loop` in
* CLAUDE.md's node-kinds list). A layout entry for one is an id nothing can ever resolve again -
* the next turn clears the card - so capture skips them and the restore's `extra` count ignores
* them rather than reporting a "node the layout does not mention" the user cannot act on.
*/
const EPHEMERAL_KINDS: ReadonlySet<string> = new Set(['subagent', 'loop'])
/** A rect in ROOT space, the coordinate space a layout entry and `withNodeRect` both speak. */
interface RootRect {
x: number
y: number
width: number
height: number
}
const finiteNumber = (value: unknown): number | undefined =>
typeof value === 'number' && Number.isFinite(value) ? value : undefined
/** A node's on-canvas width, preferring React Flow's own measurement the way `flowToNodeStates`
* does, so a captured rect matches what the user actually sees rather than the last size written. */
function capturedWidth(node: CanvasNode): number | undefined {
return (
finiteNumber(node.measured?.width) ??
finiteNumber(node.width) ??
finiteNumber(node.style?.width)
)
}
/**
* A node's EXPANDED height, which is the only height a layout may store.
*
* While a node is collapsed its on-screen height is chrome (`COLLAPSED_HEIGHT`), not a size the
* user chose, so the measurement is ignored in favor of `data.expandedHeight` - the same rule
* `flowToNodeStates` applies when it serializes a collapsed node. Storing the shrunk height would
* make every save-while-collapsed permanently shrink the node on the next restore.
*/
function capturedExpandedHeight(node: CanvasNode): number | undefined {
if (node.data.collapsed) return finiteNumber(node.data.expandedHeight)
return (
finiteNumber(node.measured?.height) ??
finiteNumber(node.height) ??
finiteNumber(node.style?.height)
)
}
/**
* Snapshot the live canvas: every node's ROOT-space rect, its collapse state and its parent.
*
* Root space rather than parent-relative because a frame that has since been ungrouped, moved or
* re-fitted must not drag its old children hundreds of pixels off screen when the layout is
* restored - the same reasoning `maximizeNodeToRect` gives for storing `premaxRect` in root space.
*
* A node whose size cannot be established is SKIPPED rather than captured at a guessed rect: an
* unaddressed node is left exactly where it is on restore (rule 1), which is always safe, while a
* guessed rect would resize it. In practice every node carries a size - `nodeStatesToFlow` and the
* node factories both write one - so this is a refusal, not a fallback.
*
* The name is trimmed and capped here so the layout survives its own reader: `sanitizeLayouts`
* drops a layout WHOLE when its name is empty after trimming, and a capture that produced an
* unreadable snapshot would look like a save that silently did nothing.
*/
export function captureLayout(
nodes: CanvasNode[],
opts: { id: string; name: string; now: number; window?: { width: number; height: number } }
): CanvasLayout {
const entries: CanvasLayoutNode[] = []
for (const node of nodes) {
if (EPHEMERAL_KINDS.has(node.type ?? '')) continue
const width = capturedWidth(node)
const height = capturedExpandedHeight(node)
if (width === undefined || height === undefined) continue
const root = rootPosition(node, nodes)
entries.push({
id: node.id,
x: root.x,
y: root.y,
width,
height,
...(node.data.collapsed ? { collapsed: true } : {}),
...(node.parentId ? { parentId: node.parentId } : {})
})
}
return {
id: opts.id,
name: opts.name.trim().slice(0, CANVAS_LAYOUT_NAME_MAX),
createdAt: opts.now,
updatedAt: opts.now,
...(opts.window ? { window: opts.window } : {}),
nodes: entries
}
}
/** What a restore did, in the terms the user-facing toast reports. Counted by the transform itself
* so the sentence cannot drift from what happened on the canvas. */
export interface ApplyLayoutResult {
nodes: CanvasNode[]
/** Nodes the layout addressed and actually placed. */
moved: number
/** Entries in the layout whose node no longer exists. Never recreated. */
missing: number
/** Live nodes the layout does not mention. Left untouched. */
extra: number
}
/** A node's rect as it is drawn right now: the rendered height, so a collapsed node contributes its
* chrome height rather than the size it would have if expanded. */
function renderedRootRect(node: CanvasNode, nodes: CanvasNode[]): RootRect {
const root = rootPosition(node, nodes)
const width =
finiteNumber(node.measured?.width) ?? finiteNumber(node.width) ?? finiteNumber(node.style?.width) ?? 0
const height =
finiteNumber(node.measured?.height) ??
finiteNumber(node.height) ??
finiteNumber(node.style?.height) ??
0
return { x: root.x, y: root.y, width, height }
}
/**
* Grow `saved` until it also contains `boxes` with the clearance `fitGroupToChildren` gives a
* frame, or return `saved` untouched when it already does.
*
* `saved` is the FLOOR and is never padded: it is the rect the user consented to, so a frame that
* nothing forces open comes back at exactly the size they saved. Growing only outward is also what
* makes a repeated restore idempotent - a rule that could shrink or re-center the frame would
* drift a little further on every apply.
*/
function grownToContain(saved: RootRect, boxes: RootRect[]): RootRect {
if (boxes.length === 0) return saved
const minX = Math.min(...boxes.map((b) => b.x)) - GROUP_PAD
const minY = Math.min(...boxes.map((b) => b.y)) - GROUP_PAD - GROUP_HEADER
const maxX = Math.max(...boxes.map((b) => b.x + b.width)) + GROUP_PAD
const maxY = Math.max(...boxes.map((b) => b.y + b.height)) + GROUP_PAD
const x = Math.min(saved.x, minX)
const y = Math.min(saved.y, minY)
const right = Math.max(saved.x + saved.width, maxX)
const bottom = Math.max(saved.y + saved.height, maxY)
return { x, y, width: right - x, height: bottom - y }
}
/**
* Move and resize one frame to `rect` while every one of its children stays exactly where it is on
* canvas, by shifting their parent-relative positions against the frame's own move - the same
* re-anchoring `fitGroupToChildren` performs. A frame is a background container, so resizing it is
* not supposed to be visible on anything inside it.
*/
function withFrameRect(nodes: CanvasNode[], frameId: string, rect: RootRect): CanvasNode[] {
const frame = nodes.find((node) => node.id === frameId)
if (!frame) return nodes
const origin = rootPosition(frame, nodes)
const dx = rect.x - origin.x
const dy = rect.y - origin.y
return nodes.map((node) => {
if (node.id === frameId) {
return {
...node,
position: { x: node.position.x + dx, y: node.position.y + dy },
width: rect.width,
height: rect.height,
style: { ...node.style, width: rect.width, height: rect.height },
measured: undefined
}
}
if (node.parentId === frameId && (dx !== 0 || dy !== 0)) {
return { ...node, position: { x: node.position.x - dx, y: node.position.y - dy } }
}
return node
})
}
/** Ancestor count, used to re-fit frames innermost-first. Read off the ORIGINAL array because a
* restore never reparents anything (rule 8), so the chain is the same before and after. */
function depthOf(node: CanvasNode, byId: Map<string, CanvasNode>): number {
let depth = 0
const seen = new Set<string>([node.id])
let parentId = node.parentId
while (parentId && !seen.has(parentId)) {
seen.add(parentId)
const parent = byId.get(parentId)
if (!parent) break
depth += 1
parentId = parent.parentId
}
return depth
}
/**
* Put the canvas back the way `layout` recorded it. Pure.
*
* The whole layout lands in ONE transform, as an explicit two-pass: resolve every target root
* origin first, then emit the nodes against those origins. A reduce over per-node placements would
* re-fit an ancestor frame between two placements, so the second node would be measured against a
* frame the first node had just moved and the arrangement would come back subtly wrong - and
* differently wrong depending on array order.
*
* Geometry only. Nothing here creates, deletes, reparents, renames or respawns anything, and the
* layout's recorded `parentId` is read for nothing at all: it is a label for the reader, and
* honoring it would turn a restore into a structural edit.
*/
export function applyLayout(nodes: CanvasNode[], layout: CanvasLayout): ApplyLayoutResult {
const byId = new Map(nodes.map((node) => [node.id, node]))
// First-wins on a duplicate id: a hand-edited file can name one node twice, and the counts below
// must describe nodes, not entries, or the toast reports more moves than there are nodes.
const entries = new Map<string, CanvasLayoutNode>()
for (const entry of layout.nodes) {
if (!entries.has(entry.id)) entries.set(entry.id, entry)
}
// Rule 2: an entry whose node is gone is skipped and counted. A layout is geometry; resurrecting
// a node would be content, and content this file has no honest copy of.
let missing = 0
const placed = new Map<string, CanvasLayoutNode>()
for (const [id, entry] of entries) {
if (byId.has(id)) placed.set(id, entry)
else missing += 1
}
// Rule 1: a node the layout does not know is left exactly where it is - not tidied, not stacked
// at the origin. It is only counted, so the user learns the layout predates it.
let extra = 0
for (const node of nodes) {
if (EPHEMERAL_KINDS.has(node.type ?? '')) continue
if (!placed.has(node.id)) extra += 1
}
// Nothing to place: hand back the SAME array so a no-op restore cannot mark the workspace dirty
// and write a project.json revision for a canvas that did not change.
if (placed.size === 0) return { nodes, moved: 0, missing, extra }
const currentRoot = new Map(nodes.map((node) => [node.id, rootPosition(node, nodes)]))
/**
* Pass one, the target ROOT origin of every node: the saved one for a node the layout addresses,
* and the CURRENT one for a node it does not (rule 1, which holds even when the frame the node
* sits in is about to move out from under it). Resolving all of them before anything is emitted
* is what makes the transform order-independent. A dangling parentId resolves to the root,
* matching how `containerOrigin` treats one.
*/
const targetRoot = (id: string): { x: number; y: number } => {
const entry = placed.get(id)
if (entry) return { x: entry.x, y: entry.y }
return currentRoot.get(id) ?? { x: 0, y: 0 }
}
const originOf = (parentId: string | undefined): { x: number; y: number } =>
parentId && byId.has(parentId) ? targetRoot(parentId) : { x: 0, y: 0 }
// Pass two. Group frames are placed here like any other node (rule 3): a frame the layout
// addresses gets the rect the user saved, and is deliberately NOT re-fitted around the children
// the layout ALSO addressed, or the fit would overwrite that rect and the arrangement would
// drift a little on every restore.
let next = nodes.map((node) => {
const origin = originOf(node.parentId)
const entry = placed.get(node.id)
if (!entry) {
// An unaddressed node holds its root position rather than riding its frame: "left where it
// is" is a claim about the canvas, not about a parent-relative offset.
const root = currentRoot.get(node.id) ?? node.position
const position = { x: root.x - origin.x, y: root.y - origin.y }
if (position.x === node.position.x && position.y === node.position.y) return node
return { ...node, position }
}
// Rule 5: the stored height is ALWAYS the expanded one, so a collapsed entry emits the chrome
// height on the node while `expandedHeight` keeps the real size. Getting this the other way
// round makes expanding a restored node snap it to a stale height.
const collapsed = entry.collapsed === true
const height = collapsed ? COLLAPSED_HEIGHT : entry.height
return {
...node,
position: { x: entry.x - origin.x, y: entry.y - origin.y },
width: entry.width,
height,
style: { ...node.style, width: entry.width, height },
// Rule 7, the reason `withNodeRect` gives: `flowToNodeStates` prefers `measured` over
// `width`/`height`, so a save racing the re-measure would persist the OLD size.
measured: undefined,
// Rule 6 and rule 8 ride on this spread: `premaxRect` and every non-geometry field (title,
// color, cwd, agentId, accountId, pendingLaunch, trigger, icon, ...) survive untouched. A
// restore is a placement, not a maximize, so a maximized node keeps its restore rect - the
// same rule `placeNodeInRect` states for zone snaps.
data: { ...node.data, collapsed, expandedHeight: entry.height }
}
})
/**
* Rule 3's one exception, and it exists to protect rule 1. A frame the layout addresses may hold
* descendants the layout predates; those keep their root position, so a saved rect too small to
* contain them would let React Flow's `extent: 'parent'` CLAMP them - a node the layout never
* mentioned would move, with nothing on screen explaining why. So the frame is grown to contain
* them instead of the node being pushed. Growing a frame is ordinary behavior the user already
* sees from `fitGroupToChildren`; a terminal that teleports is not. The saved rect stays the
* floor, so a frame nothing forces open still lands on it exactly.
*/
const childIds = new Map<string, string[]>()
for (const node of nodes) {
if (!node.parentId) continue
const siblings = childIds.get(node.parentId)
if (siblings) siblings.push(node.id)
else childIds.set(node.parentId, [node.id])
}
const unplacedDescendants = (frameId: string): CanvasNode[] => {
const out: CanvasNode[] = []
const seen = new Set<string>([frameId])
const queue = [...(childIds.get(frameId) ?? [])]
while (queue.length) {
const id = queue.shift()!
if (seen.has(id)) continue
seen.add(id)
const node = byId.get(id)
if (!node) continue
// Every level down, not just direct children: a deep node is clamped by its own frame, and
// that frame is only safe from clamping if this one contains it too.
if (!placed.has(id) && !EPHEMERAL_KINDS.has(node.type ?? '')) out.push(node)
queue.push(...(childIds.get(id) ?? []))
}
return out
}
for (const [id, entry] of placed) {
if (byId.get(id)?.type !== 'group') continue
const saved: RootRect = { x: entry.x, y: entry.y, width: entry.width, height: entry.height }
const grown = grownToContain(
saved,
unplacedDescendants(id).map((node) => renderedRootRect(node, nodes))
)
if (grown === saved) continue
next = withFrameRect(next, id, grown)
}
// Rule 3's other half: a frame the layout does NOT mention, but whose descendant just moved, is
// re-fitted around its children so it still hugs them. Deepest first, because a frame must be
// sized before the frame that has to wrap it (`fitAncestorChain`'s ordering, applied across
// every moved chain at once rather than per node).
const toFit = new Map<string, number>()
for (const id of placed.keys()) {
const seen = new Set<string>([id])
let parentId = byId.get(id)?.parentId
while (parentId && !seen.has(parentId)) {
seen.add(parentId)
const parent = byId.get(parentId)
if (!parent) break
if (!placed.has(parentId) && parent.type === 'group') {
toFit.set(parentId, depthOf(parent, byId))
}
parentId = parent.parentId
}
}
for (const id of [...toFit.keys()].sort((a, b) => (toFit.get(b) ?? 0) - (toFit.get(a) ?? 0))) {
next = fitGroupToChildren(next, id)
}
return { nodes: next, moved: placed.size, missing, extra }
}