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.

feat(canvas): arrange the canvas by lineage

Fabricio Casali6a7ee0a4931d
diff --git a/CLAUDE.md b/CLAUDE.md
index 6dbd15e6d..debeb53a9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -3516,6 +3516,31 @@ the Settings section and ShortcutsPanel start disagreeing about what a chord mea
ids it knows — so Delete, restart-agent, branch/transfer, terminal Search and Close can never
be hidden, whatever settings.json says. The group-frame menu's colors strip answers to the same
`colors` id; builders run through `tidySeparators` so a hidden row leaves no dangling rule.
+- **Arrange by lineage** (`arrangeByLineage` / `lineageLayers` in `state/workspace.ts`; pane menu
+ beside Tidy canvas, ⌘K, and the registry command `canvas.tidyLineage`, which ships UNBOUND —
+ ⌘⇧A is already the first tidy) — the second tidy: one row per LAYER of the lineage ropes
+ (`project.ropes`, i.e. "opened by" and `--after`), growing downward, so a coordinator sits above
+ the team it opened and that team above what IT opened. Four rules, each of which the naive
+ version gets wrong: **(1)** a rope is LIFTED to its top-level ancestor before it counts — an
+ agent opens a team INSIDE a frame, and the frame is the rigid unit that moves; a rope whose two
+ ends lift to the SAME object is internal to that frame and dropped, or the frame would be its own
+ opener. **(2)** a node's layer is its LONGEST path from a root, never its first — with `max`
+ every rope points strictly downward, which is the whole reason the result reads as a flow; a
+ reducer that keeps the LAST opener happens to be right in one edge order and wrong in the other,
+ so the test asserts BOTH. **(3)** nodes no rope touches are NOT layer 0 — they are a final
+ `loose` band, because a node with no lineage is not a root of anything and mixing the two puts
+ every sticky note beside the coordinator. **(4)** a cycle never hangs and never throws (the edge
+ that closes it contributes `0`): a rope cycle is not supposed to exist, but `--after` can be
+ hand-built into one and `project.json` is editable. The refusal is the transform returning the
+ SAME array — no usable rope, or under two top-level nodes — which is also what keeps a no-op out
+ of the undo stack and out of `project.json`; **that verdict is taken from `nodesRef` BEFORE the
+ write, never from a flag set inside the `setNodes` updater**, which runs when the state is
+ processed and is therefore still false on the next line (it would cost every run its `markDirty`
+ + `fitAll`). The pane row is then DISABLED with its reason while the palette OMITS it (no
+ disabled state there). Built ON `arrangeNodes` — one `row` placement per band from a shared left
+ origin — so packing, gap and the mixed-container refusal stay in ONE place. Desktop + Server
+ Edition identical (pure renderer, no new IPC); kanban N/A (a board shows cards, and geometry is
+ exactly what a column layout discards); Mobile N/A (no canvas).
- **Add menu** = bottom dock (`Dock.tsx`) `+`, mirrored by the pane menu and command palette.
`lib/addMenuSpec` is the one source for WHICH kinds are addable, and since 2026-09 also for how
the two `ContextMenu` surfaces GROUP them: `New terminal` · `New remote…` · the account-capable
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 9cbed6b7a..2d38e794d 100644
--- a/src/renderer/canvas/Canvas.tsx
+++ b/src/renderer/canvas/Canvas.tsx
@@ -105,6 +105,7 @@ import {
IconFit,
IconGear,
IconGrid,
+ IconLineage,
IconGroup,
IconJump,
IconKanban,
@@ -574,7 +575,9 @@ import {
claudeLaunchCommand,
COLLAPSED_HEIGHT,
alignNodes,
+ arrangeByLineage,
arrangeNodes,
+ lineageLayers,
commonParentId,
fitGroupToChildren,
createAccountLoginNode,
@@ -6905,6 +6908,36 @@ export function Canvas() {
fitAll()
}, [setNodes, markDirty, fitAll])
+ // The lineage ropes as the layout reads them: `controlEdges` is the live copy of what the
+ // project persists as `ropes` ("opened by" and `--after`), which is exactly the relation the
+ // user means by "who opened whom".
+ const lineageEdges = useCallback(
+ () => controlEdgesRef.current.map((e) => ({ source: e.source, target: e.target })),
+ []
+ )
+ // Whether the lineage tidy has anything to say. Asked when the menu OPENS so the row can be
+ // disabled with its reason instead of silently doing nothing on click: on a canvas nobody
+ // spawned anything into, every node is loose and the result would just be a worse Tidy canvas.
+ const hasLineageLayers = useCallback(
+ () => lineageLayers(nodesRef.current, lineageEdges()).layers.length > 0,
+ [lineageEdges]
+ )
+ // Lineage bands: one row per layer, growing downward, with the nodes no rope touches last.
+ // Mirrors arrangeAllNodes exactly — same kanban guard, same markDirty + fitAll — except that
+ // the refusal is `arrangeByLineage` returning the SAME array, which is also what keeps a
+ // no-op out of the undo stack and out of project.json.
+ const arrangeByLineageAction = useCallback(() => {
+ if (isGlobalKanbanOpen() || isKanbanOpen(useProjects.getState().activeProjectId)) return
+ const edges = lineageEdges()
+ // Decided against nodesRef BEFORE the write, never from inside the updater: a React updater
+ // runs when the state is processed, so a flag set in there is still false on the next line
+ // and markDirty/fitAll would never fire. The transform is pure, so asking it twice is free.
+ if (arrangeByLineage(nodesRef.current, edges) === nodesRef.current) return
+ setNodes((ns) => arrangeByLineage(ns, edges))
+ markDirty()
+ fitAll()
+ }, [setNodes, markDirty, fitAll, lineageEdges])
+
/** Report a refusal the user cannot act on any other way. One dismiss button, no default. */
const alertLayout = useCallback(
(message: string) => {
@@ -7809,6 +7842,7 @@ export function Canvas() {
'canvas.goForward': () => { goForward(); return true },
'canvas.fitAll': () => { fitAll(); return true },
'canvas.tidy': () => { arrangeAllNodes(); return true },
+ 'canvas.tidyLineage': () => { arrangeByLineageAction(); return true },
'canvas.deleteSelection': deleteSelectionCommand,
'node.newTerminal': () => { addTerminal(); return true },
'node.newAgent': () => {
@@ -8878,6 +8912,21 @@ export function Canvas() {
...(hasArrangeableNodes()
? [{ label: 'Tidy canvas', icon: <IconGrid />, onClick: arrangeAllNodes } as MenuItem]
: []),
+ // Same visibility gate as Tidy canvas, then disabled WITH the reason when this canvas
+ // has no lineage to lay out — a row that is off for an invisible reason teaches nothing.
+ ...(hasArrangeableNodes()
+ ? [
+ {
+ label: 'Arrange by lineage',
+ icon: <IconLineage />,
+ disabled: !hasLineageLayers(),
+ hint: hasLineageLayers()
+ ? 'One row per level: who opened whom, top to bottom.'
+ : 'Nothing on this canvas was opened by another node yet.',
+ onClick: arrangeByLineageAction
+ } as MenuItem
+ ]
+ : []),
// Project-wide: restart every idle agent CLI in place (new model pickup). Hidden on a
// canvas with no restartable agent node — there it could only ever report "0 restarted".
...(hasRestartableAgents()
@@ -8901,7 +8950,9 @@ export function Canvas() {
selectAll,
fitAll,
arrangeAllNodes,
+ arrangeByLineageAction,
hasArrangeableNodes,
+ hasLineageLayers,
hasRestartableAgents,
restartIdleAgents
]
@@ -13986,6 +14037,19 @@ export function Canvas() {
} as Command
]
: []),
+ // Omitted rather than disabled when there is no lineage: the palette has no disabled
+ // state, so an entry that does nothing would surface as a search hit that goes nowhere.
+ ...(hasArrangeableNodes() && hasLineageLayers()
+ ? [
+ {
+ id: 'arrange-lineage',
+ label: 'Arrange by lineage',
+ hint: 'layers levels who opened whom tree hierarchy organize',
+ icon: <IconLineage />,
+ run: arrangeByLineageAction
+ } as Command
+ ]
+ : []),
{ id: 'zoom-100', label: 'Zoom to 100%', icon: <IconFit />, run: zoomTo100 },
// Layouts mirror the Dock's menu, and both are withheld on a relay tab for the same reason:
// it is a live connection to another machine, never a workspace on this disk. The Dock says
diff --git a/src/renderer/components/icons.tsx b/src/renderer/components/icons.tsx
index 5be179e3f..7d813fba5 100644
--- a/src/renderer/components/icons.tsx
+++ b/src/renderer/components/icons.tsx
@@ -108,6 +108,16 @@ export const IconGrid = () => (
</svg>
)
+/** Layer bands with a shared opener above them: the lineage tidy. */
+export const IconLineage = () => (
+ <svg {...S}>
+ <rect x="9.5" y="3" width="5" height="4" rx="1" />
+ <rect x="3" y="17" width="5" height="4" rx="1" />
+ <rect x="16" y="17" width="5" height="4" rx="1" />
+ <path d="M12 7v4M5.5 17v-2.5h13V17" />
+ </svg>
+)
+
export const IconCollapse = () => (
<svg {...S}>
<path d="M8 4v4H4M16 4v4h4M8 20v-4H4M16 20v-4h4" />
diff --git a/src/renderer/state/workspace.layout.test.ts b/src/renderer/state/workspace.layout.test.ts
index 667d3631b..1183f0516 100644
--- a/src/renderer/state/workspace.layout.test.ts
+++ b/src/renderer/state/workspace.layout.test.ts
@@ -1,5 +1,5 @@
import { describe, it, expect } from 'vitest'
-import { arrangeNodes, alignNodes, type CanvasNode } from './workspace'
+import { arrangeNodes, alignNodes, arrangeByLineage, lineageLayers, type CanvasNode } from './workspace'
// Minimal node stub: only the fields the layout fns read (id, position, width/height, parentId).
const n = (id: string, x: number, y: number, w = 100, h = 50): CanvasNode =>
@@ -79,3 +79,149 @@ describe('alignNodes', () => {
expect(alignNodes(nodes, ['ghost'], 'left')).toBe(nodes)
})
})
+
+// A frame and its children: a rope routinely ends on a node INSIDE a frame, and the frame is the
+// top-level object a layer layout has to place.
+const frame = (id: string, x: number, y: number, w = 300, h = 200): CanvasNode =>
+ ({ id, type: 'group', position: { x, y }, width: w, height: h, data: { title: id, color: '#fff', group: null } }) as CanvasNode
+const child = (id: string, parentId: string, x = 10, y = 10): CanvasNode =>
+ ({ id, type: 'terminal', position: { x, y }, width: 100, height: 50, parentId, data: { title: id, color: '#fff', group: null } }) as CanvasNode
+
+describe('lineageLayers', () => {
+ it('layers by who opened whom, roots first', () => {
+ const nodes = [n('coord', 0, 0), n('arch', 500, 0), n('coder', 500, 200), n('rev', 900, 0)]
+ const { layers, loose } = lineageLayers(nodes, [
+ { source: 'coord', target: 'arch' },
+ { source: 'coord', target: 'coder' },
+ { source: 'arch', target: 'rev' }
+ ])
+ expect(layers).toEqual([['coord'], ['arch', 'coder'], ['rev']])
+ expect(loose).toEqual([])
+ })
+
+ it('lifts a rope that lands inside a frame up to the frame itself', () => {
+ // The coordinator opens a team into a group: the rope ends on `a1`, but `g1` is what moves.
+ const nodes = [n('coord', 0, 0), frame('g1', 500, 0), child('a1', 'g1'), child('a2', 'g1')]
+ const { layers, loose } = lineageLayers(nodes, [{ source: 'coord', target: 'a1' }])
+ expect(layers).toEqual([['coord'], ['g1']])
+ expect(loose).toEqual([])
+ })
+
+ it('drops a rope internal to one frame', () => {
+ // a1 opened a2 inside the same group: both lift to g1, which cannot be its own opener.
+ const nodes = [n('other', 0, 0), frame('g1', 500, 0), child('a1', 'g1'), child('a2', 'g1')]
+ const { layers, loose } = lineageLayers(nodes, [{ source: 'a1', target: 'a2' }])
+ expect(layers).toEqual([])
+ expect(loose).toEqual(['other', 'g1'])
+ })
+
+ // c is opened by a AND by b: the shortest path would put c in layer 1 beside b, and the
+ // a-to-c rope would then run sideways instead of down. Asserted in BOTH edge orders on
+ // purpose: ropes arrive in creation order out of project.json, and a reducer that keeps the
+ // LAST opener instead of the deepest one happens to be right in one of the two orders.
+ it.each([
+ ['deepest opener last', [{ source: 'a', target: 'c' }, { source: 'b', target: 'c' }]],
+ ['deepest opener first', [{ source: 'b', target: 'c' }, { source: 'a', target: 'c' }]]
+ ])('uses the LONGEST path, so every rope points downward (%s)', (_label, tail) => {
+ const nodes = [n('a', 0, 0), n('b', 300, 0), n('c', 600, 0)]
+ const { layers } = lineageLayers(nodes, [{ source: 'a', target: 'b' }, ...tail])
+ expect(layers).toEqual([['a'], ['b'], ['c']])
+ })
+
+ it('keeps untouched nodes out of layer 0, in their own loose band', () => {
+ const nodes = [n('coord', 0, 0), n('agent', 300, 0), n('note', 0, 400), n('editor', 300, 400)]
+ const { layers, loose } = lineageLayers(nodes, [{ source: 'coord', target: 'agent' }])
+ expect(layers).toEqual([['coord'], ['agent']])
+ expect(loose).toEqual(['note', 'editor'])
+ })
+
+ it('orders a layer by the slot of its opener above, so siblings sit together', () => {
+ // Two roots with two children each, interleaved on the canvas: without the slot ordering the
+ // children alternate p1,p2,p1,p2 and every rope crosses.
+ const nodes = [
+ n('p1', 0, 0),
+ n('p2', 400, 0),
+ n('b1', 600, 300),
+ n('a1', 0, 300),
+ n('b2', 900, 300),
+ n('a2', 300, 300)
+ ]
+ const { layers } = lineageLayers(nodes, [
+ { source: 'p1', target: 'a1' },
+ { source: 'p2', target: 'b1' },
+ { source: 'p1', target: 'a2' },
+ { source: 'p2', target: 'b2' }
+ ])
+ expect(layers[0]).toEqual(['p1', 'p2'])
+ expect(layers[1]).toEqual(['a1', 'a2', 'b1', 'b2'])
+ })
+
+ it('does not hang on a cycle', () => {
+ const nodes = [n('a', 0, 0), n('b', 300, 0), n('c', 600, 0)]
+ const { layers, loose } = lineageLayers(nodes, [
+ { source: 'a', target: 'b' },
+ { source: 'b', target: 'c' },
+ { source: 'c', target: 'a' }
+ ])
+ // Every node is still placed exactly once and nothing is lost.
+ expect([...layers.flat(), ...loose].sort()).toEqual(['a', 'b', 'c'])
+ })
+
+ it('ignores a rope whose endpoint is no longer on the canvas', () => {
+ const nodes = [n('a', 0, 0), n('b', 300, 0)]
+ const { layers, loose } = lineageLayers(nodes, [{ source: 'ghost', target: 'b' }])
+ expect(layers).toEqual([])
+ expect(loose).toEqual(['a', 'b'])
+ })
+})
+
+describe('arrangeByLineage', () => {
+ const edges = [
+ { source: 'coord', target: 'arch' },
+ { source: 'coord', target: 'coder' }
+ ]
+
+ it('stacks each layer as a row, growing downward from the bounding-box origin', () => {
+ const nodes = [n('coord', 100, 50), n('arch', 900, 400), n('coder', 500, 900)]
+ const out = arrangeByLineage(nodes, edges, { gap: 20 })
+ const at = (id: string) => out.find((x) => x.id === id)!.position
+ // origin = (100, 50); layer 0 holds one 50-high node, so layer 1 starts at 50 + 50 + 20.
+ expect(at('coord')).toEqual({ x: 100, y: 50 })
+ expect(at('arch')).toEqual({ x: 100, y: 120 })
+ expect(at('coder')).toEqual({ x: 100 + 100 + 20, y: 120 })
+ })
+
+ it('puts the loose band last', () => {
+ const nodes = [n('coord', 0, 0), n('arch', 300, 0), n('coder', 600, 0), n('note', 0, 500)]
+ const out = arrangeByLineage(nodes, edges, { gap: 20 })
+ const y = (id: string) => out.find((x) => x.id === id)!.position.y
+ expect(y('note')).toBeGreaterThan(y('arch'))
+ })
+
+ it('advances by the TALLEST member of a band', () => {
+ // The frame in layer 0 is 200 high; the next band must clear it, not the 50 of a terminal.
+ const nodes = [frame('g1', 0, 0), child('a1', 'g1'), n('other', 400, 0), n('kid', 0, 900)]
+ const out = arrangeByLineage(nodes, [{ source: 'a1', target: 'kid' }], { gap: 20 })
+ expect(out.find((x) => x.id === 'kid')!.position.y).toEqual(0 + 200 + 20)
+ })
+
+ it('moves a frame as one unit and leaves its children alone', () => {
+ const nodes = [n('coord', 0, 0), frame('g1', 800, 600), child('a1', 'g1', 10, 10)]
+ const out = arrangeByLineage(nodes, [{ source: 'coord', target: 'a1' }], { gap: 20 })
+ expect(out.find((x) => x.id === 'g1')!.position).toEqual({ x: 0, y: 70 })
+ // A child position is relative to its frame and must not be rewritten.
+ expect(out.find((x) => x.id === 'a1')!.position).toEqual({ x: 10, y: 10 })
+ })
+
+ it('returns the SAME array when no rope is usable', () => {
+ // The caller skips the undo entry and the project.json write rather than rewriting every
+ // position to where it already was.
+ const nodes = [n('a', 0, 0), n('b', 300, 0)]
+ expect(arrangeByLineage(nodes, [])).toBe(nodes)
+ })
+
+ it('returns the SAME array below two top-level nodes', () => {
+ const one = [n('a', 0, 0)]
+ expect(arrangeByLineage(one, edges)).toBe(one)
+ })
+})
diff --git a/src/renderer/state/workspace.ts b/src/renderer/state/workspace.ts
index 8b6bab265..549ebf5ab 100644
--- a/src/renderer/state/workspace.ts
+++ b/src/renderer/state/workspace.ts
@@ -1285,6 +1285,176 @@ export function arrangeNodes(
return nodes.map((nd) => (pos.has(nd.id) ? { ...nd, position: pos.get(nd.id)! } : nd))
}
+/** One lineage rope, as the canvas persists it (`project.ropes`): "opened by" / "--after". */
+export interface LineageEdge {
+ source: string
+ target: string
+}
+
+/**
+ * The top-level ancestor of every node, by id. A rope points at the NODE an agent opened, which is
+ * routinely a node inside a frame — and a frame moves as one rigid unit, so a layer layout has to
+ * ask which top-level object that rope really reaches. A parentId naming no live node, or a cycle
+ * (project.json is hand-editable), resolves to the last node still walkable rather than throwing.
+ */
+function topLevelAncestors(nodes: CanvasNode[]): Map<string, string> {
+ const byId = new Map(nodes.map((nd) => [nd.id, nd]))
+ const out = new Map<string, string>()
+ for (const nd of nodes) {
+ let cur = nd
+ const seen = new Set<string>([nd.id])
+ while (cur.parentId) {
+ const parent = byId.get(cur.parentId)
+ if (!parent || seen.has(parent.id)) break
+ seen.add(parent.id)
+ cur = parent
+ }
+ out.set(nd.id, cur.id)
+ }
+ return out
+}
+
+/**
+ * Splits the TOP-LEVEL nodes into lineage layers: layer 0 is every node nothing opened, layer k is
+ * a node whose deepest opener sits in layer k-1, and `loose` holds the nodes no rope touches at all.
+ *
+ * Three rules, each of which the naive version gets wrong:
+ *
+ * - **Ropes are LIFTED to the top-level ancestor.** The coordinator opens a team INSIDE a frame, so
+ * the rope ends on a child; the frame is what gets placed. An edge whose two ends lift to the
+ * same object is dropped — it is internal to that frame and would otherwise make it its own
+ * opener.
+ * - **A node's layer is its LONGEST path from a root**, not its first: with `max` every rope points
+ * strictly downward, which is the whole reason the layout reads as a flow. Taking the shortest
+ * path would let a rope run backwards up the canvas.
+ * - **A cycle never hangs and never throws.** Ropes are "opened by" and `--after`, so a cycle is
+ * not supposed to exist, but `--after` can be hand-built into one and project.json is editable.
+ * The edge that closes a cycle contributes nothing (`0`), so the result stays deterministic for
+ * a given edge order instead of recursing forever.
+ *
+ * `loose` is deliberately NOT layer 0: a node with no lineage is not a root of anything, and
+ * mixing the two would put every sticky note beside the coordinator.
+ */
+export function lineageLayers(
+ nodes: CanvasNode[],
+ edges: readonly LineageEdge[]
+): { layers: string[][]; loose: string[] } {
+ const tops = topLevelAncestors(nodes)
+ const topLevel = nodes.filter((nd) => !nd.parentId)
+ const live = new Set(topLevel.map((nd) => nd.id))
+
+ const preds = new Map<string, string[]>()
+ const touched = new Set<string>()
+ for (const e of edges) {
+ const from = tops.get(e.source)
+ const to = tops.get(e.target)
+ if (!from || !to || from === to || !live.has(from) || !live.has(to)) continue
+ const list = preds.get(to)
+ if (list) {
+ if (!list.includes(from)) list.push(from)
+ } else {
+ preds.set(to, [from])
+ }
+ touched.add(from)
+ touched.add(to)
+ }
+
+ const memo = new Map<string, number>()
+ const onStack = new Set<string>()
+ const levelOf = (id: string): number => {
+ const cached = memo.get(id)
+ if (cached !== undefined) return cached
+ if (onStack.has(id)) return 0
+ onStack.add(id)
+ let level = 0
+ for (const from of preds.get(id) ?? []) level = Math.max(level, levelOf(from) + 1)
+ onStack.delete(id)
+ memo.set(id, level)
+ return level
+ }
+
+ // Reading order of the canvas as it stands, used as the tie-break everywhere below so the
+ // result is stable and roughly preserves what the user already built.
+ const order = new Map<string, number>()
+ ;[...topLevel]
+ .sort((a, b) => a.position.y - b.position.y || a.position.x - b.position.x || (a.id < b.id ? -1 : 1))
+ .forEach((nd, i) => order.set(nd.id, i))
+ const byReadingOrder = (a: string, b: string): number => (order.get(a) ?? 0) - (order.get(b) ?? 0)
+
+ const layers: string[][] = []
+ const loose: string[] = []
+ for (const nd of topLevel) {
+ if (!touched.has(nd.id)) {
+ loose.push(nd.id)
+ continue
+ }
+ const level = levelOf(nd.id)
+ while (layers.length <= level) layers.push([])
+ layers[level].push(nd.id)
+ }
+
+ // Inside a layer, siblings sit together: a node follows its earliest opener's slot in the layer
+ // above, so the ropes fan out instead of crossing. Layer 0 and `loose` have no opener to follow
+ // and keep the canvas's own reading order.
+ layers.forEach((layer, level) => {
+ if (level === 0) {
+ layer.sort(byReadingOrder)
+ return
+ }
+ const above = new Map(layers[level - 1].map((id, i) => [id, i]))
+ const slotOf = (id: string): number => {
+ let best = Number.MAX_SAFE_INTEGER
+ for (const from of preds.get(id) ?? []) {
+ const slot = above.get(from)
+ if (slot !== undefined && slot < best) best = slot
+ }
+ return best
+ }
+ layer.sort((a, b) => slotOf(a) - slotOf(b) || byReadingOrder(a, b))
+ })
+ loose.sort(byReadingOrder)
+ return { layers, loose }
+}
+
+/**
+ * Lays the top-level nodes out as lineage bands: one row per layer, growing downward, with the
+ * nodes no rope touches in a final band of their own. Returns the input unchanged when there is
+ * nothing to arrange (under two top-level nodes, or no usable rope) — an unchanged array is the
+ * caller's signal to skip the undo entry and the project.json write.
+ *
+ * Built ON `arrangeNodes` rather than beside it: each band is one `row` placement from a shared
+ * left origin, so the packing, the gap and the mixed-container refusal all stay in ONE place.
+ */
+export function arrangeByLineage(
+ nodes: CanvasNode[],
+ edges: readonly LineageEdge[],
+ opts?: { gap?: number; origin?: { x: number; y: number } }
+): CanvasNode[] {
+ const topLevel = nodes.filter((nd) => !nd.parentId)
+ if (topLevel.length < 2) return nodes
+ const { layers, loose } = lineageLayers(nodes, edges)
+ // No rope reached two different top-level objects: every node would land in the single `loose`
+ // band, which is a worse `Tidy canvas`, not a lineage view.
+ if (layers.length === 0) return nodes
+
+ const gap = opts?.gap ?? 40
+ const origin = opts?.origin ?? {
+ x: Math.min(...topLevel.map((nd) => nd.position.x)),
+ y: Math.min(...topLevel.map((nd) => nd.position.y))
+ }
+ const bands = loose.length > 0 ? [...layers, loose] : layers
+
+ let out = nodes
+ let y = origin.y
+ for (const band of bands) {
+ if (band.length === 0) continue
+ out = arrangeNodes(out, band, { layout: 'row', gap, origin: { x: origin.x, y } })
+ const tallest = Math.max(...band.map((id) => nodeH(out.find((nd) => nd.id === id)!)))
+ y += tallest + gap
+ }
+ return out
+}
+
export type AlignEdge = 'left' | 'right' | 'top' | 'bottom' | 'hcenter' | 'vcenter'
/**
diff --git a/src/shared/keybindings.test.ts b/src/shared/keybindings.test.ts
index 5b6092b91..5c4b6e0bc 100644
--- a/src/shared/keybindings.test.ts
+++ b/src/shared/keybindings.test.ts
@@ -106,6 +106,8 @@ describe('registry invariants', () => {
darwin: [], other: [] },
{ id: 'canvas.tidy', title: 'Tidy canvas', group: 'Canvas', scope: 'canvas',
darwin: ['Cmd+Shift+A'], other: ['Cmd+Shift+A'] },
+ { id: 'canvas.tidyLineage', title: 'Arrange by lineage', group: 'Canvas', scope: 'canvas',
+ darwin: [], other: [] },
{ id: 'canvas.groupSelection', title: 'Group selection', group: 'Canvas', scope: 'canvas',
darwin: [], other: [] },
{ id: 'node.newTerminal', title: 'New terminal node', group: 'Nodes', scope: 'canvas',
diff --git a/src/shared/keybindings.ts b/src/shared/keybindings.ts
index ddcf9fe9d..9622bcecd 100644
--- a/src/shared/keybindings.ts
+++ b/src/shared/keybindings.ts
@@ -56,6 +56,7 @@ export type CommandId =
| 'canvas.deleteSelection'
| 'canvas.fitAll'
| 'canvas.tidy'
+ | 'canvas.tidyLineage'
| 'canvas.groupSelection'
| 'node.newTerminal'
| 'node.newAgent'
@@ -147,6 +148,10 @@ export const COMMAND_DEFINITIONS: readonly CommandDefinition[] = [
{ id: 'canvas.tidy', title: 'Tidy canvas', group: 'Canvas', scope: 'canvas',
// arrangeAllNodes self-guards (kanban open, <2 top-level nodes), same as the ⌘K/menu entries.
defaultBindings: both('Cmd+Shift+A') },
+ { id: 'canvas.tidyLineage', title: 'Arrange by lineage', group: 'Canvas', scope: 'canvas',
+ // Ships unbound: it is the second tidy, and Cmd+Shift+A is already the first. Self-guards
+ // exactly like arrangeAllNodes (kanban open, <2 top-level nodes, no usable rope).
+ defaultBindings: both() },
{ id: 'canvas.groupSelection', title: 'Group selection', group: 'Canvas', scope: 'canvas',
defaultBindings: both() },